@framers/sql-storage-adapter 0.6.16 → 0.7.0

package/dist/features/kv/idb.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview The part of IndexedDB the key-value store calls, typed structurally: the module compiles without the DOM
+ * library, and a page's IndexedDB satisfies these shapes.
+ * Moved unchanged from @framers/agentos src/core/storage/browser/idb.ts.
+ * @module sql-storage-adapter/kv/idb
+ */
+/** A request's outcome and its two events. */
+export interface IdbRequestLike<T> {
+    /** What the request answered, once it is done. */
+    readonly result: T;
+    /** Why the request failed, once it is done; null when it did not. */
+    readonly error: unknown;
+    /** Called when the request has succeeded. */
+    onsuccess: (() => void) | null;
+    /** Called when the request has failed. */
+    onerror: (() => void) | null;
+}
+/** A key range; only made and passed on. */
+export type IdbKeyRangeLike = object;
+/** The object store's calls the store makes. */
+export interface IdbObjectStoreLike {
+    /** Reads the value under a key. */
+    get(key: string): IdbRequestLike<unknown>;
+    /** Writes a value under a key, in place of what was there. */
+    put(value: unknown, key: string): IdbRequestLike<unknown>;
+    /** Removes one key, or every key of a range. */
+    delete(key: string | IdbKeyRangeLike): IdbRequestLike<unknown>;
+    /** Removes every key. */
+    clear(): IdbRequestLike<unknown>;
+    /** Lists the keys of a range, or every key. */
+    getAllKeys(range?: IdbKeyRangeLike): IdbRequestLike<unknown[]>;
+}
+/** A transaction and its three events. */
+export interface IdbTransactionLike {
+    /** Why the transaction was aborted; null until it is, and after a plain abort. */
+    readonly error: unknown;
+    /** One of the object stores the transaction was opened over. */
+    objectStore(name: string): IdbObjectStoreLike;
+    /** Called when everything the transaction did is kept. */
+    oncomplete: (() => void) | null;
+    /** Called when one of the transaction's requests has failed, before the transaction is aborted for it. */
+    onerror: (() => void) | null;
+    /** Called when the transaction is aborted and nothing it did is kept. */
+    onabort: (() => void) | null;
+}
+/** An open database. */
+export interface IdbDatabaseLike {
+    /** The names of the database's object stores. */
+    readonly objectStoreNames: {
+        contains(name: string): boolean;
+    };
+    /** Makes an object store with out-of-line keys; only inside an upgrade. */
+    createObjectStore(name: string): unknown;
+    /** Opens a transaction over one object store. */
+    transaction(storeName: string, mode: 'readonly' | 'readwrite'): IdbTransactionLike;
+    /** Closes the connection once its transactions are done. */
+    close(): void;
+}
+/** The request `open` answers. */
+export interface IdbOpenRequestLike extends IdbRequestLike<IdbDatabaseLike> {
+    /** The upgrade's transaction while `onupgradeneeded` runs; null outside it. */
+    readonly transaction: {
+        abort(): void;
+    } | null;
+    /** Called when the database is new or older than the version asked for, inside the upgrade. */
+    onupgradeneeded: (() => void) | null;
+    /** Called when an upgrade waits for another connection to close. */
+    onblocked: (() => void) | null;
+}
+/** The page's `indexedDB` and `IDBKeyRange`, or an error when the page has none. */
+export declare function idb(): {
+    factory: {
+        open(name: string, version?: number): IdbOpenRequestLike;
+    };
+    keyRange: {
+        bound(lower: string, upper: string): IdbKeyRangeLike;
+    };
+};
+//# sourceMappingURL=idb.d.ts.map

