@scriptdb/storage

Storage module for the script database, providing a Git-based file system with full version control capabilities.

Features

• Git-based storage: Complete version control for all files
• File operations: Add, update, delete, and retrieve files
• Repository management: Initialize, configure, and manage Git repositories
• Remote operations: Push, pull, fetch, and clone repositories
• Configuration management: Full Git configuration support
• Cross-platform compatibility: Works on Windows, macOS, and Linux

Installation

bun add @scriptdb/storage

Quick Start

import { Storage } from '@scriptdb/storage';

// Initialize storage
const storage = new Storage('./my-repo');
await storage.initialize();

// Add a file
await storage.addFile('hello.txt', 'Hello, World!');

// Commit changes
await storage.commit('Initial commit');

// Get file content
const file = await storage.getFile('hello.txt');
console.log(file.content); // "Hello, World!"

API Reference

Constructor

new Storage(repoPath: string)

Creates a new storage instance with the specified repository path.

Methods

initialize(repoPath?)

Initializes a Git repository at the specified path.

await storage.initialize(repoPath?: string): Promise<SimpleGit>

File Operations

addFile(filePath, content)

Adds a new file to the repository.

await storage.addFile(filePath: string, content: string): Promise<{ success: boolean; message: string; path?: string }>

updateFile(filePath, content)

Updates an existing file.

await storage.updateFile(filePath: string, content: string): Promise<{ success: boolean; message: string; path?: string }>

getFile(filePath)

Retrieves file content.

await storage.getFile(filePath: string): Promise<{ success: boolean; content?: string; path?: string; message?: string }>

deleteFile(filePath)

Deletes a file from the repository.

await storage.deleteFile(filePath: string): Promise<{ success: boolean; message: string }>

Repository Operations

commit(message)

Commits staged changes.

await storage.commit(message: string): Promise<{ success: boolean; message: string }>

getStatus()

Gets the current repository status.

await storage.getStatus(): Promise<RepoStatus>

getHistory(filePath)

Gets commit history for a file.

await storage.getHistory(filePath: string): Promise<CommitHistory[]>

listFiles()

Lists all files in the repository.

await storage.listFiles(): Promise<string[]>

Git Configuration

setConfig(config, scope?)

Sets Git configuration values.

await storage.setConfig(config: GitConfig, scope?: 'local' | 'global' | 'system'): Promise<{ success: boolean; message: string; changes?: any[] }>

getConfig(key, scope?)

Gets a specific Git configuration value.

await storage.getConfig(key: string, scope?: 'local' | 'global' | 'system'): Promise<{ success: boolean; key?: string; value?: string; scope?: string; message?: string }>

listConfig(scope?)

Lists all Git configuration values.

await storage.listConfig(scope?: 'local' | 'global' | 'system'): Promise<{ success: boolean; scope: string; config?: any; message?: string }>

setupBasicConfig(userName?, userEmail?, additionalConfig?)

Sets up basic Git configuration.

await storage.setupBasicConfig(userName?: string, userEmail?: string, additionalConfig?: Record<string, string>): Promise<{ success: boolean; message: string }>

Remote Operations

addRemote(name, url)

Adds a remote repository.

await storage.addRemote(name: string, url: string): Promise<{ success: boolean; message: string; name?: string; url?: string }>

removeRemote(name)

Removes a remote repository.

await storage.removeRemote(name: string): Promise<{ success: boolean; message: string; name?: string }>

listRemotes()

Lists all remote repositories.

await storage.listRemotes(): Promise<{ success: boolean; remotes: RemoteInfo[]; message?: string }>

push(remote?, branch?, options?)

Pushes changes to a remote repository.

await storage.push(remote?: string, branch?: string, options?: { force?: boolean; setUpstream?: boolean }): Promise<{ success: boolean; message: string; remote?: string; branch?: string }>

pull(remote?, branch?, options?)

Pulls changes from a remote repository.

await storage.pull(remote?: string, branch?: string, options?: { allowUnrelatedHistories?: boolean }): Promise<{ success: boolean; message: string; remote?: string; branch?: string }>

fetch(remote?, branch?, options?)

Fetches changes from a remote repository without merging.

await storage.fetch(remote?: string, branch?: string, options?: { prune?: boolean }): Promise<{ success: boolean; message: string; remote?: string; branch?: string }>

clone(url, targetPath?, options?)

Clones a remote repository.

await storage.clone(url: string, targetPath?: string, options?: { bare?: boolean; branch?: string; depth?: number }): Promise<{ success: boolean; message: string; url?: string; path?: string }>

Types

GitConfig

interface GitConfig {
  userName?: string;
  userEmail?: string;
  options?: Record<string, string>;
}

RepoStatus

interface RepoStatus {
  staged: string[];
  unstaged: string[];
  untracked: string[];
  clean: boolean;
  error?: string;
}

RemoteInfo

interface RemoteInfo {
  name: string;
  refs: string;
  pushUrl: string;
}

CommitHistory

interface CommitHistory {
  hash: string;
  message: string;
  date: string;
  author: string;
}

Examples

Basic Usage

import { Storage } from '@scriptdb/storage';

// Create storage instance
const storage = new Storage('./my-project');
await storage.initialize();

// Configure user
await storage.setupBasicConfig('John Doe', '[email protected]');

// Add files
await storage.addFile('README.md', '# My Project');
await storage.addFile('src/index.ts', 'console.log("Hello, World!");');

// Commit changes
await storage.commit('Initial commit');

// Update a file
await storage.updateFile('README.md', '# My Project\n\nA sample project.');
await storage.commit('Update README');

// Get file content
const readme = await storage.getFile('README.md');
console.log(readme.content);

// Get repository status
const status = await storage.getStatus();
console.log(status);

Working with Remotes

import { Storage } from '@scriptdb/storage';

// Initialize storage
const storage = new Storage('./my-project');
await storage.initialize();

// Add remote
await storage.addRemote('origin', 'https://github.com/username/my-project.git');

// Push changes
await storage.push('origin', 'main');

// Pull changes
await storage.pull('origin', 'main');

// Fetch changes without merging
await storage.fetch('origin', 'main');

// Clone a repository
const newStorage = new Storage('./cloned-project');
await newStorage.clone('https://github.com/username/another-project.git');

Configuration Management

import { Storage } from '@scriptdb/storage';

const storage = new Storage('./my-project');
await storage.initialize();

// Set user configuration
await storage.setConfig({
  userName: 'Jane Doe',
  userEmail: '[email protected]',
  options: {
    'core.autocrlf': 'false',
    'pull.rebase': 'true'
  }
});

// Get configuration
const userName = await storage.getConfig('user.name');
console.log(userName.value); // "Jane Doe"

// List all configuration
const config = await storage.listConfig();
console.log(config.config);

Error Handling

All methods return a result object with a success property indicating if the operation was successful. If success is false, the message property contains information about the error.

const result = await storage.addFile('test.txt', 'content');

if (result.success) {
  console.log(`File added at ${result.path}`);
} else {
  console.error(`Error: ${result.message}`);
}

Security Considerations

• Ensure proper file system permissions for the repository path
• Validate file paths and content to prevent directory traversal attacks
• Use secure authentication methods for remote operations
• Consider encrypting sensitive data before storing it

License

MIT