@haverstack/record-adapter-do-sqlite 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StackRecord, RecordChanges, RecordVersion, ActorOptions, TypeId, StackQuery, QueryResult, FileId, StackType, Association } from '@haverstack/core';
+import { StackRecord, JournalOptions, RecordChanges, RecordVersion, ActorOptions, TypeId, StackQuery, QueryResult, FileId, JournalQuery, RecordJournalEntry, StackType, Association } from '@haverstack/core';
 import { StackRecordAdapter, AdapterCapabilities } from '@haverstack/core/adapter';
 
 /**
@@ -64,47 +64,41 @@ declare abstract class SharedSqlRecordAdapter implements StackRecordAdapter {
     readonly timezone: string | undefined;
     private readonly record;
     protected constructor(exec: SqlExecutor, config: StackConfig);
-    createRecord(record: StackRecord): Promise<StackRecord>;
+    createRecord(record: StackRecord, opts?: JournalOptions): Promise<StackRecord>;
     getRecord(id: string): Promise<StackRecord | null>;
     mutateRecord(id: string, changes: RecordChanges, opts?: {
         expectedVersion?: number;
         snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord>;
+        bumpsVersion?: boolean;
+    } & ActorOptions & JournalOptions): Promise<StackRecord>;
     deleteRecord(id: string, opts?: {
         hard?: boolean;
         expectedVersion?: number;
         snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord | null>;
+    } & ActorOptions & JournalOptions): Promise<StackRecord | null>;
     undeleteRecord(id: string, opts?: {
         expectedVersion?: number;
         snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord>;
+    } & ActorOptions & JournalOptions): Promise<StackRecord>;
     restoreVersion(id: string, version: number, opts?: {
         expectedVersion?: number;
         snapshot?: RecordVersion;
-    } & {
-        restoreAssociations?: boolean;
-    } & ActorOptions): Promise<StackRecord>;
+    } & ActorOptions & JournalOptions): Promise<StackRecord>;
     commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: {
         expectedVersion?: number;
         snapshot?: RecordVersion;
-    } & ActorOptions): Promise<StackRecord>;
+    } & ActorOptions & JournalOptions): 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>;
+    getJournal(id: string, query?: JournalQuery): Promise<RecordJournalEntry[]>;
     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>;
+    associate(recordId: string, association: Association, opts?: JournalOptions): Promise<StackRecord>;
+    dissociate(recordId: string, association: Association, opts?: JournalOptions): Promise<StackRecord>;
     abstract flush(): Promise<void>;
     abstract close(): Promise<void>;
 }

package/dist/index.js

@@ -50,6 +50,9 @@ var RECORD_SCHEMA_SQL = `
   -- parent_id holds the container the record sat in, NULL for the root --
   -- the same encoding records.parent_id uses, since a snapshot states
   -- where the record was rather than an instruction to apply.
+  -- No associations column: associate()/dissociate() don't bump version,
+  -- so no version ever snapshots the association set. See
+  -- docs/spec/versioning.md \xA7 Version history.
   CREATE TABLE IF NOT EXISTS versions (
     record_id   TEXT NOT NULL REFERENCES records(id),
     version     INTEGER NOT NULL,
@@ -60,11 +63,39 @@ var RECORD_SCHEMA_SQL = `
     updated_by  TEXT,
     updated_via TEXT,
     parent_id   TEXT,
-    associations TEXT CHECK (associations IS NULL OR json_valid(associations)),
     permissions  TEXT CHECK (permissions IS NULL OR json_valid(permissions)),
     PRIMARY KEY (record_id, version)
   ) STRICT;
 
+  -- The durable half of a change event: which aspects moved, who moved
+  -- them, and the association deltas nothing else retains. Envelope-level
+  -- by design \u2014 content lives on a versions row, and copying it here
+  -- would make the journal the larger of the two stores.
+  -- See docs/spec/journal.md.
+  CREATE TABLE IF NOT EXISTS journal (
+    record_id   TEXT NOT NULL REFERENCES records(id),
+    seq         INTEGER NOT NULL,
+    at          INTEGER NOT NULL,
+    -- No 'purged': a purge destroys the log rather than appending to it,
+    -- so the constraint names exactly the kinds an entry can carry.
+    -- See docs/spec/journal.md \xA7 A hard delete destroys the journal.
+    kind        TEXT NOT NULL CHECK (kind IN ('created', 'changed', 'deleted')),
+    ops         TEXT NOT NULL CHECK (json_valid(ops)),
+    version     INTEGER NOT NULL,
+    type_id     TEXT NOT NULL,
+    parent_id   TEXT,
+    -- NULL means the entry names no origin (the record did not move);
+    -- '' means it moved off the root. parent_id above needs no such
+    -- spelling: it is state, where this is a key that may be absent --
+    -- the same input/state split parentId follows everywhere.
+    previous_parent_id TEXT,
+    actor       TEXT CHECK (actor IS NULL OR json_valid(actor)),
+    -- One tagged edit per association the write moved, each carrying the
+    -- state it displaced. See docs/spec/journal.md \xA7 The entry.
+    associations TEXT CHECK (associations IS NULL OR json_valid(associations)),
+    PRIMARY KEY (record_id, seq)
+  ) STRICT;
+
   CREATE TABLE IF NOT EXISTS types (
     id            TEXT PRIMARY KEY,
     base_id       TEXT NOT NULL,
@@ -635,12 +666,30 @@ var rowToVersion = (row) => {
     v.updatedVia = row.updated_via;
   if (row.parent_id != null)
     v.parentId = row.parent_id;
-  if (row.associations != null)
-    v.associations = JSON.parse(row.associations);
   if (row.permissions != null)
     v.permissions = JSON.parse(row.permissions);
   return v;
 };
+var rowToJournalEntry = (row) => {
+  const e = {
+    seq: row.seq,
+    at: fromMs(row.at),
+    kind: row.kind,
+    ops: JSON.parse(row.ops),
+    version: row.version,
+    typeId: row.type_id
+  };
+  if (row.parent_id != null)
+    e.parentId = row.parent_id;
+  if (row.previous_parent_id != null) {
+    e.previousParentId = row.previous_parent_id === "" ? null : row.previous_parent_id;
+  }
+  if (row.actor != null)
+    e.actor = JSON.parse(row.actor);
+  if (row.associations != null)
+    e.associations = JSON.parse(row.associations);
+  return e;
+};
 
 // ../sqlite-shared/dist/executor.js
 var isForeignKeyViolation = (err) => err instanceof Error && err.message.includes("FOREIGN KEY constraint failed");
@@ -679,7 +728,6 @@ var VERSION_COLUMNS = [
   "updated_by",
   "updated_via",
   "parent_id",
-  "associations",
   "permissions"
 ];
 var versionRowValues = (version) => [
@@ -690,7 +738,6 @@ var versionRowValues = (version) => [
   version.updatedBy ?? null,
   version.updatedVia ?? null,
   version.parentId ?? null,
-  version.associations ? JSON.stringify(version.associations) : null,
   version.permissions ? JSON.stringify(version.permissions) : null
 ];
 var indexedFieldKinds = (schema) => {
@@ -794,41 +841,51 @@ var SharedSqlRecordLogic = class {
    * A duplicate id hits the `records` PK — mapped to StackConflictError
    * instead of surfacing the raw engine exception, mirroring saveVersion's
    * collision mapping below.
+   *
+   * One transaction, because a record and the four tables that describe it
+   * are one fact. A half-applied create is worse than a failed one: the
+   * call raises, so the caller believes nothing landed, while the records
+   * row survives to fail their retry on the PK — and the row it leaves is
+   * invisible to `filter.search` and mis-ordered by `sort.contentField`
+   * until something writes it again.
    */
