@quereus/store 0.3.6 → 0.3.7

package/dist/src/common/kv-store.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Abstract key-value store interface.
+ * Implemented by LevelDBStore (Node.js) and IndexedDBStore (browser).
+ */
+/**
+ * Options for iterating over key-value pairs.
+ */
+export interface IterateOptions {
+    /** Start key (inclusive). If omitted, starts from beginning. */
+    gte?: Uint8Array;
+    /** Start key (exclusive). */
+    gt?: Uint8Array;
+    /** End key (inclusive). */
+    lte?: Uint8Array;
+    /** End key (exclusive). If omitted, iterates to end. */
+    lt?: Uint8Array;
+    /** Iterate in reverse order. */
+    reverse?: boolean;
+    /** Maximum number of entries to return. */
+    limit?: number;
+}
+/**
+ * A key-value pair from iteration.
+ */
+export interface KVEntry {
+    key: Uint8Array;
+    value: Uint8Array;
+}
+/**
+ * Batch operation types.
+ */
+export type BatchOp = {
+    type: 'put';
+    key: Uint8Array;
+    value: Uint8Array;
+} | {
+    type: 'delete';
+    key: Uint8Array;
+};
+/**
+ * Write batch for atomic operations.
+ */
+export interface WriteBatch {
+    /** Queue a put operation. */
+    put(key: Uint8Array, value: Uint8Array): void;
+    /** Queue a delete operation. */
+    delete(key: Uint8Array): void;
+    /** Execute all queued operations atomically. */
+    write(): Promise<void>;
+    /** Discard all queued operations. */
+    clear(): void;
+}
+/**
+ * Abstract key-value store interface.
+ * Provides sorted key-value storage with range iteration support.
+ */
+export interface KVStore {
+    /**
+     * Get a value by key.
+     * @returns The value, or undefined if not found.
+     */
+    get(key: Uint8Array): Promise<Uint8Array | undefined>;
+    /**
+     * Put a key-value pair.
+     */
+    put(key: Uint8Array, value: Uint8Array): Promise<void>;
+    /**
+     * Delete a key.
+     */
+    delete(key: Uint8Array): Promise<void>;
+    /**
+     * Check if a key exists.
+     */
+    has(key: Uint8Array): Promise<boolean>;
+    /**
+     * Iterate over key-value pairs in sorted order.
+     * Keys are compared lexicographically by bytes.
+     */
+    iterate(options?: IterateOptions): AsyncIterable<KVEntry>;
+    /**
+     * Create a write batch for atomic operations.
+     */
+    batch(): WriteBatch;
+    /**
+     * Close the store and release resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Get approximate number of keys in a range.
+     * Used for query planning cost estimation.
+     */
+    approximateCount(options?: IterateOptions): Promise<number>;
+}
+/**
+ * Factory function to open a KVStore.
+ */
+export type KVStoreFactory = (options: KVStoreOptions) => Promise<KVStore>;
+/**
+ * Options for opening a KVStore.
+ */
+export interface KVStoreOptions {
+    /** Storage path (LevelDB) or database name (IndexedDB). */
+    path: string;
+    /** Create if doesn't exist. Default: true. */
+    createIfMissing?: boolean;
+    /** Throw error if already exists. Default: false. */
+    errorIfExists?: boolean;
+}
+/**
+ * Provider interface for creating/getting KVStore instances.
+ *
+ * This abstraction allows different storage backends (LevelDB, IndexedDB,
+ * React Native AsyncStorage, etc.) to be used with the StoreModule.
+ *
+ * Implementations should manage store lifecycle and caching.
+ */
+export interface KVStoreProvider {
+    /**
+     * Get or create a KVStore for a table.
+     * @param schemaName - The schema name (e.g., 'main')
+     * @param tableName - The table name
+     * @param options - Additional options passed from CREATE TABLE
+     * @returns The KVStore instance
+     */
+    getStore(schemaName: string, tableName: string, options?: Record<string, unknown>): Promise<KVStore>;
+    /**
+     * Get or create a KVStore for catalog/DDL metadata.
+     * Some providers may use the same store as data, others may use a separate store.
+     * @returns The KVStore instance for catalog data
+     */
+    getCatalogStore(): Promise<KVStore>;
+    /**
+     * Close a specific store.
+     * @param schemaName - The schema name
+     * @param tableName - The table name
+     */
+    closeStore(schemaName: string, tableName: string): Promise<void>;
+    /**
+     * Close all stores managed by this provider.
+     */
+    closeAll(): Promise<void>;
+    /**
+     * Optional: Called when a store is first accessed to perform any setup.
+     * @param store - The store that was just opened
+     * @param schemaName - The schema name
+     * @param tableName - The table name
+     */
+    onStoreOpened?(store: KVStore, schemaName: string, tableName: string): void;
+}
+//# sourceMappingURL=kv-store.d.ts.map

