@haverstack/record-adapter-do-sqlite 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -1,6 +1,113 @@
 import { StackRecord, RecordChanges, RecordVersion, ActorOptions, TypeId, StackQuery, QueryResult, FileId, StackType, Association } from '@haverstack/core';
 import { StackRecordAdapter, AdapterCapabilities } from '@haverstack/core/adapter';
-import { SqlExecutor } from '@haverstack/sqlite-shared/record';
+
+/**
+ * Normalizes a SQLite binding's call convention (array-bind-then-step,
+ * spread-args run/get/all, cursor-returning exec) behind one interface,
+ * so the actual CRUD/query/version/type/association/token logic can live
+ * once in this package instead of being re-typed per engine. Each adapter
+ * package provides a thin SqlExecutor implementation over its own
+ * database handle.
+ *
+ * Deliberately synchronous: every binding this targets executes queries
+ * in-process without yielding, and an async interface would force the
+ * shared logic's transaction sequences to interleave.
+ */
+interface SqlExecutor {
+    /** Run DDL, pragmas, or any statement(s) with no bound params and no results needed. */
+    exec(sql: string): void;
+    /** Run a single parameterized statement. Returns the number of rows affected (INSERT/UPDATE/DELETE). */
+    run(sql: string, params?: readonly unknown[]): number;
+    /** Run a parameterized statement and return the first result row, or undefined. */
+    get<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): T | undefined;
+    /** Run a parameterized statement and return all result rows. */
+    all<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): T[];
+    /**
+     * Run `fn` atomically: every statement it issues commits together, or
+     * none do if it throws. `fn` must be synchronous and call back into
+     * this executor only — not every engine's transaction primitive can
+     * straddle a suspended call. A binding with a real multi-statement
+     * transaction (BEGIN/COMMIT/ROLLBACK) implements this with one; a
+     * binding whose transaction primitive is itself a callback wrapper
+     * (e.g. a Durable Object's storage.transactionSync) can pass `fn`
+     * straight through to it.
+     */
+    transaction<T>(fn: () => T): T;
+}
+
+/** timezone is optional passthrough app metadata — no default. */
+type StackConfig = {
+    entityId: string;
+    timezone: string | undefined;
+};
+
+/**
+ * The engine-independent half of a SQLite-backed StackRecordAdapter: the
+ * capability declaration and the delegation of all seventeen
+ * StackRecordAdapter methods onto SharedSqlRecordLogic. Every method here
+ * is a forward with no engine-specific content, so an adapter that owns a
+ * SqlExecutor already knows how to answer all of them.
+ *
+ * What a concrete adapter is left to supply is exactly what differs
+ * between bindings: constructing the database handle, applying the
+ * schema, and its own lifecycle (flush/close) — hence those two being the
+ * only abstract members.
+ *
+ * Lives in record.js's barrel rather than index.js's, so an adapter that
+ * imports it never pulls in token-logic.ts's `node:crypto` — see the note
+ * at the top of record.ts.
+ */
+
+declare abstract class SharedSqlRecordAdapter implements StackRecordAdapter {
+    readonly capabilities: AdapterCapabilities;
+    readonly ownerEntityId: string;
+    readonly timezone: string | undefined;
+    private readonly record;
+    protected constructor(exec: SqlExecutor, config: StackConfig);
+    createRecord(record: StackRecord): Promise<StackRecord>;
+    getRecord(id: string): Promise<StackRecord | null>;
+    mutateRecord(id: string, changes: RecordChanges, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    deleteRecord(id: string, opts?: {
+        hard?: boolean;
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord | null>;
+    undeleteRecord(id: string, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    restoreVersion(id: string, version: number, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & {
+        restoreAssociations?: boolean;
+    } & ActorOptions): Promise<StackRecord>;
+    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    queryRecords(query: StackQuery): Promise<QueryResult>;
+    deleteUnreferencedAttachmentRecords(fileId: FileId, metadataTypeIds: TypeId[]): Promise<StackRecord[]>;
+    getVersions(id: string): Promise<RecordVersion[]>;
+    getVersion(id: string, version: number): Promise<RecordVersion | null>;
+    saveVersion(id: string, version: RecordVersion): Promise<void>;
+    saveType(type: StackType): Promise<void>;
+    getType(id: TypeId): Promise<StackType | null>;
+    listTypes(): Promise<StackType[]>;
+    associate(recordId: string, association: Association, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    dissociate(recordId: string, association: Association, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    abstract flush(): Promise<void>;
+    abstract close(): Promise<void>;
+}
 
 /**
  * Normalizes a Durable Object's ctx.storage.sql to SqlExecutor.
@@ -47,12 +154,12 @@ declare class DurableObjectSqliteExecutor implements SqlExecutor {
  * call returns, so flush()/close() are no-ops kept only to satisfy the
  * optional StackRecordAdapter methods.
  *
- * This class itself is a thin binding: schema setup and the one piece of
- * genuinely engine-specific wiring — SqlExecutor.transaction() reaching
+ * This class itself is a thin binding: the one piece of genuinely
+ * engine-specific wiring — SqlExecutor.transaction() reaching
  * ctx.storage.transactionSync() instead of raw SQL BEGIN/COMMIT/ROLLBACK,
- * which DO SQLite rejects outright — live here (see executor.ts). The
- * actual StackRecordAdapter logic lives in @haverstack/sqlite-shared's
- * SharedSqlRecordLogic, exactly as it does for record-adapter-sqlite.
+ * which DO SQLite rejects outright — lives in executor.ts. Everything
+ * above storage comes from @haverstack/sqlite-shared's
+ * SharedSqlRecordAdapter, exactly as it does for record-adapter-sqlite.
  */
 
 type DoRecordCreateOptions = {
@@ -61,12 +168,7 @@ type DoRecordCreateOptions = {
     /** IANA timezone string e.g. "America/New_York". Optional passthrough app metadata — no default. */
     timezone?: string;
 };
-declare class DoSQLiteRecordAdapter implements StackRecordAdapter {
-    private readonly exec;
-    readonly capabilities: AdapterCapabilities;
-    ownerEntityId: string;
-    timezone: string | undefined;
-    private readonly record;
+declare class DoSQLiteRecordAdapter extends SharedSqlRecordAdapter {
     private constructor();
     /**
      * Create (or reattach to) the adapter for a DO instance. There is no
@@ -76,49 +178,12 @@ declare class DoSQLiteRecordAdapter implements StackRecordAdapter {
      * or it doesn't (first call — opts.entityId/timezone become the config).
      * Schema DDL is `CREATE TABLE IF NOT EXISTS`, so running it every call
      * is idempotent and cheap.
+     *
+     * DO SQLite manages its own durability and rejects PRAGMA journal_mode
+     * outright ("not authorized") — verified against the real runtime, not
+     * assumed — hence `wal: false`, unlike record-adapter-sqlite.
      */
     static create(storage: DurableObjectStorage, opts: DoRecordCreateOptions): Promise<DoSQLiteRecordAdapter>;
-    createRecord(record: StackRecord): Promise<StackRecord>;
-    getRecord(id: string): Promise<StackRecord | null>;
-    mutateRecord(id: string, changes: RecordChanges, opts?: {
-        expectedVersion?: number;
-        snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord>;
-    deleteRecord(id: string, opts?: {
-        hard?: boolean;
-        expectedVersion?: number;
-        snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord | null>;
-    undeleteRecord(id: string, opts?: {
-        expectedVersion?: number;
-        snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord>;
-    restoreVersion(id: string, version: number, opts?: {
-        expectedVersion?: number;
-        snapshot?: RecordVersion;
-    } & {
-        restoreAssociations?: boolean;
-    } & ActorOptions): Promise<StackRecord>;
-    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: {
-        expectedVersion?: number;
-        snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord>;
-    queryRecords(query: StackQuery): Promise<QueryResult>;
-    deleteUnreferencedAttachmentRecords(fileId: FileId, metadataTypeIds: TypeId[]): Promise<StackRecord[]>;
-    getVersions(id: string): Promise<RecordVersion[]>;
-    getVersion(id: string, version: number): Promise<RecordVersion | null>;
-    saveVersion(id: string, version: RecordVersion): Promise<void>;
-    saveType(type: StackType): Promise<void>;
-    getType(id: TypeId): Promise<StackType | null>;
-    listTypes(): Promise<StackType[]>;
-    associate(recordId: string, association: Association, opts?: {
-        expectedVersion?: number;
-        snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord>;
-    dissociate(recordId: string, association: Association, opts?: {
-        expectedVersion?: number;
-        snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord>;
     /** No-op: every write through ctx.storage.sql is already durable. */
     flush(): Promise<void>;
     /** No-op: no lock file, no connection to release — the DO's own lifecycle governs storage. */