@delali/sirannon-db 0.1.8 → 0.2.1-next.18

package/dist/backup-scheduler/index.d.ts

@@ -1,4 +1,5 @@
-import { e as SQLiteConnection, f as BackupScheduleOptions } from '../types-D_hQW1hr.js';
+import { e as SQLiteConnection, f as BackupScheduleOptions } from '../types-rVZKnKN-.js';
+import '../query-types-DL3LtPvY.js';
 
 declare class BackupManager {
     backup(conn: SQLiteConnection, destPath: string): Promise<void>;
@@ -8,9 +9,22 @@ declare class BackupManager {
 
 /** Runs a backup while the caller's writer lock is held, so it never shares the writer connection with another write. */
 type RunExclusive = (op: () => Promise<void>) => Promise<void>;
+/**
+ * @public
+ *
+ * Repeats a database backup on a cron schedule and keeps a bounded number of files.
+ */
 declare class BackupScheduler {
     private readonly manager;
     constructor(manager?: BackupManager);
+    /**
+     * Starts repeating backups and returns a function that stops them.
+     *
+     * @param conn - Connection to the database being copied.
+     * @param options - Cron expression, destination directory, retention, time zone, and failure callback.
+     * @param runExclusive - Runs each copy with the database's writer held so that no write commits mid-copy.
+     * @returns A function that stops the schedule.
+     */
     schedule(conn: SQLiteConnection, options: BackupScheduleOptions, runExclusive?: RunExclusive): () => void;
     private run;
 }

package/dist/backup-scheduler/index.mjs

@@ -1,2 +1,2 @@
-export { BackupScheduler } from '../chunk-VLTICJOD.mjs';
-import '../chunk-YPYVQJ4C.mjs';
+export { BackupScheduler } from '../chunk-VOYGMAU7.mjs';
+import '../chunk-PBRXXISQ.mjs';

package/dist/baseline-D93hcIEE.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Marks the migration an existing database starts from, so earlier versions are recorded without running.
+ *
+ * @public
+ */
+interface BaselineFileOption {
+    /**
+     * Version of the migration carrying the baseline.
+     */
+    version: number;
+    /**
+     * Highest version this baseline covers.
+     */
+    through: number;
+}
+
+export type { BaselineFileOption as B };

package/dist/{change-tracker-CbmaMO-N.d.ts → change-tracker-DDmXB754.d.ts}

@@ -1,25 +1,59 @@
-import { e as SQLiteConnection, C as ChangeEvent } from './types-D_hQW1hr.js';
+import { e as SQLiteConnection } from './types-rVZKnKN-.js';
+import { C as ChangeEvent } from './query-types-DL3LtPvY.js';
 
+/**
+ * How long a change tracker keeps changes, and how much it reads at a time.
+ *
+ * @public
+ */
 interface ChangeTrackerOptions {
+    /**
+     * Milliseconds a change stays readable before it is pruned. Default: 3_600_000 (one hour).
+     */
     retention?: number;
+    /**
+     * Name of the table changes are recorded in.
+     */
     changesTable?: string;
+    /**
+     * Changes read in one poll. Default: 1000.
+     */
     pollBatchSize?: number;
-    replication?: boolean;
 }
 
+/**
+ * Records every change to the tables you watch so that subscribers and replication can read them in order.
+ *
+ * Construct one, watch the tables you want captured, and pass it to a replication engine or leave it to the database that owns it.
+ *
+ * @public
+ */
 declare class ChangeTracker {
     private readonly watched;
     private lastSeq;
     private readonly retentionMs;
     private readonly changesTable;
     private readonly pollBatchSize;
-    private readonly replication;
     private changesTableReady;
+    private changesTableEnsured;
     private watchedTablesCache;
     private readonly stmtCache;
     private pruneBoundary;
+    private lastPollAtTxBoundary;
     constructor(options?: ChangeTrackerOptions);
+    /**
+     * Starts recording changes to a table by installing its change-capture triggers.
+     *
+     * @param conn - Writer connection the triggers are created on.
+     * @param table - Name of the table to watch.
+     */
     watch(conn: SQLiteConnection, table: string): Promise<void>;
+    /**
+     * Stops recording changes to a table and drops its triggers.
+     *
+     * @param conn - Writer connection the triggers are dropped from.
+     * @param table - Name of the table to stop watching.
+     */
     unwatch(conn: SQLiteConnection, table: string): Promise<void>;
     /**
      * Rebuilds CDC triggers for every watched table directly on the supplied
@@ -45,6 +79,8 @@ declare class ChangeTracker {
      *   `conn`. The cached column list is updated on success.
      * - Any other error (driver failure, identifier validation failure) is
      *   rethrown so the caller's transaction can roll back deterministically.
+     *
+     * @internal
      */
     refreshAllTriggersUsingConnection(conn: SQLiteConnection): Promise<void>;
     /**
@@ -66,33 +102,42 @@ declare class ChangeTracker {
      * re-installed triggers compiled against the new schema. Those triggers
      * are dropped here so the recreated table starts with a clean slate and
      * the caller must explicitly `watch` it again.
+     *
+     * @internal
      */
     pruneDroppedTables(conn: SQLiteConnection, tables: readonly string[]): Promise<void>;
+    /** @internal */
     poll(conn: SQLiteConnection): Promise<ChangeEvent[]>;
-    /** The highest seq already polled; live subscribers receive events beyond it. */
+    /** @internal */
+    get pollEndedAtTxBoundary(): boolean;
+    /**
+     * The highest seq already polled; live subscribers receive events beyond it.
+     *
+     * @internal
+     */
     get cursor(): bigint;
+    /** @internal */
+    readSinceTables(conn: SQLiteConnection, tables: readonly string[], afterSeq: bigint, upToSeq: bigint, limit: number): Promise<ChangeEvent[]>;
     /**
-     * Reads retained changes for one table with seq in `(afterSeq, upToSeq]`,
-     * ordered ascending and capped at `limit`. Used to replay history to a
-     * resuming subscriber without disturbing the shared poll cursor.
+     * The lowest retained seq, or `null` when the change log is empty.
+     *
+     * @internal
      */
-    readSince(conn: SQLiteConnection, table: string, afterSeq: bigint, upToSeq: bigint, limit: number): Promise<ChangeEvent[]>;
-    /** The lowest retained seq, or `null` when the change log is empty. */
     getMinSeq(conn: SQLiteConnection): Promise<bigint | null>;
-    private rowToEvent;
+    /** @internal */
     advanceToLatest(conn: SQLiteConnection): Promise<void>;
+    /** @internal */
     cleanup(conn: SQLiteConnection): Promise<number>;
+    /** @internal */
     setPruneBoundary(seq: bigint): void;
+    /** @internal */
     clearPruneBoundary(): void;
+    /** @internal */
     get watchedTables(): ReadonlySet<string>;
     private computeSeqBound;
     private assertIdentifier;
     private detectChangesTable;
     private ensureChangesTable;
-    private getColumns;
-    private getPkColumns;
-    private dropTriggers;
-    private getStmt;
     private installTriggers;
 }
 

package/dist/chunk-2QLXDHAP.mjs

@@ -0,0 +1,18 @@
+import { SirannonError } from './chunk-PBRXXISQ.mjs';
+
+// src/core/sync/errors.ts
+var ReplicationError = class extends SirannonError {
+  constructor(message, code = "REPLICATION_ERROR", details) {
+    super(message, code);
+    this.details = details;
+    this.name = "ReplicationError";
+  }
+};
+var BatchValidationError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "BATCH_VALIDATION_ERROR");
+    this.name = "BatchValidationError";
+  }
+};
+
+export { BatchValidationError, ReplicationError };

package/dist/chunk-7C36BCSN.mjs

@@ -0,0 +1,18 @@
+import { MigrationError } from './chunk-PBRXXISQ.mjs';
+
+// src/core/migrations/lazy-down.ts
+var LAZY_DOWN_SQL = /* @__PURE__ */ Symbol("sirannon.file-migration.lazy-down");
+
+// src/core/migrations/filename.ts
+var MIGRATION_FILENAME_PATTERN = /^(\d+)_(\w+)\.(up|down)\.sql$/;
+function parseMigrationFilename(filename) {
+  const match = MIGRATION_FILENAME_PATTERN.exec(filename);
+  if (!match) return null;
+  const version = parseInt(match[1], 10);
+  if (!Number.isFinite(version) || version <= 0 || !Number.isSafeInteger(version)) {
+    throw new MigrationError(`Invalid migration version: ${match[1]}`, version, "MIGRATION_VALIDATION_ERROR");
+  }
+  return { version, name: match[2], direction: match[3] };
+}
+
+export { LAZY_DOWN_SQL, MIGRATION_FILENAME_PATTERN, parseMigrationFilename };