@framers/sql-storage-adapter 0.7.1 → 0.7.3

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

@@ -0,0 +1,116 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var indexedDbKeyValueStore_exports = {};
+__export(indexedDbKeyValueStore_exports, {
+  IndexedDbKeyValueStore: () => IndexedDbKeyValueStore,
+  openIndexedDbStore: () => openIndexedDbStore
+});
+module.exports = __toCommonJS(indexedDbKeyValueStore_exports);
+var import_idb = require("./idb.js");
+var import_keyValueStore = require("./keyValueStore.js");
+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;
+    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);
+      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 === "" ? void 0 : (0, import_idb.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();
+  }
+}
+async function openIndexedDbStore(options) {
+  try {
+    const db = await new Promise((resolve, reject) => {
+      const request = (0, import_idb.idb)().factory.open(options.dbName, options.version ?? 1);
+      let answered = false;
+      const refuse = (reason) => {
+        answered = true;
+        reject(reason);
+      };
+      request.onupgradeneeded = () => {
+        if (answered && request.transaction) {
+          request.transaction.abort();
+          return;
+        }
+        if (!request.result.objectStoreNames.contains(options.storeName))
+          request.result.createObjectStore(options.storeName);
+      };
+      request.onsuccess = () => {
+        if (answered) {
+          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 import_keyValueStore.MemoryKeyValueStore();
+    return Object.assign(memory, { close: () => void 0 });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IndexedDbKeyValueStore,
+  openIndexedDbStore
+});

package/dist/cjs/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/cjs/features/kv/keyValueStore.js

@@ -0,0 +1,67 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var keyValueStore_exports = {};
+__export(keyValueStore_exports, {
+  MemoryKeyValueStore: () => MemoryKeyValueStore,
+  namespaced: () => namespaced
+});
+module.exports = __toCommonJS(keyValueStore_exports);
+class MemoryKeyValueStore {
+  constructor() {
+    this.memoryOnly = true;
+    this.values = /* @__PURE__ */ 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)) : void 0;
+  }
+  /** 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);
+  }
+}
+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)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryKeyValueStore,
+  namespaced
+});

package/dist/cjs/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/cjs/features/kv/sqlKeyValueStore.js

@@ -0,0 +1,81 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var sqlKeyValueStore_exports = {};
+__export(sqlKeyValueStore_exports, {
+  createSqlKeyValueStore: () => createSqlKeyValueStore
+});
+module.exports = __toCommonJS(sqlKeyValueStore_exports);
+var import_valueCodec = require("./valueCodec.js");
+const TABLE_PATTERN = /^[a-z_][a-z0-9_]*$/;
+const MAX_TABLE_LENGTH = 63;
+const characters = (text) => Array.from(text).length;
+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 ? (0, import_valueCodec.decodeValue)(row.value) : void 0;
+  }
+  /**
+   * 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 = (0, import_valueCodec.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() {
+  }
+}
+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);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSqlKeyValueStore
+});

package/dist/cjs/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