package/dist/src/common/kv-store.d.ts.map

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

package/dist/src/common/kv-store.js

@@ -0,0 +1,6 @@
+/**
+ * Abstract key-value store interface.
+ * Implemented by LevelDBStore (Node.js) and IndexedDBStore (browser).
+ */
+export {};
+//# sourceMappingURL=kv-store.js.map

package/dist/src/common/kv-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-store.js","sourceRoot":"","sources":["../../../src/common/kv-store.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/common/memory-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * In-memory KVStore implementation.
+ *
+ * Useful for:
+ * - Testing without filesystem/IndexedDB dependencies
+ * - Schema seed generation at build time
+ * - Temporary storage that doesn't need persistence
+ *
+ * Keys are stored using hex encoding for correct lexicographic ordering.
+ */
+import type { KVStore, KVEntry, WriteBatch, IterateOptions } from './kv-store.js';
+/**
+ * In-memory implementation of KVStore.
+ * Uses a Map with hex-encoded keys for correct byte ordering.
+ */
+export declare class InMemoryKVStore implements KVStore {
+    private data;
+    private closed;
+    get(key: Uint8Array): Promise<Uint8Array | undefined>;
+    put(key: Uint8Array, value: Uint8Array): Promise<void>;
+    delete(key: Uint8Array): Promise<void>;
+    has(key: Uint8Array): Promise<boolean>;
+    iterate(options?: IterateOptions): AsyncIterable<KVEntry>;
+    batch(): WriteBatch;
+    close(): Promise<void>;
+    approximateCount(options?: IterateOptions): Promise<number>;
+    /**
+     * Clear all data without closing the store.
+     */
+    clear(): void;
+    /**
+     * Get the number of entries in the store.
+     */
+    get size(): number;
+    private checkOpen;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/src/common/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../../src/common/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAiBlF;;;GAGG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,IAAI,CAA6D;IACzE,OAAO,CAAC,MAAM,CAAS;IAEjB,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKrD,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAStD,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtC,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC,OAAO,CAAC;IAsChE,KAAK,IAAI,UAAU;IA2Bb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,gBAAgB,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAajE;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,CAAC,SAAS;CAKlB"}

package/dist/src/common/memory-store.js

@@ -0,0 +1,146 @@
+/**
+ * In-memory KVStore implementation.
+ *
+ * Useful for:
+ * - Testing without filesystem/IndexedDB dependencies
+ * - Schema seed generation at build time
+ * - Temporary storage that doesn't need persistence
+ *
+ * Keys are stored using hex encoding for correct lexicographic ordering.
+ */
+/**
+ * Convert Uint8Array to hex string for Map key storage.
+ * Hex encoding preserves lexicographic ordering.
+ */
+function keyToHex(key) {
+    return Array.from(key).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Compare two hex strings lexicographically.
+ */
+function compareHex(a, b) {
+    return a.localeCompare(b);
+}
+/**
+ * In-memory implementation of KVStore.
+ * Uses a Map with hex-encoded keys for correct byte ordering.
+ */
+export class InMemoryKVStore {
+    data = new Map();
+    closed = false;
+    async get(key) {
+        this.checkOpen();
+        return this.data.get(keyToHex(key))?.value;
+    }
+    async put(key, value) {
+        this.checkOpen();
+        // Store copies to prevent external mutation
+        this.data.set(keyToHex(key), {
+            key: new Uint8Array(key),
+            value: new Uint8Array(value),
+        });
+    }
+    async delete(key) {
+        this.checkOpen();
+        this.data.delete(keyToHex(key));
+    }
+    async has(key) {
+        this.checkOpen();
+        return this.data.has(keyToHex(key));
+    }
+    async *iterate(options) {
+        this.checkOpen();
+        // Sort entries by hex key for correct ordering
+        const entries = Array.from(this.data.entries())
+            .sort((a, b) => compareHex(a[0], b[0]));
+        // Apply reverse if requested
+        if (options?.reverse) {
+            entries.reverse();
+        }
+        // Calculate bounds
+        const gteHex = options?.gte ? keyToHex(options.gte) : undefined;
+        const gtHex = options?.gt ? keyToHex(options.gt) : undefined;
+        const lteHex = options?.lte ? keyToHex(options.lte) : undefined;
+        const ltHex = options?.lt ? keyToHex(options.lt) : undefined;
+        let count = 0;
+        const limit = options?.limit;
+        for (const [keyHex, { key, value }] of entries) {
+            // Check lower bounds
+            if (gteHex !== undefined && keyHex < gteHex)
+                continue;
+            if (gtHex !== undefined && keyHex <= gtHex)
+                continue;
+            // Check upper bounds
+            if (lteHex !== undefined && keyHex > lteHex)
+                break;
+            if (ltHex !== undefined && keyHex >= ltHex)
+                break;
+            // Check limit
+            if (limit !== undefined && count >= limit)
+                break;
+            yield { key, value };
+            count++;
+        }
+    }
+    batch() {
+        const ops = [];
+        const store = this;
+        return {
+            put(key, value) {
+                ops.push({ type: 'put', key: new Uint8Array(key), value: new Uint8Array(value) });
+            },
+            delete(key) {
+                ops.push({ type: 'delete', key: new Uint8Array(key) });
+            },
+            async write() {
+                for (const op of ops) {
+                    if (op.type === 'put') {
+                        await store.put(op.key, op.value);
+                    }
+                    else {
+                        await store.delete(op.key);
+                    }
+                }
+                ops.length = 0;
+            },
+            clear() {
+                ops.length = 0;
+            },
+        };
+    }
+    async close() {
+        this.closed = true;
+        this.data.clear();
+    }
+    async approximateCount(options) {
+        this.checkOpen();
+        if (!options) {
+            return this.data.size;
+        }
+        // Count entries in range
+        let count = 0;
+        for await (const _ of this.iterate(options)) {
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Clear all data without closing the store.
+     */
+    clear() {
+        this.checkOpen();
+        this.data.clear();
+    }
+    /**
+     * Get the number of entries in the store.
+     */
+    get size() {
+        return this.data.size;
+    }
+    checkOpen() {
+        if (this.closed) {
+            throw new Error('InMemoryKVStore is closed');
+        }
+    }
+}
+//# sourceMappingURL=memory-store.js.map

package/dist/src/common/memory-store.js.map

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

package/dist/src/common/serialization.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Row serialization for persistent storage.
+ *
+ * Uses extended JSON format that preserves SQL value types:
+ * - bigint: { "$bigint": "12345678901234567890" }
+ * - Uint8Array: { "$blob": "base64..." }
+ * - Other types: Native JSON representation
+ */
+import type { Row, SqlValue } from '@quereus/quereus';
+/**
+ * Serialize a row to a byte array for storage.
+ */
+export declare function serializeRow(row: Row): Uint8Array;
+/**
+ * Deserialize a byte array back to a row.
+ */
+export declare function deserializeRow(buffer: Uint8Array): Row;
+/**
+ * Serialize a single SQL value to a byte array.
+ */
+export declare function serializeValue(value: SqlValue): Uint8Array;
+/**
+ * Deserialize a byte array back to a SQL value.
+ */
+export declare function deserializeValue(buffer: Uint8Array): SqlValue;
+/**
+ * Table statistics stored in metadata.
+ */
+export interface TableStats {
+    rowCount: number;
+    updatedAt: number;
+}
+/**
+ * Serialize table statistics.
+ */
+export declare function serializeStats(stats: TableStats): Uint8Array;
+/**
+ * Deserialize table statistics.
+ */
+export declare function deserializeStats(buffer: Uint8Array): TableStats;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/src/common/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/common/serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAKtD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAGjD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,GAAG,CAGtD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CAG1D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,QAAQ,CAG7D;AA6ED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAE5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAE/D"}

package/dist/src/common/serialization.js

@@ -0,0 +1,111 @@
+/**
+ * Row serialization for persistent storage.
+ *
+ * Uses extended JSON format that preserves SQL value types:
+ * - bigint: { "$bigint": "12345678901234567890" }
+ * - Uint8Array: { "$blob": "base64..." }
+ * - Other types: Native JSON representation
+ */
+const BIGINT_MARKER = '$bigint';
+const BLOB_MARKER = '$blob';
+/**
+ * Serialize a row to a byte array for storage.
+ */
+export function serializeRow(row) {
+    const json = JSON.stringify(row, replacer);
+    return new TextEncoder().encode(json);
+}
+/**
+ * Deserialize a byte array back to a row.
+ */
+export function deserializeRow(buffer) {
+    const json = new TextDecoder().decode(buffer);
+    return JSON.parse(json, reviver);
+}
+/**
+ * Serialize a single SQL value to a byte array.
+ */
+export function serializeValue(value) {
+    const json = JSON.stringify(value, replacer);
+    return new TextEncoder().encode(json);
+}
+/**
+ * Deserialize a byte array back to a SQL value.
+ */
+export function deserializeValue(buffer) {
+    const json = new TextDecoder().decode(buffer);
+    return JSON.parse(json, reviver);
+}
+/**
+ * JSON replacer function for SQL values.
+ */
+function replacer(_key, value) {
+    if (typeof value === 'bigint') {
+        return { [BIGINT_MARKER]: value.toString() };
+    }
+    if (value instanceof Uint8Array) {
+        return { [BLOB_MARKER]: uint8ArrayToBase64(value) };
+    }
+    return value;
+}
+/**
+ * JSON reviver function for SQL values.
+ */
+function reviver(_key, value) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        if (BIGINT_MARKER in obj && typeof obj[BIGINT_MARKER] === 'string') {
+            return BigInt(obj[BIGINT_MARKER]);
+        }
+        if (BLOB_MARKER in obj && typeof obj[BLOB_MARKER] === 'string') {
+            return base64ToUint8Array(obj[BLOB_MARKER]);
+        }
+    }
+    return value;
+}
+/**
+ * Convert Uint8Array to base64 string.
+ * Works in both Node.js and browser environments.
+ */
+function uint8ArrayToBase64(bytes) {
+    // Use Buffer in Node.js for efficiency
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(bytes).toString('base64');
+    }
+    // Browser fallback
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Convert base64 string to Uint8Array.
+ * Works in both Node.js and browser environments.
+ */
+function base64ToUint8Array(base64) {
+    // Use Buffer in Node.js for efficiency
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(base64, 'base64'));
+    }
+    // Browser fallback
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Serialize table statistics.
+ */
+export function serializeStats(stats) {
+    return new TextEncoder().encode(JSON.stringify(stats));
+}
+/**
+ * Deserialize table statistics.
+ */
+export function deserializeStats(buffer) {
+    return JSON.parse(new TextDecoder().decode(buffer));
+}
+//# sourceMappingURL=serialization.js.map

package/dist/src/common/serialization.js.map

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

package/dist/src/common/store-connection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Generic VirtualTableConnection implementation for KVStore-backed tables.
+ *
+ * Delegates transaction operations to a shared TransactionCoordinator.
+ */
+import type { VirtualTableConnection } from '@quereus/quereus';
+import type { TransactionCoordinator } from './transaction.js';
+/**
+ * Connection to a KVStore-backed table.
+ * All connections share a TransactionCoordinator for multi-table atomicity.
+ */
+export declare class StoreConnection implements VirtualTableConnection {
+    readonly connectionId: string;
+    readonly tableName: string;
+    private coordinator;
+    constructor(tableName: string, coordinator: TransactionCoordinator);
+    /** Begin a transaction. */
+    begin(): void;
+    /** Commit the transaction. */
+    commit(): Promise<void>;
+    /** Rollback the transaction. */
+    rollback(): void;
+    /** Create a savepoint. */
+    createSavepoint(index: number): void;
+    /** Release a savepoint. */
+    releaseSavepoint(index: number): void;
+    /** Rollback to a savepoint. */
+    rollbackToSavepoint(index: number): void;
+    /** Disconnect (rolls back if in transaction). */
+    disconnect(): Promise<void>;
+    /** Get the coordinator for mutation operations. */
+    getCoordinator(): TransactionCoordinator;
+}
+//# sourceMappingURL=store-connection.d.ts.map

package/dist/src/common/store-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-connection.d.ts","sourceRoot":"","sources":["../../../src/common/store-connection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAI/D;;;GAGG;AACH,qBAAa,eAAgB,YAAW,sBAAsB;IAC5D,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,OAAO,CAAC,WAAW,CAAyB;gBAEhC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,sBAAsB;IAMlE,2BAA2B;IAC3B,KAAK,IAAI,IAAI;IAIb,8BAA8B;IACxB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,gCAAgC;IAChC,QAAQ,IAAI,IAAI;IAIhB,0BAA0B;IAC1B,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIpC,2BAA2B;IAC3B,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIrC,+BAA+B;IAC/B,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIxC,iDAAiD;IAC3C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,mDAAmD;IACnD,cAAc,IAAI,sBAAsB;CAGzC"}

package/dist/src/common/store-connection.js

@@ -0,0 +1,55 @@
+/**
+ * Generic VirtualTableConnection implementation for KVStore-backed tables.
+ *
+ * Delegates transaction operations to a shared TransactionCoordinator.
+ */
+let connectionCounter = 0;
+/**
+ * Connection to a KVStore-backed table.
+ * All connections share a TransactionCoordinator for multi-table atomicity.
+ */
+export class StoreConnection {
+    connectionId;
+    tableName;
+    coordinator;
+    constructor(tableName, coordinator) {
+        this.connectionId = `store-${tableName}-${++connectionCounter}`;
+        this.tableName = tableName;
+        this.coordinator = coordinator;
+    }
+    /** Begin a transaction. */
+    begin() {
+        this.coordinator.begin();
+    }
+    /** Commit the transaction. */
+    async commit() {
+        await this.coordinator.commit();
+    }
+    /** Rollback the transaction. */
+    rollback() {
+        this.coordinator.rollback();
+    }
+    /** Create a savepoint. */
+    createSavepoint(index) {
+        this.coordinator.createSavepoint(index);
+    }
+    /** Release a savepoint. */
+    releaseSavepoint(index) {
+        this.coordinator.releaseSavepoint(index);
+    }
+    /** Rollback to a savepoint. */
+    rollbackToSavepoint(index) {
+        this.coordinator.rollbackToSavepoint(index);
+    }
+    /** Disconnect (rolls back if in transaction). */
+    async disconnect() {
+        if (this.coordinator.isInTransaction()) {
+            this.coordinator.rollback();
+        }
+    }
+    /** Get the coordinator for mutation operations. */
+    getCoordinator() {
+        return this.coordinator;
+    }
+}
+//# sourceMappingURL=store-connection.js.map

package/dist/src/common/store-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-connection.js","sourceRoot":"","sources":["../../../src/common/store-connection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,IAAI,iBAAiB,GAAG,CAAC,CAAC;AAE1B;;;GAGG;AACH,MAAM,OAAO,eAAe;IACV,YAAY,CAAS;IACrB,SAAS,CAAS;IAC1B,WAAW,CAAyB;IAE5C,YAAY,SAAiB,EAAE,WAAmC;QAChE,IAAI,CAAC,YAAY,GAAG,SAAS,SAAS,IAAI,EAAE,iBAAiB,EAAE,CAAC;QAChE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED,2BAA2B;IAC3B,KAAK;QACH,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED,8BAA8B;IAC9B,KAAK,CAAC,MAAM;QACV,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;IAClC,CAAC;IAED,gCAAgC;IAChC,QAAQ;QACN,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;IAC9B,CAAC;IAED,0BAA0B;IAC1B,eAAe,CAAC,KAAa;QAC3B,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,2BAA2B;IAC3B,gBAAgB,CAAC,KAAa;QAC5B,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,+BAA+B;IAC/B,mBAAmB,CAAC,KAAa;QAC/B,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,UAAU;QACd,IAAI,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,EAAE,CAAC;YACvC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,mDAAmD;IACnD,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF"}