@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/data/sqlite/sqlTableSchema.js

@@ -0,0 +1,138 @@
+import { SQL } from "drizzle-orm";
+import { getTableConfig, SQLiteSyncDialect, } from "drizzle-orm/sqlite-core";
+import { hasCompletedConnectionOnce, markCompletedConnectionOnce, runSerializedSqlMutation, } from "./sqlExec.js";
+const sqliteDialect = new SQLiteSyncDialect();
+function renderIdentifier(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+function renderDefaultValue(value) {
+    if (value === null) {
+        return "NULL";
+    }
+    if (typeof value === "boolean") {
+        return value ? "1" : "0";
+    }
+    if (value instanceof SQL) {
+        return sqliteDialect.sqlToQuery(value).sql;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    if (typeof value === "string") {
+        return `'${value.replaceAll("'", "''")}'`;
+    }
+    throw new Error(`Unsupported SQLite default value: ${String(value)}`);
+}
+function renderColumn(column, inlinePrimaryKeyColumnName) {
+    const parts = [
+        renderIdentifier(column.name),
+        column.getSQLType().toUpperCase(),
+    ];
+    if (column.notNull) {
+        parts.push("NOT NULL");
+    }
+    if (column.hasDefault) {
+        parts.push("DEFAULT", renderDefaultValue(column.default));
+    }
+    if (column.primary || column.name === inlinePrimaryKeyColumnName) {
+        parts.push("PRIMARY KEY");
+    }
+    if (column.isUnique) {
+        parts.push("UNIQUE");
+    }
+    return parts.join(" ");
+}
+function renderPrimaryKey(columns) {
+    const columnNames = columns.map((column) => renderIdentifier(column.name));
+    return `PRIMARY KEY (${columnNames.join(", ")})`;
+}
+function renderUniqueConstraint(columns) {
+    const columnNames = columns.map((column) => renderIdentifier(column.name));
+    return `UNIQUE (${columnNames.join(", ")})`;
+}
+function isSQLiteColumn(value) {
+    return ("name" in value && typeof value.name === "string" && "getSQLType" in value);
+}
+function renderIndexColumn(column) {
+    if (isSQLiteColumn(column)) {
+        return renderIdentifier(column.name);
+    }
+    return sqliteDialect.sqlToQuery(column.getSQL(), "indexes").sql;
+}
+function renderIndex(indexDefinition) {
+    const config = indexDefinition.config;
+    const unique = config.unique ? "UNIQUE " : "";
+    const columns = config.columns.map(renderIndexColumn).join(", ");
+    const where = config.where
+        ? ` WHERE ${sqliteDialect.sqlToQuery(config.where, "indexes").sql}`
+        : "";
+    return `CREATE ${unique}INDEX IF NOT EXISTS ${renderIdentifier(config.name)} ON ${renderIdentifier(getTableConfig(config.table).name)} (${columns})${where}`;
+}
+/**
+ * Render a Drizzle SQLite table definition into executable schema SQL.
+ *
+ * The client runtime creates local tables through `ensureSqlTables`, which works
+ * with raw SQL strings rather than Drizzle migrations. This helper keeps the
+ * Drizzle table definitions as the source of truth while preserving primary
+ * keys, table-level unique constraints, partial indexes, default values, and
+ * identifier quoting.
+ */
+export function defineSqlTableSchema(table) {
+    const config = getTableConfig(table);
+    const inlinePrimaryKeyColumnName = config.primaryKeys.length === 1 &&
+        config.primaryKeys[0]?.columns.length === 1
+        ? config.primaryKeys[0].columns[0]?.name
+        : undefined;
+    const columns = config.columns.map((column) => renderColumn(column, inlinePrimaryKeyColumnName));
+    const primaryKeys = inlinePrimaryKeyColumnName
+        ? []
+        : config.primaryKeys.map((key) => renderPrimaryKey(key.columns));
+    const uniqueConstraints = config.uniqueConstraints.map((constraint) => renderUniqueConstraint(constraint.columns));
+    const columnDefinitions = [...columns, ...primaryKeys, ...uniqueConstraints];
+    return {
+        name: config.name,
+        createSql: `CREATE TABLE IF NOT EXISTS ${renderIdentifier(config.name)} (
+  ${columnDefinitions.join(",\n  ")}
+)`,
+        indexes: config.indexes.map(renderIndex),
+    };
+}
+function getTableEnsureKey(table) {
+    return `sql-table:${table.name}`;
+}
+async function assertRequiredColumns(execSql, table) {
+    if (!table.requiredColumns || table.requiredColumns.length === 0) {
+        return;
+    }
+    const rows = await execSql(`PRAGMA table_info(${renderIdentifier(table.name)})`);
+    const storedColumns = new Set(rows.map(({ name }) => name));
+    const missingColumns = table.requiredColumns.filter((column) => !storedColumns.has(column));
+    if (missingColumns.length > 0) {
+        throw new Error(`Local database schema for ${table.name} is obsolete; reset the local database before continuing`);
+    }
+}
+// Table ensures run on every query path, so completed ones are
+// remembered per connection: a re-ensure of an already-ensured table skips the
+// DDL round-trips AND the serialized mutation lock, keeping diagnostic reads
+// from queueing behind bulk-import writes just to re-issue CREATE IF NOT
+// EXISTS no-ops. `resetConnectionSchemaMemo` forgets the memo when the schema
+// is rebuilt out from under the runtime (local backup restore).
+export async function ensureSqlTables(execSql, tables) {
+    const pendingTables = tables.filter((table) => !hasCompletedConnectionOnce(execSql, getTableEnsureKey(table)));
+    if (pendingTables.length === 0) {
+        return;
+    }
+    await runSerializedSqlMutation(execSql, async (lockedExecSql) => {
+        for (const table of pendingTables) {
+            await lockedExecSql(table.createSql);
+            for (const indexSql of table.indexes ?? []) {
+                await lockedExecSql(indexSql);
+            }
+            await assertRequiredColumns(lockedExecSql, table);
+        }
+    });
+    for (const table of pendingTables) {
+        markCompletedConnectionOnce(execSql, getTableEnsureKey(table));
+    }
+}
+//# sourceMappingURL=sqlTableSchema.js.map

package/data/sqlite/sqlTableSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlTableSchema.js","sourceRoot":"","sources":["sqlTableSchema.ts"],"names":[],"mappings":"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","sourcesContent":["import { SQL } from \"drizzle-orm\";\nimport {\n  getTableConfig,\n  type Index,\n  type IndexColumn,\n  type SQLiteColumn,\n  SQLiteSyncDialect,\n  type SQLiteTable,\n} from \"drizzle-orm/sqlite-core\";\nimport type { ExecSql } from \"./sqlExec\";\nimport {\n  hasCompletedConnectionOnce,\n  markCompletedConnectionOnce,\n  runSerializedSqlMutation,\n} from \"./sqlExec\";\n\nexport interface SqlTableSchema {\n  name: string;\n  createSql: string;\n  indexes?: ReadonlyArray<string>;\n  requiredColumns?: ReadonlyArray<string>;\n}\n\nconst sqliteDialect = new SQLiteSyncDialect();\n\nfunction renderIdentifier(name: string): string {\n  return `\"${name.replaceAll('\"', '\"\"')}\"`;\n}\n\nfunction renderDefaultValue(value: unknown): string {\n  if (value === null) {\n    return \"NULL\";\n  }\n\n  if (typeof value === \"boolean\") {\n    return value ? \"1\" : \"0\";\n  }\n\n  if (value instanceof SQL) {\n    return sqliteDialect.sqlToQuery(value).sql;\n  }\n\n  if (typeof value === \"number\") {\n    return String(value);\n  }\n\n  if (typeof value === \"string\") {\n    return `'${value.replaceAll(\"'\", \"''\")}'`;\n  }\n\n  throw new Error(`Unsupported SQLite default value: ${String(value)}`);\n}\n\nfunction renderColumn(\n  column: SQLiteColumn,\n  inlinePrimaryKeyColumnName?: string,\n): string {\n  const parts = [\n    renderIdentifier(column.name),\n    column.getSQLType().toUpperCase(),\n  ];\n\n  if (column.notNull) {\n    parts.push(\"NOT NULL\");\n  }\n\n  if (column.hasDefault) {\n    parts.push(\"DEFAULT\", renderDefaultValue(column.default));\n  }\n\n  if (column.primary || column.name === inlinePrimaryKeyColumnName) {\n    parts.push(\"PRIMARY KEY\");\n  }\n\n  if (column.isUnique) {\n    parts.push(\"UNIQUE\");\n  }\n\n  return parts.join(\" \");\n}\n\nfunction renderPrimaryKey(columns: ReadonlyArray<SQLiteColumn>): string {\n  const columnNames = columns.map((column) => renderIdentifier(column.name));\n  return `PRIMARY KEY (${columnNames.join(\", \")})`;\n}\n\nfunction renderUniqueConstraint(columns: ReadonlyArray<SQLiteColumn>): string {\n  const columnNames = columns.map((column) => renderIdentifier(column.name));\n  return `UNIQUE (${columnNames.join(\", \")})`;\n}\n\nfunction isSQLiteColumn(value: IndexColumn): value is SQLiteColumn {\n  return (\n    \"name\" in value && typeof value.name === \"string\" && \"getSQLType\" in value\n  );\n}\n\nfunction renderIndexColumn(column: IndexColumn): string {\n  if (isSQLiteColumn(column)) {\n    return renderIdentifier(column.name);\n  }\n\n  return sqliteDialect.sqlToQuery(column.getSQL(), \"indexes\").sql;\n}\n\nfunction renderIndex(indexDefinition: Index): string {\n  const config = indexDefinition.config;\n  const unique = config.unique ? \"UNIQUE \" : \"\";\n  const columns = config.columns.map(renderIndexColumn).join(\", \");\n  const where = config.where\n    ? ` WHERE ${sqliteDialect.sqlToQuery(config.where, \"indexes\").sql}`\n    : \"\";\n\n  return `CREATE ${unique}INDEX IF NOT EXISTS ${renderIdentifier(\n    config.name,\n  )} ON ${renderIdentifier(getTableConfig(config.table).name)} (${columns})${where}`;\n}\n\n/**\n * Render a Drizzle SQLite table definition into executable schema SQL.\n *\n * The client runtime creates local tables through `ensureSqlTables`, which works\n * with raw SQL strings rather than Drizzle migrations. This helper keeps the\n * Drizzle table definitions as the source of truth while preserving primary\n * keys, table-level unique constraints, partial indexes, default values, and\n * identifier quoting.\n */\nexport function defineSqlTableSchema(table: SQLiteTable): SqlTableSchema {\n  const config = getTableConfig(table);\n  const inlinePrimaryKeyColumnName =\n    config.primaryKeys.length === 1 &&\n    config.primaryKeys[0]?.columns.length === 1\n      ? config.primaryKeys[0].columns[0]?.name\n      : undefined;\n  const columns = config.columns.map((column) =>\n    renderColumn(column, inlinePrimaryKeyColumnName),\n  );\n  const primaryKeys = inlinePrimaryKeyColumnName\n    ? []\n    : config.primaryKeys.map((key) => renderPrimaryKey(key.columns));\n  const uniqueConstraints = config.uniqueConstraints.map((constraint) =>\n    renderUniqueConstraint(constraint.columns),\n  );\n  const columnDefinitions = [...columns, ...primaryKeys, ...uniqueConstraints];\n\n  return {\n    name: config.name,\n    createSql: `CREATE TABLE IF NOT EXISTS ${renderIdentifier(config.name)} (\n  ${columnDefinitions.join(\",\\n  \")}\n)`,\n    indexes: config.indexes.map(renderIndex),\n  };\n}\n\nfunction getTableEnsureKey(table: SqlTableSchema): string {\n  return `sql-table:${table.name}`;\n}\n\nasync function assertRequiredColumns(\n  execSql: ExecSql,\n  table: SqlTableSchema,\n): Promise<void> {\n  if (!table.requiredColumns || table.requiredColumns.length === 0) {\n    return;\n  }\n  const rows = await execSql(\n    `PRAGMA table_info(${renderIdentifier(table.name)})`,\n  );\n  const storedColumns = new Set(rows.map(({ name }) => name));\n  const missingColumns = table.requiredColumns.filter(\n    (column) => !storedColumns.has(column),\n  );\n  if (missingColumns.length > 0) {\n    throw new Error(\n      `Local database schema for ${table.name} is obsolete; reset the local database before continuing`,\n    );\n  }\n}\n\n// Table ensures run on every query path, so completed ones are\n// remembered per connection: a re-ensure of an already-ensured table skips the\n// DDL round-trips AND the serialized mutation lock, keeping diagnostic reads\n// from queueing behind bulk-import writes just to re-issue CREATE IF NOT\n// EXISTS no-ops. `resetConnectionSchemaMemo` forgets the memo when the schema\n// is rebuilt out from under the runtime (local backup restore).\nexport async function ensureSqlTables(\n  execSql: ExecSql,\n  tables: ReadonlyArray<SqlTableSchema>,\n): Promise<void> {\n  const pendingTables = tables.filter(\n    (table) => !hasCompletedConnectionOnce(execSql, getTableEnsureKey(table)),\n  );\n  if (pendingTables.length === 0) {\n    return;\n  }\n\n  await runSerializedSqlMutation(execSql, async (lockedExecSql) => {\n    for (const table of pendingTables) {\n      await lockedExecSql(table.createSql);\n      for (const indexSql of table.indexes ?? []) {\n        await lockedExecSql(indexSql);\n      }\n      await assertRequiredColumns(lockedExecSql, table);\n    }\n  });\n  for (const table of pendingTables) {\n    markCompletedConnectionOnce(execSql, getTableEnsureKey(table));\n  }\n}\n"]}