-  async createRecord(record) {
-    try {
-      this.exec.run(`INSERT INTO records
+  async createRecord(record, opts = {}) {
+    this.exec.transaction(() => {
+      try {
+        this.exec.run(`INSERT INTO records
           (id, type_id, created_at, updated_at, content, version,
            parent_id, entity_id, app_id, principal_id, updated_by, updated_via,
            deleted_at, unlisted_at, permissions)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
-        record.id,
-        record.typeId,
-        toMs(record.createdAt),
-        toMs(record.updatedAt),
-        JSON.stringify(record.content),
-        record.version,
-        record.parentId ?? null,
-        record.entityId ?? null,
-        record.appId ?? null,
-        record.principalId ?? null,
-        record.updatedBy ?? null,
-        record.updatedVia ?? null,
-        record.deletedAt ? toMs(record.deletedAt) : null,
-        record.unlistedAt ? toMs(record.unlistedAt) : null,
-        record.permissions ? JSON.stringify(record.permissions) : null
-      ]);
-    } catch (err) {
-      if (isUniqueConstraintViolation(err)) {
-        throw new StackConflictError(`Record already exists: "${record.id}"`);
+          record.id,
+          record.typeId,
+          toMs(record.createdAt),
+          toMs(record.updatedAt),
+          JSON.stringify(record.content),
+          record.version,
+          record.parentId ?? null,
+          record.entityId ?? null,
+          record.appId ?? null,
+          record.principalId ?? null,
+          record.updatedBy ?? null,
+          record.updatedVia ?? null,
+          record.deletedAt ? toMs(record.deletedAt) : null,
+          record.unlistedAt ? toMs(record.unlistedAt) : null,
+          record.permissions ? JSON.stringify(record.permissions) : null
+        ]);
+      } catch (err) {
+        if (isUniqueConstraintViolation(err)) {
+          throw new StackConflictError(`Record already exists: "${record.id}"`);
+        }
+        throw err;
       }