package/dist/features/kv/idb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idb.d.ts","sourceRoot":"","sources":["../../../src/features/kv/idb.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/B,0CAA0C;IAC1C,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9B;AAED,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC;AAErC,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAC1D,gDAAgD;IAChD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAC/D,yBAAyB;IACzB,KAAK,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IACjC,+CAA+C;IAC/C,UAAU,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC;CAChE;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gEAAgE;IAChE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAC9C,0DAA0D;IAC1D,UAAU,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IAChC,0GAA0G;IAC1G,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,yEAAyE;IACzE,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9B;AAED,wBAAwB;AACxB,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,gBAAgB,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC/D,2EAA2E;IAC3E,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,iDAAiD;IACjD,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,kBAAkB,CAAC;IACnF,4DAA4D;IAC5D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,kCAAkC;AAClC,MAAM,WAAW,kBAAmB,SAAQ,cAAc,CAAC,eAAe,CAAC;IACzE,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE;QAAE,KAAK,IAAI,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/C,+FAA+F;IAC/F,eAAe,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IACrC,oEAAoE;IACpE,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;CAChC;AAED,oFAAoF;AACpF,wBAAgB,GAAG,IAAI;IAAE,OAAO,EAAE;QAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAAA;KAAE,CAAC;IAAC,QAAQ,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAAA;KAAE,CAAA;CAAE,CAOnK"}

package/dist/features/kv/idb.js

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview The part of IndexedDB the key-value store calls, typed structurally: the module compiles without the DOM
+ * library, and a page's IndexedDB satisfies these shapes.
+ * Moved unchanged from @framers/agentos src/core/storage/browser/idb.ts.
+ * @module sql-storage-adapter/kv/idb
+ */
+/** The page's `indexedDB` and `IDBKeyRange`, or an error when the page has none. */
+export function idb() {
+    const scope = globalThis;
+    if (!scope.indexedDB || !scope.IDBKeyRange)
+        throw new Error('IndexedDB is not available here.');
+    return { factory: scope.indexedDB, keyRange: scope.IDBKeyRange };
+}
+//# sourceMappingURL=idb.js.map

package/dist/features/kv/idb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idb.js","sourceRoot":"","sources":["../../../src/features/kv/idb.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmEH,oFAAoF;AACpF,MAAM,UAAU,GAAG;IACjB,MAAM,KAAK,GAAG,UAGb,CAAC;IACF,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAChG,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;AACnE,CAAC"}

package/dist/features/kv/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview The key-value module, `@framers/sql-storage-adapter/kv`: one `KeyValueStore` contract and its
+ * stores. `openIndexedDbStore` keeps values in one IndexedDB object store, moved unchanged from @framers/agentos, so a
+ * page's keys stay where they are; `createSqlKeyValueStore` keeps them in a SQL table on any adapter; the memory store
+ * keeps them for the page alone.
+ *
+ * The module imports no adapter, so a page that loads it for its key-value store loads neither sql.js nor pg.
+ * @module sql-storage-adapter/kv
+ */
+export { MemoryKeyValueStore, namespaced, type KeyValueStore } from './keyValueStore.js';
+export { IndexedDbKeyValueStore, openIndexedDbStore, type IndexedDbStoreOptions } from './indexedDbKeyValueStore.js';
+export { idb, type IdbDatabaseLike, type IdbKeyRangeLike, type IdbObjectStoreLike, type IdbOpenRequestLike, type IdbRequestLike, type IdbTransactionLike, } from './idb.js';
+export { createSqlKeyValueStore, type SqlKeyValueStoreOptions } from './sqlKeyValueStore.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/features/kv/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/kv/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAClH,OAAO,EACL,GAAG,EACH,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,sBAAsB,EAAE,KAAK,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/features/kv/index.js

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview The key-value module, `@framers/sql-storage-adapter/kv`: one `KeyValueStore` contract and its
+ * stores. `openIndexedDbStore` keeps values in one IndexedDB object store, moved unchanged from @framers/agentos, so a
+ * page's keys stay where they are; `createSqlKeyValueStore` keeps them in a SQL table on any adapter; the memory store
+ * keeps them for the page alone.
+ *
+ * The module imports no adapter, so a page that loads it for its key-value store loads neither sql.js nor pg.
+ * @module sql-storage-adapter/kv
+ */
+export { MemoryKeyValueStore, namespaced } from './keyValueStore.js';
+export { IndexedDbKeyValueStore, openIndexedDbStore } from './indexedDbKeyValueStore.js';
+export { idb, } from './idb.js';
+export { createSqlKeyValueStore } from './sqlKeyValueStore.js';
+//# sourceMappingURL=index.js.map

