@haverstack/record-adapter-sqlite 0.22.0 → 0.24.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>;

package/dist/index.js

@@ -33,6 +33,11 @@ var RECORD_SCHEMA_SQL = `
   -- a foreign namespace. All four are in the primary key, so two targets
   -- differing only by namespace are two associations.
   --
+  -- attachment_record_id stays out of the primary key: it annotates a
+  -- reference rather than naming one, so re-pointing it updates the row an
+  -- associate() lands on instead of writing a second reference to the same
+  -- file. See docs/spec/attachments.md \xA7 Naming the upload a reference came from.
+  --
   -- The primary key leads with record_id, so its implicit index already
   -- serves every by-record read and delete; the indexes below exist only
   -- for the filter directions it cannot answer.
@@ -45,6 +50,7 @@ var RECORD_SCHEMA_SQL = `
     related_id    TEXT NOT NULL DEFAULT '',
     related_ns    TEXT NOT NULL DEFAULT '',
     related_stack TEXT NOT NULL DEFAULT '',
+    attachment_record_id TEXT NOT NULL DEFAULT '',
     PRIMARY KEY (record_id, kind, label, file_id, related_scope, related_id, related_ns, related_stack)
   ) STRICT;
 
@@ -151,6 +157,12 @@ var FTS5_SCHEMA_SQL = `
 `;
 var PRAGMA_FOREIGN_KEYS_ON = `PRAGMA foreign_keys = ON;`;
 var PRAGMA_JOURNAL_MODE_WAL = `PRAGMA journal_mode = WAL;`;