-      throw err;
-    }
-    if (record.associations?.length) {
-      this.insertAssociations(record.id, record.associations);
-    }
-    fts5Strategy.insert(this.exec, record.id, JSON.stringify(record.content));
-    this.syncContentIndex(record.id, record.typeId, record.content);
+      if (record.associations?.length) {
+        this.insertAssociations(record.id, record.associations);
+      }
+      fts5Strategy.insert(this.exec, record.id, JSON.stringify(record.content));
+      this.syncContentIndex(record.id, record.typeId, record.content);
+      this.appendJournal(record.id, opts.journal);
+    });
     return record;
   }
   async getRecord(id) {
@@ -861,17 +918,40 @@ var SharedSqlRecordLogic = class {
    * replaced when it carries one, and the snapshot written alongside — so
    * one call is one version whatever it moved.
    *
-   * The expectedVersion check is standalone rather than folded into the
-   * UPDATE alone, because a content change needs fts.remove() to run
-   * *before* the records-table content changes. The guard is still in the
-   * UPDATE's WHERE, so a writer that slipped in between the read and the
-   * write is caught there rather than overwriting.
+   * `opts.bumpsVersion: false` is a change set that touches only
+   * `associations` — Stack computes this from which ops the set actually
+   * moves. Such a write skips the records-table UPDATE (and the snapshot)
+   * entirely: nothing on that row changes, so there is nothing to bump and
+   * no version to snapshot. `expectedVersion`, if given, is still
+   * re-checked synchronously inside the transaction — the CAS guard the
+   * bumping path gets from its UPDATE's WHERE clause, restated as a read
+   * because there is no UPDATE here to carry it. See
+   * docs/spec/versioning.md § Version history.
+   *
+   * The expectedVersion check for a bumping write is standalone rather than
+   * folded into the UPDATE alone, because a content change needs
+   * fts.remove() to run *before* the records-table content changes. The
+   * guard is still in the UPDATE's WHERE, so a writer that slipped in
+   * between the read and the write is caught there rather than overwriting.
    */
   async mutateRecord(id, changes, opts = {}) {
     const existing = await this.getRecord(id);
     if (!existing)
       throw new StackNotFoundError(`Record not found: "${id}"`);
     this.checkExpectedVersion(existing, opts.expectedVersion);
+    if (opts.bumpsVersion === false) {
+      this.exec.transaction(() => {
+        const current = this.readRecord(id);
+        if (!current)
+          throw new StackNotFoundError(`Record not found: "${id}"`);
+        this.checkExpectedVersion(current, opts.expectedVersion);
+        if (changes.associations !== void 0) {
+          this.replaceAssociations(id, changes.associations);
+        }
+        this.appendJournal(id, opts.journal);
+      });
+      return this.reread(id, "mutateRecord");
+    }
     const merged = changes.contentPatch ? applyMergePatch(existing.content, changes.contentPatch) : void 0;
     const sets = [];
     const values = [];
@@ -905,6 +985,7 @@ var SharedSqlRecordLogic = class {
         fts5Strategy.insert(this.exec, id, JSON.stringify(merged));
         this.syncContentIndex(id, existing.typeId, merged);
       }
+      this.appendJournal(id, opts.journal);
     });
     return this.reread(id, "mutateRecord");
   }