package/dist/features/kv/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/features/kv/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAsB,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAA8B,MAAM,0BAA0B,CAAC;AAClH,OAAO,EACL,GAAG,GAOJ,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,sBAAsB,EAAgC,MAAM,oBAAoB,CAAC"}

package/dist/features/kv/indexedDbKeyValueStore.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview The key-value store over one IndexedDB object store with out-of-line keys. It opens a database at
+ * the version given (1 by default) and creates the object store only when the open upgrades the database (a new one,
+ * or one below that version), so a database another page made at that version is read in place. A browser that
+ * refuses IndexedDB gets the memory store.
+ * Moved unchanged from @framers/agentos src/core/storage/browser/IndexedDbKeyValueStore.ts: the same database,
+ * object store, version and keys.
+ * @module sql-storage-adapter/kv/indexedDbKeyValueStore
+ */
+import { type IdbDatabaseLike } from './idb.js';
+import { type KeyValueStore } from './keyValueStore.js';
+/** Where the store lives. */
+export interface IndexedDbStoreOptions {
+    /** The database's name. */
+    dbName: string;
+    /** The object store's name. It is made, with out-of-line keys, only when the open upgrades the database. */
+    storeName: string;
+    /**
+     * The version the database is opened at. A database that exists at this version is opened as it is, even when it
+     * lacks the object store, and every call of the store then rejects; one below it is upgraded, and gains the object
+     * store when it lacks it; one above it is refused by the browser.
+     * @default 1
+     */
+    version?: number;
+}
+/**
+ * The store over IndexedDB. Each call is one transaction over the object store: its promise is fulfilled when that
+ * transaction completes, and rejected with the reason when its request fails or the transaction is aborted.
+ *
+ * `keys` and `deletePrefix` read the keys between `prefix` and `prefix` followed by U+FFFF, so they miss a key that
+ * holds U+FFFF right after the prefix and goes on: keep keys to characters below it.
+ *
+ * The connection stays open until `close`: when another tab opens the database at a newer version, its upgrade waits
+ * for this tab to close the store or go. A connection the browser closes (the database deleted, the site's storage
+ * cleared) is not opened again, and every call then rejects.
+ */
+export declare class IndexedDbKeyValueStore implements KeyValueStore {
+    private readonly db;
+    private readonly storeName;
+    /** Always false: the values are in the browser's database. */
+    readonly memoryOnly = false;
+    /**
+     * @param db - An open database that holds the object store.
+     * @param storeName - The object store's name.
+     */
+    constructor(db: IdbDatabaseLike, storeName: string);
+    private run;
+    private static range;
+    /** The value held under `key`, or undefined when there is none. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Holds a structured clone of `value` under `key`. */
+    set(key: string, value: unknown): Promise<void>;
+    /** Removes `key`. */
+    delete(key: string): Promise<void>;
+    /**
+     * Every key that begins with `prefix`, in order. With an empty prefix, every key of the object store, a key that is
+     * not a string (a number, a date or an array another page wrote) given as `String` writes it.
+     */
+    keys(prefix: string): Promise<string[]>;
+    /** Removes every key that begins with `prefix`; with an empty prefix, everything the object store holds. */
+    deletePrefix(prefix: string): Promise<void>;
+    /** Closes the database connection. */
+    close(): void;
+}
+/**
+ * Opens the store, or the memory store when the browser refuses IndexedDB: a page with no `indexedDB`, an `open`
+ * that throws or fails (a database above `version` among them), or an upgrade that waits on another tab. The
+ * answer's `memoryOnly` says which it is; the memory store's `close` does nothing.
+ *
+ * An upgrade that waited on another tab still has its turn once that tab closes the database. It is aborted then,
+ * so the database stays as it was and the connection it opened is closed: nothing is left open behind the memory
+ * store.
+ */
+export declare function openIndexedDbStore(options: IndexedDbStoreOptions): Promise<KeyValueStore & {
+    close(): void;
+}>;
+//# sourceMappingURL=indexedDbKeyValueStore.d.ts.map

