verso-db 0.1.5 → 0.2.0

package/dist/storage/WriteAheadLog.js

@@ -0,0 +1,321 @@
+/**
+ * Write-Ahead Log (WAL) for Incremental Index Updates
+ *
+ * Provides durability and efficient incremental writes for HNSW index operations.
+ * Instead of rewriting the entire index on each update, operations are appended
+ * to a log file. The log can be compacted into a full snapshot periodically.
+ *
+ * Benefits:
+ * - Fast appends (no full serialization)
+ * - Crash recovery (replay log after restart)
+ * - Reduced I/O for frequent updates
+ */
+export var WALOperationType;
+(function (WALOperationType) {
+    WALOperationType[WALOperationType["ADD_VECTOR"] = 1] = "ADD_VECTOR";
+    WALOperationType[WALOperationType["ADD_NEIGHBORS"] = 2] = "ADD_NEIGHBORS";
+    WALOperationType[WALOperationType["UPDATE_ENTRY_POINT"] = 3] = "UPDATE_ENTRY_POINT";
+    WALOperationType[WALOperationType["CHECKPOINT"] = 4] = "CHECKPOINT";
+})(WALOperationType || (WALOperationType = {}));
+/**
+ * WriteAheadLog - Append-only log for incremental index updates
+ */
+export class WriteAheadLog {
+    storage;
+    logKey;
+    pendingEntries = [];
+    flushThreshold;
+    entryCount = 0;
+    flushPromise = null;
+    /**
+     * Create a new WAL
+     * @param storage StorageBackend for persistence
+     * @param logKey Storage key for the WAL data (e.g., "myindex.wal")
+     * @param flushThreshold Number of entries before auto-flush (default: 100)
+     */
+    constructor(storage, logKey, flushThreshold = 100) {
+        this.storage = storage;
+        this.logKey = logKey;
+        this.flushThreshold = flushThreshold;
+    }
+    /**
+     * Get the WAL storage key
+     */
+    getKey() {
+        return this.logKey;
+    }
+    /**
+     * Check if WAL data exists
+     */
+    async exists() {
+        return this.storage.exists(this.logKey);
+    }
+    /**
+     * Append a vector addition operation to the log
+     */
+    async appendVector(id, vector) {
+        // Format: [id (4 bytes)] [vector length (4 bytes)] [vector data]
+        const dataSize = 4 + 4 + vector.length * 4;
+        const buffer = new ArrayBuffer(dataSize);
+        const view = new DataView(buffer);
+        view.setUint32(0, id, true);
+        view.setUint32(4, vector.length, true);
+        const floatView = new Float32Array(buffer, 8);
+        floatView.set(vector);
+        const entry = {
+            type: WALOperationType.ADD_VECTOR,
+            timestamp: Date.now(),
+            data: buffer,
+        };
+        this.pendingEntries.push(entry);
+        this.entryCount++;
+        if (this.pendingEntries.length >= this.flushThreshold) {
+            await this.flush();
+        }
+    }
+    /**
+     * Append a neighbor update operation to the log
+     */
+    async appendNeighbors(nodeId, layer, neighbors) {
+        // Format: [nodeId (4)] [layer (4)] [neighborCount (4)] [neighbors...]
+        const dataSize = 4 + 4 + 4 + neighbors.length * 4;
+        const buffer = new ArrayBuffer(dataSize);
+        const view = new DataView(buffer);
+        view.setUint32(0, nodeId, true);
+        view.setUint32(4, layer, true);
+        view.setUint32(8, neighbors.length, true);
+        let offset = 12;
+        for (const neighbor of neighbors) {
+            view.setUint32(offset, neighbor, true);
+            offset += 4;
+        }
+        const entry = {
+            type: WALOperationType.ADD_NEIGHBORS,
+            timestamp: Date.now(),
+            data: buffer,
+        };
+        this.pendingEntries.push(entry);
+        this.entryCount++;
+        if (this.pendingEntries.length >= this.flushThreshold) {
+            await this.flush();
+        }
+    }
+    /**
+     * Append entry point update to the log
+     */
+    async appendEntryPointUpdate(entryPointId, maxLevel) {
+        const buffer = new ArrayBuffer(8);
+        const view = new DataView(buffer);
+        view.setInt32(0, entryPointId, true);
+        view.setInt32(4, maxLevel, true);
+        const entry = {
+            type: WALOperationType.UPDATE_ENTRY_POINT,
+            timestamp: Date.now(),
+            data: buffer,
+        };
+        this.pendingEntries.push(entry);
+        this.entryCount++;
+        if (this.pendingEntries.length >= this.flushThreshold) {
+            await this.flush();
+        }
+    }
+    /**
+     * Write a checkpoint marker to the log
+     */
+    async checkpoint() {
+        const buffer = new ArrayBuffer(8);
+        const view = new DataView(buffer);
+        view.setFloat64(0, Date.now(), true);
+        const entry = {
+            type: WALOperationType.CHECKPOINT,
+            timestamp: Date.now(),
+            data: buffer,
+        };
+        this.pendingEntries.push(entry);
+        this.entryCount++;
+        await this.flush();
+    }
+    /**
+     * Serialize a WAL entry to bytes
+     */
+    serializeEntry(entry) {
+        // Format: [type (1)] [timestamp (8)] [dataLength (4)] [data...]
+        const headerSize = 1 + 8 + 4;
+        const totalSize = headerSize + entry.data.byteLength;
+        const buffer = new ArrayBuffer(totalSize);
+        const view = new DataView(buffer);
+        view.setUint8(0, entry.type);
+        view.setFloat64(1, entry.timestamp, true);
+        view.setUint32(9, entry.data.byteLength, true);
+        const dataView = new Uint8Array(buffer, headerSize);
+        dataView.set(new Uint8Array(entry.data));
+        return new Uint8Array(buffer);
+    }
+    /**
+     * Flush pending entries to storage
+     * Uses append for efficient O(1) writes
+     */
+    async flush() {
+        while (true) {
+            if (this.flushPromise) {
+                await this.flushPromise;
+            }
+            if (this.pendingEntries.length === 0) {
+                return;
+            }
+            // Capture and clear atomically before async work to avoid losing
+            // entries added by concurrent appendVector() calls during the await.
+            const toFlush = this.pendingEntries;
+            this.pendingEntries = [];
+            const currentFlush = this.flushEntries(toFlush);
+            this.flushPromise = currentFlush;
+            try {
+                await currentFlush;
+            }
+            finally {
+                if (this.flushPromise === currentFlush) {
+                    this.flushPromise = null;
+                }
+            }
+        }
+    }
+    async flushEntries(toFlush) {
+        // Serialize captured entries
+        const serializedEntries = toFlush.map(e => this.serializeEntry(e));
+        // Calculate total size
+        let totalSize = 0;
+        for (const entry of serializedEntries) {
+            totalSize += entry.length;
+        }
+        // Combine into single buffer
+        const combined = new Uint8Array(totalSize);
+        let offset = 0;
+        for (const entry of serializedEntries) {
+            combined.set(entry, offset);
+            offset += entry.length;
+        }
+        // Append to storage
+        try {
+            await this.storage.append(this.logKey, combined);
+        }
+        catch (err) {
+            // Restore entries on failure so they aren't lost
+            this.pendingEntries = [...toFlush, ...this.pendingEntries];
+            throw err;
+        }
+    }
+    /**
+     * Read all entries from the WAL
+     */
+    async readEntries() {
+        const data = await this.storage.read(this.logKey);
+        if (!data || data.byteLength === 0) {
+            return [];
+        }
+        const buffer = data;
+        const view = new DataView(buffer);
+        const entries = [];
+        const headerSize = 13; // 1 (type) + 8 (timestamp) + 4 (dataLength)
+        let offset = 0;
+        while (offset < buffer.byteLength) {
+            // Check we can read the header
+            if (offset + headerSize > buffer.byteLength) {
+                console.warn(`WAL: truncated entry header at offset ${offset}, stopping replay`);
+                break;
+            }
+            // Read header
+            const type = view.getUint8(offset);
+            const timestamp = view.getFloat64(offset + 1, true);
+            const dataLength = view.getUint32(offset + 9, true);
+            // Validate data length
+            if (dataLength > buffer.byteLength - offset - headerSize) {
+                console.warn(`WAL: truncated entry data at offset ${offset} (expected ${dataLength} bytes, only ${buffer.byteLength - offset - headerSize} available), stopping replay`);
+                break;
+            }
+            // Validate operation type
+            if (type < 1 || type > 4) {
+                console.warn(`WAL: unknown operation type ${type} at offset ${offset}, stopping replay`);
+                break;
+            }
+            // Read data
+            const entryData = buffer.slice(offset + headerSize, offset + headerSize + dataLength);
+            entries.push({ type, timestamp, data: entryData });
+            offset += headerSize + dataLength;
+        }
+        this.entryCount = entries.length + this.pendingEntries.length;
+        return entries;
+    }
+    /**
+     * Parse a vector addition entry
+     */
+    static parseVectorEntry(data) {
+        const view = new DataView(data);
+        const id = view.getUint32(0, true);
+        const vectorLength = view.getUint32(4, true);
+        const vector = new Float32Array(data, 8, vectorLength);
+        return { id, vector };
+    }
+    /**
+     * Parse a neighbor update entry
+     */
+    static parseNeighborsEntry(data) {
+        const view = new DataView(data);
+        const nodeId = view.getUint32(0, true);
+        const layer = view.getUint32(4, true);
+        const neighborCount = view.getUint32(8, true);
+        const neighbors = [];
+        for (let i = 0; i < neighborCount; i++) {
+            neighbors.push(view.getUint32(12 + i * 4, true));
+        }
+        return { nodeId, layer, neighbors };
+    }
+    /**
+     * Parse an entry point update entry
+     */
+    static parseEntryPointEntry(data) {
+        const view = new DataView(data);
+        return {
+            entryPointId: view.getInt32(0, true),
+            maxLevel: view.getInt32(4, true),
+        };
+    }
+    /**
+     * Get entry count since last compact
+     */
+    getEntryCount() {
+        return this.entryCount;
+    }
+    /**
+     * Clear the WAL (after successful compaction)
+     */
+    async clear() {
+        if (this.flushPromise) {
+            await this.flushPromise.catch(() => { });
+        }
+        // Clear in-memory state first to prevent flush() from writing entries
+        // after we truncate the on-disk WAL.
+        this.pendingEntries = [];
+        this.entryCount = 0;
+        if (await this.storage.exists(this.logKey)) {
+            await this.storage.write(this.logKey, new Uint8Array(0));
+        }
+    }
+    /**
+     * Delete the WAL data
+     */
+    async delete() {
+        if (this.flushPromise) {
+            await this.flushPromise.catch(() => { });
+        }
+        // Clear in-memory state first to prevent race with concurrent appends
+        this.pendingEntries = [];
+        this.entryCount = 0;
+        try {
+            await this.storage.delete(this.logKey);
+        }
+        catch {
+            // Key may not exist
+        }
+    }
+}
+//# sourceMappingURL=WriteAheadLog.js.map

