@haverstack/record-adapter-sqlite 0.31.0 → 0.33.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StackCapabilities, StackRecord, RecordChangeSet, RecordVersion, ActorOptions, TypeId, StackQuery, QueryResult, FileId, JournalQuery, RecordJournalEntry, StackType, Association, Actor } from '@haverstack/core';
+import { StackCapabilities, StackRecord, RecordChangeSet, RecordVersion, ActorOptions, TypeId, StackQuery, QueryResult, FileId, VersionsQuery, JournalQuery, RecordJournalEntry, StackType, AssociationEdit, Actor } from '@haverstack/core';
 import { StackRecordAdapter, JournalOptions } from '@haverstack/core/adapter';
 import { StackTokenStore, TokenSession, TokenInfo } from '@haverstack/core/wire';
 
@@ -91,15 +91,14 @@ declare abstract class SharedSqlRecordAdapter implements StackRecordAdapter {
     } & ActorOptions & JournalOptions): Promise<StackRecord>;
     queryRecords(query: StackQuery): Promise<QueryResult>;
     deleteUnreferencedAttachmentRecords(fileId: FileId, metadataTypeIds: TypeId[]): Promise<StackRecord[]>;
-    getVersions(id: string): Promise<RecordVersion[]>;
+    getVersions(id: string, query?: VersionsQuery): 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?: JournalOptions): Promise<StackRecord>;
-    dissociate(recordId: string, association: Association, opts?: JournalOptions): Promise<StackRecord>;
+    amendAssociations(recordId: string, changes: AssociationEdit[], opts?: JournalOptions): Promise<StackRecord>;
     abstract flush(): Promise<void>;
     abstract close(): Promise<void>;
 }
@@ -157,8 +156,8 @@ declare class NativeTokenStore implements StackTokenStore {
  * Full-text search uses FTS5.
  *
  * A stack file is owned by exactly one process at a time (see
- * docs/spec/adapters.md § Concurrency & storage ownership). open()/initialize()
- * acquire a PID-stamped lock file beside the database and reject if
+ * docs/spec/adapters.md § Concurrency & storage ownership). open()
+ * acquires a PID-stamped lock file beside the database and rejects if
  * another live process already holds it; close() releases it.
  *
  * Token storage is a separate concern — see NativeTokenStore in this
@@ -173,19 +172,15 @@ declare class NativeTokenStore implements StackTokenStore {
  * spread-args run/get/all calls to it).
  */
 