package/dist/features/kv/indexedDbKeyValueStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexedDbKeyValueStore.d.ts","sourceRoot":"","sources":["../../../src/features/kv/indexedDbKeyValueStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAO,KAAK,eAAe,EAAsE,MAAM,OAAO,CAAC;AACtH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE1E,6BAA6B;AAC7B,MAAM,WAAW,qBAAqB;IACpC,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,4GAA4G;IAC5G,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,sBAAuB,YAAW,aAAa;IAQ9C,OAAO,CAAC,QAAQ,CAAC,EAAE;IAAmB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAP5E,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,SAAS;IAE5B;;;OAGG;gBAC0B,EAAE,EAAE,eAAe,EAAmB,SAAS,EAAE,MAAM;IAEpF,OAAO,CAAC,GAAG;IAaX,OAAO,CAAC,MAAM,CAAC,KAAK;IAIpB,mEAAmE;IAC7D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAI3D,uDAAuD;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,qBAAqB;IACf,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK7C,4GAA4G;IACtG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,sCAAsC;IACtC,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,GAAG;IAAE,KAAK,IAAI,IAAI,CAAA;CAAE,CAAC,CAoCnH"}

package/dist/features/kv/indexedDbKeyValueStore.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview The key-value store over one IndexedDB object store with out-of-line keys. It opens a database at
+ * the version given (1 by default) and creates the object store only when the open upgrades the database (a new one,
+ * or one below that version), so a database another page made at that version is read in place. A browser that
+ * refuses IndexedDB gets the memory store.
+ * Moved unchanged from @framers/agentos src/core/storage/browser/IndexedDbKeyValueStore.ts: the same database,
+ * object store, version and keys.
+ * @module sql-storage-adapter/kv/indexedDbKeyValueStore
+ */
+import { idb } from './idb.js';
+import { MemoryKeyValueStore } from './keyValueStore.js';
+/**
+ * The store over IndexedDB. Each call is one transaction over the object store: its promise is fulfilled when that
+ * transaction completes, and rejected with the reason when its request fails or the transaction is aborted.
+ *
+ * `keys` and `deletePrefix` read the keys between `prefix` and `prefix` followed by U+FFFF, so they miss a key that
+ * holds U+FFFF right after the prefix and goes on: keep keys to characters below it.
+ *
+ * The connection stays open until `close`: when another tab opens the database at a newer version, its upgrade waits
+ * for this tab to close the store or go. A connection the browser closes (the database deleted, the site's storage
+ * cleared) is not opened again, and every call then rejects.
+ */
+export class IndexedDbKeyValueStore {
+    /**
+     * @param db - An open database that holds the object store.
+     * @param storeName - The object store's name.
+     */
+    constructor(db, storeName) {
+        this.db = db;
+        this.storeName = storeName;
+        /** Always false: the values are in the browser's database. */
+        this.memoryOnly = false;
+    }
+    run(mode, work) {
+        return new Promise((resolve, reject) => {
+            const transaction = this.db.transaction(this.storeName, mode);
+            const request = work(transaction.objectStore(this.storeName));
+            transaction.oncomplete = () => resolve(request.result);
+            // A failed request's event reaches the transaction before the transaction is aborted for it, so the
+            // transaction's own error is still null then, and the request's says why. A transaction aborted for a reason
+            // of its own has that reason set by the time its unfinished request's event arrives.
+            transaction.onerror = () => reject(transaction.error ?? request.error ?? new Error('IndexedDB request failed'));
+            transaction.onabort = () => reject(transaction.error ?? new Error('IndexedDB transaction aborted'));
+        });
+    }
+    static range(prefix) {
+        return prefix === '' ? undefined : idb().keyRange.bound(prefix, `${prefix}\uffff`);
+    }
+    /** The value held under `key`, or undefined when there is none. */
+    async get(key) {
+        return (await this.run('readonly', (store) => store.get(key)));
+    }
+    /** Holds a structured clone of `value` under `key`. */
+    async set(key, value) {
+        await this.run('readwrite', (store) => store.put(value, key));
+    }
+    /** Removes `key`. */
+    async delete(key) {
+        await this.run('readwrite', (store) => store.delete(key));
+    }
+    /**
+     * Every key that begins with `prefix`, in order. With an empty prefix, every key of the object store, a key that is
+     * not a string (a number, a date or an array another page wrote) given as `String` writes it.
+     */
+    async keys(prefix) {
+        const keys = await this.run('readonly', (store) => store.getAllKeys(IndexedDbKeyValueStore.range(prefix)));
+        return keys.map(String).filter((key) => key.startsWith(prefix)).sort();
+    }
+    /** Removes every key that begins with `prefix`; with an empty prefix, everything the object store holds. */
+    async deletePrefix(prefix) {
+        const range = IndexedDbKeyValueStore.range(prefix);
+        await this.run('readwrite', (store) => (range ? store.delete(range) : store.clear()));
+    }
+    /** Closes the database connection. */
+    close() {
+        this.db.close();
+    }
+}
+/**
+ * Opens the store, or the memory store when the browser refuses IndexedDB: a page with no `indexedDB`, an `open`
+ * that throws or fails (a database above `version` among them), or an upgrade that waits on another tab. The
+ * answer's `memoryOnly` says which it is; the memory store's `close` does nothing.
+ *
+ * An upgrade that waited on another tab still has its turn once that tab closes the database. It is aborted then,
+ * so the database stays as it was and the connection it opened is closed: nothing is left open behind the memory
+ * store.
+ */
+export async function openIndexedDbStore(options) {
+    try {
+        const db = await new Promise((resolve, reject) => {
+            const request = idb().factory.open(options.dbName, options.version ?? 1);
+            // True once the promise is settled. The browser does not end a blocked open: it goes on when the other tab
+            // closes the database, after the store has answered from memory, and what it opens then is nobody's.
+            let answered = false;
+            const refuse = (reason) => {
+                answered = true;
+                reject(reason);
+            };
+            request.onupgradeneeded = () => {
+                if (answered && request.transaction) {
+                    // Aborting the upgrade fails the open, which closes its connection and leaves the database as it was.
+                    request.transaction.abort();
+                    return;
+                }
+                if (!request.result.objectStoreNames.contains(options.storeName))
+                    request.result.createObjectStore(options.storeName);
+            };
+            request.onsuccess = () => {
+                if (answered) {
+                    // An open that succeeds after the answer (an upgrade that could not be aborted) is closed at once.
+                    request.result.close();
+                    return;
+                }
+                answered = true;
+                resolve(request.result);
+            };
+            request.onerror = () => refuse(request.error);
+            request.onblocked = () => refuse(new Error('the database is held open by another tab at an older version'));
+        });
+        return new IndexedDbKeyValueStore(db, options.storeName);
+    }
+    catch {
+        const memory = new MemoryKeyValueStore();
+        return Object.assign(memory, { close: () => undefined });
+    }
+}
+//# sourceMappingURL=indexedDbKeyValueStore.js.map

