@powerhousedao/reactor 4.1.0-dev.12 → 4.1.0-dev.121

package/dist/src/cache/buffer/ring-buffer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * RingBuffer is a generic circular buffer implementation that stores a fixed number
+ * of items. When the buffer is full, new items overwrite the oldest items.
+ *
+ * This implementation maintains O(1) time complexity for push operations and provides
+ * items in chronological order (oldest to newest) via getAll().
+ *
+ * @template T - The type of items stored in the buffer
+ */
+export declare class RingBuffer<T> {
+    private buffer;
+    private head;
+    private size;
+    private capacity;
+    constructor(capacity: number);
+    /**
+     * Adds an item to the buffer. If the buffer is full, overwrites the oldest item.
+     *
+     * @param item - The item to add
+     */
+    push(item: T): void;
+    /**
+     * Returns all items in the buffer in chronological order (oldest to newest).
+     *
+     * @returns Array of items in insertion order
+     */
+    getAll(): T[];
+    /**
+     * Clears all items from the buffer.
+     */
+    clear(): void;
+    /**
+     * Gets the current number of items in the buffer.
+     */
+    get length(): number;
+}
+//# sourceMappingURL=ring-buffer.d.ts.map

package/dist/src/cache/buffer/ring-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../../../../src/cache/buffer/ring-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,EAAE,MAAM;IAQ5B;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAYnB;;;;OAIG;IACH,MAAM,IAAI,CAAC,EAAE;IAab;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;CACF"}

package/dist/src/cache/buffer/ring-buffer.js

@@ -0,0 +1,69 @@
+/**
+ * RingBuffer is a generic circular buffer implementation that stores a fixed number
+ * of items. When the buffer is full, new items overwrite the oldest items.
+ *
+ * This implementation maintains O(1) time complexity for push operations and provides
+ * items in chronological order (oldest to newest) via getAll().
+ *
+ * @template T - The type of items stored in the buffer
+ */
+export class RingBuffer {
+    buffer;
+    head = 0;
+    size = 0;
+    capacity;
+    constructor(capacity) {
+        if (capacity <= 0) {
+            throw new Error("Ring buffer capacity must be greater than 0");
+        }
+        this.capacity = capacity;
+        this.buffer = new Array(capacity);
+    }
+    /**
+     * Adds an item to the buffer. If the buffer is full, overwrites the oldest item.
+     *
+     * @param item - The item to add
+     */
+    push(item) {
+        const index = (this.head + this.size) % this.capacity;
+        if (this.size < this.capacity) {
+            this.buffer[index] = item;
+            this.size++;
+        }
+        else {
+            this.buffer[this.head] = item;
+            this.head = (this.head + 1) % this.capacity;
+        }
+    }
+    /**
+     * Returns all items in the buffer in chronological order (oldest to newest).
+     *
+     * @returns Array of items in insertion order
+     */
+    getAll() {
+        if (this.size === 0) {
+            return [];
+        }
+        const result = [];
+        for (let i = 0; i < this.size; i++) {
+            const index = (this.head + i) % this.capacity;
+            result.push(this.buffer[index]);
+        }
+        return result;
+    }
+    /**
+     * Clears all items from the buffer.
+     */
+    clear() {
+        this.buffer = new Array(this.capacity);
+        this.head = 0;
+        this.size = 0;
+    }
+    /**
+     * Gets the current number of items in the buffer.
+     */
+    get length() {
+        return this.size;
+    }
+}
+//# sourceMappingURL=ring-buffer.js.map

package/dist/src/cache/buffer/ring-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-buffer.js","sourceRoot":"","sources":["../../../../src/cache/buffer/ring-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,UAAU;IACb,MAAM,CAAM;IACZ,IAAI,GAAW,CAAC,CAAC;IACjB,IAAI,GAAW,CAAC,CAAC;IACjB,QAAQ,CAAS;IAEzB,YAAY,QAAgB;QAC1B,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,KAAK,CAAI,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,IAAO;QACV,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QAEtD,IAAI,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;YAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;YAC9B,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9C,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,MAAM,GAAQ,EAAE,CAAC;QACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC9C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,KAAK,CAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/src/cache/index.d.ts

