verso-db 0.1.5 → 0.2.0

package/src/storage/MemoryBackend.ts

@@ -1,122 +0,0 @@
-/**
- * In-Memory Storage Backend
- *
- * Stores all data in memory using a Map. Useful for:
- * - Testing without file system
- * - Small datasets that fit in memory
- * - Browser environments without OPFS/IndexedDB
- * - Temporary caches
- */
-
-import type { StorageBackend } from './StorageBackend';
-
-export class MemoryBackend implements StorageBackend {
-  readonly type = 'memory';
-  private storage: Map<string, ArrayBuffer> = new Map();
-  private directories: Set<string> = new Set();
-
-  constructor() {
-    this.directories.add(''); // Root directory always exists
-  }
-
-  async read(key: string): Promise<ArrayBuffer | null> {
-    const data = this.storage.get(key);
-    if (!data) return null;
-    // Return a copy to prevent mutation
-    return data.slice(0);
-  }
-
-  async write(key: string, data: ArrayBuffer | Uint8Array): Promise<void> {
-    // Store a copy to prevent external mutation
-    const buffer = data instanceof ArrayBuffer ? data : data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;
-    this.storage.set(key, buffer.slice(0));
-  }
-
-  async append(key: string, data: ArrayBuffer | Uint8Array): Promise<void> {
-    const appendData = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
-
-    const existing = this.storage.get(key);
-    if (existing) {
-      const existingArray = new Uint8Array(existing);
-      const combined = new Uint8Array(existingArray.length + appendData.length);
-      combined.set(existingArray, 0);
-      combined.set(appendData, existingArray.length);
-      this.storage.set(key, combined.buffer.slice(0) as ArrayBuffer);
-    } else {
-      this.storage.set(key, appendData.buffer.slice(appendData.byteOffset, appendData.byteOffset + appendData.byteLength) as ArrayBuffer);
-    }
-  }
-
-  async delete(key: string): Promise<void> {
-    this.storage.delete(key);
-  }
-
-  async exists(key: string): Promise<boolean> {
-    return this.storage.has(key);
-  }
-
-  async list(prefix?: string): Promise<string[]> {
-    const keys: string[] = [];
-    // Match BunStorageBackend/OPFSBackend semantics: prefix is a directory path
-    const dirPrefix = prefix ? (prefix.endsWith('/') ? prefix : prefix + '/') : '';
-    for (const key of this.storage.keys()) {
-      if (!dirPrefix || key.startsWith(dirPrefix)) {
-        keys.push(key);
-      }
-    }
-    return keys;
-  }
-
-  async mkdir(path: string): Promise<void> {
-    this.directories.add(path);
-    // Also add parent directories
-    const parts = path.split('/');
-    for (let i = 1; i <= parts.length; i++) {
-      this.directories.add(parts.slice(0, i).join('/'));
-    }
-  }
-
-  /**
-   * Clear all data
-   */
-  clear(): void {
-    this.storage.clear();
-    this.directories.clear();
-    this.directories.add('');
-  }
-
-  /**
-   * Get memory usage statistics
-   */
-  getStats(): { keyCount: number; totalBytes: number } {
-    let totalBytes = 0;
-    for (const value of this.storage.values()) {
-      totalBytes += value.byteLength;
-    }
-    return {
-      keyCount: this.storage.size,
-      totalBytes,
-    };
-  }
-
-  /**
-   * Export all data as a serializable object
-   * Useful for debugging or saving state
-   */
-  export(): Record<string, ArrayBuffer> {
-    const result: Record<string, ArrayBuffer> = {};
-    for (const [key, value] of this.storage.entries()) {
-      result[key] = value.slice(0);
-    }
-    return result;
-  }
-
-  /**
-   * Import data from a serializable object
-   */
-  import(data: Record<string, ArrayBuffer>): void {
-    for (const [key, value] of Object.entries(data)) {
-      this.storage.set(key, value.slice(0));
-    }
-  }
-}

package/src/storage/OPFSBackend.ts

