@haverstack/record-adapter-sqlite 0.21.0 → 0.23.0

package/dist/index.d.ts

@@ -1,7 +1,115 @@
-import { TokenSession, StackRecord, RecordChanges, RecordVersion, ActorOptions, TypeId, StackQuery, QueryResult, FileId, StackType, Association } from '@haverstack/core';
+import { StackRecord, RecordChanges, RecordVersion, ActorOptions, TypeId, StackQuery, QueryResult, FileId, StackType, Association, TokenSession } from '@haverstack/core';
 import { StackRecordAdapter, AdapterCapabilities } from '@haverstack/core/adapter';
 import { StackTokenStore, TokenInfo } from '@haverstack/core/wire';
 
+/**
+ * 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>;
+}
+
 /**
  * Bearer-token storage backing @haverstack/core's StackTokenStore,
  * implemented against its own file — deliberately separate from
@@ -64,12 +172,12 @@ declare class NativeTokenStore implements StackTokenStore {
  * package, which implements @haverstack/core's StackTokenStore against
  * its own file rather than this adapter's records database.
  *
- * This class itself is a thin node:sqlite binding: schema setup,
- * pragmas, and the storage-ownership lock are genuinely engine-specific
- * and live here. The actual StackRecordAdapter logic lives in
- * @haverstack/sqlite-shared's SharedSqlRecordLogic, reached through the
- * SqlExecutor interface (NativeSqliteExecutor here normalizes
- * node:sqlite's spread-args run/get/all calls to it).
+ * This class itself is a thin node:sqlite binding: opening the file, the
+ * storage-ownership lock, and the WAL checkpoint are what's genuinely
+ * engine-specific and live here. Everything above storage comes from
+ * @haverstack/sqlite-shared's SharedSqlRecordAdapter, reached through the
+ * SqlExecutor interface (NativeSqliteExecutor here normalizes node:sqlite's
+ * spread-args run/get/all calls to it).
  */
 
 type NativeRecordInitializeOptions = {
@@ -93,15 +201,17 @@ type NativeRecordOpenOptions = {
      */
     force?: boolean;
 };
-declare class NativeSQLiteRecordAdapter implements StackRecordAdapter {
+declare class NativeSQLiteRecordAdapter extends SharedSqlRecordAdapter {
     private readonly path;
-    readonly capabilities: AdapterCapabilities;
-    ownerEntityId: string;
-    timezone: string | undefined;
-    private db;
-    private record;
+    private readonly db;
     private constructor();
-    private wire;
+    /**
+     * Takes the storage-ownership lock, opens the file, and brings the
+     * schema up. Shared by initialize() and open(), which differ only in
+     * whether the file may already exist and in where the config record
+     * comes from.
+     */
+    private static attach;
     /**
      * Initialize a new stack database. Fails if the file already exists —
      * use open() for existing databases.
@@ -112,47 +222,6 @@ declare class NativeSQLiteRecordAdapter implements StackRecordAdapter {
      * use initialize() for new databases.
      */
     static open(opts: NativeRecordOpenOptions): Promise<NativeSQLiteRecordAdapter>;
-    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>;
     /** Folds the WAL back into the main file — useful before copying/backing up the database. */
     flush(): Promise<void>;
     close(): Promise<void>;