@@ -0,0 +1,3 @@
+export type { IOperationIndex, IOperationIndexTxn, OperationIndexEntry, } from "./operation-index-types.js";
+export { KyselyOperationIndex } from "./kysely-operation-index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/src/cache/index.js

@@ -0,0 +1,2 @@
+export { KyselyOperationIndex } from "./kysely-operation-index.js";
+//# sourceMappingURL=index.js.map

package/dist/src/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/src/cache/kysely-operation-index.d.ts

@@ -0,0 +1,13 @@
+import type { Kysely } from "kysely";
+import type { PagedResults, PagingOptions, ViewFilter } from "../storage/interfaces.js";
+import type { Database } from "../storage/kysely/types.js";
+import type { IOperationIndex, IOperationIndexTxn, OperationIndexEntry } from "./operation-index-types.js";
+export declare class KyselyOperationIndex implements IOperationIndex {
+    private db;
+    constructor(db: Kysely<Database>);
+    start(): IOperationIndexTxn;
+    commit(txn: IOperationIndexTxn, signal?: AbortSignal): Promise<void>;
+    find(collectionId: string, cursor?: number, view?: ViewFilter, paging?: PagingOptions, signal?: AbortSignal): Promise<PagedResults<OperationIndexEntry>>;
+    private rowToOperationIndexEntry;
+}
+//# sourceMappingURL=kysely-operation-index.d.ts.map

package/dist/src/cache/kysely-operation-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely-operation-index.d.ts","sourceRoot":"","sources":["../../../src/cache/kysely-operation-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,UAAU,EACX,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAGV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AAsEpC,qBAAa,oBAAqB,YAAW,eAAe;IAC9C,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC;IAExC,KAAK,IAAI,kBAAkB;IAIrB,MAAM,CAAC,GAAG,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAyGpE,IAAI,CACR,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,UAAU,EACjB,MAAM,CAAC,EAAE,aAAa,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,CAAC,mBAAmB,CAAC,CAAC;IA4D7C,OAAO,CAAC,wBAAwB;CAiBjC"}

package/dist/src/cache/kysely-operation-index.js

