@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/change-tracker-DqCdeEyx.d.ts

@@ -0,0 +1,128 @@
+import { I as SQLiteConnection } from './types-Dc8oWlxj.js';
+import { C as ChangeEvent } from './query-types-5B02ixH0.js';
+
+type PruneBoundarySource = 'device-sync' | 'replication' | 'device-cursors';
+
+/**
+ * Configures a change tracker's retention period, change log table, and poll size.
+ *
+ * @public
+ */
+interface ChangeTrackerOptions {
+    /**
+     * The age in milliseconds after which the tracker's cleanup can delete a change, which defaults to `3_600_000`, one hour.
+     */
+    retention?: number;
+    /**
+     * The name of the change log table, which defaults to `_sirannon_changes`.
+     */
+    changesTable?: string;
+    /**
+     * The number of changes that one poll requests, which defaults to 1000. A poll can return more, so that it ends on a transaction boundary.
+     */
+    pollBatchSize?: number;
+}
+
+/**
+ * Records every insert, update, and delete on each table that you watch as a row in the change log, so that subscribers and replication can consume the changes in order.
+ *
+ * Once you watch each table that you want to capture, you can pass the tracker to a replication engine.
+ *
+ * @public
+ */
+declare class ChangeTracker {
+    private readonly watched;
+    private lastSeq;
+    private readonly retentionMs;
+    private readonly changesTable;
+    private readonly pollBatchSize;
+    private changesTableReady;
+    private changesTableEnsured;
+    private watchedTablesCache;
+    private readonly stmtCache;
+    private readonly pruneBoundaries;
+    private lastPollAtTxBoundary;
+    constructor(options?: ChangeTrackerOptions);
+    /**
+     * Installs change-capture triggers on a table, so that every later write to it adds a row to the change log.
+     *
+     * @param conn - The writer connection on which the tracker creates the triggers.
+     * @param table - The name of the table to watch.
+     */
+    watch(conn: SQLiteConnection, table: string): Promise<void>;
+    /**
+     * Drops a table's change-capture triggers and removes the table from the watched set.
+     *
+     * @param conn - The writer connection on which the tracker drops the triggers.
+     * @param table - The name of the table to stop watching.
+     */
+    unwatch(conn: SQLiteConnection, table: string): Promise<void>;
+    /**
+     * Rebuilds the change-capture triggers on `conn` for every watched table
+     * whose column list has changed, without opening a nested transaction.
+     *
+     * Call it after a DDL statement inside an open transaction, so that the next
+     * write in that transaction records the new columns in `new_data`. You can
+     * also call it outside a transaction, in which case SQLite commits each
+     * `CREATE TRIGGER` and `DROP TRIGGER` statement on its own. The method skips
+     * a watched table that no longer exists, and it leaves that table's entry for
+     * `pruneDroppedTables` to remove after the commit. A
+     * driver error or an invalid column name propagates to the caller, so that
+     * the caller can roll back its transaction.
+     *
+     * @internal
+     */
+    refreshAllTriggersUsingConnection(conn: SQLiteConnection): Promise<void>;
+    /**
+     * Drops the change-capture triggers of each named table that the tracker
+     * watches, and removes that table from the watched set.
+     *
+     * Call it once a transaction that drops watched tables commits, and skip the
+     * call when that transaction rolls back. The method skips each table outside
+     * the watched set and issues `DROP TRIGGER IF EXISTS`, so a second call leaves
+     * the same state. When one transaction drops a table and creates another with
+     * the same name, `refreshAllTriggersUsingConnection` can
+     * install triggers on the new table. This method drops those triggers too, so
+     * you have to call `watch` again for the new table.
+     *
+     * @internal
+     */
+    pruneDroppedTables(conn: SQLiteConnection, tables: readonly string[]): Promise<void>;
+    /** @internal */
+    poll(conn: SQLiteConnection): Promise<ChangeEvent[]>;
+    /** @internal */
+    get pollEndedAtTxBoundary(): boolean;
+    /**
+     * Returns the sequence number of the last change that the tracker polled or skipped with `advanceToLatest`, so live subscribers receive only later changes.
+     *
+     * @internal
+     */
+    get cursor(): bigint;
+    /** @internal */
+    readSinceTables(conn: SQLiteConnection, tables: readonly string[], afterSeq: bigint, upToSeq: bigint, limit: number): Promise<ChangeEvent[]>;
+    /**
+     * Returns the lowest sequence number in the change log, or `null` when the log is empty or missing.
+     *
+     * @internal
+     */
+    getMinSeq(conn: SQLiteConnection): Promise<bigint | null>;
+    /** @internal */
+    advanceToLatest(conn: SQLiteConnection): Promise<void>;
+    /** @internal */
+    cleanup(conn: SQLiteConnection): Promise<number>;
+    /** @internal */
+    setPruneBoundary(source: PruneBoundarySource, seq: bigint): void;
+    /** @internal */
+    clearPruneBoundary(source: PruneBoundarySource): void;
+    /** @internal */
+    get changeLogTable(): string;
+    /** @internal */
+    get watchedTables(): ReadonlySet<string>;
+    private computeSeqBound;
+    private assertIdentifier;
+    private detectChangesTable;
+    private ensureChangesTable;
+    private installTriggers;
+}
+
+export { ChangeTracker as C, type ChangeTrackerOptions as a };