package/dist/storage/WriteAheadLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WriteAheadLog.js","sourceRoot":"","sources":["../../src/storage/WriteAheadLog.ts"],"names":[],"mappings":"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"}

package/dist/storage/createStorageBackend.d.ts

@@ -12,6 +12,10 @@ export interface CreateStorageOptions extends StorageOptions {
     /** Force a specific storage type */
     type?: StorageType;
 }
+/**
+ * Detect the current runtime environment
+ */
+export declare function detectEnvironment(): 'bun' | 'browser' | 'node' | 'unknown';
 /**
  * Create the optimal storage backend for the current environment
  *

package/dist/storage/createStorageBackend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createStorageBackend.d.ts","sourceRoot":"","sources":["../../src/storage/createStorageBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAKvE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7D,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,oCAAoC;IACpC,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAmBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CA+ClG;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,WAAW,CAYvD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAajE"}
+{"version":3,"file":"createStorageBackend.d.ts","sourceRoot":"","sources":["../../src/storage/createStorageBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAMvE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7D,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,oCAAoC;IACpC,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAiB1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CA+ClG;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,WAAW,CAYvD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAajE"}

package/dist/storage/createStorageBackend.js

@@ -0,0 +1,119 @@
+/**
+ * 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 { BunStorageBackend } from './BunStorageBackend.js';
+import { MemoryBackend } from './MemoryBackend.js';
+import { OPFSBackend } from './OPFSBackend.js';
+import { StorageError } from '../errors.js';
+/**
+ * Detect the current runtime environment
+ */
+export function detectEnvironment() {
+    // Check for Bun
+    if (typeof Bun !== 'undefined') {
+        return 'bun';
+    }
+    // Check for browser
+    if (typeof window !== 'undefined' && typeof navigator !== 'undefined') {
+        return 'browser';
+    }
+    // Check for Node.js
+    if (typeof process !== 'undefined' && !!process.versions?.node) {
+        return 'node';
+    }
+    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) {
+    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 StorageError('init', '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' || env === 'node') {
+        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() {
+    const env = detectEnvironment();
+    if (env === 'bun' || env === 'node') {
+        return 'bun';
+    }
+    if (env === 'browser' && OPFSBackend.isAvailable()) {
+        return 'opfs';
+    }
+    return 'memory';
+}
+/**
+ * Check if a specific storage type is available
+ */
+export function isStorageTypeAvailable(type) {
+    switch (type) {
+        case 'bun':
+            return typeof Bun !== 'undefined' || (typeof process !== 'undefined' && !!process.versions?.node);
+        case 'opfs':
+            return OPFSBackend.isAvailable();
+        case 'memory':
+            return true;
+        case 'auto':
+            return true;
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=createStorageBackend.js.map

package/dist/storage/createStorageBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStorageBackend.js","sourceRoot":"","sources":["../../src/storage/createStorageBackend.ts"],"names":[],"mappings":"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"}

package/{src/storage/index.ts → dist/storage/index.js}

@@ -20,34 +20,14 @@
  * 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';
-
+export { BunStorageBackend } from './BunStorageBackend.js';
+export { MemoryBackend } from './MemoryBackend.js';
+export { OPFSBackend } from './OPFSBackend.js';
 // Factory function and utilities
-export {
-  createStorageBackend,
-  getRecommendedStorageType,
-  isStorageTypeAvailable,
-  type StorageType,
-  type CreateStorageOptions,
-} from './createStorageBackend';
-
+export { createStorageBackend, getRecommendedStorageType, isStorageTypeAvailable, } from './createStorageBackend.js';
 // Write-ahead log for incremental updates
-export {
-  WriteAheadLog,
-  WALOperationType,
-  type WALEntry,
-} from './WriteAheadLog';
-
+export { WriteAheadLog, WALOperationType, } from './WriteAheadLog.js';
 // Batch write coalescing for reduced I/O
-export {
-  BatchWriter,
-  createBatchWriter,
-  type BatchWriterOptions,
-} from './BatchWriter';
+export { BatchWriter, createBatchWriter, } from './BatchWriter.js';
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,kCAAkC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,iCAAiC;AACjC,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,sBAAsB,GAGvB,MAAM,wBAAwB,CAAC;AAEhC,0CAA0C;AAC1C,OAAO,EACL,aAAa,EACb,gBAAgB,GAEjB,MAAM,iBAAiB,CAAC;AAEzB,yCAAyC;AACzC,OAAO,EACL,WAAW,EACX,iBAAiB,GAElB,MAAM,eAAe,CAAC"}

package/dist/storage/nodeFsRuntime.d.ts

@@ -0,0 +1,14 @@
+export declare function resolveBasePath(basePath: string): string;
+export declare function resolveStoragePath(basePath: string, key: string): string;
+export declare function dirname(fullPath: string): string;
+export declare function ensureDir(dir: string): Promise<void>;
+export declare function read(fullPath: string): Promise<ArrayBuffer | null>;
+export declare function writeAtomic(fullPath: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+export declare function append(fullPath: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+export declare function deleteFile(fullPath: string): Promise<void>;
+export declare function exists(fullPath: string): Promise<boolean>;
+export declare function list(basePath: string, searchPath: string): Promise<string[]>;
+export declare function clear(basePath: string): Promise<string>;
+export declare function size(fullPath: string): Promise<number>;
+export declare function stream(fullPath: string): ReadableStream<Uint8Array>;
+//# sourceMappingURL=nodeFsRuntime.d.ts.map

package/dist/storage/nodeFsRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeFsRuntime.d.ts","sourceRoot":"","sources":["../../src/storage/nodeFsRuntime.ts"],"names":[],"mappings":"AAMA,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOxE;AAED,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,wBAAsB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAUxE;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAIjG;AAED,wBAAsB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5F;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhE;AAED,wBAAsB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU/D;AAED,wBAAsB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAelF;AAED,wBAAsB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK7D;AAED,wBAAsB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAU5D;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAEnE"}

package/dist/storage/nodeFsRuntime.js

@@ -0,0 +1,105 @@
+import { mkdir, readdir, unlink, rm, appendFile, rename, readFile, writeFile, stat } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import * as path from 'node:path';
+import { Readable } from 'node:stream';
+import { StorageError } from '../errors.js';
+export function resolveBasePath(basePath) {
+    return path.resolve(basePath);
+}
+export function resolveStoragePath(basePath, key) {
+    const fullPath = path.resolve(basePath, key);
+    const resolvedBase = resolveBasePath(basePath);
+    if (!fullPath.startsWith(resolvedBase + path.sep) && fullPath !== resolvedBase) {
+        throw new StorageError('validate', `Path traversal detected: key '${key}' resolves outside storage directory`);
+    }
+    return fullPath;
+}
+export function dirname(fullPath) {
+    return path.dirname(fullPath);
+}
+export async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+export async function read(fullPath) {
+    try {
+        const data = await readFile(fullPath);
+        return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
+}
+export async function writeAtomic(fullPath, data) {
+    const tmpPath = fullPath + '.tmp';
+    await writeFile(tmpPath, data instanceof ArrayBuffer ? new Uint8Array(data) : data);
+    await rename(tmpPath, fullPath);
+}
+export async function append(fullPath, data) {
+    const appendData = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+    await appendFile(fullPath, appendData);
+}
+export async function deleteFile(fullPath) {
+    try {
+        await unlink(fullPath);
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+}
+export async function exists(fullPath) {
+    try {
+        await stat(fullPath);
+        return true;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return false;
+        }
+        throw err;
+    }
+}
+export async function list(basePath, searchPath) {
+    try {
+        const entries = await readdir(searchPath, { recursive: true, withFileTypes: true });
+        const resolvedBase = resolveBasePath(basePath);
+        const results = [];
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const entryDir = entry.parentPath ?? entry.path ?? searchPath;
+            const fullPath = path.join(entryDir, entry.name);
+            results.push(path.relative(resolvedBase, fullPath));
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+export async function clear(basePath) {
+    const resolvedBase = resolveBasePath(basePath);
+    await rm(resolvedBase, { recursive: true, force: true }).catch(() => { });
+    await mkdir(resolvedBase, { recursive: true }).catch(() => { });
+    return resolvedBase;
+}
+export async function size(fullPath) {
+    try {
+        const stats = await stat(fullPath);
+        return stats.size;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return 0;
+        }
+        throw err;
+    }
+}
+export function stream(fullPath) {
+    return Readable.toWeb(createReadStream(fullPath));
+}
+//# sourceMappingURL=nodeFsRuntime.js.map

package/dist/storage/nodeFsRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeFsRuntime.js","sourceRoot":"","sources":["../../src/storage/nodeFsRuntime.ts"],"names":[],"mappings":"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"}