package/data/sqlite/sqlitePersistenceRuntime.d.ts

@@ -0,0 +1,34 @@
+import type { SqliteRemoteDatabase } from "drizzle-orm/sqlite-proxy";
+import { clientSQLiteSchema } from "./schema.js";
+import { type ExecSql, type ExecSqlClientLike } from "./sqlSchema.js";
+export type ClientSQLiteSchema = typeof clientSQLiteSchema;
+export type ClientSQLiteDatabase = SqliteRemoteDatabase<ClientSQLiteSchema>;
+export type ClientSQLiteTransactionConfig = NonNullable<Parameters<ClientSQLiteDatabase["transaction"]>[1]>;
+/**
+ * The handle a runtime transaction callback receives: the transaction's
+ * query interface WITHOUT `rollback` (throw instead — every scope maps an
+ * exception to its own rollback) and WITHOUT `transaction` (nest by calling
+ * `runtime.transaction` again, which scopes to a savepoint). Narrowing the
+ * contract here is what lets a nested scope share the connection-backed
+ * database handle safely.
+ */
+export type ClientSQLiteTransactionScope = Pick<ClientSQLiteDatabase, "all" | "delete" | "get" | "insert" | "query" | "run" | "select" | "selectDistinct" | "update" | "values">;
+export interface ClientSQLitePersistenceRuntime {
+    db: ClientSQLiteDatabase;
+    execSql: ExecSql;
+    runMutation<T>(operation: (db: ClientSQLiteDatabase) => Promise<T> | T): Promise<T>;
+    transaction<T>(operation: (tx: ClientSQLiteTransactionScope) => Promise<T>, config?: ClientSQLiteTransactionConfig): Promise<T>;
+    /**
+     * A transaction whose commit is gated on a SYNCHRONOUS guard: the guard
+     * runs and — when it passes — the COMMIT is dispatched in the same
+     * synchronous slice, so no JavaScript (an identity replacement included)
+     * can interleave between the decision and the commit dispatch. Resolves
+     * with `committed: false` (all writes rolled back) when the guard refuses.
+     */
+    guardedTransaction<T>(operation: (tx: ClientSQLiteTransactionScope) => Promise<T>, canCommit: () => boolean, config?: ClientSQLiteTransactionConfig): Promise<{
+        committed: boolean;
+        result: T | null;
+    }>;
+}
+export declare function getClientSQLitePersistenceRuntime(execSql: ExecSql): ClientSQLitePersistenceRuntime;
+export declare function createClientSQLitePersistenceRuntime(client: ExecSqlClientLike): ClientSQLitePersistenceRuntime;

