@classytic/mongokit 3.41.0 → 3.43.0

package/dist/sync/index.mjs

@@ -1,77 +1,133 @@
 import { o as withTransaction } from "../transaction-DmiB4k2P.mjs";
-import { Schema } from "mongoose";
+import { Schema, Types } from "mongoose";
 //#region src/sync/index.ts
 function createChangeLogModels(connection, options = {}) {
-	const { collection = "sync_changes", modelName = "SyncChange" } = options;
+	const { collection = "sync_changes", modelName = "SyncChange", sequencing = "in-transaction" } = options;
 	const entriesName = modelName;
 	const counterName = `${modelName}Counter`;
-	return {
-		entries: connection.models[entriesName] ?? connection.model(entriesName, (() => {
-			const schema = new Schema({
-				seq: {
-					type: Number,
-					required: true
-				},
-				scope: {
-					type: String,
-					required: true
-				},
-				docId: {
-					type: String,
-					required: true
-				},
-				op: {
-					type: String,
-					enum: ["upsert", "delete"],
-					required: true
-				},
-				version: {
-					type: Number,
-					required: true
-				},
-				doc: { type: Schema.Types.Mixed },
-				tenantId: { type: String },
-				at: {
-					type: Date,
-					required: true
-				}
-			}, {
-				collection,
-				versionKey: false,
-				minimize: false
-			});
-			schema.index({ seq: 1 }, {
-				unique: true,
-				name: "feed_order"
-			});
-			schema.index({
-				tenantId: 1,
-				scope: 1,
-				seq: 1
-			}, { name: "tenant_scope_feed" });
-			schema.index({
-				scope: 1,
-				docId: 1,
-				seq: 1
-			}, { name: "doc_versions" });
-			return schema;
-		})()),
-		counter: connection.models[counterName] ?? connection.model(counterName, new Schema({
-			_id: {
+	const entries = connection.models[entriesName] ?? connection.model(entriesName, (() => {
+		const schema = new Schema({
+			seq: {
+				type: Number,
+				required: true
+			},
+			scope: {
 				type: String,
 				required: true
 			},
-			seq: {
+			docId: {
+				type: String,
+				required: true
+			},
+			op: {
+				type: String,
+				enum: ["upsert", "delete"],
+				required: true
+			},
+			version: {
 				type: Number,
 				required: true
-			}
+			},
+			doc: { type: Schema.Types.Mixed },
+			tenantId: { type: String },
+			at: {
+				type: Date,
+				required: true
+			},
+			/** The staged row this entry was numbered from (deferred sequencing) — the sequencer's idempotency key. */
+			pendingId: { type: String }
 		}, {
-			collection: `${collection}_counter`,
-			versionKey: false
-		})),
+			collection,
+			versionKey: false,
+			minimize: false
+		});
+		schema.index({ seq: 1 }, {
+			unique: true,
+			name: "feed_order"
+		});
+		schema.index({ pendingId: 1 }, {
+			unique: true,
+			name: "sequenced_from",
+			partialFilterExpression: { pendingId: { $gte: "" } }
+		});
+		schema.index({
+			tenantId: 1,
+			scope: 1,
+			seq: 1
+		}, { name: "tenant_scope_feed" });
+		schema.index({
+			scope: 1,
+			docId: 1,
+			seq: 1
+		}, { name: "doc_versions" });
+		return schema;
+	})());
+	const counter = connection.models[counterName] ?? connection.model(counterName, new Schema({
+		_id: {
+			type: String,
+			required: true
+		},
+		seq: {
+			type: Number,
+			required: true
+		},
+		/** The deferred sequencer's lease. */
+		lockUntil: { type: Date },
+		lockBy: { type: String }
+	}, {
+		collection: `${collection}_counter`,
+		versionKey: false
+	}));
+	const pendingName = `${modelName}Pending`;
+	const pending = sequencing === "deferred" ? connection.models[pendingName] ?? connection.model(pendingName, new Schema({
+		scope: {
+			type: String,
+			required: true
+		},
+		docId: {
+			type: String,
+			required: true
+		},
+		op: {
+			type: String,
+			enum: ["upsert", "delete"],
+			required: true
+		},
+		version: {
+			type: Number,
+			required: true
+		},
+		doc: { type: Schema.Types.Mixed },
+		tenantId: { type: String },
+		at: {
+			type: Date,
+			required: true
+		}
+	}, {
+		collection: `${collection}_pending`,
+		versionKey: false,
+		minimize: false
+	})) : void 0;
+	return {
+		entries,
+		counter,
+		...pending ? { pending } : {},
+		sequencing,
 		feed: collection
 	};
 }
+/** A change as staged under deferred sequencing — the feed row without its `seq`. */
+function stagedRow(entry, at) {
+	return {
+		scope: entry.scope,
+		docId: entry.docId,
+		op: entry.op,
+		version: entry.version,
+		...entry.op === "upsert" && entry.doc !== void 0 ? { doc: entry.doc } : {},
+		...entry.tenantId !== void 0 ? { tenantId: entry.tenantId } : {},
+		at
+	};
+}
 /** Fixed-width, so the opaque cursor also sorts as text. */
 const toCursor = (seq) => String(seq).padStart(16, "0");
 const fromCursor = (cursor) => {
@@ -81,8 +137,96 @@ const fromCursor = (cursor) => {
 	return seq;
 };
 const DEFAULT_LIMIT = 500;
+/** How long one sequencer holds the lease — far above one batch, so a live holder never loses it mid-batch. */
+const SEQUENCER_LEASE_MS = 3e4;
+const SEQUENCER_BATCH = 500;
 function createChangeLogStore(models) {
-	const { entries, counter, feed } = models;
+	const { entries, counter, feed, pending } = models;
+	const deferred = models.sequencing === "deferred" && pending !== void 0;
+	/**
+	* One pass under the lease: committed staged rows → the feed, in staging order, numbered above everything.
+	* Nothing staged costs ONE read. A crash mid-pass is converged by the next one: an entry already in the feed is
+	* recognised by its unique `pendingId`, and a stale counter is caught by the unique `seq` index.
+	*/
+	const sequencePending = async () => {
+		if (!deferred || !pending) return 0;
+		if (!await pending.exists({}).exec()) return 0;
+		const token = new Types.ObjectId().toString();
+		const unlocked = {
+			_id: feed,
+			$or: [
+				{ lockUntil: { $exists: false } },
+				{ lockUntil: null },
+				{ lockUntil: { $lt: /* @__PURE__ */ new Date() } }
+			]
+		};
+		const takeLease = () => counter.findOneAndUpdate(unlocked, { $set: {
+			lockUntil: new Date(Date.now() + SEQUENCER_LEASE_MS),
+			lockBy: token
+		} }, {
+			returnDocument: "after",
+			lean: true
+		}).exec();
+		let lease = await takeLease();
+		if (!lease) {
+			if (await counter.exists({ _id: feed }).exec()) return null;
+			await counter.create([{
+				_id: feed,
+				seq: 0
+			}]).catch((err) => {
+				if (err.code !== 11e3) throw err;
+			});
+			lease = await takeLease();
+			if (!lease) return null;
+		}
+		let seq = lease.seq ?? 0;
+		let numbered = 0;
+		try {
+			for (;;) {
+				const rows = await pending.find({}).sort({ _id: 1 }).limit(SEQUENCER_BATCH).lean().exec();
+				if (rows.length === 0) break;
+				const build = (from, list) => list.map((r, i) => {
+					const { _id, ...rest } = r;
+					return {
+						...rest,
+						seq: from + i + 1,
+						pendingId: String(_id)
+					};
+				});
+				try {
+					await entries.insertMany(build(seq, rows), { ordered: true });
+					seq += rows.length;
+					numbered += rows.length;
+				} catch (err) {
+					if (err.code !== 11e3) throw err;
+					const placed = new Set((await entries.find({ pendingId: { $in: rows.map((r) => String(r._id)) } }).select({ pendingId: 1 }).lean().exec()).map((e) => e.pendingId));
+					const fresh = rows.filter((r) => !placed.has(String(r._id)));
+					const top = await entries.findOne({}).sort({ seq: -1 }).select({ seq: 1 }).lean().exec();
+					seq = Math.max(seq, top?.seq ?? 0);
+					if (fresh.length > 0) {
+						await entries.insertMany(build(seq, fresh), { ordered: true });
+						seq += fresh.length;
+						numbered += fresh.length;
+					}
+				}
+				await counter.updateOne({
+					_id: feed,
+					lockBy: token
+				}, { $max: { seq } }).exec();
+				await pending.deleteMany({ _id: { $in: rows.map((r) => r._id) } }).exec();
+				if (rows.length < SEQUENCER_BATCH) break;
+			}
+		} finally {
+			await counter.updateOne({
+				_id: feed,
+				lockBy: token
+			}, { $set: {
+				lockUntil: null,
+				lockBy: null
+			} }).exec();
+		}
+		return numbered;
+	};
 	const sessionOf = (options) => options?.session ? { session: options.session } : {};
 	const filterOf = (after, options = {}) => {
 		const { tenantId, scopes, sharedScopes } = options;
@@ -104,8 +248,37 @@ function createChangeLogStore(models) {
 		cursor: toCursor(row.seq)
 	});
 	return {
+		sequencePending,
+		async stage(entry, options) {
+			if (!deferred || !pending) {
+				await this.append(entry, options);
+				return;
+			}
+			await pending.create([stagedRow(entry, /* @__PURE__ */ new Date())], sessionOf(options));
+		},
 		async append(entry, options) {
 			const session = sessionOf(options);
+			if (deferred && pending) {
+				const at = /* @__PURE__ */ new Date();
+				const [staged] = await pending.create([stagedRow(entry, at)], session);
+				if (options?.session) return {
+					...entry,
+					at,
+					cursor: ""
+				};
+				const stagedId = String(staged?._id);
+				for (let attempt = 0; attempt < 50; attempt++) {
+					await sequencePending();
+					const at2 = await entries.findOne({ pendingId: stagedId }).select({ seq: 1 }).lean().exec();
+					if (typeof at2?.seq === "number") return {
+						...entry,
+						at,
+						cursor: toCursor(at2.seq)
+					};
+					await new Promise((r) => setTimeout(r, 20));
+				}
+				throw new Error(`[mongokit:sync] staged entry ${stagedId} was not sequenced — a sequencer lease is stuck`);
+			}
 			const seq = (await counter.findOneAndUpdate({ _id: feed }, { $inc: { seq: 1 } }, {
 				upsert: true,
 				returnDocument: "after",
@@ -130,6 +303,7 @@ function createChangeLogStore(models) {
 			};
 		},
 		async since(cursor, options = {}) {
+			if (deferred) await sequencePending();
 			const limit = options.limit ?? DEFAULT_LIMIT;
 			const rows = await entries.find(filterOf(fromCursor(cursor), options)).sort({ seq: 1 }).limit(limit + 1).lean().exec();
 			const page = rows.slice(0, limit).map(toEntry);
@@ -141,6 +315,7 @@ function createChangeLogStore(models) {
 			};
 		},
 		async latestCursor(options = {}) {
+			if (deferred) await sequencePending();
 			const row = await entries.findOne(filterOf(0, options)).sort({ seq: -1 }).select({ seq: 1 }).lean().exec();
 			return row?.seq ? toCursor(row.seq) : "";
 		},

package/dist/testkit/index.d.mts

@@ -1,5 +1,5 @@
-import { r as Repository } from "../Repository-pnLw1rG5.mjs";
-import { n as CreateRepositoryConfig } from "../create-repository-BUx9vfG9.mjs";
+import { r as Repository } from "../Repository-DnL4xk5w.mjs";
+import { n as CreateRepositoryConfig } from "../create-repository-CJtVdwig.mjs";
 import { Connection, Model, Schema } from "mongoose";
 import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
 //#region src/testkit/query-plan.d.ts

package/dist/testkit/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRepository } from "../create-repository-Bg0H5rte.mjs";
+import { t as createRepository } from "../create-repository-UjwPWR1z.mjs";
 import { createConnection } from "mongoose";
 //#region src/testkit/query-plan.ts
 const PLANNABLE = /* @__PURE__ */ new Set([

package/dist/{timestamp.plugin-DvZlnKEc.mjs → timestamp.plugin-DpOWavVI.mjs}

@@ -1,4 +1,4 @@
-import { i as ALL_OPERATIONS, o as OP_REGISTRY, t as HOOK_PRIORITY } from "./Repository-DlhPbXlG.mjs";
+import { a as ALL_OPERATIONS, s as OP_REGISTRY, t as HOOK_PRIORITY } from "./Repository-Dj6xqPxJ.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { n as declareCollectionScope } from "./join-scope-DSAznE8E.mjs";
 import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";

package/dist/{to-plain-CjgEInWV.d.mts → to-plain-o5tUY2nV.d.mts}

@@ -1,5 +1,5 @@
-import { v as UserContext } from "./repository-DNHfjAZX.mjs";
-import { r as FieldPreset } from "./plugin-options-CRhIvSzx.mjs";
+import { y as UserContext } from "./repository-MqAP409e.mjs";
+import { r as FieldPreset } from "./plugin-options-Cirmb4Kp.mjs";
 import mongoose, { Schema } from "mongoose";
 import { CacheAdapter } from "@classytic/repo-core/cache";
 import { HttpError } from "@classytic/repo-core/errors";

package/dist/utils/index.d.mts

@@ -1,4 +1,4 @@
-import { _ as getMongooseProjection, a as createMemoryCache, b as createError, c as IdType, d as isObjectIdInstance, f as isValidIdForType, g as getFieldsForUser, h as filterResponseData, i as buildCrudSchemasFromMongooseSchema, l as getSchemaIdType, m as createFieldPreset, n as CrudSchemasFramework, o as LoggerConfig, p as toObjectId, r as buildCrudSchemasFromModel, s as configureLogger, t as toPlain, v as CreateErrorOptions, y as ParseDuplicateKeyOptions } from "../to-plain-CjgEInWV.mjs";
+import { _ as getMongooseProjection, a as createMemoryCache, b as createError, c as IdType, d as isObjectIdInstance, f as isValidIdForType, g as getFieldsForUser, h as filterResponseData, i as buildCrudSchemasFromMongooseSchema, l as getSchemaIdType, m as createFieldPreset, n as CrudSchemasFramework, o as LoggerConfig, p as toObjectId, r as buildCrudSchemasFromModel, s as configureLogger, t as toPlain, v as CreateErrorOptions, y as ParseDuplicateKeyOptions } from "../to-plain-o5tUY2nV.mjs";
 import { ClientSession, Model } from "mongoose";
 //#region src/utils/id-chunks.d.ts
 /**

package/dist/{validation-chain.plugin-CTcNJCmV.d.mts → validation-chain.plugin-BAeC5eVT.d.mts}

@@ -1,6 +1,6 @@
 import { A as ObjectId, F as SortSpec, N as SelectSpec, j as PopulateSpec } from "./pagination-D6psses0.mjs";
-import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-DNHfjAZX.mjs";
-import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-CRhIvSzx.mjs";
+import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-MqAP409e.mjs";
+import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-Cirmb4Kp.mjs";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -719,6 +719,15 @@ interface ObservabilityOptions {
 }
 declare function observabilityPlugin(options: ObservabilityOptions): Plugin;
 //#endregion
+//#region src/plugins/search-keys.plugin.d.ts
+interface SearchKeysPluginOptions {
+  /** Source fields (dotted paths allowed; string, number, or arrays of them). */
+  fields: readonly string[];
+  /** Field that stores the keys. Default `'_searchKeys'`. */
+  keysField?: string;
+}
+declare function searchKeysPlugin(options: SearchKeysPluginOptions): Plugin;
+//#endregion
 //#region src/plugins/soft-delete.plugin.d.ts
 /**
  * Soft delete plugin
@@ -964,4 +973,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-export { IdempotencyStoreMethods as A, batchOperationsPlugin as B, LeaseMethods as C, ImmutableStatesPluginOptions as D, ImmutableClaimView as E, elasticSearchPlugin as F, aggregateHelpersPlugin as G, AppendOnlyPluginOptions as H, cascadePlugin as I, BatchOperationsMethods as L, idempotencyStorePlugin as M, fieldFilterPlugin as N, immutableStatesPlugin as O, ElasticSearchOptions as P, BulkWriteOptions as R, methodRegistryPlugin as S, leasePlugin as T, appendOnlyPlugin as U, auditLogPlugin as V, AggregateHelpersMethods as W, OperationMetric as _, requireField as a, mongoOperationsPlugin as b, timestampPlugin as c, createTenantContext as d, SubdocumentMethods as f, ObservabilityOptions as g, softDeletePlugin as h, immutableField as i, IdempotencyStorePluginOptions as j, IdempotencyClaim as k, TenantContext as l, SoftDeleteMethods as m, autoInject as n, uniqueField as o, subdocumentPlugin as p, blockIf as r, validationChainPlugin as s, OperationType as t, TenantStore as u, observabilityPlugin as v, LeasePluginOptions as w, MethodRegistryRepository as x, MongoOperationsMethods as y, BulkWriteResult as z };
+export { immutableStatesPlugin as A, BulkWriteOptions as B, MethodRegistryRepository as C, leasePlugin as D, LeasePluginOptions as E, fieldFilterPlugin as F, appendOnlyPlugin as G, batchOperationsPlugin as H, ElasticSearchOptions as I, AggregateHelpersMethods as K, elasticSearchPlugin as L, IdempotencyStoreMethods as M, IdempotencyStorePluginOptions as N, ImmutableClaimView as O, idempotencyStorePlugin as P, cascadePlugin as R, mongoOperationsPlugin as S, LeaseMethods as T, auditLogPlugin as U, BulkWriteResult as V, AppendOnlyPluginOptions as W, searchKeysPlugin as _, requireField as a, observabilityPlugin as b, timestampPlugin as c, createTenantContext as d, SubdocumentMethods as f, SearchKeysPluginOptions as g, softDeletePlugin as h, immutableField as i, IdempotencyClaim as j, ImmutableStatesPluginOptions as k, TenantContext as l, SoftDeleteMethods as m, autoInject as n, uniqueField as o, subdocumentPlugin as p, aggregateHelpersPlugin as q, blockIf as r, validationChainPlugin as s, OperationType as t, TenantStore as u, ObservabilityOptions as v, methodRegistryPlugin as w, MongoOperationsMethods as x, OperationMetric as y, BatchOperationsMethods as z };

package/dist/{validation-chain.plugin-D1WsGCYr.mjs → validation-chain.plugin-DRApTmkN.mjs}

@@ -1,9 +1,9 @@
 import { n as collectIds, r as idChunks, t as DEFAULT_ID_CHUNK } from "./id-chunks-BmAwsqNk.mjs";
-import { i as ALL_OPERATIONS, o as OP_REGISTRY } from "./Repository-DlhPbXlG.mjs";
+import { a as ALL_OPERATIONS, s as OP_REGISTRY } from "./Repository-Dj6xqPxJ.mjs";
 import { w as upsert } from "./update-WgeAUJ_I.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
-import { c as tenantContextKeysOf, o as forwardScope } from "./timestamp.plugin-DvZlnKEc.mjs";
+import { c as tenantContextKeysOf, o as forwardScope } from "./timestamp.plugin-DpOWavVI.mjs";
 import { r as getFieldsForUser } from "./field-selection-FSQFLpsU.mjs";
 import mongoose from "mongoose";
 import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
@@ -1223,6 +1223,7 @@ const MONGOKIT_PLUGIN_NAMES = {
 	mongoOperations: "mongo-operations",
 	multiTenant: "multi-tenant",
 	observability: "observability",
+	searchKeys: "search-keys",
 	softDelete: "softDelete",
 	subdocument: "subdocument",
 	timestamp: "timestamp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.41.0",
+  "version": "3.43.0",
   "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
   "type": "module",
   "sideEffects": false,
@@ -95,6 +95,10 @@
     "./kernel-conformance": {
       "types": "./dist/kernel-conformance/index.d.mts",
       "default": "./dist/kernel-conformance/index.mjs"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.mts",
+      "default": "./dist/search/index.mjs"
     }
   },
   "files": [
@@ -199,7 +203,7 @@
     "@better-auth/mongo-adapter": "^1.6.29",
     "@biomejs/biome": "^2.5.8",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/repo-core": "^0.31.0",
+    "@classytic/repo-core": "^0.31.1",
     "@types/node": "^26.2.0",
     "@vitest/coverage-v8": "^4.1.10",
     "ajv": "^8.20.0",