@@ -1,348 +0,0 @@
-/**
- * Origin Private File System (OPFS) Storage Backend
- *
- * High-performance browser storage using the File System Access API.
- * OPFS provides file-like semantics with significantly better performance
- * than IndexedDB for large binary data (up to 10x faster).
- *
- * Features:
- * - Auto-initializing (no manual init() required)
- * - High performance for large binary data
- *
- * Browser Support:
- * - Chrome 86+
- * - Safari 15.2+
- * - Firefox 111+
- * - Edge 86+
- *
- * Note: This module is designed for browser environments only.
- * It will not work in Node.js/Bun server environments.
- */
-
-import type { StorageBackend } from './StorageBackend';
-
-export class OPFSBackend implements StorageBackend {
-  readonly type = 'opfs';
-  private root: FileSystemDirectoryHandle | null = null;
-  private initialized: boolean = false;
-  private initPromise: Promise<void> | null = null;
-  private appendLocks: Map<string, Promise<void>> = new Map();
-
-  /**
-   * Initialize the OPFS backend (optional - auto-initializes on first operation)
-   * @deprecated No longer required - operations auto-initialize
-   */
-  async init(): Promise<void> {
-    return this.doInit();
-  }
-
-  private async doInit(): Promise<void> {
-    if (this.initialized) return;
-
-    if (typeof navigator === 'undefined' || !navigator.storage?.getDirectory) {
-      throw new Error('OPFS not available in this environment. Use MemoryBackend or IndexedDBBackend instead.');
-    }
-
-    this.root = await navigator.storage.getDirectory();
-    this.initialized = true;
-  }
-
-  /**
-   * Ensure backend is initialized (lazy init on first use).
-   * Safe to call concurrently — only runs initialization once.
-   */
-  private async ensureInitialized(): Promise<void> {
-    if (this.initialized) return;
-    if (!this.initPromise) {
-      this.initPromise = this.doInit().catch((err) => {
-        // Allow retry after transient initialization failures
-        this.initPromise = null;
-        throw err;
-      });
-    }
-    return this.initPromise;
-  }
-
-  private isNotFoundError(err: unknown): boolean {
-    return (
-      !!err &&
-      typeof err === 'object' &&
-      'name' in err &&
-      (err as any).name === 'NotFoundError'
-    );
-  }
-
-  private formatError(err: unknown): string {
-    if (err instanceof Error) {
-      return err.message;
-    }
-    return String(err);
-  }
-
-  private validateAndSplitPath(path: string, allowEmpty: boolean): string[] {
-    if (typeof path !== 'string') {
-      throw new Error('Path must be a string');
-    }
-    if (path.includes('\0')) {
-      throw new Error(`Invalid path '${path}': contains null byte`);
-    }
-    if (path.length === 0) {
-      if (allowEmpty) return [];
-      throw new Error('Invalid path: empty path is not allowed');
-    }
-
-    const parts: string[] = [];
-    for (const part of path.split('/')) {
-      if (part === '') continue;
-      if (part === '.' || part === '..') {
-        throw new Error(`Path traversal detected: '${path}' contains '${part}' segment`);
-      }
-      if (part.includes('\\')) {
-        throw new Error(`Invalid path '${path}': backslashes are not allowed`);
-      }
-      parts.push(part);
-    }
-
-    if (!allowEmpty && parts.length === 0) {
-      throw new Error(`Invalid path '${path}': no file name`);
-    }
-    return parts;
-  }
-
-  /**
-   * Get a file handle, creating parent directories as needed
-   */
-  private async getFileHandle(key: string, create: boolean = false): Promise<FileSystemFileHandle | null> {
-    await this.ensureInitialized();
-
-    const parts = this.validateAndSplitPath(key, false);
-    const fileName = parts.pop()!;
-
-    // Navigate/create directories
-    let currentDir = this.root!;
-    for (const part of parts) {
-      try {
-        currentDir = await currentDir.getDirectoryHandle(part, { create });
-      } catch (err) {
-        if (!create && this.isNotFoundError(err)) return null;
-        throw new Error(`Failed to access directory '${part}' for '${key}': ${this.formatError(err)}`);
-      }
-    }
-
-    // Get file handle
-    try {
-      return await currentDir.getFileHandle(fileName, { create });
-    } catch (err) {
-      if (!create && this.isNotFoundError(err)) return null;
-      throw new Error(`Failed to access file '${key}': ${this.formatError(err)}`);
-    }
-  }
-
-  /**
-   * Get a directory handle, creating if needed
-   */
-  private async getDirectoryHandle(path: string, create: boolean = false): Promise<FileSystemDirectoryHandle | null> {
-    await this.ensureInitialized();
-
-    const parts = this.validateAndSplitPath(path, true);
-
-    let currentDir = this.root!;
-    for (const part of parts) {
-      try {
-        currentDir = await currentDir.getDirectoryHandle(part, { create });
-      } catch (err) {
-        if (!create && this.isNotFoundError(err)) return null;
-        throw new Error(`Failed to access directory '${path}': ${this.formatError(err)}`);
-      }
-    }
-
-    return currentDir;
-  }
-
-  async read(key: string): Promise<ArrayBuffer | null> {
-    await this.ensureInitialized();
-
-    const handle = await this.getFileHandle(key, false);
-    if (!handle) return null;
-
-    try {
-      const file = await handle.getFile();
-      return file.arrayBuffer();
-    } catch (err) {
-      if (this.isNotFoundError(err)) return null;
-      throw new Error(`Failed to read file '${key}': ${this.formatError(err)}`);
-    }
-  }
-
-  async write(key: string, data: ArrayBuffer | Uint8Array): Promise<void> {
-    await this.ensureInitialized();
-
-    const handle = await this.getFileHandle(key, true);
-    if (!handle) {
-      throw new Error(`Failed to create file: ${key}`);
-    }
-
-    const writable = await handle.createWritable();
-    try {
-      // Convert to ArrayBuffer for FileSystemWriteChunkType compatibility
-      const writeData = data instanceof ArrayBuffer ? data : data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;
-      await writable.write(writeData);
-      await writable.close();
-    } catch (err) {
-      // Abort on error to discard the temp file — close() would commit partial data
-      try { await writable.abort(); } catch { /* abort best-effort */ }
-      throw err;
-    }
-  }
-
-  async append(key: string, data: ArrayBuffer | Uint8Array): Promise<void> {
-    // Serialize appends per-key to prevent TOCTOU race condition
-    // (concurrent appends reading the same file size would overwrite each other)
-    const prev = this.appendLocks.get(key) ?? Promise.resolve();
-    let resolve: () => void;
-    const lock = new Promise<void>(r => { resolve = r; });
-    this.appendLocks.set(key, lock);
-
-    try {
-      await prev;
-      await this.doAppend(key, data);
-    } finally {
-      resolve!();
-      if (this.appendLocks.get(key) === lock) {
-        this.appendLocks.delete(key);
-      }
-    }
-  }
-
-  private async doAppend(key: string, data: ArrayBuffer | Uint8Array): Promise<void> {
-    await this.ensureInitialized();
-
-    const handle = await this.getFileHandle(key, true);
-    if (!handle) {
-      throw new Error(`Failed to create file: ${key}`);
-    }
-
-    const appendData = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
-
-    // Get current file size to seek to end
-    let existingSize = 0;
-    try {
-      const file = await handle.getFile();
-      existingSize = file.size;
-    } catch {
-      existingSize = 0;
-    }
-
-    // Use keepExistingData: true for O(1) append (no full read required)
-    // Then seek to end and write only new data
-    const writable = await handle.createWritable({ keepExistingData: true });
-    try {
-      // Seek to end of file
-      await writable.seek(existingSize);
-      // Write only the new data - O(data.length) not O(existingSize + data.length)
-      // Convert to ArrayBuffer for FileSystemWriteChunkType compatibility
-      const writeData = appendData.buffer.slice(appendData.byteOffset, appendData.byteOffset + appendData.byteLength) as ArrayBuffer;
-      await writable.write(writeData);
-      await writable.close();
-    } catch (err) {
-      // Abort on error to discard the temp file — close() would commit partial/corrupt data
-      try { await writable.abort(); } catch { /* abort best-effort */ }
-      throw err;
-    }
-  }
-
-  async delete(key: string): Promise<void> {
-    await this.ensureInitialized();
-
-    const parts = this.validateAndSplitPath(key, false);
-    const fileName = parts.pop()!;
-
-    // Navigate to parent directory
-    let currentDir = this.root!;
-    for (const part of parts) {
-      try {
-        currentDir = await currentDir.getDirectoryHandle(part, { create: false });
-      } catch (err) {
-        if (this.isNotFoundError(err)) {
-          return; // Parent doesn't exist, nothing to delete
-        }
-        throw new Error(`Failed to access directory for '${key}': ${this.formatError(err)}`);
-      }
-    }
-
-    // Remove the file
-    try {
-      await currentDir.removeEntry(fileName);
-    } catch (err) {
-      if (this.isNotFoundError(err)) {
-        return; // Parent doesn't exist, nothing to delete
-      }
-      throw new Error(`Failed to delete '${key}': ${this.formatError(err)}`);
-    }
-  }
-
-  async exists(key: string): Promise<boolean> {
-    await this.ensureInitialized();
-
-    const handle = await this.getFileHandle(key, false);
-    return handle !== null;
-  }
-
-  async list(prefix?: string): Promise<string[]> {
-    await this.ensureInitialized();
-
-    const results: string[] = [];
-    const basePath = prefix ?? '';
-    if (basePath.length > 0) {
-      this.validateAndSplitPath(basePath, true);
-    }
-
-    const dir = basePath ? await this.getDirectoryHandle(basePath, false) : this.root!;
-    if (!dir) return results;
-
-    // Recursive list
-    const listDir = async (dirHandle: FileSystemDirectoryHandle, pathPrefix: string): Promise<void> => {
-      for await (const entry of (dirHandle as any).values()) {
-        const entryPath = pathPrefix ? `${pathPrefix}/${entry.name}` : entry.name;
-
-        if (entry.kind === 'file') {
-          results.push(entryPath);
-        } else if (entry.kind === 'directory') {
-          await listDir(entry, entryPath);
-        }
-      }
-    };
-
-    await listDir(dir, basePath);
-    return results;
-  }
-
-  async mkdir(path: string): Promise<void> {
-    await this.ensureInitialized();
-    this.validateAndSplitPath(path, true);
-    await this.getDirectoryHandle(path, true);
-  }
-
-  /**
-   * Clear all data in OPFS
-   */
-  async clear(): Promise<void> {
-    await this.ensureInitialized();
-
-    // Collect entry names first to avoid modifying directory during iteration
-    const names: string[] = [];
-    for await (const entry of (this.root as any).values()) {
-      names.push(entry.name);
-    }
-    for (const name of names) {
-      await this.root!.removeEntry(name, { recursive: true });
-    }
-  }
-
-  /**
-   * Check if OPFS is available in the current environment
-   */
-  static isAvailable(): boolean {
-    return typeof navigator !== 'undefined' && !!navigator.storage?.getDirectory;
-  }
-}

