@classytic/mongokit 3.43.0 → 3.44.0

package/dist/{repository-MqAP409e.d.mts → repository-DzVIwhU2.d.mts}

@@ -1,10 +1,9 @@
-import { A as ObjectId, D as AnyDocument, F as SortSpec, M as ReadPreferenceType, N as SelectSpec, _ as QueryDefaults, b as WriteConcernSpec, i as CountStrategy, j as PopulateSpec, k as FilterQuery, p as AggregateDefaults, v as ReadConcernLevel } from "./pagination-D6psses0.mjs";
-import { r as DocField } from "./type-utils-CLzRFtIA.mjs";
+import { A as ObjectId, D as AnyDocument, F as SortSpec, M as ReadPreferenceType, N as SelectSpec, _ as QueryDefaults, b as WriteConcernSpec, i as CountStrategy, j as PopulateSpec, k as FilterQuery, p as AggregateDefaults, v as ReadConcernLevel } from "./pagination-DAUg5zOY.mjs";
+import { r as DocField } from "./type-utils-CKvuewAL.mjs";
 import { DistributionConfig, DistributionMissHandler, RepoCapabilities, RepositoryBase } from "@classytic/repo-core/repository";
 import { Model, PipelineStage } from "mongoose";
 import { HttpError } from "@classytic/repo-core/errors";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
-//#region src/plugins/names.d.ts
 /**
  * Canonical identifiers exposed by mongokit's bundled plugins.
  *
@@ -13,34 +12,32 @@ import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
  * The values intentionally preserve the plugins' existing public names.
  */
 declare const MONGOKIT_PLUGIN_NAMES: {
-  readonly aggregateHelpers: "aggregate-helpers";
-  readonly appendOnly: "appendOnly";
-  readonly auditLog: "auditLog";
-  readonly auditTrail: "auditTrail";
-  readonly batchOperations: "batch-operations";
-  readonly cache: "cache";
-  readonly cascade: "cascade";
-  readonly changeLog: "changeLog";
-  readonly customId: "custom-id";
-  readonly elasticSearch: "elastic-search";
-  readonly fieldFilter: "fieldFilter";
-  readonly immutableStates: "immutableStates";
-  readonly lease: "lease";
-  readonly methodRegistry: "method-registry";
-  readonly mongoOperations: "mongo-operations";
-  readonly multiTenant: "multi-tenant";
-  readonly observability: "observability";
-  readonly searchKeys: "search-keys";
-  readonly softDelete: "softDelete";
-  readonly subdocument: "subdocument";
-  readonly timestamp: "timestamp";
-  readonly validationChain: "validation-chain";
+  readonly aggregateHelpers: 'aggregate-helpers';
+  readonly appendOnly: 'appendOnly';
+  readonly auditLog: 'auditLog';
+  readonly auditTrail: 'auditTrail';
+  readonly batchOperations: 'batch-operations';
+  readonly cache: 'cache';
+  readonly cascade: 'cascade';
+  readonly changeLog: 'changeLog';
+  readonly customId: 'custom-id';
+  readonly elasticSearch: 'elastic-search';
+  readonly fieldFilter: 'fieldFilter';
+  readonly immutableStates: 'immutableStates';
+  readonly lease: 'lease';
+  readonly methodRegistry: 'method-registry';
+  readonly mongoOperations: 'mongo-operations';
+  readonly multiTenant: 'multi-tenant';
+  readonly observability: 'observability';
+  readonly searchKeys: 'search-keys';
+  readonly softDelete: 'softDelete';
+  readonly subdocument: 'subdocument';
+  readonly timestamp: 'timestamp';
+  readonly validationChain: 'validation-chain';
 };
 type MongoKitPluginName = (typeof MONGOKIT_PLUGIN_NAMES)[keyof typeof MONGOKIT_PLUGIN_NAMES];
 /** Bundled-name autocomplete while remaining open to third-party plugins. */
 type RepositoryPluginName = MongoKitPluginName | (string & Record<never, never>);
-//#endregion
-//#region src/types/repository.d.ts
 /** Hook execution mode */
 type HookMode = 'sync' | 'async';
 /**
@@ -533,7 +530,7 @@ type AllPluginMethods<TDoc> = {
   setMin(id: string | ObjectId, field: DocField<TDoc>, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
   setMax(id: string | ObjectId, field: DocField<TDoc>, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
   atomicUpdate(id: string | ObjectId, operators: Record<string, Record<string, unknown>>, options?: Record<string, unknown>): Promise<TDoc>;
-  bulkWrite(operations: Record<string, unknown>[], options?: {
+  bulkWrite(operations: readonly Record<string, unknown>[], options?: {
     session?: unknown;
     ordered?: boolean;
   }): Promise<{
@@ -602,5 +599,4 @@ type AllPluginMethods<TDoc> = {
  * ```
  */
 type WithPlugins<TDoc, TRepo extends RepositoryInstance = RepositoryInstance> = TRepo & AllPluginMethods<TDoc>;
-//#endregion
 export { RepositoryPluginName as C, MongoKitPluginName as S, RepositoryOptions as _, HookMode as a, WithPlugins as b, MinimalRepoView as c, PluginType as d, PrioritizedHook as f, RepositoryOperation as g, RepositoryInstance as h, EventPhase as i, Plugin as l, RepositoryEvent as m, EventHandlers as n, Middleware as o, RepositoryContext as p, EventPayload as r, MiddlewareContext as s, AllPluginMethods as t, PluginFunction as u, RepositorySearchMode as v, MONGOKIT_PLUGIN_NAMES as x, UserContext as y };

package/dist/retention-purge-DqcYvRnG.d.mts