package/data/sqlite/sqlitePersistenceRuntime.js

@@ -0,0 +1,204 @@
+import { drizzle } from "drizzle-orm/sqlite-proxy";
+import { clientSQLiteSchema } from "./schema.js";
+import { createExecSql, resetConnectionSchemaMemo, resolveCanonicalExecSql, runSerializedSqlMutation, } from "./sqlSchema.js";
+const runtimeByExecSql = new WeakMap();
+function transactionBeginStatement(config) {
+    if (config?.behavior === "immediate")
+        return "BEGIN IMMEDIATE";
+    if (config?.behavior === "exclusive")
+        return "BEGIN EXCLUSIVE";
+    return "BEGIN";
+}
+// One transaction depth per underlying connection (canonical executor), so a
+// runtime.transaction call made while another transaction is already open on
+// the same connection degrades to a SAVEPOINT scope instead of issuing a
+// second BEGIN. Callers inside a serialized mutation get separate runtime
+// instances per locked executor, so the depth cannot live on the runtime.
+const transactionDepthByCanonicalExecSql = new WeakMap();
+// Sibling nested scopes on one connection must not interleave: SQLite
+// savepoints form a stack, so releasing an earlier savepoint would also
+// release a later sibling started concurrently. Scopes serialize per
+// NESTING DEPTH — siblings share a depth and queue behind each other, while
+// a descendant runs one level deeper and must NOT wait on its own enclosing
+// scope (that wait can never resolve).
+const nestedScopeChainsByCanonicalExecSql = new WeakMap();
+const execSqlByClient = new WeakMap();
+function toSqlRowValue(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        return value;
+    }
+    if (typeof value === "boolean") {
+        return value ? 1 : 0;
+    }
+    throw new Error(`Unsupported SQLite bind value: ${String(value)}`);
+}
+function createRemoteCallback(getExecSql) {
+    function getRemoteResult(rows) {
+        const row = rows[0];
+        if (row !== undefined) {
+            return { rows: row };
+        }
+        // Drizzle's RemoteCallback type requires rows, but sqlite-proxy's get()
+        // mapper treats an undefined rows value as "no row found".
+        return Object.defineProperty({ rows: [] }, "rows", {
+            enumerable: true,
+            value: undefined,
+        });
+    }
+    return async (sql, params, method) => {
+        const rows = await getExecSql()(sql, params.map(toSqlRowValue), {
+            rowMode: "array",
+        });
+        if (method === "get") {
+            return getRemoteResult(rows);
+        }
+        return { rows };
+    };
+}
+function createClientSQLiteDatabase(getExecSql) {
+    return drizzle(createRemoteCallback(getExecSql), {
+        schema: clientSQLiteSchema,
+    });
+}
+// Serialize nested savepoint scopes per connection AND depth: a sibling
+// (same depth) queues behind the previous sibling so their savepoints
+// strictly nest instead of interleaving on the shared stack, while a
+// descendant (called from inside an executing scope, so one level deeper)
+// starts on its own depth's chain and never waits on its unresolved parent.
+async function runNestedSavepointScope(canonical, lockedExecSql, operation) {
+    const depthAtEntry = transactionDepthByCanonicalExecSql.get(canonical) ?? 0;
+    const chains = nestedScopeChainsByCanonicalExecSql.get(canonical) ??
+        new Map();
+    nestedScopeChainsByCanonicalExecSql.set(canonical, chains);
+    const previous = chains.get(depthAtEntry) ?? Promise.resolve();
+    let tracked = Promise.resolve();
+    const scope = previous
+        .catch(() => undefined)
+        .then(async () => {
+        const depth = transactionDepthByCanonicalExecSql.get(canonical) ?? 0;
+        transactionDepthByCanonicalExecSql.set(canonical, depth + 1);
+        const savepoint = `runtime_transaction_sp_${depth}`;
+        try {
+            await lockedExecSql(`SAVEPOINT ${savepoint}`);
+            const result = await operation();
+            await lockedExecSql(`RELEASE SAVEPOINT ${savepoint}`);
+            return result;
+        }
+        catch (error) {
+            await lockedExecSql(`ROLLBACK TO SAVEPOINT ${savepoint}`).catch(() => undefined);
+            await lockedExecSql(`RELEASE SAVEPOINT ${savepoint}`).catch(() => undefined);
+            resetConnectionSchemaMemo(canonical);
+            throw error;
+        }
+        finally {
+            transactionDepthByCanonicalExecSql.set(canonical, depth);
+            if (chains.get(depthAtEntry) === tracked) {
+                chains.delete(depthAtEntry);
+            }
+        }
+    });
+    tracked = scope.catch(() => undefined);
+    chains.set(depthAtEntry, tracked);
+    return scope;
+}
+function createRuntimeForExecSql(execSql) {
+    let activeExecSql = execSql;
+    const db = createClientSQLiteDatabase(() => activeExecSql);
+    async function withActiveExecSql(nextExecSql, operation) {
+        const previousExecSql = activeExecSql;
+        activeExecSql = nextExecSql;
+        try {
+            return await operation();
+        }
+        finally {
+            activeExecSql = previousExecSql;
+        }
+    }
+    const runtime = {
+        db,
+        execSql,
+        runMutation(operation) {
+            return runSerializedSqlMutation(execSql, async (lockedExecSql) => withActiveExecSql(lockedExecSql, () => operation(db)));
+        },
+        transaction(operation, config) {
+            // A caller already inside an open transaction on this connection MUST
+            // reach us through the transaction's locked executor (the runtime that
+            // executor resolves to detects the open transaction below and joins it
+            // as a savepoint scope). Re-entering through the canonical executor
+            // queues here for full isolation — the contract every persistence
+            // helper follows by passing its received locked executor down.
+            const canonical = resolveCanonicalExecSql(execSql);
+            return runSerializedSqlMutation(execSql, async (lockedExecSql) => withActiveExecSql(lockedExecSql, async () => {
+                if ((transactionDepthByCanonicalExecSql.get(canonical) ?? 0) > 0) {
+                    return runNestedSavepointScope(canonical, lockedExecSql, () => operation(db));
+                }
+                transactionDepthByCanonicalExecSql.set(canonical, 1);
+                try {
+                    return await db.transaction(operation, config);
+                }
+                catch (error) {
+                    // The rollback undid any DDL this transaction ran, but the
+                    // per-connection ensure memo still claims it exists — reset it
+                    // so later operations re-ensure instead of hitting missing
+                    // tables.
+                    resetConnectionSchemaMemo(canonical);
+                    throw error;
+                }
+                finally {
+                    transactionDepthByCanonicalExecSql.delete(canonical);
+                }
+            }));
+        },
+        guardedTransaction(operation, canCommit, config) {
+            return runSerializedSqlMutation(execSql, async (lockedExecSql) => withActiveExecSql(lockedExecSql, async () => {
+                const canonical = resolveCanonicalExecSql(execSql);
+                if ((transactionDepthByCanonicalExecSql.get(canonical) ?? 0) > 0) {
+                    throw new Error("guardedTransaction cannot nest inside an open transaction");
+                }
+                transactionDepthByCanonicalExecSql.set(canonical, 1);
+                try {
+                    await lockedExecSql(transactionBeginStatement(config));
+                    const result = await operation(db);
+                    if (!canCommit()) {
+                        await lockedExecSql("ROLLBACK");
+                        resetConnectionSchemaMemo(canonical);
+                        return { committed: false, result: null };
+                    }
+                    // The guard passed in THIS synchronous slice and the COMMIT is
+                    // dispatched in the same slice: no JavaScript can run between
+                    // the two, so the decision cannot go stale before dispatch. (A
+                    // host tearing the connection down concurrently is resolved by
+                    // SQLite's own commit atomicity, not by anything client-side.)
+                    const commit = lockedExecSql("COMMIT");
+                    await commit;
+                    return { committed: true, result };
+                }
+                catch (error) {
+                    await lockedExecSql("ROLLBACK").catch(() => undefined);
+                    resetConnectionSchemaMemo(canonical);
+                    throw error;
+                }
+                finally {
+                    transactionDepthByCanonicalExecSql.delete(canonical);
+                }
+            }));
+        },
+    };
+    runtimeByExecSql.set(execSql, runtime);
+    return runtime;
+}
+export function getClientSQLitePersistenceRuntime(execSql) {
+    return runtimeByExecSql.get(execSql) ?? createRuntimeForExecSql(execSql);
+}
+export function createClientSQLitePersistenceRuntime(client) {
+    let execSql = execSqlByClient.get(client);
+    if (!execSql) {
+        execSql = createExecSql(client);
+        execSqlByClient.set(client, execSql);
+    }
+    return getClientSQLitePersistenceRuntime(execSql);
+}
+//# sourceMappingURL=sqlitePersistenceRuntime.js.map

