@framers/sql-storage-adapter 0.6.15 → 0.7.0

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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"}

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

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview The text the SQL key-value store keeps each value as. A value comes back as the structured clone,
+ * which IndexedDB applies to every value it stores, gives it back: the SQL store and the IndexedDB store then answer
+ * alike, and a copy from one into the other can be checked value by value.
+ *
+ * What comes back, as the structured clone gives it (V8's serializer, which Chrome and Node.js run, is the model):
+ * strings (lone surrogates too), numbers (`-0`, `NaN` and the infinities too), booleans, `null`, `undefined`,
+ * bigints; plain objects and class instances as plain objects with their own enumerable string-keyed properties, in
+ * order; arrays with their holes and their own properties; `Date`, `RegExp` (source and flags), `Map`, `Set`,
+ * `ArrayBuffer`, the typed arrays and `DataView` (a view keeps its buffer, its offset and its length, and two views of
+ * one buffer share it); `Number`, `String`, `Boolean` and `BigInt` objects; errors, as `Error`, `EvalError`,
+ * `RangeError`, `ReferenceError`, `SyntaxError`, `TypeError` or `URIError` by their name, with their message, stack
+ * and cause. An object reached twice comes back as one object, and a cycle as a cycle.
+ *
+ * Refused with a `DataCloneError`, as the structured clone refuses them: functions, symbols, `WeakMap`, `WeakSet`,
+ * `WeakRef`, promises, iterators, generators, `SharedArrayBuffer`. Refused too, though IndexedDB keeps them: `Blob`,
+ * `File`, `ImageData`, `CryptoKey` and the other host objects, which text cannot hold.
+ *
+ * The text is JSON: it holds no NUL character, which PostgreSQL's text type refuses, and no lone surrogate, which
+ * cannot be encoded as UTF-8.
+ * @module sql-storage-adapter/kv/valueCodec
+ */
+/**
+ * Encodes `value` as text the SQL store keeps.
+ *
+ * @throws {Error} A `DataCloneError` for a value the structured clone refuses, or one text cannot hold.
+ */
+export declare function encodeValue(value: unknown): string;
+/**
+ * Decodes text `encodeValue` wrote.
+ *
+ * @throws {Error} When the text is not one `encodeValue` writes.
+ */
+export declare function decodeValue(text: string): unknown;
+//# sourceMappingURL=valueCodec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"valueCodec.d.ts","sourceRoot":"","sources":["../../../src/features/kv/valueCodec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAkIH;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA0HlD;AAaD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAiLjD"}