@classytic/mongokit 3.39.0 → 3.40.1

package/dist/read-model/index.d.mts

@@ -0,0 +1,66 @@
+import { r as Repository } from "../Repository-pnLw1rG5.mjs";
+import { BulkUpsertResult } from "@classytic/repo-core/repository";
+//#region src/read-model/index.d.ts
+declare const READ_MODEL_ERROR_CODES: {
+  readonly MERGE_IN_TRANSACTION: "mongokit.read_model.merge_in_transaction";
+  readonly ON_NOT_UNIQUE: "mongokit.read_model.on_not_unique";
+  readonly ON_MISSING_SCOPE: "mongokit.read_model.on_missing_scope";
+  readonly DEDUPE_NEEDS_TRANSACTION: "mongokit.read_model.dedupe_needs_transaction";
+  readonly DEDUPE_KEY_MISSING: "mongokit.read_model.dedupe_key_missing";
+  readonly INCREMENT_FAILED: "mongokit.read_model.increment_failed";
+  readonly TOO_LARGE: "mongokit.read_model.too_large";
+};
+/** Caller scope forwarded to every repository call (tenant, bypass, attribution). */
+type ReadModelScope = Record<string, unknown>;
+interface IncrementGrain {
+  /** The read-model key (without the policy scope, which the repository adds). */
+  key: Record<string, unknown>;
+  inc: Record<string, number>;
+  setOnInsert?: Record<string, unknown>;
+  /** Identity of the event this grain comes from; required when a ledger is given. */
+  dedupeKey?: string;
+}
+/** Sum grains per key, apply them in one upsert; with a ledger, count each dedupeKey once. */
+declare function applyIncrements<TDoc>(target: Repository<TDoc>, grains: readonly IncrementGrain[], options?: ReadModelScope & {
+  session?: unknown;
+  /** Repository over a collection unique on (scope, `dedupeKey`). */
+  ledger?: Repository<unknown>;
+}): Promise<BulkUpsertResult>;
+interface RebuildOptions {
+  /** Source stages producing one row per read-model grain (with every `on` field except scope fields). */
+  pipeline: readonly unknown[];
+  /** Fields identifying a grain; must equal a unique index of the target and include its tenant field. */
+  on: readonly string[];
+  whenMatched?: 'replace' | 'merge';
+  /** Caller scope (tenant etc.), applied to the source read and stamped on the target rows. */
+  scope?: ReadModelScope;
+  session?: unknown;
+}
+/** Rebuild the scope's slice of `target` from `source` with one `$merge`, then drop stale grains. */
+declare function rebuildInto<TSrc, TDoc>(source: Repository<TSrc>, target: Repository<TDoc>, options: RebuildOptions): Promise<{
+  rebuildId: string;
+  removed: number;
+}>;
+interface ReconcileOptions {
+  pipeline: readonly unknown[];
+  on: readonly string[];
+  /** Fields compared between the recomputed and the stored row. */
+  measures: readonly string[];
+  scope?: ReadModelScope;
+  /** Refuse past this many rows on either side (both are held in memory). Default 100,000. */
+  maxRows?: number;
+}
+interface DriftRow {
+  key: Record<string, unknown>;
+  /** Recomputed measures, `null` when the source produces no such grain. */
+  expected: Record<string, unknown> | null;
+  /** Stored measures, `null` when the read model lacks the grain. */
+  actual: Record<string, unknown> | null;
+}
+/** Recompute the scope's grains from `source` and report every one that differs in `target`. */
+declare function reconcile<TSrc, TDoc>(source: Repository<TSrc>, target: Repository<TDoc>, options: ReconcileOptions): Promise<{
+  drift: DriftRow[];
+  compared: number;
+}>;
+//#endregion
+export { DriftRow, IncrementGrain, READ_MODEL_ERROR_CODES, ReadModelScope, RebuildOptions, ReconcileOptions, applyIncrements, rebuildInto, reconcile };

package/dist/read-model/index.mjs

