verso-db 0.1.4 → 0.2.0

package/dist/storage/MemoryBackend.js

@@ -0,0 +1,109 @@
+/**
+ * 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
+ */
+export class MemoryBackend {
+    type = 'memory';
+    storage = new Map();
+    directories = new Set();
+    constructor() {
+        this.directories.add(''); // Root directory always exists
+    }
+    async read(key) {
+        const data = this.storage.get(key);
+        if (!data)
+            return null;
+        // Return a copy to prevent mutation
+        return data.slice(0);
+    }
+    async write(key, data) {
+        // Store a copy to prevent external mutation
+        const buffer = data instanceof ArrayBuffer ? data : data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+        this.storage.set(key, buffer.slice(0));
+    }
+    async append(key, data) {
+        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));
+        }
+        else {
+            this.storage.set(key, appendData.buffer.slice(appendData.byteOffset, appendData.byteOffset + appendData.byteLength));
+        }
+    }
+    async delete(key) {
+        this.storage.delete(key);
+    }
+    async exists(key) {
+        return this.storage.has(key);
+    }
+    async list(prefix) {
+        const keys = [];
+        // 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) {
+        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() {
+        this.storage.clear();
+        this.directories.clear();
+        this.directories.add('');
+    }
+    /**
+     * Get memory usage statistics
+     */
+    getStats() {
+        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() {
+        const result = {};
+        for (const [key, value] of this.storage.entries()) {
+            result[key] = value.slice(0);
+        }
+        return result;
+    }
+    /**
+     * Import data from a serializable object
+     */
+    import(data) {
+        for (const [key, value] of Object.entries(data)) {
+            this.storage.set(key, value.slice(0));
+        }
+    }
+}
+//# sourceMappingURL=MemoryBackend.js.map

package/dist/storage/MemoryBackend.js.map

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

package/dist/storage/OPFSBackend.d.ts

@@ -23,15 +23,22 @@ export declare class OPFSBackend implements StorageBackend {
     readonly type = "opfs";
     private root;
     private initialized;
+    private initPromise;
+    private appendLocks;
     /**
      * Initialize the OPFS backend (optional - auto-initializes on first operation)
      * @deprecated No longer required - operations auto-initialize
      */
     init(): Promise<void>;
+    private doInit;
     /**
-     * Ensure backend is initialized (lazy init on first use)
+     * Ensure backend is initialized (lazy init on first use).
+     * Safe to call concurrently — only runs initialization once.
      */
     private ensureInitialized;
+    private isNotFoundError;
+    private formatError;
+    private validateAndSplitPath;
     /**
      * Get a file handle, creating parent directories as needed
      */
@@ -43,6 +50,7 @@ export declare class OPFSBackend implements StorageBackend {
     read(key: string): Promise<ArrayBuffer | null>;
     write(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
     append(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    private doAppend;
     delete(key: string): Promise<void>;
     exists(key: string): Promise<boolean>;
     list(prefix?: string): Promise<string[]>;

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

@@ -1 +1 @@
-{"version":3,"file":"OPFSBackend.d.ts","sourceRoot":"","sources":["../../src/storage/OPFSBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,qBAAa,WAAY,YAAW,cAAc;IAChD,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,IAAI,CAA0C;IACtD,OAAO,CAAC,WAAW,CAAkB;IAErC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;OAEG;YACW,iBAAiB;IAM/B;;OAEG;YACW,aAAa;IA0B3B;;OAEG;YACW,kBAAkB;IAkB1B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAc9C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBjE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAkClE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOrC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA0BxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,OAAO;CAG9B"}
+{"version":3,"file":"OPFSBackend.d.ts","sourceRoot":"","sources":["../../src/storage/OPFSBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD,qBAAa,WAAY,YAAW,cAAc;IAChD,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,IAAI,CAA0C;IACtD,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,WAAW,CAAyC;IAE5D;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAIb,MAAM;IAWpB;;;OAGG;YACW,iBAAiB;IAY/B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,oBAAoB;IA8B5B;;OAEG;YACW,aAAa;IA0B3B;;OAEG;YACW,kBAAkB;IAkB1B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAe9C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBjE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;YAmB1D,QAAQ;IAqChB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOrC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA6BxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,OAAO;CAG9B"}

package/dist/storage/OPFSBackend.js

@@ -0,0 +1,325 @@
+/**
+ * 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 { StorageError } from '../errors.js';
+export class OPFSBackend {
+    type = 'opfs';
+    root = null;
+    initialized = false;
+    initPromise = null;
+    appendLocks = new Map();
+    /**
+     * Initialize the OPFS backend (optional - auto-initializes on first operation)
+     * @deprecated No longer required - operations auto-initialize
+     */
+    async init() {
+        return this.doInit();
+    }
+    async doInit() {
+        if (this.initialized)
+            return;
+        if (typeof navigator === 'undefined' || !navigator.storage?.getDirectory) {
+            throw new StorageError('init', '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.
+     */
+    async ensureInitialized() {
+        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;
+    }
+    isNotFoundError(err) {
+        return (!!err &&
+            typeof err === 'object' &&
+            'name' in err &&
+            err.name === 'NotFoundError');
+    }
+    formatError(err) {
+        if (err instanceof Error) {
+            return err.message;
+        }
+        return String(err);
+    }
+    validateAndSplitPath(path, allowEmpty) {
+        if (typeof path !== 'string') {
+            throw new StorageError('validate', 'Path must be a string');
+        }
+        if (path.includes('\0')) {
+            throw new StorageError('validate', `Invalid path '${path}': contains null byte`);
+        }
+        if (path.length === 0) {
+            if (allowEmpty)
+                return [];
+            throw new StorageError('validate', 'Invalid path: empty path is not allowed');
+        }
+        const parts = [];
+        for (const part of path.split('/')) {
+            if (part === '')
+                continue;
+            if (part === '.' || part === '..') {
+                throw new StorageError('validate', `Path traversal detected: '${path}' contains '${part}' segment`);
+            }
+            if (part.includes('\\')) {
+                throw new StorageError('validate', `Invalid path '${path}': backslashes are not allowed`);
+            }
+            parts.push(part);
+        }
+        if (!allowEmpty && parts.length === 0) {
+            throw new StorageError('validate', `Invalid path '${path}': no file name`);
+        }
+        return parts;
+    }
+    /**
+     * Get a file handle, creating parent directories as needed
+     */
+    async getFileHandle(key, create = false) {
+        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 StorageError('read', `Failed to access directory '${part}' for '${key}': ${this.formatError(err)}`, key);
+            }
+        }
+        // Get file handle
+        try {
+            return await currentDir.getFileHandle(fileName, { create });
+        }
+        catch (err) {
+            if (!create && this.isNotFoundError(err))
+                return null;
+            throw new StorageError('read', `Failed to access file '${key}': ${this.formatError(err)}`, key);
+        }
+    }
+    /**
+     * Get a directory handle, creating if needed
+     */
+    async getDirectoryHandle(path, create = false) {
+        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 StorageError('list', `Failed to access directory '${path}': ${this.formatError(err)}`, path);
+            }
+        }
+        return currentDir;
+    }
+    async read(key) {
+        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 StorageError('read', `Failed to read file '${key}': ${this.formatError(err)}`, key);
+        }
+    }
+    async write(key, data) {
+        await this.ensureInitialized();
+        const handle = await this.getFileHandle(key, true);
+        if (!handle) {
+            throw new StorageError('write', `Failed to create file: ${key}`, 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);
+            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, data) {
+        // 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;
+        const lock = new Promise(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);
+            }
+        }
+    }
+    async doAppend(key, data) {
+        await this.ensureInitialized();
+        const handle = await this.getFileHandle(key, true);
+        if (!handle) {
+            throw new StorageError('write', `Failed to create file: ${key}`, 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);
+            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) {
+        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 StorageError('delete', `Failed to access directory for '${key}': ${this.formatError(err)}`, key);
+            }
+        }
+        // Remove the file
+        try {
+            await currentDir.removeEntry(fileName);
+        }
+        catch (err) {
+            if (this.isNotFoundError(err)) {
+                return; // Parent doesn't exist, nothing to delete
+            }
+            throw new StorageError('delete', `Failed to delete '${key}': ${this.formatError(err)}`, key);
+        }
+    }
+    async exists(key) {
+        await this.ensureInitialized();
+        const handle = await this.getFileHandle(key, false);
+        return handle !== null;
+    }
+    async list(prefix) {
+        await this.ensureInitialized();
+        const results = [];
+        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, pathPrefix) => {
+            for await (const entry of dirHandle.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) {
+        await this.ensureInitialized();
+        this.validateAndSplitPath(path, true);
+        await this.getDirectoryHandle(path, true);
+    }
+    /**
+     * Clear all data in OPFS
+     */
+    async clear() {
+        await this.ensureInitialized();
+        // Collect entry names first to avoid modifying directory during iteration
+        const names = [];
+        for await (const entry of this.root.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() {
+        return typeof navigator !== 'undefined' && !!navigator.storage?.getDirectory;
+    }
+}
+//# sourceMappingURL=OPFSBackend.js.map

package/dist/storage/OPFSBackend.js.map

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

package/dist/storage/StorageBackend.d.ts

@@ -2,7 +2,7 @@
  * Storage Backend Interface
  *
  * Provides a unified interface for persisting vector index data across different platforms:
- * - Bun/Node.js: File system storage with Bun.file APIs
+ * - Bun/Node.js: File system storage via BunStorageBackend
  * - Browser: OPFS (Origin Private File System) or IndexedDB
  * - Testing: In-memory storage
  *

package/dist/storage/StorageBackend.js

@@ -0,0 +1,12 @@
+/**
+ * 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 {};
+//# sourceMappingURL=StorageBackend.js.map

package/dist/storage/StorageBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageBackend.js","sourceRoot":"","sources":["../../src/storage/StorageBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/storage/WriteAheadLog.d.ts

@@ -10,6 +10,7 @@
  * - Crash recovery (replay log after restart)
  * - Reduced I/O for frequent updates
  */
+import type { StorageBackend } from './StorageBackend';
 export declare enum WALOperationType {
     ADD_VECTOR = 1,
     ADD_NEIGHBORS = 2,
@@ -25,23 +26,25 @@ export interface WALEntry {
  * WriteAheadLog - Append-only log for incremental index updates
  */
 export declare class WriteAheadLog {
-    private logPath;
+    private storage;
+    private logKey;
     private pendingEntries;
     private flushThreshold;
-    private lastFlushTime;
     private entryCount;
+    private flushPromise;
     /**
      * Create a new WAL
-     * @param basePath Base path for the index (WAL will be basePath.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(basePath: string, flushThreshold?: number);
+    constructor(storage: StorageBackend, logKey: string, flushThreshold?: number);
     /**
-     * Get the WAL file path
+     * Get the WAL storage key
      */
-    getPath(): string;
+    getKey(): string;
     /**
-     * Check if WAL file exists
+     * Check if WAL data exists
      */
     exists(): Promise<boolean>;
     /**
@@ -65,12 +68,13 @@ export declare class WriteAheadLog {
      */
     private serializeEntry;
     /**
-     * Flush pending entries to disk
-     * Uses O(1) append instead of O(n) read-modify-write
+     * Flush pending entries to storage
+     * Uses append for efficient O(1) writes
      */
     flush(): Promise<void>;
+    private flushEntries;
     /**
-     * Read all entries from the WAL file
+     * Read all entries from the WAL
      */
     readEntries(): Promise<WALEntry[]>;
     /**
@@ -104,7 +108,7 @@ export declare class WriteAheadLog {
      */
     clear(): Promise<void>;
     /**
-     * Delete the WAL file
+     * Delete the WAL data
      */
     delete(): Promise<void>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"WriteAheadLog.d.ts","sourceRoot":"","sources":["../../src/storage/WriteAheadLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,oBAAY,gBAAgB;IAC1B,UAAU,IAAI;IACd,aAAa,IAAI;IACjB,kBAAkB,IAAI;IACtB,UAAU,IAAI;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;OAIG;gBACS,QAAQ,EAAE,MAAM,EAAE,cAAc,GAAE,MAAY;IAK1D;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAKhC;;OAEG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnE;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BxF;;OAEG;IACG,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBnF;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC;;OAEG;IACH,OAAO,CAAC,cAAc;IAiBtB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgC5B;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IA4BxC;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE;IAQhF;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE;IAcrG;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAQ1F;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAS9B"}
+{"version":3,"file":"WriteAheadLog.d.ts","sourceRoot":"","sources":["../../src/storage/WriteAheadLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,oBAAY,gBAAgB;IAC1B,UAAU,IAAI;IACd,aAAa,IAAI;IACjB,kBAAkB,IAAI;IACtB,UAAU,IAAI;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,YAAY,CAA8B;IAElD;;;;;OAKG;gBACS,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAE,MAAY;IAMjF;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAIhC;;OAEG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnE;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BxF;;OAEG;IACG,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBnF;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBjC;;OAEG;IACH,OAAO,CAAC,cAAc;IAiBtB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YA2Bd,YAAY;IA4B1B;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAgDxC;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE;IAQhF;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE;IAcrG;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAQ1F;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAa9B"}