package/data/sqlite/sqlitePersistenceRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlitePersistenceRuntime.js","sourceRoot":"","sources":["sqlitePersistenceRuntime.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  RemoteCallback,\n  SqliteRemoteDatabase,\n} from \"drizzle-orm/sqlite-proxy\";\nimport { drizzle } from \"drizzle-orm/sqlite-proxy\";\nimport { clientSQLiteSchema } from \"./schema\";\nimport {\n  createExecSql,\n  type ExecSql,\n  type ExecSqlClientLike,\n  resetConnectionSchemaMemo,\n  resolveCanonicalExecSql,\n  runSerializedSqlMutation,\n  type SqlArrayRow,\n  type SqlRowValue,\n} from \"./sqlSchema\";\n\nexport type ClientSQLiteSchema = typeof clientSQLiteSchema;\nexport type ClientSQLiteDatabase = SqliteRemoteDatabase<ClientSQLiteSchema>;\nexport type ClientSQLiteTransactionConfig = NonNullable<\n  Parameters<ClientSQLiteDatabase[\"transaction\"]>[1]\n>;\n/**\n * The handle a runtime transaction callback receives: the transaction's\n * query interface WITHOUT `rollback` (throw instead — every scope maps an\n * exception to its own rollback) and WITHOUT `transaction` (nest by calling\n * `runtime.transaction` again, which scopes to a savepoint). Narrowing the\n * contract here is what lets a nested scope share the connection-backed\n * database handle safely.\n */\nexport type ClientSQLiteTransactionScope = Pick<\n  ClientSQLiteDatabase,\n  | \"all\"\n  | \"delete\"\n  | \"get\"\n  | \"insert\"\n  | \"query\"\n  | \"run\"\n  | \"select\"\n  | \"selectDistinct\"\n  | \"update\"\n  | \"values\"\n>;\n\nexport interface ClientSQLitePersistenceRuntime {\n  db: ClientSQLiteDatabase;\n  execSql: ExecSql;\n  runMutation<T>(\n    operation: (db: ClientSQLiteDatabase) => Promise<T> | T,\n  ): Promise<T>;\n  transaction<T>(\n    operation: (tx: ClientSQLiteTransactionScope) => Promise<T>,\n    config?: ClientSQLiteTransactionConfig,\n  ): Promise<T>;\n  /**\n   * A transaction whose commit is gated on a SYNCHRONOUS guard: the guard\n   * runs and — when it passes — the COMMIT is dispatched in the same\n   * synchronous slice, so no JavaScript (an identity replacement included)\n   * can interleave between the decision and the commit dispatch. Resolves\n   * with `committed: false` (all writes rolled back) when the guard refuses.\n   */\n  guardedTransaction<T>(\n    operation: (tx: ClientSQLiteTransactionScope) => Promise<T>,\n    canCommit: () => boolean,\n    config?: ClientSQLiteTransactionConfig,\n  ): Promise<{ committed: boolean; result: T | null }>;\n}\n\nconst runtimeByExecSql = new WeakMap<ExecSql, ClientSQLitePersistenceRuntime>();\n\nfunction transactionBeginStatement(\n  config: ClientSQLiteTransactionConfig | undefined,\n): \"BEGIN\" | \"BEGIN EXCLUSIVE\" | \"BEGIN IMMEDIATE\" {\n  if (config?.behavior === \"immediate\") return \"BEGIN IMMEDIATE\";\n  if (config?.behavior === \"exclusive\") return \"BEGIN EXCLUSIVE\";\n  return \"BEGIN\";\n}\n\n// One transaction depth per underlying connection (canonical executor), so a\n// runtime.transaction call made while another transaction is already open on\n// the same connection degrades to a SAVEPOINT scope instead of issuing a\n// second BEGIN. Callers inside a serialized mutation get separate runtime\n// instances per locked executor, so the depth cannot live on the runtime.\nconst transactionDepthByCanonicalExecSql = new WeakMap<ExecSql, number>();\n// Sibling nested scopes on one connection must not interleave: SQLite\n// savepoints form a stack, so releasing an earlier savepoint would also\n// release a later sibling started concurrently. Scopes serialize per\n// NESTING DEPTH — siblings share a depth and queue behind each other, while\n// a descendant runs one level deeper and must NOT wait on its own enclosing\n// scope (that wait can never resolve).\nconst nestedScopeChainsByCanonicalExecSql = new WeakMap<\n  ExecSql,\n  Map<number, Promise<unknown>>\n>();\nconst execSqlByClient = new WeakMap<ExecSqlClientLike, ExecSql>();\n\nfunction toSqlRowValue(value: unknown): SqlRowValue {\n  if (value === null || value === undefined) {\n    return null;\n  }\n\n  if (typeof value === \"string\" || typeof value === \"number\") {\n    return value;\n  }\n\n  if (typeof value === \"boolean\") {\n    return value ? 1 : 0;\n  }\n\n  throw new Error(`Unsupported SQLite bind value: ${String(value)}`);\n}\n\nfunction createRemoteCallback(getExecSql: () => ExecSql): RemoteCallback {\n  type RemoteResult = Awaited<ReturnType<RemoteCallback>>;\n\n  function getRemoteResult(rows: readonly SqlArrayRow[]): RemoteResult {\n    const row = rows[0];\n    if (row !== undefined) {\n      return { rows: row } satisfies RemoteResult;\n    }\n\n    // Drizzle's RemoteCallback type requires rows, but sqlite-proxy's get()\n    // mapper treats an undefined rows value as \"no row found\".\n    return Object.defineProperty({ rows: [] } satisfies RemoteResult, \"rows\", {\n      enumerable: true,\n      value: undefined,\n    });\n  }\n\n  return async (sql, params, method) => {\n    const rows = await getExecSql()(sql, params.map(toSqlRowValue), {\n      rowMode: \"array\",\n    });\n\n    if (method === \"get\") {\n      return getRemoteResult(rows);\n    }\n\n    return { rows } satisfies RemoteResult;\n  };\n}\n\nfunction createClientSQLiteDatabase(\n  getExecSql: () => ExecSql,\n): ClientSQLiteDatabase {\n  return drizzle(createRemoteCallback(getExecSql), {\n    schema: clientSQLiteSchema,\n  });\n}\n\n// Serialize nested savepoint scopes per connection AND depth: a sibling\n// (same depth) queues behind the previous sibling so their savepoints\n// strictly nest instead of interleaving on the shared stack, while a\n// descendant (called from inside an executing scope, so one level deeper)\n// starts on its own depth's chain and never waits on its unresolved parent.\nasync function runNestedSavepointScope<T>(\n  canonical: ExecSql,\n  lockedExecSql: ExecSql,\n  operation: () => Promise<T>,\n): Promise<T> {\n  const depthAtEntry = transactionDepthByCanonicalExecSql.get(canonical) ?? 0;\n  const chains =\n    nestedScopeChainsByCanonicalExecSql.get(canonical) ??\n    new Map<number, Promise<unknown>>();\n  nestedScopeChainsByCanonicalExecSql.set(canonical, chains);\n  const previous = chains.get(depthAtEntry) ?? Promise.resolve();\n  let tracked: Promise<unknown> = Promise.resolve();\n  const scope = previous\n    .catch(() => undefined)\n    .then(async () => {\n      const depth = transactionDepthByCanonicalExecSql.get(canonical) ?? 0;\n      transactionDepthByCanonicalExecSql.set(canonical, depth + 1);\n      const savepoint = `runtime_transaction_sp_${depth}`;\n      try {\n        await lockedExecSql(`SAVEPOINT ${savepoint}`);\n        const result = await operation();\n        await lockedExecSql(`RELEASE SAVEPOINT ${savepoint}`);\n        return result;\n      } catch (error: unknown) {\n        await lockedExecSql(`ROLLBACK TO SAVEPOINT ${savepoint}`).catch(\n          () => undefined,\n        );\n        await lockedExecSql(`RELEASE SAVEPOINT ${savepoint}`).catch(\n          () => undefined,\n        );\n        resetConnectionSchemaMemo(canonical);\n        throw error;\n      } finally {\n        transactionDepthByCanonicalExecSql.set(canonical, depth);\n        if (chains.get(depthAtEntry) === tracked) {\n          chains.delete(depthAtEntry);\n        }\n      }\n    });\n  tracked = scope.catch(() => undefined);\n  chains.set(depthAtEntry, tracked);\n  return scope;\n}\n\nfunction createRuntimeForExecSql(\n  execSql: ExecSql,\n): ClientSQLitePersistenceRuntime {\n  let activeExecSql = execSql;\n  const db = createClientSQLiteDatabase(() => activeExecSql);\n\n  async function withActiveExecSql<T>(\n    nextExecSql: ExecSql,\n    operation: () => Promise<T> | T,\n  ): Promise<T> {\n    const previousExecSql = activeExecSql;\n    activeExecSql = nextExecSql;\n\n    try {\n      return await operation();\n    } finally {\n      activeExecSql = previousExecSql;\n    }\n  }\n\n  const runtime: ClientSQLitePersistenceRuntime = {\n    db,\n    execSql,\n    runMutation(operation) {\n      return runSerializedSqlMutation(execSql, async (lockedExecSql) =>\n        withActiveExecSql(lockedExecSql, () => operation(db)),\n      );\n    },\n    transaction(operation, config) {\n      // A caller already inside an open transaction on this connection MUST\n      // reach us through the transaction's locked executor (the runtime that\n      // executor resolves to detects the open transaction below and joins it\n      // as a savepoint scope). Re-entering through the canonical executor\n      // queues here for full isolation — the contract every persistence\n      // helper follows by passing its received locked executor down.\n      const canonical = resolveCanonicalExecSql(execSql);\n      return runSerializedSqlMutation(execSql, async (lockedExecSql) =>\n        withActiveExecSql(lockedExecSql, async () => {\n          if ((transactionDepthByCanonicalExecSql.get(canonical) ?? 0) > 0) {\n            return runNestedSavepointScope(canonical, lockedExecSql, () =>\n              operation(db),\n            );\n          }\n\n          transactionDepthByCanonicalExecSql.set(canonical, 1);\n          try {\n            return await db.transaction(operation, config);\n          } catch (error: unknown) {\n            // The rollback undid any DDL this transaction ran, but the\n            // per-connection ensure memo still claims it exists — reset it\n            // so later operations re-ensure instead of hitting missing\n            // tables.\n            resetConnectionSchemaMemo(canonical);\n            throw error;\n          } finally {\n            transactionDepthByCanonicalExecSql.delete(canonical);\n          }\n        }),\n      );\n    },\n    guardedTransaction(operation, canCommit, config) {\n      return runSerializedSqlMutation(execSql, async (lockedExecSql) =>\n        withActiveExecSql(lockedExecSql, async () => {\n          const canonical = resolveCanonicalExecSql(execSql);\n          if ((transactionDepthByCanonicalExecSql.get(canonical) ?? 0) > 0) {\n            throw new Error(\n              \"guardedTransaction cannot nest inside an open transaction\",\n            );\n          }\n\n          transactionDepthByCanonicalExecSql.set(canonical, 1);\n          try {\n            await lockedExecSql(transactionBeginStatement(config));\n            const result = await operation(db);\n            if (!canCommit()) {\n              await lockedExecSql(\"ROLLBACK\");\n              resetConnectionSchemaMemo(canonical);\n              return { committed: false, result: null };\n            }\n            // The guard passed in THIS synchronous slice and the COMMIT is\n            // dispatched in the same slice: no JavaScript can run between\n            // the two, so the decision cannot go stale before dispatch. (A\n            // host tearing the connection down concurrently is resolved by\n            // SQLite's own commit atomicity, not by anything client-side.)\n            const commit = lockedExecSql(\"COMMIT\");\n            await commit;\n            return { committed: true, result };\n          } catch (error: unknown) {\n            await lockedExecSql(\"ROLLBACK\").catch(() => undefined);\n            resetConnectionSchemaMemo(canonical);\n            throw error;\n          } finally {\n            transactionDepthByCanonicalExecSql.delete(canonical);\n          }\n        }),\n      );\n    },\n  };\n\n  runtimeByExecSql.set(execSql, runtime);\n  return runtime;\n}\n\nexport function getClientSQLitePersistenceRuntime(\n  execSql: ExecSql,\n): ClientSQLitePersistenceRuntime {\n  return runtimeByExecSql.get(execSql) ?? createRuntimeForExecSql(execSql);\n}\n\nexport function createClientSQLitePersistenceRuntime(\n  client: ExecSqlClientLike,\n): ClientSQLitePersistenceRuntime {\n  let execSql = execSqlByClient.get(client);\n  if (!execSql) {\n    execSql = createExecSql(client);\n    execSqlByClient.set(client, execSql);\n  }\n\n  return getClientSQLitePersistenceRuntime(execSql);\n}\n"]}

