verso-db 0.1.1

package/src/storage/createStorageBackend.ts

@@ -0,0 +1,137 @@
+/**
+ * Storage Backend Factory
+ *
+ * Auto-detects the best storage backend for the current environment:
+ * - Bun/Node.js: BunStorageBackend (file system)
+ * - Modern browsers: OPFSBackend (Origin Private File System)
+ * - Fallback: MemoryBackend (in-memory)
+ */
+
+import type { StorageBackend, StorageOptions } from './StorageBackend';
+import { BunStorageBackend } from './BunStorageBackend';
+import { MemoryBackend } from './MemoryBackend';
+import { OPFSBackend } from './OPFSBackend';
+
+export type StorageType = 'auto' | 'bun' | 'opfs' | 'memory';
+
+export interface CreateStorageOptions extends StorageOptions {
+  /** Force a specific storage type */
+  type?: StorageType;
+}
+
+/**
+ * Detect the current runtime environment
+ */
+function detectEnvironment(): 'bun' | 'browser' | 'unknown' {
+  // Check for Bun
+  if (typeof Bun !== 'undefined') {
+    return 'bun';
+  }
+
+  // Check for browser
+  if (typeof window !== 'undefined' && typeof navigator !== 'undefined') {
+    return 'browser';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Create the optimal storage backend for the current environment
+ *
+ * @param options Configuration options
+ * @returns Initialized storage backend
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect best backend
+ * const storage = await createStorageBackend();
+ *
+ * // Force specific backend
+ * const bunStorage = await createStorageBackend({ type: 'bun', path: './data' });
+ * const memStorage = await createStorageBackend({ type: 'memory' });
+ * ```
+ */
+export async function createStorageBackend(options?: CreateStorageOptions): Promise<StorageBackend> {
+  const type = options?.type ?? 'auto';
+
+  // Force specific backend type
+  if (type === 'bun') {
+    const backend = new BunStorageBackend(options?.path ?? './vectordb_data');
+    await backend.init();
+    return backend;
+  }
+
+  if (type === 'opfs') {
+    if (!OPFSBackend.isAvailable()) {
+      throw new Error('OPFS not available in this environment');
+    }
+    const backend = new OPFSBackend();
+    await backend.init();
+    return backend;
+  }
+
+  if (type === 'memory') {
+    return new MemoryBackend();
+  }
+
+  // Auto-detect
+  const env = detectEnvironment();
+
+  if (env === 'bun') {
+    const backend = new BunStorageBackend(options?.path ?? './vectordb_data');
+    await backend.init();
+    return backend;
+  }
+
+  if (env === 'browser') {
+    // Try OPFS first (modern browsers)
+    if (OPFSBackend.isAvailable()) {
+      try {
+        const backend = new OPFSBackend();
+        await backend.init();
+        return backend;
+      } catch {
+        // Fall through to memory backend
+      }
+    }
+  }
+
+  // Fallback to memory backend
+  return new MemoryBackend();
+}
+
+/**
+ * Get the recommended storage type for the current environment
+ */
+export function getRecommendedStorageType(): StorageType {
+  const env = detectEnvironment();
+
+  if (env === 'bun') {
+    return 'bun';
+  }
+
+  if (env === 'browser' && OPFSBackend.isAvailable()) {
+    return 'opfs';
+  }
+
+  return 'memory';
+}
+
+/**
+ * Check if a specific storage type is available
+ */
+export function isStorageTypeAvailable(type: StorageType): boolean {
+  switch (type) {
+    case 'bun':
+      return typeof Bun !== 'undefined';
+    case 'opfs':
+      return OPFSBackend.isAvailable();
+    case 'memory':
+      return true;
+    case 'auto':
+      return true;
+    default:
+      return false;
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Storage Module
+ *
+ * Provides pluggable storage backends for vector index persistence.
+ * Supports multiple platforms:
+ * - Bun/Node.js: File system with Bun.file APIs
+ * - Modern browsers: OPFS (Origin Private File System)
+ * - Testing/fallback: In-memory storage
+ *
+ * @example
+ * ```typescript
+ * import { createStorageBackend, WriteAheadLog } from 'bun-vector-search/storage';
+ *
+ * // Auto-detect best storage for current environment
+ * const storage = await createStorageBackend();
+ *
+ * // Use WAL for incremental writes
+ * const wal = new WriteAheadLog('./index');
+ * await wal.appendVector(1, new Float32Array([1, 2, 3]));
+ * await wal.flush();
+ * ```
+ */
+
+// Storage backend interface and types
+export type { StorageBackend, StorageOptions } from './StorageBackend';
+
+// Storage backend implementations
+export { BunStorageBackend } from './BunStorageBackend';
+export { MemoryBackend } from './MemoryBackend';
+export { OPFSBackend } from './OPFSBackend';
+
+// Factory function and utilities
+export {
+  createStorageBackend,
+  getRecommendedStorageType,
+  isStorageTypeAvailable,
+  type StorageType,
+  type CreateStorageOptions,
+} from './createStorageBackend';
+
+// Write-ahead log for incremental updates
+export {
+  WriteAheadLog,
+  WALOperationType,
+  type WALEntry,
+} from './WriteAheadLog';
+
+// Batch write coalescing for reduced I/O
+export {
+  BatchWriter,
+  createBatchWriter,
+  type BatchWriterOptions,
+} from './BatchWriter';