package/dist/features/kv/indexedDbKeyValueStore.js.map

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

package/dist/features/kv/keyValueStore.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview A key-value store for a page: values are structured-cloneable, keys are listed and removed by
+ * prefix. `namespaced` scopes one to a prefix, which keeps two users of one browser apart when neither's prefix
+ * begins with the other's.
+ * Moved unchanged from @framers/agentos src/core/storage/browser/KeyValueStore.ts.
+ * @module sql-storage-adapter/kv/keyValueStore
+ */
+/** What a page's store does. */
+export interface KeyValueStore {
+    /** True when nothing outlives the page (a browser that refused the database). */
+    readonly memoryOnly: boolean;
+    /**
+     * The value held under `key`, or undefined when there is none. The type argument is the caller's word for what
+     * it stored: the store checks nothing of what it reads.
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Holds `value` under `key`, in place of what was there. The value must be one the structured clone can copy. */
+    set(key: string, value: unknown): Promise<void>;
+    /** Removes `key`. A key that is not held is no error. */
+    delete(key: string): Promise<void>;
+    /** Every key that begins with `prefix`, in order. */
+    keys(prefix: string): Promise<string[]>;
+    /** Removes every key that begins with `prefix`. */
+    deletePrefix(prefix: string): Promise<void>;
+}
+/** A store held in memory. Values are copied in and out with `structuredClone`, as IndexedDB copies them. */
+export declare class MemoryKeyValueStore implements KeyValueStore {
+    /** Always true: the values go with the page. */
+    readonly memoryOnly = true;
+    private readonly values;
+    /** A copy of the value held under `key`, or undefined. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Holds a copy of `value` under `key`. */
+    set(key: string, value: unknown): Promise<void>;
+    /** Removes `key`. */
+    delete(key: string): Promise<void>;
+    /** Every key that begins with `prefix`, in order. */
+    keys(prefix: string): Promise<string[]>;
+    /** Removes every key that begins with `prefix`. */
+    deletePrefix(prefix: string): Promise<void>;
+}
+/**
+ * A store whose keys all begin with `prefix`; its own keys are answered without it. Two namespaces stay apart only
+ * when neither prefix begins with the other, so end each with a character no id holds: the keys under `anna` are
+ * among those under `ann`, while `ann/` and `anna/` never meet. Each call makes a new store object.
+ */
+export declare function namespaced(store: KeyValueStore, prefix: string): KeyValueStore;
+//# sourceMappingURL=keyValueStore.d.ts.map