package/src/storage/StorageBackend.ts

@@ -1,74 +0,0 @@
-/**
- * Storage Backend Interface
- *
- * Provides a unified interface for persisting vector index data across different platforms:
- * - Bun/Node.js: File system storage via BunStorageBackend
- * - Browser: OPFS (Origin Private File System) or IndexedDB
- * - Testing: In-memory storage
- *
- * All operations are async to support both sync and async underlying storage.
- */
-
-export interface StorageBackend {
-  /**
-   * Read data from storage
-   * @param key Unique key/path for the data
-   * @returns ArrayBuffer of data or null if not found
-   */
-  read(key: string): Promise<ArrayBuffer | null>;
-
-  /**
-   * Write data to storage (overwrites existing)
-   * @param key Unique key/path for the data
-   * @param data Data to write
-   */
-  write(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
-
-  /**
-   * Append data to existing file (for WAL)
-   * @param key Unique key/path for the data
-   * @param data Data to append
-   */
-  append(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
-
-  /**
-   * Delete data from storage
-   * @param key Unique key/path to delete
-   */
-  delete(key: string): Promise<void>;
-
-  /**
-   * Check if key exists in storage
-   * @param key Unique key/path to check
-   */
-  exists(key: string): Promise<boolean>;
-
-  /**
-   * List all keys with given prefix
-   * @param prefix Optional prefix to filter keys
-   */
-  list(prefix?: string): Promise<string[]>;
-
-  /**
-   * Create a directory (for file-based backends)
-   * @param path Directory path to create
-   */
-  mkdir(path: string): Promise<void>;
-
-  /**
-   * Get storage type identifier
-   */
-  readonly type: string;
-}
-
-/**
- * Options for creating a storage backend
- */
-export interface StorageOptions {
-  /** Base path for file-based storage */
-  path?: string;
-  /** Database name for IndexedDB */
-  dbName?: string;
-  /** Store name for IndexedDB */
-  storeName?: string;
-}