package/data/sqlite/storagePersistence.d.ts

@@ -0,0 +1,68 @@
+import type { DatabasePersistenceMode } from "../../internal/sqlite-worker/types.js";
+/**
+ * Platform-normalized storage persistence policy.
+ *
+ * Every platform shell (web, capacitor, electrobun) composes its database +
+ * blob-store stack from the same primitives, so the decision of *whether* and
+ * *how* to persist lives here rather than being re-derived in each app entry
+ * point. A policy answers two questions:
+ *
+ *  1. Which SQLite storage backend should the worker use? (`databasePersistence`)
+ *  2. Should we ask the browser to make OPFS durable (exempt from eviction)?
+ *     (`requestPersistentStorage`)
+ *
+ * Both default to the persistent choice; callers on platforms that cannot
+ * persist (or that deliberately want ephemeral storage, e.g. tests) override.
+ */
+export interface StoragePersistencePolicy {
+    /** SQLite worker storage backend. */
+    readonly databasePersistence: DatabasePersistenceMode;
+    /**
+     * When `true`, {@link requestPersistentStorage} will call
+     * `navigator.storage.persist()` so the OPFS-backed SQLite database and blob
+     * store are not evicted under storage pressure.
+     */
+    readonly requestPersistentStorage: boolean;
+}
+/**
+ * Persist everything that can be persisted: OPFS-SAHPool SQLite + a durable
+ * storage request. This is the right default for every shipping platform.
+ */
+export declare const PERSISTENT_STORAGE_POLICY: StoragePersistencePolicy;
+/**
+ * Keep everything in memory and make no durability request. Matches the
+ * historical behavior; useful for tests and for contexts known to lack OPFS.
+ */
+export declare const EPHEMERAL_STORAGE_POLICY: StoragePersistencePolicy;
+/**
+ * Whether the persistent OPFS-SAHPool backend can run in the current context.
+ *
+ * OPFS itself is reachable from both window and worker contexts via
+ * `navigator.storage.getDirectory`. The SAHPool VFS additionally needs the
+ * `Worker`/WASM machinery, which the worker provides; from the main thread we
+ * can only check the OPFS surface, which is the meaningful gate for picking a
+ * policy. The worker performs the authoritative check and hard-fails if the VFS
+ * cannot be installed.
+ */
+export declare function isPersistentStorageSupported(): boolean;
+/**
+ * Resolve the persistence policy for the current platform.
+ *
+ * Pass an explicit `preferred` policy to force a choice (a platform shell that
+ * knows it always has OPFS, or a test that wants ephemeral storage). With no
+ * argument it auto-detects: persistent when OPFS is available, ephemeral
+ * otherwise. Auto-detection never throws — the worker is responsible for the
+ * hard failure when persistence is requested but unavailable.
+ */
+export declare function resolveStoragePersistencePolicy(preferred?: StoragePersistencePolicy): StoragePersistencePolicy;
+export type RequestPersistentStorageResult = "persisted" | "not-persisted" | "unsupported" | "not-requested";
+/**
+ * Ask the browser to make this origin's storage durable so OPFS data (the
+ * SQLite database and the blob store) survives eviction.
+ *
+ * Safe to call repeatedly and on every platform: it is a no-op when the policy
+ * does not request persistence, when the API is unavailable, or when it throws.
+ * The returned value reports what happened for logging/telemetry; callers
+ * generally do not need to branch on it.
+ */
+export declare function requestPersistentStorage(policy: StoragePersistencePolicy): Promise<RequestPersistentStorageResult>;