@@ -0,0 +1,207 @@
+import { sql } from "kysely";
+class KyselyOperationIndexTxn {
+    collections = [];
+    collectionMemberships = [];
+    collectionRemovals = [];
+    operations = [];
+    createCollection(collectionId) {
+        this.collections.push(collectionId);
+    }
+    addToCollection(collectionId, documentId) {
+        const lastOpIndex = this.operations.length - 1;
+        if (lastOpIndex < 0) {
+            throw new Error("addToCollection must be called after write() - no operations in transaction");
+        }
+        this.collectionMemberships.push({
+            collectionId,
+            documentId,
+            operationIndex: lastOpIndex,
+        });
+    }
+    removeFromCollection(collectionId, documentId) {
+        const lastOpIndex = this.operations.length - 1;
+        if (lastOpIndex < 0) {
+            throw new Error("removeFromCollection must be called after write() - no operations in transaction");
+        }
+        this.collectionRemovals.push({
+            collectionId,
+            documentId,
+            operationIndex: lastOpIndex,
+        });
+    }
+    write(operations) {
+        this.operations.push(...operations);
+    }
+    getCollections() {
+        return this.collections;
+    }
+    getCollectionMemberships() {
+        return this.collectionMemberships;
+    }
+    getCollectionRemovals() {
+        return this.collectionRemovals;
+    }
+    getOperations() {
+        return this.operations;
+    }
+}
+export class KyselyOperationIndex {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    start() {
+        return new KyselyOperationIndexTxn();
+    }
+    async commit(txn, signal) {
+        if (signal?.aborted) {
+            throw new Error("Operation aborted");
+        }
+        const kyselyTxn = txn;
+        const collections = kyselyTxn.getCollections();
+        const memberships = kyselyTxn.getCollectionMemberships();
+        const removals = kyselyTxn.getCollectionRemovals();
+        const operations = kyselyTxn.getOperations();
+        await this.db.transaction().execute(async (trx) => {
+            if (collections.length > 0) {
+                const collectionRows = collections.map((collectionId) => ({
+                    documentId: collectionId,
+                    collectionId,
+                    joinedOrdinal: BigInt(0),
+                    leftOrdinal: null,
+                }));
+                await trx
+                    .insertInto("document_collections")
+                    .values(collectionRows)
+                    .onConflict((oc) => oc.doNothing())
+                    .execute();
+            }
+            let operationOrdinals = [];
+            if (operations.length > 0) {
+                const operationRows = operations.map((op) => {
+                    const timestamp = op.timestampUtcMs;
+                    let timestampMs;
+                    if (/^\d+$/.test(timestamp)) {
+                        timestampMs = Number(timestamp);
+                    }
+                    else {
+                        timestampMs = new Date(timestamp).getTime();
+                    }
+                    return {
+                        opId: op.id || "",
+                        documentId: op.documentId,
+                        documentType: op.documentType,
+                        scope: op.scope,
+                        branch: op.branch,
+                        timestampUtcMs: BigInt(timestampMs || 0),
+                        index: op.index,
+                        skip: op.skip,
+                        hash: op.hash,
+                        action: op.action,
+                    };
+                });
+                const insertedOps = await trx
+                    .insertInto("operation_index_operations")
+                    .values(operationRows)
+                    .returning("ordinal")
+                    .execute();
+                operationOrdinals = insertedOps.map((row) => row.ordinal);
+            }
+            if (memberships.length > 0) {
+                for (const m of memberships) {
+                    // this is guaranteed to be defined because we enforce in KyselyOperationIndexTxn
+                    const ordinal = operationOrdinals[m.operationIndex];
+                    await trx
+                        .insertInto("document_collections")
+                        .values({
+                        documentId: m.documentId,
+                        collectionId: m.collectionId,
+                        joinedOrdinal: BigInt(ordinal),
+                        leftOrdinal: null,
+                    })
+                        .onConflict((oc) => oc.columns(["documentId", "collectionId"]).doUpdateSet({
+                        joinedOrdinal: BigInt(ordinal),
+                        leftOrdinal: null,
+                    }))
+                        .execute();
+                }
+            }
+            if (removals.length > 0) {
+                for (const r of removals) {
+                    // this is guaranteed to be defined because we enforce in KyselyOperationIndexTxn
+                    const ordinal = operationOrdinals[r.operationIndex];
+                    await trx
+                        .updateTable("document_collections")
+                        .set({
+                        leftOrdinal: BigInt(ordinal),
+                    })
+                        .where("collectionId", "=", r.collectionId)
+                        .where("documentId", "=", r.documentId)
+                        .where("leftOrdinal", "is", null)
+                        .execute();
+                }
+            }
+        });
+    }
+    async find(collectionId, cursor, view, paging, signal) {
+        if (signal?.aborted) {
+            throw new Error("Operation aborted");
+        }
+        let query = this.db
+            .selectFrom("operation_index_operations as oi")
+            .innerJoin("document_collections as dc", "oi.documentId", "dc.documentId")
+            .selectAll("oi")
+            .select(["dc.documentId", "dc.collectionId"])
+            .where("dc.collectionId", "=", collectionId)
+            .whereRef("oi.ordinal", ">=", "dc.joinedOrdinal")
+            .where(sql `dc."leftOrdinal" IS NULL OR oi.ordinal < dc."leftOrdinal"`)
+            .orderBy("oi.ordinal", "asc");
+        if (cursor !== undefined) {
+            query = query.where("oi.ordinal", ">", cursor);
+        }
+        if (view?.branch) {
+            query = query.where("oi.branch", "=", view.branch);
+        }
+        if (view?.scopes && view.scopes.length > 0) {
+            query = query.where("oi.scope", "in", view.scopes);
+        }
+        if (paging?.cursor) {
+            const cursorOrdinal = Number.parseInt(paging.cursor, 10);
+            query = query.where("oi.ordinal", ">", cursorOrdinal);
+        }
+        if (paging?.limit) {
+            query = query.limit(paging.limit + 1);
+        }
+        const rows = await query.execute();
+        let hasMore = false;
+        let items = rows;
+        if (paging?.limit && rows.length > paging.limit) {
+            hasMore = true;
+            items = rows.slice(0, paging.limit);
+        }
+        const nextCursor = hasMore && items.length > 0
+            ? items[items.length - 1].ordinal.toString()
+            : undefined;
+        return {
+            items: items.map((row) => this.rowToOperationIndexEntry(row)),
+            nextCursor,
+            hasMore,
+        };
+    }
+    rowToOperationIndexEntry(row) {
+        return {
+            ordinal: row.ordinal,
+            documentId: row.documentId,
+            documentType: row.documentType,
+            branch: row.branch,
+            scope: row.scope,
+            index: row.index,
+            timestampUtcMs: row.timestampUtcMs.toString(),
+            hash: row.hash,
+            skip: row.skip,
+            action: row.action,
+            id: row.opId,
+        };
+    }
+}
+//# sourceMappingURL=kysely-operation-index.js.map