package/dist/{chunk-VOSJBZ6Q.mjs → chunk-2ES3DT4A.mjs}

@@ -1,28 +1,35 @@
-import { tokenizeSql, readSelectItems, findClauses } from './chunk-SBL6GN43.mjs';
-import { operationRegistryDigest } from './chunk-TUD5CJ76.mjs';
+import { tokenizeSql, readSelectItems, findClauses } from './chunk-ZYWI45EN.mjs';
+import { operationRegistryDigest } from './chunk-KB4OLJAD.mjs';
 import { mkdirSync, writeFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { pathToFileURL } from 'url';
 
 // src/codegen/manifest.ts
 var OPERATION_MANIFEST_VERSION = 1;
-function buildOperationManifest(registry) {
+function buildOperationManifest(registry, shared) {
   const databases = {};
   for (const databaseId of Object.keys(registry).sort()) {
-    const operations = registry[databaseId] ?? {};
-    const reads = {};
-    const writes = {};
-    for (const name of Object.keys(operations.reads ?? {}).sort()) {
-      const read = operations.reads?.[name];
-      if (read !== void 0) reads[name] = readShape(read);
-    }
-    for (const name of Object.keys(operations.writes ?? {}).sort()) {
-      const write2 = operations.writes?.[name];
-      if (write2 !== void 0) writes[name] = writeShape(write2);
-    }
-    databases[databaseId] = { reads, writes };
+    databases[databaseId] = databaseManifest(registry[databaseId] ?? {});
+  }
+  return {
+    version: OPERATION_MANIFEST_VERSION,
+    digest: operationRegistryDigest(registry, shared),
+    databases,
+    ...shared === void 0 ? {} : { shared: databaseManifest(shared) }
+  };
+}
+function databaseManifest(operations) {
+  const reads = {};
+  const writes = {};
+  for (const name of Object.keys(operations.reads ?? {}).sort()) {
+    const read = operations.reads?.[name];
+    if (read !== void 0) reads[name] = readShape(read);
+  }
+  for (const name of Object.keys(operations.writes ?? {}).sort()) {
+    const write2 = operations.writes?.[name];
+    if (write2 !== void 0) writes[name] = writeShape(write2);
   }
-  return { version: OPERATION_MANIFEST_VERSION, digest: operationRegistryDigest(registry), databases };
+  return { reads, writes };
 }
 function readShape(operation) {
   const args = [...operation.args ?? []];
@@ -69,34 +76,48 @@ function renderOperationTypes(manifest, options) {
   const declared = /* @__PURE__ */ new Map();
   for (const databaseId of Object.keys(manifest.databases).sort()) {
     const database = manifest.databases[databaseId];
-    lines.push("", ...renderDatabase(databaseId, database, declared));
+    const names = {
+      constant: identifier(databaseId),
+      rowPrefix: pascalCase(databaseId),
+      claimant: { owner: `database/${databaseId}`, label: databaseId }
+    };
+    lines.push("", ...renderOperations(names, database, declared));
+  }
+  if (manifest.shared !== void 0) {
+    const names = { constant: SHARED_CONSTANT, rowPrefix: SHARED_ROW_PREFIX, claimant: SHARED_CLAIMANT };
+    lines.push("", ...renderOperations(names, manifest.shared, declared));
   }
   return `${lines.join("\n")}
 `;
 }
-function claim(declared, generated, source) {
+var SHARED_CONSTANT = "sharedOperations";
+var SHARED_ROW_PREFIX = "Shared";
+var SHARED_CLAIMANT = { owner: "shared", label: SHARED_CONSTANT };
+function claim(declared, generated, claimant) {
   const taken = declared.get(generated);
-  if (taken !== void 0 && taken !== source) {
+  if (taken !== void 0 && taken.owner !== claimant.owner) {
     throw new Error(
-      `'${source}' and '${taken}' both generate the identifier '${generated}'. Rename one of them so the generated file declares each name once.`
+      `'${claimant.label}' and '${taken.label}' both generate the identifier '${generated}'. Rename one of them so the generated file declares each name once.`
     );
   }
-  declared.set(generated, source);
+  declared.set(generated, claimant);
   return generated;
 }
-function renderDatabase(databaseId, database, declared) {
-  const prefix = pascalCase(databaseId);
+function readClaimant(claimant, name) {
+  return { owner: `${claimant.owner}/reads/${name}`, label: `${claimant.label}.reads.${name}` };
+}
+function renderOperations(names, database, declared) {
   const rowTypes = /* @__PURE__ */ new Map();
   const lines = [];
   for (const [name, shape] of Object.entries(database.reads)) {
     if (shape.columns === null) continue;
-    const rowType = claim(declared, `${prefix}${pascalCase(name)}Row`, `${databaseId}.reads.${name}`);
+    const rowType = claim(declared, `${names.rowPrefix}${pascalCase(name)}Row`, readClaimant(names.claimant, name));
     rowTypes.set(name, rowType);
     lines.push(`export interface ${rowType} {`);
     for (const column of shape.columns) lines.push(`  ${propertyKey(column)}: unknown`);
     lines.push("}", "");
   }
-  lines.push(`export const ${claim(declared, identifier(databaseId), databaseId)} = {`, "  reads: {");
+  lines.push(`export const ${claim(declared, names.constant, names.claimant)} = {`, "  reads: {");
   for (const [name, shape] of Object.entries(database.reads)) {
     const row = rowTypes.get(name) ?? "Record<string, unknown>";
     lines.push(
@@ -127,11 +148,15 @@ function identifier(value) {
 function pascalCase(value) {
   return value.split(/[^A-Za-z0-9]+/).filter((part) => part.length > 0).map((part) => part[0].toUpperCase() + part.slice(1)).join("");
 }
-var CODEGEN_USAGE = `sirannon-codegen --registry <module> --out <file> [--manifest <file>] [--export <name>] [--package <name>]
+var CODEGEN_USAGE = `sirannon-codegen --registry <module> --out <file> [--manifest <file>] [--export <name>] [--shared-export <name>] [--package <name>]
 
-Reads the operation registry a server is built from and writes the typed
-references a client calls it through. The registry module is imported, so run
-it under a loader that reads your source format when it is not JavaScript.`;
+Reads the operations that you register with a server and writes the typed
+references through which a client calls them. The generator takes the
+per-database registry from the 'operations' export, or from the default
+export, and the operations for every database from the 'sharedOperations'
+export. The generator imports the registry module, so run it under a loader
+that reads your source format when that format is not JavaScript.`;
+var DEFAULT_SHARED_EXPORT = "sharedOperations";
 function parseOptions(argv) {
   const values = /* @__PURE__ */ new Map();
   for (let i = 0; i < argv.length; i += 2) {
@@ -156,16 +181,28 @@ ${CODEGEN_USAGE}`);
     out,
     manifest: values.get("manifest"),
     exportName: values.get("export"),
+    sharedExportName: values.get("shared-export"),
     packageName: values.get("package")
   };
 }
-function readRegistry(module, exportName, path) {
+function readShared(module, exportName, path) {
+  const candidate = module[exportName ?? DEFAULT_SHARED_EXPORT];
+  if (candidate === void 0 && exportName === void 0) return void 0;
+  if (candidate === void 0 || candidate === null || typeof candidate !== "object") {
+    throw new Error(`Module '${path}' exports no shared operations named '${exportName ?? DEFAULT_SHARED_EXPORT}'`);
+  }
+  return candidate;
+}
+function readRegistry(module, options, path) {
+  const shared = readShared(module, options.sharedExportName, path);
+  const { exportName } = options;
   const candidate = exportName === void 0 ? module.operations ?? module.default : module[exportName];
-  if (candidate === void 0 || typeof candidate !== "object") {
+  if (candidate === void 0 && exportName === void 0 && shared !== void 0) return { registry: {}, shared };
+  if (candidate === void 0 || candidate === null || typeof candidate !== "object") {
     const named = exportName === void 0 ? "'operations' or a default export" : `'${exportName}'`;
     throw new Error(`Module '${path}' exports no operation registry named ${named}`);
   }
-  return candidate;
+  return { registry: candidate, shared };
 }
 function write(path, contents) {
   const target = resolve(path);
@@ -176,7 +213,8 @@ async function runCodegen(argv) {
   const options = parseOptions(argv);
   const modulePath = resolve(options.registry);
   const imported = await import(pathToFileURL(modulePath).href);
-  const manifest = buildOperationManifest(readRegistry(imported, options.exportName, modulePath));
+  const { registry, shared } = readRegistry(imported, options, modulePath);
+  const manifest = buildOperationManifest(registry, shared);
   write(options.out, renderOperationTypes(manifest, { packageName: options.packageName }));
   if (options.manifest !== void 0) {
     write(options.manifest, `${JSON.stringify(manifest, null, 2)}

package/dist/{chunk-6CMCO7S4.mjs → chunk-2O3PP4CF.mjs}

@@ -1,4 +1,4 @@
-import { ForbiddenSqlError } from './chunk-PBRXXISQ.mjs';
+import { ForbiddenSqlError } from './chunk-KINDFBQP.mjs';
 
 // src/core/internal-tables.ts
 var INTERNAL_TABLE_PREFIX = "_sirannon_";

package/dist/{chunk-E7Q7HE46.mjs → chunk-3BZLZ47R.mjs}

@@ -1,9 +1,9 @@
-import { planBackupRestore } from './chunk-YNTDOFTN.mjs';
-import { listStoredFilePieces, fetchStoredFile, checkpointLog } from './chunk-U445A3C4.mjs';
-import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS, reportQuietly, LOG_HEADER_BYTES, LOG_FRAME_HEADER_BYTES, readLogHeader, foldLogChecksum, MAGIC_WITH_LITTLE_ENDIAN_CONTENT, LOG_FORMAT_VERSION } from './chunk-GYCEJNU4.mjs';
-import { readBackupChains, DEFAULT_CHAIN_NAME } from './chunk-YVF2ZJTE.mjs';
+import { planBackupRestore } from './chunk-YW7IKQ7T.mjs';
+import { listStoredFilePieces, fetchStoredFile, checkpointLog } from './chunk-QGVRRKB2.mjs';
+import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS, reportQuietly, LOG_HEADER_BYTES, LOG_FRAME_HEADER_BYTES, readLogHeader, foldLogChecksum, MAGIC_WITH_LITTLE_ENDIAN_CONTENT, LOG_FORMAT_VERSION } from './chunk-R7GBXNTO.mjs';
+import { readBackupChains, DEFAULT_CHAIN_NAME } from './chunk-CZL4D3BM.mjs';
 import { randomHex } from './chunk-QBBLSQHQ.mjs';
-import { SirannonError } from './chunk-PBRXXISQ.mjs';
+import { SirannonError } from './chunk-KINDFBQP.mjs';
 import { rename, open, rm, stat } from 'fs/promises';
 
 // src/core/backup/write-fully.ts
@@ -134,11 +134,11 @@ var RestoreLogWriter = class _RestoreLogWriter {
   expected;
   closed = false;
   /**
-   * Opens the log beside a restored database and writes its header.
+   * Creates the log next to a restored database and writes its header.
    *
-   * @param path - Path of the log file.
-   * @param pageSize - Size of one page of the database being restored, in bytes.
-   * @param logSequence - Checkpoint sequence number to record in the header.
+   * @param path - The path of the log file.
+   * @param pageSize - The page size of the database that Sirannon restores, in bytes.
+   * @param logSequence - The checkpoint sequence number to write into the header.
    * @returns The writer, ready for the first piece.
    */
   static async create(path, pageSize, logSequence) {
@@ -156,21 +156,20 @@ var RestoreLogWriter = class _RestoreLogWriter {
     }
     return new _RestoreLogWriter(handle, path, pageSize, salt1, salt2, checksum);
   }
-  /** Bytes one frame takes, being its header plus one page. */
+  /** The size of one frame in bytes, which is its header plus one page. */
   get frameBytes() {
     return LOG_FRAME_HEADER_BYTES + this.pageSize;
   }
   /**
-   * Starts a new change piece, naming how many bytes of log header stand in
-   * front of its first frame.
+   * Starts a new change piece, with the number of log header bytes before its
+   * first frame.
    *
-   * Where the piece begins with a header, this reads it and checks it against
-   * the record that named the piece. A record claiming a page size the frames
-   * were never written at would otherwise have SQLite read every frame at the
-   * wrong length.
+   * Where the piece begins with a header, the writer checks that header against
+   * the chain record of the piece, since a record with the wrong page size would
+   * make SQLite read every frame at the wrong length.
    *
-   * @param headerBytes - Bytes of log header in front of the frames.
-   * @param expected - What the piece's chain record says that header holds.
+   * @param headerBytes - The number of log header bytes before the frames.
+   * @param expected - The header values that the chain record of the piece states.
    */
   beginPiece(headerBytes, expected) {
     if (this.carry.byteLength > 0) {
@@ -183,11 +182,12 @@ var RestoreLogWriter = class _RestoreLogWriter {
     this.expected = expected;
   }
   /**
-   * Stamps every whole frame in the bytes given and appends them to the log.
-   * Where a frame is split across two pieces, this keeps the first part until
-   * the second one is added.
+   * Writes the salts and checksum of this log into every whole frame in the
+   * given bytes, and appends those frames to the log. Where a frame spans two
+   * stored pieces, the writer keeps the first part until the next call supplies
+   * the rest.
    *
-   * @param bytes - The next run of bytes of the change piece.
+   * @param bytes - The next bytes of the change piece.
    */
   async add(bytes) {
     let arriving = bytes;
@@ -251,10 +251,10 @@ var RestoreLogWriter = class _RestoreLogWriter {
     }
   }
   /**
-   * Closes the log and reports what it holds.
+   * Closes the log and returns its frame count and the resulting database size.
    *
-   * @returns The frames the log holds, and the size the database reaches once SQLite replays them.
-   * @throws A `BACKUP_CHAIN_BROKEN` where the pieces ended part-way through a frame, or where the last frame commits nothing.
+   * @returns The number of frames in the log, and the number of pages in the database after SQLite applies them.
+   * @throws A `BACKUP_CHAIN_BROKEN` where the pieces end part-way through a frame, or where the last frame commits no transaction.
    */
   async finish() {
     await this.close();
@@ -270,7 +270,7 @@ var RestoreLogWriter = class _RestoreLogWriter {
     }
     return { frameCount: this.framesWritten, databasePages: this.lastDatabasePages };
   }
-  /** Closes the log without checking it, which is what a failed batch calls before it removes the file. */
+  /** Closes the log without checking it, which Sirannon does for a failed batch before it deletes the file. */
   async abandon() {
     await this.close().catch(() => {
     });