package/data/sqlite/storagePersistence.js

@@ -0,0 +1,81 @@
+/**
+ * Persist everything that can be persisted: OPFS-SAHPool SQLite + a durable
+ * storage request. This is the right default for every shipping platform.
+ */
+export const PERSISTENT_STORAGE_POLICY = {
+    databasePersistence: "opfs-sahpool",
+    requestPersistentStorage: true,
+};
+/**
+ * Keep everything in memory and make no durability request. Matches the
+ * historical behavior; useful for tests and for contexts known to lack OPFS.
+ */
+export const EPHEMERAL_STORAGE_POLICY = {
+    databasePersistence: "memory",
+    requestPersistentStorage: false,
+};
+/**
+ * Whether the persistent OPFS-SAHPool backend can run in the current context.
+ *
+ * OPFS itself is reachable from both window and worker contexts via
+ * `navigator.storage.getDirectory`. The SAHPool VFS additionally needs the
+ * `Worker`/WASM machinery, which the worker provides; from the main thread we
+ * can only check the OPFS surface, which is the meaningful gate for picking a
+ * policy. The worker performs the authoritative check and hard-fails if the VFS
+ * cannot be installed.
+ */
+export function isPersistentStorageSupported() {
+    return (typeof navigator === "object" &&
+        navigator !== null &&
+        typeof navigator.storage === "object" &&
+        navigator.storage !== null &&
+        typeof navigator.storage.getDirectory === "function");
+}
+/**
+ * Resolve the persistence policy for the current platform.
+ *
+ * Pass an explicit `preferred` policy to force a choice (a platform shell that
+ * knows it always has OPFS, or a test that wants ephemeral storage). With no
+ * argument it auto-detects: persistent when OPFS is available, ephemeral
+ * otherwise. Auto-detection never throws — the worker is responsible for the
+ * hard failure when persistence is requested but unavailable.
+ */
+export function resolveStoragePersistencePolicy(preferred) {
+    if (preferred) {
+        return preferred;
+    }
+    return isPersistentStorageSupported()
+        ? PERSISTENT_STORAGE_POLICY
+        : EPHEMERAL_STORAGE_POLICY;
+}
+/**
+ * Ask the browser to make this origin's storage durable so OPFS data (the
+ * SQLite database and the blob store) survives eviction.
+ *
+ * Safe to call repeatedly and on every platform: it is a no-op when the policy
+ * does not request persistence, when the API is unavailable, or when it throws.
+ * The returned value reports what happened for logging/telemetry; callers
+ * generally do not need to branch on it.
+ */
+export async function requestPersistentStorage(policy) {
+    if (!policy.requestPersistentStorage) {
+        return "not-requested";
+    }
+    const storage = typeof navigator === "object" && navigator !== null
+        ? navigator.storage
+        : undefined;
+    if (!storage || typeof storage.persist !== "function") {
+        return "unsupported";
+    }
+    try {
+        if (typeof storage.persisted === "function" &&
+            (await storage.persisted())) {
+            return "persisted";
+        }
+        return (await storage.persist()) ? "persisted" : "not-persisted";
+    }
+    catch {
+        return "unsupported";
+    }
+}
+//# sourceMappingURL=storagePersistence.js.map