package/dist/features/kv/keyValueStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyValueStore.d.ts","sourceRoot":"","sources":["../../../src/features/kv/keyValueStore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,gCAAgC;AAChC,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACtD,kHAAkH;IAClH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,yDAAyD;IACzD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,qDAAqD;IACrD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,mDAAmD;IACnD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,6GAA6G;AAC7G,qBAAa,mBAAoB,YAAW,aAAa;IACvD,gDAAgD;IAChD,QAAQ,CAAC,UAAU,QAAQ;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IAErD,0DAA0D;IACpD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAI3D,2CAA2C;IACrC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,qBAAqB;IACf,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,qDAAqD;IAC/C,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI7C,mDAAmD;IAC7C,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAW9E"}

package/dist/features/kv/keyValueStore.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview A key-value store for a page: values are structured-cloneable, keys are listed and removed by
+ * prefix. `namespaced` scopes one to a prefix, which keeps two users of one browser apart when neither's prefix
+ * begins with the other's.
+ * Moved unchanged from @framers/agentos src/core/storage/browser/KeyValueStore.ts.
+ * @module sql-storage-adapter/kv/keyValueStore
+ */
+/** A store held in memory. Values are copied in and out with `structuredClone`, as IndexedDB copies them. */
+export class MemoryKeyValueStore {
+    constructor() {
+        /** Always true: the values go with the page. */
+        this.memoryOnly = true;
+        this.values = new Map();
+    }
+    /** A copy of the value held under `key`, or undefined. */
+    async get(key) {
+        return this.values.has(key) ? structuredClone(this.values.get(key)) : undefined;
+    }
+    /** Holds a copy of `value` under `key`. */
+    async set(key, value) {
+        this.values.set(key, structuredClone(value));
+    }
+    /** Removes `key`. */
+    async delete(key) {
+        this.values.delete(key);
+    }
+    /** Every key that begins with `prefix`, in order. */
+    async keys(prefix) {
+        return [...this.values.keys()].filter((key) => key.startsWith(prefix)).sort();
+    }
+    /** Removes every key that begins with `prefix`. */
+    async deletePrefix(prefix) {
+        for (const key of await this.keys(prefix))
+            this.values.delete(key);
+    }
+}
+/**
+ * A store whose keys all begin with `prefix`; its own keys are answered without it. Two namespaces stay apart only
+ * when neither prefix begins with the other, so end each with a character no id holds: the keys under `anna` are
+ * among those under `ann`, while `ann/` and `anna/` never meet. Each call makes a new store object.
+ */
+export function namespaced(store, prefix) {
+    return {
+        get memoryOnly() {
+            return store.memoryOnly;
+        },
+        get: (key) => store.get(prefix + key),
+        set: (key, value) => store.set(prefix + key, value),
+        delete: (key) => store.delete(prefix + key),
+        keys: async (inner) => (await store.keys(prefix + inner)).map((key) => key.slice(prefix.length)),
+        deletePrefix: (inner) => store.deletePrefix(prefix + inner),
+    };
+}
+//# sourceMappingURL=keyValueStore.js.map