@@ -0,0 +1,193 @@
+import { t as createError } from "../error-BuByZwKU.mjs";
+import { i as scopeForCollection, o as tenantFieldsOf } from "../join-scope-DSAznE8E.mjs";
+import { randomUUID } from "node:crypto";
+//#region src/read-model/index.ts
+/**
+* `@classytic/mongokit/read-model` — maintain and verify a derived (read) collection.
+*
+* - {@link applyIncrements}: grains summed per key, then ONE `bulkUpsert` (`$inc` + `$setOnInsert`)
+*   inside the caller's unit of work. With a `ledger`, each grain's `dedupeKey` is recorded in the
+*   SAME transaction and a key already recorded is skipped, so a replayed event counts once.
+* - {@link rebuildInto}: the source pipeline (scoped by the source repository) ends in a `$merge`
+*   on a unique `on`; grains of the scope the source no longer produces are then removed.
+*   `$merge` cannot run in a transaction, so a session inside one is refused.
+* - {@link reconcile}: recompute from the source and compare with the read model; returns drift.
+*/
+const READ_MODEL_ERROR_CODES = {
+	MERGE_IN_TRANSACTION: "mongokit.read_model.merge_in_transaction",
+	ON_NOT_UNIQUE: "mongokit.read_model.on_not_unique",
+	ON_MISSING_SCOPE: "mongokit.read_model.on_missing_scope",
+	DEDUPE_NEEDS_TRANSACTION: "mongokit.read_model.dedupe_needs_transaction",
+	DEDUPE_KEY_MISSING: "mongokit.read_model.dedupe_key_missing",
+	INCREMENT_FAILED: "mongokit.read_model.increment_failed",
+	TOO_LARGE: "mongokit.read_model.too_large"
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function inTransaction(session) {
+	const s = session;
+	return typeof s?.inTransaction === "function" && s.inTransaction();
+}
+/** Sum grains per key, apply them in one upsert; with a ledger, count each dedupeKey once. */
+async function applyIncrements(target, grains, options = {}) {
+	const { ledger, ...scope } = options;
+	let live = grains;
+	if (ledger) {
+		if (!inTransaction(scope.session)) throw createError(500, "[mongokit] applyIncrements: a dedupe ledger is only correct inside a transaction", { code: READ_MODEL_ERROR_CODES.DEDUPE_NEEDS_TRANSACTION });
+		if (grains.some((g) => !g.dedupeKey)) throw createError(400, "[mongokit] applyIncrements: every grain needs a dedupeKey when a ledger is given", { code: READ_MODEL_ERROR_CODES.DEDUPE_KEY_MISSING });
+		const keys = [...new Set(grains.flatMap((g) => g.dedupeKey ? [g.dedupeKey] : []))];
+		const seen = new Set((await ledger.findAll({ dedupeKey: { $in: keys } }, {
+			...scope,
+			select: "dedupeKey",
+			lean: true
+		})).map((d) => d).filter(isRecord).map((d) => String(d.dedupeKey)));
+		const fresh = keys.filter((k) => !seen.has(k));
+		if (fresh.length > 0) await ledger.createMany(fresh.map((dedupeKey) => ({ dedupeKey })), scope);
+		const freshSet = new Set(fresh);
+		const taken = /* @__PURE__ */ new Set();
+		live = grains.filter((g) => {
+			const k = g.dedupeKey;
+			if (!k || !freshSet.has(k) || taken.has(k)) return false;
+			taken.add(k);
+			return true;
+		});
+	}
+	if (live.length === 0) return {
+		results: [],
+		inserted: 0,
+		updated: 0,
+		unchanged: 0,
+		failed: 0
+	};
+	const summed = /* @__PURE__ */ new Map();
+	for (const g of live) {
+		const id = JSON.stringify(Object.keys(g.key).sort().map((k) => [k, g.key[k]]));
+		const slot = summed.get(id) ?? {
+			key: g.key,
+			inc: {},
+			setOnInsert: { ...g.setOnInsert }
+		};
+		for (const [field, n] of Object.entries(g.inc)) slot.inc[field] = (slot.inc[field] ?? 0) + n;
+		summed.set(id, slot);
+	}
+	const rows = [...summed.values()].map((s) => ({
+		...s.key,
+		...s.inc,
+		...s.setOnInsert
+	}));
+	const first = [...summed.values()][0];
+	const result = await target.bulkUpsert(rows, {
+		...scope,
+		key: Object.keys(first?.key ?? {}),
+		inc: [...new Set([...summed.values()].flatMap((s) => Object.keys(s.inc)))],
+		setOnInsert: [...new Set([...summed.values()].flatMap((s) => Object.keys(s.setOnInsert)))]
+	});
+	if (result.failed > 0) throw createError(500, `[mongokit] applyIncrements: ${result.failed} grain(s) failed; the unit of work must abort`, {
+		code: READ_MODEL_ERROR_CODES.INCREMENT_FAILED,
+		meta: { failures: result.results.filter((r) => r.outcome === "failed") }
+	});
+	return result;
+}
+function contextOf(scope) {
+	return {
+		operation: "aggregatePipeline",
+		model: "read-model",
+		...scope
+	};
+}
+/** The target's policy predicate for this scope (tenant + live docs), as equality fields. */
+function targetScope(target, scope) {
+	const predicate = scopeForCollection(target.Model.collection.collectionName, {
+		connection: target.Model.db,
+		context: contextOf(scope),
+		operation: "aggregatePipeline"
+	});
+	if (!predicate) return {};
+	const parts = Array.isArray(predicate.$and) ? predicate.$and.filter(isRecord) : [predicate];
+	return Object.assign({}, ...parts);
+}
+/** Rebuild the scope's slice of `target` from `source` with one `$merge`, then drop stale grains. */
+async function rebuildInto(source, target, options) {
+	const scope = options.scope ?? {};
+	if (inTransaction(options.session)) throw createError(500, "[mongokit] rebuildInto: $merge cannot run inside a transaction", { code: READ_MODEL_ERROR_CODES.MERGE_IN_TRANSACTION });
+	const on = [...options.on];
+	const missing = tenantFieldsOf(target.Model).filter((f) => !on.includes(f));
+	if (missing.length > 0) throw createError(400, `[mongokit] rebuildInto: 'on' must include the target's tenant field(s) ${missing.join(", ")}`, { code: READ_MODEL_ERROR_CODES.ON_MISSING_SCOPE });
+	if (!target.Model.schema.indexes().some(([fields, opts]) => opts.unique === true && sameSet(Object.keys(fields), on))) throw createError(400, `[mongokit] rebuildInto: $merge needs a unique index on exactly (${on.join(", ")})`, { code: READ_MODEL_ERROR_CODES.ON_NOT_UNIQUE });
+	const rebuildId = randomUUID();
+	const stamp = {
+		...targetScope(target, scope),
+		_rebuildId: rebuildId
+	};
+	const stages = [
+		...options.pipeline,
+		{ $set: stamp },
+		{ $merge: {
+			into: target.Model.collection.collectionName,
+			on,
+			whenMatched: options.whenMatched ?? "replace",
+			whenNotMatched: "insert"
+		} }
+	];
+	await source.aggregatePipeline(stages, {
+		...scope,
+		...options.session ? { session: options.session } : {}
+	});
+	return {
+		rebuildId,
+		removed: (await target.deleteMany({ _rebuildId: { $ne: rebuildId } }, {
+			...scope,
+			...options.session ? { session: options.session } : {}
+		})).deletedCount
+	};
+}
+function sameSet(a, b) {
+	return a.length === b.length && a.every((x) => b.includes(x));
+}
+function canonical(value) {
+	if (value === null || value === void 0) return "null";
+	if (isRecord(value) && value._bsontype === "Decimal128") return String(Number(String(value)));
+	return JSON.stringify(value);
+}
+/** Recompute the scope's grains from `source` and report every one that differs in `target`. */
+async function reconcile(source, target, options) {
+	const scope = options.scope ?? {};
+	const maxRows = options.maxRows ?? 1e5;
+	const stamp = targetScope(target, scope);
+	const keyFields = options.on.filter((f) => !(f in stamp));
+	const pick = (row, fields) => Object.fromEntries(fields.map((f) => [f, row[f] ?? null]));
+	const id = (row) => keyFields.map((f) => canonical(row[f])).join("|");
+	const expectedRows = await source.aggregatePipeline([...options.pipeline, { $limit: maxRows + 1 }], scope);
+	const actualRows = (await target.findAll({}, {
+		...scope,
+		select: [...keyFields, ...options.measures].join(" "),
+		limit: maxRows + 1,
+		lean: true
+	})).map((d) => d).filter(isRecord);
+	if (expectedRows.length > maxRows || actualRows.length > maxRows) throw createError(500, `[mongokit] reconcile: more than ${maxRows} grains in scope; reconcile a narrower scope`, { code: READ_MODEL_ERROR_CODES.TOO_LARGE });
+	const actual = new Map(actualRows.map((r) => [id(r), r]));
+	const drift = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const e of expectedRows) {
+		const k = id(e);
+		seen.add(k);
+		const a = actual.get(k);
+		if (!a || options.measures.some((m) => canonical(e[m]) !== canonical(a[m]))) drift.push({
+			key: pick(e, keyFields),
+			expected: pick(e, options.measures),
+			actual: a ? pick(a, options.measures) : null
+		});
+	}
+	for (const [k, a] of actual) if (!seen.has(k)) drift.push({
+		key: pick(a, keyFields),
+		expected: null,
+		actual: pick(a, options.measures)
+	});
+	return {
+		drift,
+		compared: expectedRows.length
+	};
+}
+//#endregion
+export { READ_MODEL_ERROR_CODES, applyIncrements, rebuildInto, reconcile };