package/data/sqlite/storagePersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storagePersistence.js","sourceRoot":"","sources":["storagePersistence.ts"],"names":[],"mappings":"AA4BA;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAA6B;IACjE,mBAAmB,EAAE,cAAc;IACnC,wBAAwB,EAAE,IAAI;CAC/B,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA6B;IAChE,mBAAmB,EAAE,QAAQ;IAC7B,wBAAwB,EAAE,KAAK;CAChC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B;IAC1C,OAAO,CACL,OAAO,SAAS,KAAK,QAAQ;QAC7B,SAAS,KAAK,IAAI;QAClB,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ;QACrC,SAAS,CAAC,OAAO,KAAK,IAAI;QAC1B,OAAO,SAAS,CAAC,OAAO,CAAC,YAAY,KAAK,UAAU,CACrD,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,+BAA+B,CAC7C,SAAoC;IAEpC,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,4BAA4B,EAAE;QACnC,CAAC,CAAC,yBAAyB;QAC3B,CAAC,CAAC,wBAAwB,CAAC;AAC/B,CAAC;AAQD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAgC;IAEhC,IAAI,CAAC,MAAM,CAAC,wBAAwB,EAAE,CAAC;QACrC,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,MAAM,OAAO,GACX,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI;QACjD,CAAC,CAAC,SAAS,CAAC,OAAO;QACnB,CAAC,CAAC,SAAS,CAAC;IAEhB,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACtD,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,IAAI,CAAC;QACH,IACE,OAAO,OAAO,CAAC,SAAS,KAAK,UAAU;YACvC,CAAC,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC,EAC3B,CAAC;YACD,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,OAAO,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,aAAa,CAAC;IACvB,CAAC;AACH,CAAC","sourcesContent":["import type { DatabasePersistenceMode } from \"@tearleads/sqlite-worker/types\";\n\n/**\n * Platform-normalized storage persistence policy.\n *\n * Every platform shell (web, capacitor, electrobun) composes its database +\n * blob-store stack from the same primitives, so the decision of *whether* and\n * *how* to persist lives here rather than being re-derived in each app entry\n * point. A policy answers two questions:\n *\n *  1. Which SQLite storage backend should the worker use? (`databasePersistence`)\n *  2. Should we ask the browser to make OPFS durable (exempt from eviction)?\n *     (`requestPersistentStorage`)\n *\n * Both default to the persistent choice; callers on platforms that cannot\n * persist (or that deliberately want ephemeral storage, e.g. tests) override.\n */\nexport interface StoragePersistencePolicy {\n  /** SQLite worker storage backend. */\n  readonly databasePersistence: DatabasePersistenceMode;\n  /**\n   * When `true`, {@link requestPersistentStorage} will call\n   * `navigator.storage.persist()` so the OPFS-backed SQLite database and blob\n   * store are not evicted under storage pressure.\n   */\n  readonly requestPersistentStorage: boolean;\n}\n\n/**\n * Persist everything that can be persisted: OPFS-SAHPool SQLite + a durable\n * storage request. This is the right default for every shipping platform.\n */\nexport const PERSISTENT_STORAGE_POLICY: StoragePersistencePolicy = {\n  databasePersistence: \"opfs-sahpool\",\n  requestPersistentStorage: true,\n};\n\n/**\n * Keep everything in memory and make no durability request. Matches the\n * historical behavior; useful for tests and for contexts known to lack OPFS.\n */\nexport const EPHEMERAL_STORAGE_POLICY: StoragePersistencePolicy = {\n  databasePersistence: \"memory\",\n  requestPersistentStorage: false,\n};\n\n/**\n * Whether the persistent OPFS-SAHPool backend can run in the current context.\n *\n * OPFS itself is reachable from both window and worker contexts via\n * `navigator.storage.getDirectory`. The SAHPool VFS additionally needs the\n * `Worker`/WASM machinery, which the worker provides; from the main thread we\n * can only check the OPFS surface, which is the meaningful gate for picking a\n * policy. The worker performs the authoritative check and hard-fails if the VFS\n * cannot be installed.\n */\nexport function isPersistentStorageSupported(): boolean {\n  return (\n    typeof navigator === \"object\" &&\n    navigator !== null &&\n    typeof navigator.storage === \"object\" &&\n    navigator.storage !== null &&\n    typeof navigator.storage.getDirectory === \"function\"\n  );\n}\n\n/**\n * Resolve the persistence policy for the current platform.\n *\n * Pass an explicit `preferred` policy to force a choice (a platform shell that\n * knows it always has OPFS, or a test that wants ephemeral storage). With no\n * argument it auto-detects: persistent when OPFS is available, ephemeral\n * otherwise. Auto-detection never throws — the worker is responsible for the\n * hard failure when persistence is requested but unavailable.\n */\nexport function resolveStoragePersistencePolicy(\n  preferred?: StoragePersistencePolicy,\n): StoragePersistencePolicy {\n  if (preferred) {\n    return preferred;\n  }\n\n  return isPersistentStorageSupported()\n    ? PERSISTENT_STORAGE_POLICY\n    : EPHEMERAL_STORAGE_POLICY;\n}\n\nexport type RequestPersistentStorageResult =\n  | \"persisted\"\n  | \"not-persisted\"\n  | \"unsupported\"\n  | \"not-requested\";\n\n/**\n * Ask the browser to make this origin's storage durable so OPFS data (the\n * SQLite database and the blob store) survives eviction.\n *\n * Safe to call repeatedly and on every platform: it is a no-op when the policy\n * does not request persistence, when the API is unavailable, or when it throws.\n * The returned value reports what happened for logging/telemetry; callers\n * generally do not need to branch on it.\n */\nexport async function requestPersistentStorage(\n  policy: StoragePersistencePolicy,\n): Promise<RequestPersistentStorageResult> {\n  if (!policy.requestPersistentStorage) {\n    return \"not-requested\";\n  }\n\n  const storage =\n    typeof navigator === \"object\" && navigator !== null\n      ? navigator.storage\n      : undefined;\n\n  if (!storage || typeof storage.persist !== \"function\") {\n    return \"unsupported\";\n  }\n\n  try {\n    if (\n      typeof storage.persisted === \"function\" &&\n      (await storage.persisted())\n    ) {\n      return \"persisted\";\n    }\n\n    return (await storage.persist()) ? \"persisted\" : \"not-persisted\";\n  } catch {\n    return \"unsupported\";\n  }\n}\n"]}