package/dist/features/kv/keyValueStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyValueStore.js","sourceRoot":"","sources":["../../../src/features/kv/keyValueStore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH,6GAA6G;AAC7G,MAAM,OAAO,mBAAmB;IAAhC;QACE,gDAAgD;QACvC,eAAU,GAAG,IAAI,CAAC;QACV,WAAM,GAAG,IAAI,GAAG,EAAmB,CAAC;IA0BvD,CAAC;IAxBC,0DAA0D;IAC1D,KAAK,CAAC,GAAG,CAAc,GAAW;QAChC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACzF,CAAC;IAED,2CAA2C;IAC3C,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAc;QACnC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,qBAAqB;IACrB,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAChF,CAAC;IAED,mDAAmD;IACnD,KAAK,CAAC,YAAY,CAAC,MAAc;QAC/B,KAAK,MAAM,GAAG,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrE,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAoB,EAAE,MAAc;IAC7D,OAAO;QACL,IAAI,UAAU;YACZ,OAAO,KAAK,CAAC,UAAU,CAAC;QAC1B,CAAC;QACD,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC;QACrC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,KAAK,CAAC;QACnD,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC;QAC3C,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAChG,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,KAAK,CAAC;KAC5D,CAAC;AACJ,CAAC"}

package/dist/features/kv/sqlKeyValueStore.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview The key-value store over a SQL table, on any adapter: better-sqlite3 and sql.js files, the IndexedDB
+ * adapter in a browser, Capacitor on a phone, PostgreSQL on a server. It answers the calls the IndexedDB store answers,
+ * and gives back each value as the structured clone does (see `valueCodec`), so a host keeps one key-value contract on
+ * every platform.
+ * @module sql-storage-adapter/kv/sqlKeyValueStore
+ */
+import type { StorageAdapter } from '../../core/contracts/index.js';
+import type { KeyValueStore } from './keyValueStore.js';
+/** Where the store keeps its keys and values. */
+export interface SqlKeyValueStoreOptions {
+    /**
+     * The table: lower-case letters, digits and underscores, starting with a letter or an underscore, at most 63
+     * characters. It is made, with a `key` and a `value` column, when it is missing.
+     */
+    table: string;
+}
+/**
+ * Opens the key-value store over `options.table` on `adapter`, making the table when it is missing. The adapter must
+ * be open; the store never closes it.
+ *
+ * @example
+ * ```typescript
+ * const db = await createDatabase({ segment: 'agentos' });
+ * const kv = await createSqlKeyValueStore(db, { table: 'agentos_kv' });
+ * await kv.set('notes/1', { title: 'One', saved: Date.now() });
+ * ```
+ *
+ * @throws {Error} When `options.table` is not a table name the store takes.
+ */
+export declare function createSqlKeyValueStore(adapter: StorageAdapter, options: SqlKeyValueStoreOptions): Promise<KeyValueStore & {
+    close(): void;
+}>;
+//# sourceMappingURL=sqlKeyValueStore.d.ts.map

package/dist/features/kv/sqlKeyValueStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlKeyValueStore.d.ts","sourceRoot":"","sources":["../../../src/features/kv/sqlKeyValueStore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAmFD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,aAAa,GAAG;IAAE,KAAK,IAAI,IAAI,CAAA;CAAE,CAAC,CAU5C"}