package/dist/{repository-ZbLtL7Nk.d.mts → repository-DNHfjAZX.d.mts}

@@ -1,4 +1,4 @@
-import { _ as PopulateSpec, g as ObjectId, h as FilterQuery, i as CountStrategy, p as AnyDocument, v as ReadPreferenceType, x as SortSpec, y as SelectSpec } from "./pagination-BpIv2bdS.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-D6psses0.mjs";
 import { r as DocField } from "./type-utils-CLzRFtIA.mjs";
 import { DistributionConfig, DistributionMissHandler, RepoCapabilities, RepositoryBase } from "@classytic/repo-core/repository";
 import { Model, PipelineStage } from "mongoose";
@@ -199,6 +199,13 @@ interface RepositoryOptions {
    * ```
    */
   requirePlugins?: readonly RepositoryPluginName[];
+  /**
+   * Time bound and concerns for every command this repository issues. A per-call value
+   * wins; unset fields fall back to `configureQueryDefaults` (see `repository/query-defaults.ts`).
+   */
+  queryDefaults?: QueryDefaults;
+  /** Aggregation-only defaults, consulted before `queryDefaults`. */
+  aggregateDefaults?: AggregateDefaults;
   /**
    * Declare the collection's shard key so every filter-taking verb
    * (`getAll`, `findAll`, `getOne`, `count`, `updateMany`, `aggregate`, …)
@@ -327,6 +334,13 @@ interface RepositoryContext {
   hint?: string | Record<string, 1 | -1>;
   /** Maximum execution time in milliseconds */
   maxTimeMS?: number;
+  /** Per-call read concern / comment / write concern / disk use (see `queryDefaults`). */
+  readConcern?: ReadConcernLevel;
+  comment?: string;
+  writeConcern?: WriteConcernSpec;
+  allowDiskUse?: boolean;
+  /** Collections the caller asserts are company-wide (joins only). */
+  unscopedJoins?: readonly string[];
   /** Count strategy for offset pagination. See {@link CountStrategy}. */
   countStrategy?: CountStrategy;
   /** Ceiling for `countStrategy: 'capped'` (default 10000). */
@@ -363,8 +377,23 @@ interface RepositoryContext {
   _cacheResolved?: unknown;
   /** Cache hit status (internal — `'fresh'` or `'stale'`) */
   _cacheStatus?: 'fresh' | 'stale' | 'miss' | 'disabled' | 'bypass';
-  /** IDs to cascade delete (internal) */
-  _cascadeIds?: unknown[];
+  /**
+   * Parent key values captured before a delete, by `parentKey` (internal —
+   * cascade plugin). Restrict, detach and cascade all read these.
+   */
+  _cascadeParentKeys?: Map<string, unknown[]>;
+  /**
+   * Memo shared by every hook of THIS operation: N plugins that need the same read pay for
+   * one. Scoped to the operation, so it can never serve a value across writes. A rejected
+   * load is forgotten, so the next caller retries.
+   */
+  memo?: <T>(key: string, load: () => Promise<T>) => Promise<T>;
+  /**
+   * The persisted document an id-addressed operation targets, as it is BEFORE the write,
+   * read once under the operation's session (not tenant-filtered — the write's own filter
+   * decides whether it applies). Use this instead of `Model.findById(context.id)` in a hook.
+   */
+  loadTarget?: () => Promise<Record<string, unknown> | null>;
   /** Custom context data from plugins */
   [key: string]: unknown;
 }
@@ -432,7 +461,7 @@ interface RepositoryInstance extends RepositoryBase {
   [key: string]: unknown;
 }
 /** Repository operation names */
-type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'findOneAndUpdate' | 'delete' | 'deleteMany' | 'restore' | 'getById' | 'getByQuery' | 'getOne' | 'getAll' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'aggregatePipeline' | 'aggregatePipelinePaginate' | 'lookupPopulate' | 'bulkWrite' | 'claim' | 'claimVersion' | 'cursor' | 'watch';
+type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'findOneAndUpdate' | 'delete' | 'deleteMany' | 'restore' | 'getById' | 'getByQuery' | 'getOne' | 'getAll' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'aggregatePipeline' | 'aggregatePipelinePaginate' | 'lookupPopulate' | 'bulkWrite' | 'bulkUpsert' | 'claim' | 'claimVersion' | 'cursor' | 'iterate' | 'watch';
 /** Event lifecycle phases */
 type EventPhase = 'before' | 'after' | 'error';
 /** Repository event names (generated from template literals) */
@@ -528,6 +557,9 @@ type AllPluginMethods<TDoc> = {
   deleteSubdocument(parentId: string | ObjectId, arrayPath: DocField<TDoc>, subId: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc>;
   restore(id: string | ObjectId, options?: {
     session?: unknown;
+    organizationId?: unknown;
+    bypassTenant?: boolean;
+    [key: string]: unknown;
   }): Promise<TDoc>;
   getDeleted(params?: {
     filters?: Record<string, unknown>;

package/dist/sync/index.d.mts

@@ -0,0 +1,53 @@
+import { ClientSession, Connection, Model } from "mongoose";
+import { ChangeLogStore, CommandStreamStore, CommandStreamTx } from "@classytic/repo-core/sync";
+//#region src/sync/index.d.ts
+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. */
+  modelName?: string;
+}
+interface ChangeLogModels {
+  entries: Model<Record<string, unknown>>;
+  counter: Model<Record<string, unknown>>;
+  /** The counter document's id (one feed per entries collection). */
+  feed: string;
+}
+declare function createChangeLogModels(connection: Connection, options?: ChangeLogModelOptions): ChangeLogModels;
+/** The mongo change feed: the `ChangeLogStore` contract plus superseded-entry compaction. */
+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.
+   */
+  compactSuperseded(options?: {
+    batchSize?: number;
+  }): Promise<{
+    removed: number;
+  }>;
+}
+declare function createChangeLogStore(models: ChangeLogModels): MongoChangeLogStore;
+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 {
+  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 {
+  readonly session: ClientSession;
+}
+/**
+ * The mongo {@link CommandStreamStore} (replica set). Proven by `runCommandStreamStoreConformance`.
+ * 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 };