-type NativeSQLiteRecordAdapterInitializeOptions = {
-    /** Absolute path to the .db file. Must not already exist. */
-    path: string;
-    /** IANA timezone string e.g. "America/New_York". Optional passthrough app metadata — no default. */
-    timezone?: string;
-    /** Entity ID of the stack owner. */
-    ownerEntityId: string;
-    /** Bypass the storage-ownership lock check. See NativeSQLiteRecordAdapterOpenOptions.force. */
-    force?: boolean;
-};
+/** What open() does when the store is missing or present, like O_CREAT / O_EXCL. */
+type StoreCreateMode = 'never' | 'ifMissing' | 'exclusive';
+/** A plain DID, or a lazy provider called only when a store is actually created. */
+type OwnerEntityIdInput = string | (() => string | Promise<string>);
 type NativeSQLiteRecordAdapterOpenOptions = {
-    /** Absolute path to an existing .db file. */
+    /** Absolute path to the .db file. */
     path: string;
+    /** IANA timezone string e.g. "America/New_York". Consulted only when a store is created. No default. */
+    timezone?: string;
     /**
      * Open even if a lock file from another live process is present.
      * Only needed if that process is gone but its PID was reused by
@@ -193,26 +188,29 @@ type NativeSQLiteRecordAdapterOpenOptions = {
      * locks whose owning process is no longer running).
      */
     force?: boolean;
-};
+} & ({
+    /** Open an existing store; fail if the file is missing. */
+    create?: 'never';
+    /** Checked against the existing store's owner; a mismatch throws OwnerMismatchError. */
+    ownerEntityId?: string;
+} | {
+    /** `'ifMissing'` opens the store if present and creates it if not; `'exclusive'` creates it and fails if present. */
+    create: 'ifMissing' | 'exclusive';
+    /**
+     * Owner of a newly created store. A plain string is also checked against an
+     * existing store's owner; a lazy provider is never called just to compare.
+     */
+    ownerEntityId: OwnerEntityIdInput;
+});
 declare class NativeSQLiteRecordAdapter extends SharedSqlRecordAdapter {
     private readonly path;
     private readonly db;
     private constructor();
     /**
-     * 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.
-     */
-    static initialize(opts: NativeSQLiteRecordAdapterInitializeOptions): Promise<NativeSQLiteRecordAdapter>;
-    /**
-     * Open an existing stack database. Fails if the file does not exist —
-     * use initialize() for new databases.
+     * Opens or creates the stack database at `path` according to `create`.
+     * Takes the storage-ownership lock first and releases it again if the
+     * open fails, since the caller never receives an adapter to close.
+     * See docs/spec/adapters.md § Construction.
      */
     static open(opts: NativeSQLiteRecordAdapterOpenOptions): Promise<NativeSQLiteRecordAdapter>;
     /** Folds the WAL back into the main file — useful before copying/backing up the database. */
@@ -220,4 +218,4 @@ declare class NativeSQLiteRecordAdapter extends SharedSqlRecordAdapter {
     close(): Promise<void>;
 }
 
-export { NativeSQLiteRecordAdapter, type NativeSQLiteRecordAdapterInitializeOptions, type NativeSQLiteRecordAdapterOpenOptions, NativeTokenStore, type NativeTokenStoreOpenOptions, defaultTokenStorePath };
+export { NativeSQLiteRecordAdapter, type NativeSQLiteRecordAdapterOpenOptions, NativeTokenStore, type NativeTokenStoreOpenOptions, type OwnerEntityIdInput, type StoreCreateMode, defaultTokenStorePath };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { existsSync, writeFileSync, unlinkSync, readFileSync } from 'fs';
-import { StackNotFoundError, StackConflictError, applyMergePatch, StackVersionConflictError, StackBadRequestError, NATIVE_SORT_FIELDS } from '@haverstack/core';
-import { contentSortEntry, parseContentFilterKey, contentSortKey } from '@haverstack/core/adapter';
+import { StackNotFoundError, StackConflictError, applyMergePatch, assertOneSurface, StackVersionConflictError, StackBadRequestError, NATIVE_SORT_FIELDS } from '@haverstack/core';
+import { OwnerMismatchError, contentSortEntry, parseContentFilterKey, contentSortKey } from '@haverstack/core/adapter';
 import { randomBytes, createHash } from 'crypto';
 
 // src/node-sqlite.ts
@@ -44,7 +44,7 @@ var RECORD_SCHEMA_SQL = `
   --
   -- 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
+  -- an amendAssociations() add 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
@@ -93,7 +93,7 @@ var RECORD_SCHEMA_SQL = `
     -- 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 purge destroys the journal.
-    kind        TEXT NOT NULL CHECK (kind IN ('created', 'changed', 'deleted')),
+    kind        TEXT NOT NULL CHECK (kind IN ('created', 'changed', 'removed')),
     ops         TEXT NOT NULL CHECK (json_valid(ops)),
     version     INTEGER NOT NULL,
     type_id     TEXT NOT NULL,
@@ -375,7 +375,7 @@ var atBudget = (page, rows) => ({
   params: [...page.params, rows]
 });
 var sqlDirection = (query) => {
-  const dir = query.sort?.direction ?? "desc";
+  const dir = query.sort ? query.sort.direction : "desc";
   if (dir !== "asc" && dir !== "desc") {
     throw new StackBadRequestError(`Invalid sort direction "${dir}": expected "asc" or "desc".`);
   }
@@ -1191,8 +1191,14 @@ var SharedSqlRecordLogic = class _SharedSqlRecordLogic {
   // -------------------------------------------------------
   // Versions
   // -------------------------------------------------------
-  async getVersions(id) {
-    const rows = this.exec.all("SELECT * FROM versions WHERE record_id = ? ORDER BY version DESC", [id]);
+  async getVersions(id, query = {}) {
+    const conditions = ["record_id = ?"];
+    const values = [id];
+    if (query.beforeVersion !== void 0) {
+      conditions.push("version < ?");
+      values.push(query.beforeVersion);
+    }
+    const rows = this.exec.all(`SELECT * FROM versions WHERE ${conditions.join(" AND ")} ORDER BY version DESC${query.limit !== void 0 ? " LIMIT ?" : ""}`, query.limit !== void 0 ? [...values, query.limit] : values);
     return rows.map(rowToVersion);
   }
   async getVersion(id, version) {
@@ -1342,24 +1348,20 @@ var SharedSqlRecordLogic = class _SharedSqlRecordLogic {
   // -------------------------------------------------------
   /**
    * Never bumps `version`/`updatedAt` and never snapshots — see
-   * StackRecordAdapter.associate(). The records row is untouched entirely;
-   * only the associations table changes.
+   * StackRecordAdapter.amendAssociations(). The records row is untouched
+   * entirely; only the associations table changes, in one transaction:
+   * removes first, then adds.
    */
-  async associate(recordId, association, opts = {}) {
+  async amendAssociations(recordId, changes, opts = {}) {
+    assertOneSurface(changes);
     this.exec.transaction(() => {
       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 (!this.readRecord(recordId))
-        throw new StackNotFoundError(`Record not found: "${recordId}"`);
-      this.exec.run(`DELETE FROM associations
+      for (const change of changes) {
+        if (change.op !== "remove")
+          continue;
+        const { association } = change;
+        this.exec.run(`DELETE FROM associations
        WHERE record_id = ?
          AND kind = ?
          AND label = ?
@@ -1369,9 +1371,13 @@ var SharedSqlRecordLogic = class _SharedSqlRecordLogic {
          AND related_ns    = ?
          AND related_stack = ?
          AND related_role  = ?`, [recordId, association.kind, association.label, ...associationKeyColumns(association)]);
+      }
+      const adds = changes.flatMap((c) => c.op === "add" ? [c.association] : []);
+      if (adds.length)
+        this.insertAssociations(recordId, adds);
       this.appendJournal(recordId, opts.journal);
     });
-    return this.reread(recordId, "dissociate");
+    return this.reread(recordId, "amendAssociations");
   }
   /** The kinds each change-set key replaces, and nothing else. */
   static DATA_KINDS = ["tag", "attachment", "relationship"];
@@ -1408,7 +1414,7 @@ var SharedSqlRecordLogic = class _SharedSqlRecordLogic {
    *
    * 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
+   * here to StackNotFoundError so amendAssociations() on a nonexistent record
    * fails loudly instead of silently creating an orphan row.
    */
   insertAssociations(recordId, associations) {
@@ -1543,8 +1549,8 @@ var SharedSqlRecordAdapter = class {
   // -------------------------------------------------------
   // Versions
   // -------------------------------------------------------
-  getVersions(id) {
-    return this.record.getVersions(id);
+  getVersions(id, query) {
+    return this.record.getVersions(id, query);
   }
   getVersion(id, version) {
     return this.record.getVersion(id, version);
@@ -1573,11 +1579,8 @@ var SharedSqlRecordAdapter = class {
   // -------------------------------------------------------
   // Associations
   // -------------------------------------------------------
-  associate(recordId, association, opts) {
-    return this.record.associate(recordId, association, opts);
-  }
-  dissociate(recordId, association, opts) {
-    return this.record.dissociate(recordId, association, opts);
+  amendAssociations(recordId, changes, opts) {
+    return this.record.amendAssociations(recordId, changes, opts);
   }
 };
 var lockPathFor = (dbPath) => `${dbPath}.lock`;
@@ -1746,44 +1749,60 @@ var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter extends SharedS
   path;
   db;
   /**
-   * 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 —
-   * use open() for existing databases.
-   */
-  static async initialize(opts) {
-    if (existsSync(opts.path)) {
-      throw new Error(
-        `Cannot initialize: database already exists at "${opts.path}". Use NativeSQLiteRecordAdapter.open() instead.`
-      );
-    }
-    const [db, exec] = _NativeSQLiteRecordAdapter.attach(opts.path, opts.force);
-    const config = insertConfigRecord(exec, opts.ownerEntityId, opts.timezone);
-    return new _NativeSQLiteRecordAdapter(opts.path, db, exec, config);
-  }
-  /**
-   * Open an existing stack database. Fails if the file does not exist —
-   * use initialize() for new databases.
+   * Opens or creates the stack database at `path` according to `create`.
+   * Takes the storage-ownership lock first and releases it again if the
+   * open fails, since the caller never receives an adapter to close.
+   * See docs/spec/adapters.md § Construction.
    */
   static async open(opts) {
-    if (!existsSync(opts.path)) {
-      throw new Error(
-        `Cannot open: no database found at "${opts.path}". Use NativeSQLiteRecordAdapter.initialize() to create one.`
-      );
+    const mode = opts.create ?? "never";
+    const checkMode = (exists) => {
+      if (!exists && mode === "never") {
+        throw new Error(
+          `Cannot open: no database found at "${opts.path}". Pass create: 'ifMissing' or 'exclusive' to create one.`
+        );
+      }
+      if (exists && mode === "exclusive") {
+        throw new Error(
+          `Cannot create: database already exists at "${opts.path}". Pass create: 'never' or 'ifMissing' to open it.`
+        );
+      }
+    };
+    const existedBeforeLock = existsSync(opts.path);
+    checkMode(existedBeforeLock);
+    let newOwner;
+    if (!existedBeforeLock) {
+      newOwner = typeof opts.ownerEntityId === "function" ? await opts.ownerEntityId() : opts.ownerEntityId;
+      if (!newOwner) {
+        throw new Error(
+          `Cannot create: no ownerEntityId given for the new database at "${opts.path}".`
+        );
+      }
+    }
+    acquireLock(opts.path, opts.force);
+    let db;
+    try {
+      const exists = existsSync(opts.path);
+      checkMode(exists);
+      db = new DatabaseSync(opts.path);
+      const exec = new NativeSqliteExecutor(db);
+      applyRecordSchema(exec, { wal: true });
+      let config;
+      if (exists) {
+        config = readStackConfig(exec);
+        if (typeof opts.ownerEntityId === "string" && opts.ownerEntityId !== config.entityId) {
+          throw new OwnerMismatchError(opts.ownerEntityId, config.entityId, `"${opts.path}"`);
+        }
+      } else {
+        if (!newOwner) throw new Error(`Cannot create: "${opts.path}" vanished while opening.`);
+        config = insertConfigRecord(exec, newOwner, opts.timezone);
+      }
+      return new _NativeSQLiteRecordAdapter(opts.path, db, exec, config);
+    } catch (err) {
+      db?.close();
+      releaseLock(opts.path);
+      throw err;
     }
-    const [db, exec] = _NativeSQLiteRecordAdapter.attach(opts.path, opts.force);
-    return new _NativeSQLiteRecordAdapter(opts.path, db, exec, readStackConfig(exec));
   }
   // -------------------------------------------------------
   // Lifecycle