@@ -917,6 +998,7 @@ var SharedSqlRecordLogic = class {
       if (opts.snapshot)
         this.snapshotBeforeMutation(id, opts.snapshot);
       this.versionedUpdate(id, ["deleted_at = ?"], [now], opts, now);
+      this.appendJournal(id, opts.journal);
     });
     return this.reread(id, "deleteRecord");
   }
@@ -940,6 +1022,7 @@ var SharedSqlRecordLogic = class {
     fts5Strategy.remove(this.exec, id);
     this.exec.run("DELETE FROM associations WHERE record_id = ?", [id]);
     this.exec.run("DELETE FROM versions WHERE record_id = ?", [id]);
+    this.exec.run("DELETE FROM journal WHERE record_id = ?", [id]);
     this.exec.run("DELETE FROM content_index WHERE record_id = ?", [id]);
     this.exec.run("DELETE FROM records WHERE id = ?", [id]);
     return purged;
@@ -949,36 +1032,36 @@ var SharedSqlRecordLogic = class {
       if (opts.snapshot)
         this.snapshotBeforeMutation(id, opts.snapshot);
       this.versionedUpdate(id, ["deleted_at = NULL"], [], opts);
+      this.appendJournal(id, opts.journal);
     });
     return this.reread(id, "undelete");
   }
   async restoreVersion(id, version, opts = {}) {
     const existing = await this.getRecord(id);
     if (!existing)
-      throw new Error(`Record not found: "${id}"`);
+      throw new StackNotFoundError(`Record not found: "${id}"`);
     this.checkExpectedVersion(existing, opts.expectedVersion);
     const target = await this.getVersion(id, version);
     if (!target)
-      throw new Error(`Version not found: ${id}@${version}`);
+      throw new StackNotFoundError(`Version not found: "${id}"@${version}`);
     this.exec.transaction(() => {
       if (opts.snapshot)
         this.snapshotBeforeMutation(id, opts.snapshot);
       this.rewriteContent(id, target.typeId, target.content, opts, ["parent_id = ?"], [target.parentId ?? null]);
-      const applied = opts.restoreAssociations === false ? void 0 : target.associations;
-      if (applied !== void 0)
-        this.replaceAssociations(id, applied);
+      this.appendJournal(id, opts.journal);
     });
     return this.reread(id, "restoreVersion");
   }
   async commitMigration(id, toTypeId, content, opts = {}) {
     const existing = await this.getRecord(id);
     if (!existing)
-      throw new Error(`Record not found: "${id}"`);
+      throw new StackNotFoundError(`Record not found: "${id}"`);
     this.checkExpectedVersion(existing, opts.expectedVersion);
     this.exec.transaction(() => {
       if (opts.snapshot)
         this.snapshotBeforeMutation(id, opts.snapshot);
       this.rewriteContent(id, toTypeId, content, opts);
+      this.appendJournal(id, opts.journal);
     });
     return this.reread(id, "commitMigration");
   }
@@ -1121,6 +1204,59 @@ var SharedSqlRecordLogic = class {
     }
   }
   // -------------------------------------------------------