+var applyRecordSchema = (exec, opts) => {
+  exec.exec(PRAGMA_FOREIGN_KEYS_ON);
+  exec.exec(PRAGMA_JOURNAL_MODE_WAL);
+  exec.exec(RECORD_SCHEMA_SQL);
+  exec.exec(FTS5_SCHEMA_SQL);
+};
 var SORT_FIELDS = NATIVE_SORT_FIELDS;
 var toBase64 = (text) => {
   const bytes = new TextEncoder().encode(text);
@@ -575,10 +587,15 @@ var rowToAssociation = (row) => {
     return { kind: "tag", label: row.label };
   }
   if (row.kind === "attachment") {
+    const attachmentRecordId = row.attachment_record_id;
     return {
       kind: "attachment",
       label: row.label,
-      fileId: row.file_id
+      fileId: row.file_id,
+      // Stored as '' when absent, like every other optional column here —
+      // the field is omitted rather than served empty, so a round trip
+      // produces the association the caller wrote.
+      ...attachmentRecordId && { attachmentRecordId }
     };
   }
   return {
@@ -650,18 +667,26 @@ var isForeignKeyViolation = (err) => err instanceof Error && err.message.include
 var isUniqueConstraintViolation = (err) => err instanceof Error && err.message.includes("UNIQUE constraint failed");
 
 // ../sqlite-shared/dist/config.js
+var CONFIG_ROW_SQL = `SELECT content FROM records WHERE id = '_config'`;
 var insertConfigRecord = (exec, entityId, timezone) => {
   const now = Date.now();
   exec.run(`INSERT INTO records (id, type_id, created_at, updated_at, content, version)
      VALUES ('_config', '_config@1', ?, ?, ?, 1)`, [now, now, JSON.stringify({ entityId, timezone })]);
+  return { entityId, timezone };
 };
-var readStackConfig = (exec) => {
-  const row = exec.get(`SELECT content FROM records WHERE id = '_config'`);
+var tryReadStackConfig = (exec) => {
+  const row = exec.get(CONFIG_ROW_SQL);
   if (!row)
-    throw new Error("Stack database is missing its config record.");
+    return null;
   const content = JSON.parse(row.content);
   return { entityId: content.entityId, timezone: content.timezone };
 };
+var readStackConfig = (exec) => {
+  const config = tryReadStackConfig(exec);
+  if (!config)
+    throw new Error("Stack database is missing its config record.");
+  return config;
+};
 var asStackQueryError = (query, run) => {
   try {
     return run();
@@ -1189,6 +1214,10 @@ var SharedSqlRecordLogic = class {
       this.insertAssociations(recordId, associations);
   }
   /**
+   * Upserts on association identity: the primary key decides which row a
+   * write lands on, and `attachment_record_id` — outside it — is whatever
+   * the incoming association says, so re-pointing one costs no second row.
+   *
    * FK enforcement (PRAGMA_FOREIGN_KEYS_ON) means inserting an
    * association against a record that doesn't exist throws — mapped
    * here to StackNotFoundError so associate() on a nonexistent record
@@ -1197,9 +1226,17 @@ var SharedSqlRecordLogic = class {
   insertAssociations(recordId, associations) {
     for (const assoc of associations) {
       try {
-        this.exec.run(`INSERT OR IGNORE INTO associations
-            (record_id, kind, label, file_id, related_scope, related_id, related_ns, related_stack)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [recordId, assoc.kind, assoc.label, ...associationKeyColumns(assoc)]);
+        this.exec.run(`INSERT INTO associations
+            (record_id, kind, label, file_id, related_scope, related_id, related_ns,
+             related_stack, attachment_record_id)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT DO UPDATE SET attachment_record_id = excluded.attachment_record_id`, [
+          recordId,
+          assoc.kind,
+          assoc.label,
+          ...associationKeyColumns(assoc),
+          assoc.kind === "attachment" ? assoc.attachmentRecordId ?? "" : ""
+        ]);
       } catch (err) {
         if (isForeignKeyViolation(err)) {
           throw new StackNotFoundError(`Record not found: "${recordId}"`);
@@ -1258,6 +1295,97 @@ var SharedSqlRecordLogic = class {
     return this.getIndexedFields(record.typeId).get(field);
   }
 };
+
+// ../sqlite-shared/dist/record-adapter.js
+var SQLITE_RECORD_CAPABILITIES = {
+  filter: {
+    content: "path",
+    contentPresent: true,
+    search: true
+  },
+  sort: {
+    fields: ["createdAt", "updatedAt", "version"],
+    contentField: true
+  },
+  limits: {
+    attachmentBytes: null,
+    contentBytes: null
+  }
+};
+var SharedSqlRecordAdapter = class {
+  capabilities = SQLITE_RECORD_CAPABILITIES;
+  ownerEntityId;
+  timezone;
+  record;
+  constructor(exec, config) {
+    this.record = new SharedSqlRecordLogic({ exec });
+    this.ownerEntityId = config.entityId;
+    this.timezone = config.timezone;
+  }
+  // -------------------------------------------------------
+  // Records
+  // -------------------------------------------------------
+  createRecord(record) {
+    return this.record.createRecord(record);
+  }
+  getRecord(id) {
+    return this.record.getRecord(id);
+  }
+  mutateRecord(id, changes, opts) {
+    return this.record.mutateRecord(id, changes, opts);
+  }
+  deleteRecord(id, opts) {
+    return this.record.deleteRecord(id, opts);
+  }
+  undeleteRecord(id, opts) {
+    return this.record.undeleteRecord(id, opts);
+  }
+  restoreVersion(id, version, opts) {
+    return this.record.restoreVersion(id, version, opts);
+  }
+  commitMigration(id, toTypeId, content, opts) {
+    return this.record.commitMigration(id, toTypeId, content, opts);
+  }
+  queryRecords(query) {
+    return this.record.queryRecords(query);
+  }
+  deleteUnreferencedAttachmentRecords(fileId, metadataTypeIds) {
+    return this.record.deleteUnreferencedAttachmentRecords(fileId, metadataTypeIds);
+  }
+  // -------------------------------------------------------
+  // Versions
+  // -------------------------------------------------------
+  getVersions(id) {
+    return this.record.getVersions(id);
+  }
+  getVersion(id, version) {
+    return this.record.getVersion(id, version);
+  }
+  saveVersion(id, version) {
+    return this.record.saveVersion(id, version);
+  }
+  // -------------------------------------------------------
+  // Types
+  // -------------------------------------------------------
+  saveType(type) {
+    return this.record.saveType(type);
+  }
+  getType(id) {
+    return this.record.getType(id);
+  }
+  listTypes() {
+    return this.record.listTypes();
+  }
+  // -------------------------------------------------------
+  // Associations
+  // -------------------------------------------------------
+  associate(recordId, association, opts) {
+    return this.record.associate(recordId, association, opts);
+  }
+  dissociate(recordId, association, opts) {
+    return this.record.dissociate(recordId, association, opts);
+  }
+};
 var lockPathFor = (dbPath) => `${dbPath}.lock`;
 var isProcessAlive = (pid) => {
   try {
@@ -1415,33 +1543,26 @@ var NativeTokenStore = class _NativeTokenStore {
 };
 
 // src/index.ts
-var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter {
-  constructor(path) {
+var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter extends SharedSqlRecordAdapter {
+  constructor(path, db, exec, config) {
+    super(exec, config);
     this.path = path;
+    this.db = db;
   }
   path;
-  capabilities = {
-    filter: {
-      content: "path",
-      contentPresent: true,
-      search: true
-    },
-    sort: {
-      fields: ["createdAt", "updatedAt", "version"],
-      contentField: true
-    },
-    limits: {
-      attachmentBytes: null,
-      contentBytes: null
-    }
-  };
-  ownerEntityId;
-  timezone;
   db;
-  record;
-  wire() {
-    const exec = new NativeSqliteExecutor(this.db);
-    this.record = new SharedSqlRecordLogic({ exec });
+  /**
+   * 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.
+   */
+  static attach(path, force) {
+    acquireLock(path, force);
+    const db = new DatabaseSync(path);
+    const exec = new NativeSqliteExecutor(db);
+    applyRecordSchema(exec);
+    return [db, exec];
   }
   /**
    * Initialize a new stack database. Fails if the file already exists —
@@ -1453,18 +1574,9 @@ var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter {
         `Cannot initialize: database already exists at "${opts.path}". Use NativeSQLiteRecordAdapter.open() instead.`
       );
     }
-    acquireLock(opts.path, opts.force);
-    const adapter = new _NativeSQLiteRecordAdapter(opts.path);
-    adapter.db = new DatabaseSync(opts.path);
-    adapter.db.exec(PRAGMA_FOREIGN_KEYS_ON);
-    adapter.db.exec(PRAGMA_JOURNAL_MODE_WAL);
-    adapter.db.exec(RECORD_SCHEMA_SQL);
-    adapter.db.exec(FTS5_SCHEMA_SQL);
-    adapter.wire();
-    insertConfigRecord(new NativeSqliteExecutor(adapter.db), opts.entityId, opts.timezone);
-    adapter.ownerEntityId = opts.entityId;
-    adapter.timezone = opts.timezone;
-    return adapter;
+    const [db, exec] = _NativeSQLiteRecordAdapter.attach(opts.path, opts.force);
+    const config = insertConfigRecord(exec, opts.entityId, opts.timezone);
+    return new _NativeSQLiteRecordAdapter(opts.path, db, exec, config);
   }
   /**
    * Open an existing stack database. Fails if the file does not exist —
@@ -1476,81 +1588,8 @@ var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter {
         `Cannot open: no database found at "${opts.path}". Use NativeSQLiteRecordAdapter.initialize() to create one.`
       );
     }
-    acquireLock(opts.path, opts.force);
-    const adapter = new _NativeSQLiteRecordAdapter(opts.path);
-    adapter.db = new DatabaseSync(opts.path);
-    adapter.db.exec(PRAGMA_FOREIGN_KEYS_ON);
-    adapter.db.exec(PRAGMA_JOURNAL_MODE_WAL);
-    adapter.db.exec(RECORD_SCHEMA_SQL);
-    adapter.db.exec(FTS5_SCHEMA_SQL);
-    adapter.wire();
-    const config = readStackConfig(new NativeSqliteExecutor(adapter.db));
-    adapter.ownerEntityId = config.entityId;
-    adapter.timezone = config.timezone;
-    return adapter;
-  }
-  // -------------------------------------------------------
-  // Records
-  // -------------------------------------------------------
-  createRecord(record) {
-    return this.record.createRecord(record);
-  }
-  getRecord(id) {
-    return this.record.getRecord(id);
-  }
-  mutateRecord(id, changes, opts) {
-    return this.record.mutateRecord(id, changes, opts);
-  }
-  deleteRecord(id, opts) {
-    return this.record.deleteRecord(id, opts);
-  }
-  undeleteRecord(id, opts) {
-    return this.record.undeleteRecord(id, opts);
-  }
-  restoreVersion(id, version, opts) {
-    return this.record.restoreVersion(id, version, opts);
-  }
-  commitMigration(id, toTypeId, content, opts) {
-    return this.record.commitMigration(id, toTypeId, content, opts);
-  }
-  queryRecords(query) {
-    return this.record.queryRecords(query);
-  }
-  deleteUnreferencedAttachmentRecords(fileId, metadataTypeIds) {
-    return this.record.deleteUnreferencedAttachmentRecords(fileId, metadataTypeIds);
-  }
-  // -------------------------------------------------------
-  // Versions
-  // -------------------------------------------------------
-  getVersions(id) {
-    return this.record.getVersions(id);
-  }
-  getVersion(id, version) {
-    return this.record.getVersion(id, version);
-  }
-  saveVersion(id, version) {
-    return this.record.saveVersion(id, version);
-  }
-  // -------------------------------------------------------
-  // Types
-  // -------------------------------------------------------
-  saveType(type) {
-    return this.record.saveType(type);
-  }
-  getType(id) {
-    return this.record.getType(id);
-  }
-  listTypes() {
-    return this.record.listTypes();
-  }
-  // -------------------------------------------------------
-  // Associations
-  // -------------------------------------------------------
-  associate(recordId, association, opts) {
-    return this.record.associate(recordId, association, opts);
-  }
-  dissociate(recordId, association, opts) {
-    return this.record.dissociate(recordId, association, opts);
+    const [db, exec] = _NativeSQLiteRecordAdapter.attach(opts.path, opts.force);
+    return new _NativeSQLiteRecordAdapter(opts.path, db, exec, readStackConfig(exec));
   }
   // -------------------------------------------------------
   // Lifecycle