@@ -0,0 +1,35 @@
+import { p as RepositoryContext } from "./repository-DzVIwhU2.mjs";
+/** Per-call retention purge request (`options.retentionPurge`). */
+interface RetentionPurgeRequest {
+  /** Why the rows are removed (e.g. `'retention: 7 years'`). Required, non-blank. */
+  reason: string;
+  /** Who or what purges (user id, `'job:retention'`). Carried to the audit events. */
+  actor?: string | undefined;
+}
+/** Common payload of the per-plugin purge audit events, one per successful delete call. */
+interface RetentionPurgeEvent {
+  operation: 'delete' | 'deleteMany';
+  reason: string;
+  actor: string | undefined;
+  /** `delete`: the id. */
+  id: unknown;
+  /** `deleteMany`: the final filter (after policy hooks such as tenant scope). */
+  filter: Record<string, unknown> | undefined;
+  /** Rows removed (`delete`: 1 or 0). */
+  deletedCount: number;
+  /**
+   * The delete's session, when the call ran in one. Write the audit row with it
+   * (`{ session: event.session }`) so the delete and its audit commit or abort
+   * together. Listeners are awaited and a throwing one fails the purge call.
+   */
+  session: unknown;
+  context: RepositoryContext;
+}
+/** Error codes thrown for a malformed or unauthorized retention purge. */
+declare const RETENTION_PURGE_ERROR_CODES: {
+  readonly DISABLED: 'RETENTION_PURGE_DISABLED';
+  readonly REASON_REQUIRED: 'RETENTION_PURGE_REASON_REQUIRED';
+  readonly INVALID_ACTOR: 'RETENTION_PURGE_INVALID_ACTOR';
+  readonly HARD_ONLY: 'RETENTION_PURGE_HARD_ONLY';
+};
+export { RetentionPurgeEvent as n, RetentionPurgeRequest as r, RETENTION_PURGE_ERROR_CODES as t };

package/dist/{rolldown-runtime-D7D4PA-g.mjs → rolldown-runtime-D8jQpDG7.mjs}

@@ -1,4 +1,4 @@
-//#region \0rolldown/runtime.js
+// \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -9,5 +9,4 @@ var __exportAll = (all, no_symbols) => {
 	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
-//#endregion
 export { __exportAll as t };

package/dist/search/index.d.mts

@@ -1,2 +1,2 @@
-import { a as prefixSearchFilter, c as SearchMatchRange, d as tokenizeSearchText, f as SEARCH_KEYS_ERROR_CODES, i as buildSearchKeys, l as findSearchMatches, n as MAX_PREFIX_SEARCH_TERMS, o as searchKeysIndex, p as SearchKeysWriteError, r as PrefixSearchFilterOptions, s as searchKeysPath, t as DEFAULT_SEARCH_KEYS_FIELD, u as normalizeSearchText } from "../index-C0AjVqX3.mjs";
+import { a as prefixSearchFilter, c as SearchMatchRange, d as tokenizeSearchText, f as SEARCH_KEYS_ERROR_CODES, i as buildSearchKeys, l as findSearchMatches, n as MAX_PREFIX_SEARCH_TERMS, o as searchKeysIndex, p as SearchKeysWriteError, r as PrefixSearchFilterOptions, s as searchKeysPath, t as DEFAULT_SEARCH_KEYS_FIELD, u as normalizeSearchText } from "../index-ehGZLbrd.mjs";
 export { DEFAULT_SEARCH_KEYS_FIELD, MAX_PREFIX_SEARCH_TERMS, type PrefixSearchFilterOptions, SEARCH_KEYS_ERROR_CODES, SearchKeysWriteError, type SearchMatchRange, buildSearchKeys, findSearchMatches, normalizeSearchText, prefixSearchFilter, searchKeysIndex, searchKeysPath, tokenizeSearchText };

package/dist/search/index.mjs

@@ -1,2 +1 @@
-import { _ as tokenizeSearchText, d as buildSearchKeys, f as prefixSearchFilter, g as normalizeSearchText, h as findSearchMatches, l as DEFAULT_SEARCH_KEYS_FIELD, m as searchKeysPath, n as SearchKeysWriteError, p as searchKeysIndex, t as SEARCH_KEYS_ERROR_CODES, u as MAX_PREFIX_SEARCH_TERMS } from "../derive-DRBiegRH.mjs";
-export { DEFAULT_SEARCH_KEYS_FIELD, MAX_PREFIX_SEARCH_TERMS, SEARCH_KEYS_ERROR_CODES, SearchKeysWriteError, buildSearchKeys, findSearchMatches, normalizeSearchText, prefixSearchFilter, searchKeysIndex, searchKeysPath, tokenizeSearchText };
+export { l as DEFAULT_SEARCH_KEYS_FIELD, u as MAX_PREFIX_SEARCH_TERMS, t as SEARCH_KEYS_ERROR_CODES, n as SearchKeysWriteError, d as buildSearchKeys, h as findSearchMatches, g as normalizeSearchText, f as prefixSearchFilter, p as searchKeysIndex, m as searchKeysPath, _ as tokenizeSearchText } from "../derive-Dxsc31fV.mjs";

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, 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,21 +13,40 @@ 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;
 /** 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
+   * Delete every entry a later COMMITTED entry of the same `(tenantId, 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.
    */
@@ -37,6 +55,29 @@ interface MongoChangeLogStore extends ChangeLogStore {
   }): Promise<{
     removed: number;
   }>;
+  /**
+   * Retention with a horizon (the `ChangeLogStore.prune` contract). Deletes every entry older than
+   * `before` (`at < before`) that a later entry of the same `(tenantId, scope, docId)` replaced:
+   * each document's latest entry stays, tombstone or not, so a full reload 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 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 +88,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. A pruned or compacted
+   * document still has its latest entry (both keep it).
+   */
+  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 +151,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>;