package/dist/src/cache/kysely-operation-index.js.map

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

package/dist/src/cache/kysely-write-cache.d.ts

@@ -0,0 +1,134 @@
+import type { PHDocument } from "document-model";
+import type { IDocumentModelRegistry } from "../registry/interfaces.js";
+import type { IKeyframeStore, IOperationStore } from "../storage/interfaces.js";
+import { RingBuffer } from "./buffer/ring-buffer.js";
+import type { CachedSnapshot, WriteCacheConfig } from "./write-cache-types.js";
+import type { IWriteCache } from "./write/interfaces.js";
+type DocumentStream = {
+    key: string;
+    ringBuffer: RingBuffer<CachedSnapshot>;
+};
+/**
+ * In-memory write cache with keyframe persistence for PHDocuments.
+ *
+ * Caches document snapshots in ring buffers with LRU eviction. On cache miss,
+ * rebuilds documents from nearest keyframe or full operation history.
+ *
+ * **Performance Characteristics:**
+ * - Cache hit: O(1) lookup in ring buffer
+ * - Cold miss: O(n) where n is total operation count, or O(k) where k is operations since keyframe
+ * - Warm miss: O(m) where m is operations since cached revision
+ * - Eviction: O(1) for LRU tracking and removal
+ *
+ * **Thread Safety:**
+ * Not thread-safe. Designed for single-threaded job executor environment.
+ * External synchronization required for concurrent access across multiple executors.
+ *
+ * **Example:**
+ * ```typescript
+ * const cache = new KyselyWriteCache(
+ *   keyframeStore,
+ *   operationStore,
+ *   registry,
+ *   { maxDocuments: 1000, ringBufferSize: 10, keyframeInterval: 10 }
+ * );
+ *
+ * await cache.startup();
+ *
+ * // Retrieve or rebuild document
+ * const doc = await cache.getState(docId, docType, scope, branch, revision);
+ *
+ * // Cache result after job execution
+ * cache.putState(docId, docType, scope, branch, newRevision, updatedDoc);
+ *
+ * await cache.shutdown();
+ * ```
+ */
+export declare class KyselyWriteCache implements IWriteCache {
+    private streams;
+    private lruTracker;
+    private keyframeStore;
+    private operationStore;
+    private registry;
+    private config;
+    constructor(keyframeStore: IKeyframeStore, operationStore: IOperationStore, registry: IDocumentModelRegistry, config: WriteCacheConfig);
+    /**
+     * Initializes the write cache.
+     * Currently a no-op as keyframe store lifecycle is managed externally.
+     */
+    startup(): Promise<void>;
+    /**
+     * Shuts down the write cache.
+     * Currently a no-op as keyframe store lifecycle is managed externally.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Retrieves document state at a specific revision from cache or rebuilds it.
+     *
+     * Cache hit path: Returns cached snapshot if available (O(1))
+     * Warm miss path: Rebuilds from cached base revision + incremental ops
+     * Cold miss path: Rebuilds from keyframe or from scratch using all operations
+     *
+     * @param documentId - The document identifier
+     * @param scope - The operation scope
+     * @param branch - The operation branch
+     * @param targetRevision - The target revision, or undefined for newest
+     * @param signal - Optional abort signal to cancel the operation
+     * @returns The document at the target revision
+     * @throws {Error} "Operation aborted" if signal is aborted
+     * @throws {ModuleNotFoundError} If document type not registered in registry
+     * @throws {Error} "Failed to rebuild document" if operation store fails
+     * @throws {Error} If reducer throws during operation application
+     * @throws {Error} If document serialization fails
+     */
+    getState(documentId: string, scope: string, branch: string, targetRevision?: number, signal?: AbortSignal): Promise<PHDocument>;
+    /**
+     * Stores a document snapshot in the cache at a specific revision.
+     *
+     * Stores the document reference as-is. Callers must avoid mutating cached
+     * snapshots if they need to preserve historical revisions.
+     * Updates LRU tracker and may evict least recently used stream if at capacity.
+     * Asynchronously persists keyframes at configured intervals (fire-and-forget).
+     *
+     * @param documentId - The document identifier
+     * @param scope - The operation scope
+     * @param branch - The operation branch
+     * @param revision - The revision number
+     * @param document - The document to cache
+     * @throws {Error} If document serialization fails
+     */
+    putState(documentId: string, scope: string, branch: string, revision: number, document: PHDocument): void;
+    /**
+     * Invalidates cached document streams.
+     *
+     * Supports three invalidation scopes:
+     * - Document-level: invalidate(documentId) - removes all streams for document
+     * - Scope-level: invalidate(documentId, scope) - removes all branches for scope
+     * - Stream-level: invalidate(documentId, scope, branch) - removes specific stream
+     *
+     * @param documentId - The document identifier
+     * @param scope - Optional scope to narrow invalidation
+     * @param branch - Optional branch to narrow invalidation (requires scope)
+     * @returns The number of streams evicted
+     */
+    invalidate(documentId: string, scope?: string, branch?: string): number;
+    /**
+     * Clears the entire cache, removing all cached document streams.
+     * Resets LRU tracking state. This operation always succeeds.
+     */
+    clear(): void;
+    /**
+     * Retrieves a specific stream for a document. Exposed on the implementation
+     * for testing, but not on the interface.
+     */
+    getStream(documentId: string, scope: string, branch: string): DocumentStream | undefined;
+    private findNearestKeyframe;
+    private coldMissRebuild;
+    private warmMissRebuild;
+    private findNearestOlderSnapshot;
+    private makeStreamKey;
+    private getOrCreateStream;
+    private isKeyframeRevision;
+}
+export {};
+//# sourceMappingURL=kysely-write-cache.d.ts.map

package/dist/src/cache/kysely-write-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely-write-cache.d.ts","sourceRoot":"","sources":["../../../src/cache/kysely-write-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAMvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,KAAK,cAAc,GAAG;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,MAAM,CAA6B;gBAGzC,aAAa,EAAE,cAAc,EAC7B,cAAc,EAAE,eAAe,EAC/B,QAAQ,EAAE,sBAAsB,EAChC,MAAM,EAAE,gBAAgB;IAc1B;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CACZ,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC;IAiEtB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,UAAU,GACnB,IAAI;IAuBP;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;IA+BvE;;;OAGG;IACH,KAAK,IAAI,IAAI;IAKb;;;OAGG;IACH,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,cAAc,GAAG,SAAS;YAKf,mBAAmB;YAoBnB,eAAe;YAmJf,eAAe;IA6D7B,OAAO,CAAC,wBAAwB;IAiBhC,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,kBAAkB;CAG3B"}