+  // Change journal
+  // -------------------------------------------------------
+  /**
+   * Append one entry, stamping the record-derived half off the row as it
+   * now stands — so every caller must already sit inside the same
+   * transaction as the write it describes, after that write has landed.
+   *
+   * `seq` is allocated here, from the log's own max, rather than computed
+   * by the caller. That is what spares this table the collision healing
+   * versions needs: nothing outside this statement ever holds a seq it
+   * expects to be free. See docs/spec/journal.md § Ordering.
+   */
+  appendJournal(recordId, entry) {
+    if (!entry)
+      return;
+    const row = this.exec.get("SELECT version, type_id, parent_id FROM records WHERE id = ?", [recordId]);
+    if (!row)
+      throw new StackNotFoundError(`Record not found: "${recordId}"`);
+    this.exec.run(`INSERT INTO journal
+        (record_id, seq, at, kind, ops, version, type_id, parent_id,
+         previous_parent_id, actor, associations)
+       VALUES (
+         ?,
+         (SELECT COALESCE(MAX(seq), 0) + 1 FROM journal WHERE record_id = ?),
+         ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      recordId,
+      recordId,
+      toMs(/* @__PURE__ */ new Date()),
+      entry.kind,
+      JSON.stringify(entry.ops),
+      row.version,
+      row.type_id,
+      row.parent_id,
+      // '' is the root; NULL is an entry that names no origin at all.
+      entry.previousParentId === void 0 ? null : entry.previousParentId ?? "",
+      entry.actor ? JSON.stringify(entry.actor) : null,
+      entry.associations?.length ? JSON.stringify(entry.associations) : null
+    ]);
+  }
+  async getJournal(id, query = {}) {
+    if (!this.exec.get("SELECT 1 FROM records WHERE id = ?", [id])) {
+      throw new StackNotFoundError(`Record not found: "${id}"`);
+    }
+    const conditions = ["record_id = ?"];
+    const values = [id];
+    if (query.sinceSeq !== void 0) {
+      conditions.push("seq > ?");
+      values.push(query.sinceSeq);
+    }
+    const rows = this.exec.all(`SELECT * FROM journal WHERE ${conditions.join(" AND ")} ORDER BY seq ASC${query.limit !== void 0 ? " LIMIT ?" : ""}`, query.limit !== void 0 ? [...values, query.limit] : values);
+    return rows.map(rowToJournalEntry);
+  }
+  // -------------------------------------------------------
   // Types
   // -------------------------------------------------------
   async saveType(type) {
@@ -1150,20 +1286,27 @@ var SharedSqlRecordLogic = class {
   // -------------------------------------------------------
   // Associations
   // -------------------------------------------------------
+  /**
+   * Never bumps `version`/`updatedAt` and never snapshots — a set-add
+   * composes correctly regardless of write order, so it needs neither OCC
+   * nor rollback history. The records row is untouched entirely; only the
+   * associations table changes. See docs/spec/versioning.md § Version
+   * history.
+   */
   async associate(recordId, association, opts = {}) {
     this.exec.transaction(() => {
-      if (opts.snapshot)
-        this.snapshotBeforeMutation(recordId, opts.snapshot);
-      this.versionedUpdate(recordId, [], [], opts);
+      if (!this.readRecord(recordId))
+        throw new StackNotFoundError(`Record not found: "${recordId}"`);
       this.insertAssociations(recordId, [association]);
+      this.appendJournal(recordId, opts.journal);
     });
     return this.reread(recordId, "associate");
   }
+  /** Never bumps `version`/`updatedAt` — see associate(). */
   async dissociate(recordId, association, opts = {}) {
     this.exec.transaction(() => {
-      if (opts.snapshot)
-        this.snapshotBeforeMutation(recordId, opts.snapshot);
-      this.versionedUpdate(recordId, [], [], opts);
+      if (!this.readRecord(recordId))
+        throw new StackNotFoundError(`Record not found: "${recordId}"`);
       this.exec.run(`DELETE FROM associations
        WHERE record_id = ?
          AND kind = ?
@@ -1173,6 +1316,7 @@ var SharedSqlRecordLogic = class {
          AND related_id    = ?
          AND related_ns    = ?
          AND related_stack = ?`, [recordId, association.kind, association.label, ...associationKeyColumns(association)]);
+      this.appendJournal(recordId, opts.journal);
     });
     return this.reread(recordId, "dissociate");
   }
@@ -1299,8 +1443,8 @@ var SharedSqlRecordAdapter = class {
   // -------------------------------------------------------
   // Records
   // -------------------------------------------------------
-  createRecord(record) {
-    return this.record.createRecord(record);
+  createRecord(record, opts) {
+    return this.record.createRecord(record, opts);
   }
   getRecord(id) {
     return this.record.getRecord(id);
@@ -1339,6 +1483,12 @@ var SharedSqlRecordAdapter = class {
     return this.record.saveVersion(id, version);
   }
   // -------------------------------------------------------
+  // Change journal
+  // -------------------------------------------------------
+  getJournal(id, query) {
+    return this.record.getJournal(id, query);
+  }
+  // -------------------------------------------------------
   // Types
   // -------------------------------------------------------
   saveType(type) {