@classytic/mongokit 3.43.1 → 3.45.0

package/dist/sync/index.d.mts

@@ -1,7 +1,6 @@
 import { ClientSession, Connection, Model } from "mongoose";
-import { ChangeLogAppendOptions, ChangeLogStore, CommandStreamStore, CommandStreamTx } from "@classytic/repo-core/sync";
-//#region src/sync/index.d.ts
-interface ChangeLogModelOptions {
+import { ChangeEntry, ChangeLogAppendOptions, ChangeLogStore, ChangesPage, ChangesSinceOptions, CommandStreamStore, CommandStreamTx } from "@classytic/repo-core/sync";
+export interface ChangeLogModelOptions {
   /** Entries collection. Default `sync_changes`; its counter lives in `<collection>_counter`. */
   collection?: string;
   /** Mongoose model name prefix. Default `SyncChange`. Must be unique per connection. */
@@ -14,29 +13,87 @@ interface ChangeLogModelOptions {
    * before, so no reader can checkpoint past an entry that appears later.
    */
   sequencing?: 'in-transaction' | 'deferred';
+  /**
+   * Deferred sequencing: how long the sequencer lease lasts, in ms (default {@link DEFAULT_SEQUENCER_LEASE_MS}).
+   * The holder renews it with every batch it commits, so this bounds one batch, not one pass, and it is the longest
+   * a sequencer that dies mid-pass can delay numbering. Expiry is judged on the database clock (`$$NOW`), so
+   * process clock skew does not stretch it. A holder whose lease was taken over cannot write: each batch commits
+   * in one transaction gated on the lease token. Integer, at least 100.
+   */
+  sequencerLeaseMs?: number;
 }
-interface ChangeLogModels {
+/** Default deferred-sequencer lease: a crashed holder delays numbering at most this long. */
+export declare const DEFAULT_SEQUENCER_LEASE_MS = 5000;
+export interface ChangeLogModels {
   entries: Model<Record<string, unknown>>;
   counter: Model<Record<string, unknown>>;
+  /**
+   * `prune`'s horizons per `(tenantId, scope)` (`<collection>_horizon`, `tenantId: null` for untenanted entries):
+   * the highest seq it deleted there. A filtered reader is expired only by the horizons of what it can see.
+   * Always set by `createChangeLogModels`; a hand-built models object without it falls back to the feed-wide
+   * horizon for every reader.
+   */
+  horizons?: Model<Record<string, unknown>>;
   /** Staged, not-yet-numbered entries — present only under `sequencing: 'deferred'`. */
   pending?: Model<Record<string, unknown>>;
   sequencing: 'in-transaction' | 'deferred';
+  /** Deferred sequencer lease in ms; {@link DEFAULT_SEQUENCER_LEASE_MS} when absent (a hand-built models object). */
+  sequencerLeaseMs?: number;
   /** The counter document's id (one feed per entries collection). */
   feed: string;
 }
-declare function createChangeLogModels(connection: Connection, options?: ChangeLogModelOptions): ChangeLogModels;
+export declare function createChangeLogModels(connection: Connection, options?: ChangeLogModelOptions): ChangeLogModels;
+/** {@link MongoChangeLogStore.snapshot}'s options: the reader's view, plus the bound after the first page. */
+export interface ChangesSnapshotOptions extends ChangesSinceOptions {
+  /** The `upTo` the first page returned; omit it on the first page. */
+  readonly upTo?: string;
+}
+/** One snapshot page. `cursor` pages the snapshot; `upTo` is where `since()` resumes once `hasMore` is false. */
+export interface ChangesSnapshotPage extends ChangesPage {
+  readonly upTo: string;
+}
 /** The mongo change feed: the `ChangeLogStore` contract plus superseded-entry compaction. */
-interface MongoChangeLogStore extends ChangeLogStore {
+export interface MongoChangeLogStore extends ChangeLogStore {
   /**
-   * Delete every entry a later COMMITTED entry of the same `(scope, docId)` replaced. Safe for any client
-   * cursor: entries carry whole documents, so a reader only ever needs the latest one; tombstones and
-   * each document's latest entry stay. Idempotent; run it on a schedule.
+   * Delete every entry of a `(tenantId, scope, docId)` but the one a reader ends on (the last
+   * tombstone, or the highest-version upsert after it). Safe for any client cursor: entries carry
+   * whole documents, and a reader would have skipped every deleted one. Idempotent; run it on a schedule.
    */
   compactSuperseded(options?: {
     batchSize?: number;
   }): Promise<{
     removed: number;
   }>;
+  /**
+   * Retention with a horizon (the `ChangeLogStore.prune` contract). Deletes every entry older than
+   * `before` (`at < before`) except, per `(tenantId, scope, docId)`, the one a reader ends on (as
+   * `compactSuperseded` keeps), so a snapshot still sees every document. Records a HORIZON (the highest deleted cursor, never lowered) per `(tenantId, scope)`
+   * and feed-wide, BEFORE deleting, and returns the feed-wide one, `''` while nothing was ever
+   * pruned. `since(cursor, options)` with a cursor below the horizon of what that reader can see
+   * (its tenant, shared scopes and `scopes`; the feed-wide horizon when unfiltered; `''` included)
+   * throws repo-core's `CursorExpiredError(cursor, horizon)`: that reader missed deleted
+   * intermediate entries and must resync from `latestCursor(options)`, which never answers below
+   * that horizon. Pruning one tenant never expires another tenant's cursor. Unlike
+   * `compactSuperseded`, which is safe for any cursor but silently drops intermediate entries a
+   * resuming reader has not seen, a reader never gets a silent gap here. Idempotent; schedule it
+   * (e.g. hourly with `before = now - 24h`).
+   */
+  prune(before: Date, options?: {
+    batchSize?: number;
+  }): Promise<string>;
+  /**
+   * The resync bootstrap for a reader `since()` expired: each document's latest entry at or below
+   * `upTo` (the reader's horizon, fixed by the first page), tombstones left out, in feed order. Then
+   * `since(upTo)` carries on, delivering every change above it, deletes included. Complete because
+   * `prune` and `compactSuperseded` never delete a document's latest entry. If that `since(upTo)`
+   * expires again, a prune raised the horizon in between: bootstrap again.
+   */
+  snapshot(cursor: string, options?: ChangesSnapshotOptions): Promise<ChangesSnapshotPage>;
+  /**
+   * The compaction horizon cursor a reader with these options is held to (`''` while nothing it
+   * can see was pruned); feed-wide without options.
+   */
+  horizon(options?: Pick<ChangesSinceOptions, 'tenantId' | 'scopes' | 'sharedScopes'>): Promise<string>;
   /**
    * Number every staged entry (deferred sequencing; a no-op otherwise). Reads call it first; a scheduler may too.
    * Returns how many it numbered, or `null` when another sequencer holds the lease.
@@ -47,21 +104,62 @@ interface MongoChangeLogStore extends ChangeLogStore {
    * never use the cursor (`changeLogPlugin`). Under in-transaction sequencing it is `append`.
    */
   stage(entry: Parameters<ChangeLogStore['append']>[0], options?: ChangeLogAppendOptions): Promise<void>;
+  /**
+   * Point read of ONE document's latest recorded change: its last staged entry when one waits for a cursor
+   * (deferred sequencing; `cursor: ''`, as `append` answers inside a transaction), else its highest numbered
+   * entry; `null` when the feed holds none. Reads only (it never runs the sequencer), so it is cheap on a hot
+   * path, e.g. a writer that needs the last recorded state of a record before it appends the next change.
+   * A document is `(tenantId, scope, docId)`: `tenantId` omitted or `null` reads the untenanted document.
+   * Pass `session` to see what the caller staged or appended in its own transaction. Pruning and
+   * compaction keep the entry a reader ends on, which may not be the last one recorded.
+   */
+  latestOf(scope: string, docId: string, options?: {
+    tenantId?: string | null;
+    session?: unknown;
+  }): Promise<ChangeEntry | null>;
+}
+/** What {@link ChangeLogStoreOptions.onSequenced} is told: new entries now have cursors up to `cursor`. */
+export interface ChangeLogSequencedEvent {
+  /** The highest numbered cursor of the feed after the pass (readers reading past their cursor see the new entries). */
+  cursor: string;
+  /** How many entries were numbered since this store last looked (by this store, or by another holder). */
+  numbered: number;
+  /** `'self'`: this store's pass numbered them. `'other'`: another holder did, while a read of this store waited. */
+  by: 'self' | 'other';
+}
+/** Runtime options of {@link createChangeLogStore} (the models carry the storage options). */
+export interface ChangeLogStoreOptions {
+  /**
+   * Clock for every entry's `at` (staged and in-transaction appends). Default `() => new Date()`. Inject the host's
+   * clock so `at` and `prune(before)` cutoffs agree with a driven test clock. The deferred sequencer's LEASE stays on
+   * the database clock (`$$NOW`): it is shared by every process, so it must not depend on any one process's clock.
+   */
+  now?: () => Date;
+  /**
+   * Deferred sequencing: called after new entries got cursors, so a host's replay hub can `notify()` its tails at
+   * once. Fires when this store's pass numbered entries (`by: 'self'`), and when a read of this store found the
+   * sequencer lease held by another holder: the store then retries in the background (short backoff, unref'd
+   * timers, for at most three leases) until that holder is done, and reports what it numbered meanwhile
+   * (`by: 'other'`), or takes over a lease left by a holder that died and numbers the entries itself
+   * (`by: 'self'`). Without this hook nothing is retried in the background. A throwing hook is ignored. Never
+   * called under in-transaction sequencing (every append already has its cursor).
+   */
+  onSequenced?: (event: ChangeLogSequencedEvent) => void;
 }
-declare function createChangeLogStore(models: ChangeLogModels): MongoChangeLogStore;
-interface CommandStreamModelOptions {
+export declare function createChangeLogStore(models: ChangeLogModels, storeOptions?: ChangeLogStoreOptions): MongoChangeLogStore;
+export interface CommandStreamModelOptions {
   /** Collection prefix: `<prefix>_streams`, `<prefix>_verdicts`, `<prefix>_aliases`. Default `sync`. */
   prefix?: string;
   /** Mongoose model name prefix. Default `SyncStream`. Must be unique per connection. */
   modelName?: string;
 }
-interface CommandStreamModels {
+export interface CommandStreamModels {
   streams: Model<Record<string, unknown>>;
   verdicts: Model<Record<string, unknown>>;
   aliases: Model<Record<string, unknown>>;
 }
-declare function createCommandStreamModels(connection: Connection, options?: CommandStreamModelOptions): CommandStreamModels;
-interface MongoCommandStreamTx extends CommandStreamTx {
+export declare function createCommandStreamModels(connection: Connection, options?: CommandStreamModelOptions): CommandStreamModels;
+export interface MongoCommandStreamTx extends CommandStreamTx {
   readonly session: ClientSession;
 }
 /**
@@ -69,6 +167,4 @@ interface MongoCommandStreamTx extends CommandStreamTx {
  * Concurrent transactions on one stream write-conflict on its document and `withTransaction`
  * retries the loser, which then reads the winner's watermark.
  */
-declare function createCommandStreamStore(connection: Pick<Connection, 'startSession'>, models: CommandStreamModels, changes: ChangeLogStore): CommandStreamStore<MongoCommandStreamTx>;
-//#endregion
-export { ChangeLogModelOptions, ChangeLogModels, CommandStreamModelOptions, CommandStreamModels, MongoChangeLogStore, MongoCommandStreamTx, createChangeLogModels, createChangeLogStore, createCommandStreamModels, createCommandStreamStore };
+export declare function createCommandStreamStore(connection: Pick<Connection, 'startSession'>, models: CommandStreamModels, changes: ChangeLogStore): CommandStreamStore<MongoCommandStreamTx>;