package/dist/features/kv/sqlKeyValueStore.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview The key-value store over a SQL table, on any adapter: better-sqlite3 and sql.js files, the IndexedDB
+ * adapter in a browser, Capacitor on a phone, PostgreSQL on a server. It answers the calls the IndexedDB store answers,
+ * and gives back each value as the structured clone does (see `valueCodec`), so a host keeps one key-value contract on
+ * every platform.
+ * @module sql-storage-adapter/kv/sqlKeyValueStore
+ */
+import { decodeValue, encodeValue } from './valueCodec.js';
+/** A table name the store takes: an unquoted PostgreSQL identifier, which SQLite takes too. */
+const TABLE_PATTERN = /^[a-z_][a-z0-9_]*$/;
+/** PostgreSQL's identifier limit. */
+const MAX_TABLE_LENGTH = 63;
+/** The length of `text` in characters (code points), as SQLite's and PostgreSQL's `substr` count them. */
+const characters = (text) => Array.from(text).length;
+/**
+ * The store over one table. Each call is one statement on the adapter, so it is atomic, and runs in the adapter's
+ * transaction rules: through a transaction's handle it joins that transaction.
+ *
+ * Keys are text and are listed in the order of their UTF-16 code units, as IndexedDB orders them, whatever the
+ * database's collation. On PostgreSQL a key cannot hold the NUL character, which its text type refuses.
+ */
+class SqlKeyValueStore {
+    constructor(adapter, table) {
+        this.adapter = adapter;
+        this.table = table;
+        this.memoryOnly = !adapter.capabilities.has('persistence');
+    }
+    /** The value held under `key`, or undefined when there is none. */
+    async get(key) {
+        const row = await this.adapter.get(`SELECT "value" FROM "${this.table}" WHERE "key" = ?`, [key]);
+        return row ? decodeValue(row.value) : undefined;
+    }
+    /**
+     * Holds `value` under `key`, in place of what was there. A value the structured clone refuses is refused with a
+     * `DataCloneError` before anything is written, and the key keeps what it held.
+     */
+    async set(key, value) {
+        const text = encodeValue(value);
+        await this.adapter.run(`INSERT INTO "${this.table}" ("key", "value") VALUES (?, ?) ON CONFLICT ("key") DO UPDATE SET "value" = excluded."value"`, [key, text]);
+    }
+    /** Removes `key`. A key that is not held is no error. */
+    async delete(key) {
+        await this.adapter.run(`DELETE FROM "${this.table}" WHERE "key" = ?`, [key]);
+    }
+    /**
+     * Every key that begins with `prefix`, in order. The prefix is read literally: `%`, `_` and `*` are characters,
+     * not patterns.
+     */
+    async keys(prefix) {
+        const rows = prefix === ''
+            ? await this.adapter.all(`SELECT "key" FROM "${this.table}"`)
+            : await this.adapter.all(`SELECT "key" FROM "${this.table}" WHERE substr("key", 1, ?) = ?`, [characters(prefix), prefix]);
+        return rows
+            .map((row) => row.key)
+            .filter((key) => key.startsWith(prefix))
+            .sort();
+    }
+    /** Removes every key that begins with `prefix`; with an empty prefix, every key of the table. */
+    async deletePrefix(prefix) {
+        if (prefix === '') {
+            await this.adapter.run(`DELETE FROM "${this.table}"`);
+            return;
+        }
+        await this.adapter.run(`DELETE FROM "${this.table}" WHERE substr("key", 1, ?) = ?`, [characters(prefix), prefix]);
+    }
+    /** Does nothing: the adapter is its caller's, who closes it. */
+    close() { }
+}
+/**
+ * Opens the key-value store over `options.table` on `adapter`, making the table when it is missing. The adapter must
+ * be open; the store never closes it.
+ *
+ * @example
+ * ```typescript
+ * const db = await createDatabase({ segment: 'agentos' });
+ * const kv = await createSqlKeyValueStore(db, { table: 'agentos_kv' });
+ * await kv.set('notes/1', { title: 'One', saved: Date.now() });
+ * ```
+ *
+ * @throws {Error} When `options.table` is not a table name the store takes.
+ */
+export async function createSqlKeyValueStore(adapter, options) {
+    const table = options.table;
+    if (typeof table !== 'string' || !TABLE_PATTERN.test(table) || table.length > MAX_TABLE_LENGTH) {
+        throw new Error(`Invalid table name ${JSON.stringify(table)} for the key-value store: lower-case letters, digits and underscores, ` +
+            `starting with a letter or an underscore, at most ${MAX_TABLE_LENGTH} characters.`);
+    }
+    await adapter.exec(`CREATE TABLE IF NOT EXISTS "${table}" ("key" TEXT PRIMARY KEY NOT NULL, "value" TEXT NOT NULL)`);
+    return new SqlKeyValueStore(adapter, table);
+}
+//# sourceMappingURL=sqlKeyValueStore.js.map

package/dist/features/kv/sqlKeyValueStore.js.map

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