package/data/stableUuid.js

@@ -0,0 +1,39 @@
+const TEXT_ENCODER = new TextEncoder();
+function concatenateBytes(left, right) {
+    const bytes = new Uint8Array(left.byteLength + right.byteLength);
+    bytes.set(left, 0);
+    bytes.set(right, left.byteLength);
+    return bytes;
+}
+function byteToHex(byte) {
+    return byte.toString(16).padStart(2, "0");
+}
+function formatUuid(bytes) {
+    const hex = Array.from(bytes, byteToHex).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function toUuidV4ShapedBytes(bytes) {
+    return bytes.slice(0, 16).map((byte, index) => {
+        if (index === 6) {
+            return (byte & 0x0f) | 0x40;
+        }
+        if (index === 8) {
+            return (byte & 0x3f) | 0x80;
+        }
+        return byte;
+    });
+}
+/**
+ * Derives a stable, UUID-shaped id from a 16-byte namespace and a name string.
+ *
+ * The digest (RFC-4122 v5 style: SHA-1 over namespace ++ name) makes the id
+ * idempotent — the same inputs always yield the same id, so a retry after a lost
+ * response re-sends the id the first attempt used. The version and variant bits
+ * are normalized to a v4 shape because the remote APIs validate ids against the
+ * same v4 UUID contract they use for random `crypto.randomUUID()` ids.
+ */
+export async function deriveStableUuidV4Shaped(namespace, name) {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-1", concatenateBytes(namespace, TEXT_ENCODER.encode(name))));
+    return formatUuid(toUuidV4ShapedBytes(digest));
+}
+//# sourceMappingURL=stableUuid.js.map