@classytic/mongokit 3.39.0 → 3.40.1

package/dist/sync/index.mjs

@@ -0,0 +1,371 @@
+import { i as withTransaction } from "../transaction-BrRYtH_b.mjs";
+import { Schema } from "mongoose";
+//#region src/sync/index.ts
+function createChangeLogModels(connection, options = {}) {
+	const { collection = "sync_changes", modelName = "SyncChange" } = 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: {
+				type: String,
+				required: true
+			},
+			seq: {
+				type: Number,
+				required: true
+			}
+		}, {
+			collection: `${collection}_counter`,
+			versionKey: false
+		})),
+		feed: collection
+	};
+}
+/** Fixed-width, so the opaque cursor also sorts as text. */
+const toCursor = (seq) => String(seq).padStart(16, "0");
+const fromCursor = (cursor) => {
+	if (cursor === "") return 0;
+	const seq = Number(cursor);
+	if (!Number.isSafeInteger(seq) || seq < 0) throw new Error(`[mongokit:sync] "${cursor}" is not a cursor from this feed`);
+	return seq;
+};
+const DEFAULT_LIMIT = 500;
+function createChangeLogStore(models) {
+	const { entries, counter, feed } = models;
+	const sessionOf = (options) => options?.session ? { session: options.session } : {};
+	const filterOf = (after, options = {}) => {
+		const { tenantId, scopes, sharedScopes } = options;
+		const tenant = tenantId === void 0 ? {} : sharedScopes?.length ? { $or: [{ tenantId }, { scope: { $in: [...sharedScopes] } }] } : { tenantId };
+		return {
+			seq: { $gt: after },
+			...tenant,
+			...scopes ? { scope: { $in: [...scopes] } } : {}
+		};
+	};
+	const toEntry = (row) => ({
+		scope: row.scope,
+		docId: row.docId,
+		op: row.op,
+		version: row.version,
+		...row.doc !== void 0 && row.doc !== null ? { doc: row.doc } : {},
+		...typeof row.tenantId === "string" ? { tenantId: row.tenantId } : {},
+		at: row.at,
+		cursor: toCursor(row.seq)
+	});
+	return {
+		async append(entry, options) {
+			const session = sessionOf(options);
+			const seq = (await counter.findOneAndUpdate({ _id: feed }, { $inc: { seq: 1 } }, {
+				upsert: true,
+				returnDocument: "after",
+				lean: true,
+				...session
+			}).exec()).seq;
+			const at = /* @__PURE__ */ new Date();
+			await entries.create([{
+				seq,
+				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
+			}], session);
+			return {
+				...entry,
+				at,
+				cursor: toCursor(seq)
+			};
+		},
+		async since(cursor, options = {}) {
+			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);
+			const last = page[page.length - 1];
+			return {
+				changes: page,
+				cursor: last ? last.cursor : cursor,
+				hasMore: rows.length > limit
+			};
+		},
+		async latestCursor(options = {}) {
+			const row = await entries.findOne(filterOf(0, options)).sort({ seq: -1 }).select({ seq: 1 }).lean().exec();
+			return row?.seq ? toCursor(row.seq) : "";
+		},
+		async compactSuperseded(options = {}) {
+			const batchSize = options.batchSize ?? 1e3;
+			const groups = entries.aggregate([
+				{ $group: {
+					_id: {
+						scope: "$scope",
+						docId: "$docId"
+					},
+					latest: { $max: "$seq" },
+					n: { $sum: 1 }
+				} },
+				{ $match: { n: { $gt: 1 } } },
+				{ $project: { latest: 1 } }
+			]).allowDiskUse(true).cursor({ batchSize });
+			let removed = 0;
+			let ops = [];
+			const flush = async () => {
+				if (ops.length === 0) return;
+				removed += (await entries.bulkWrite(ops, { ordered: false })).deletedCount;
+				ops = [];
+			};
+			for await (const g of groups) {
+				ops.push({ deleteMany: { filter: {
+					scope: g._id.scope,
+					docId: g._id.docId,
+					seq: { $lt: g.latest }
+				} } });
+				if (ops.length >= batchSize) await flush();
+			}
+			await flush();
+			return { removed };
+		}
+	};
+}
+function createCommandStreamModels(connection, options = {}) {
+	const { prefix = "sync", modelName = "SyncStream" } = options;
+	const model = (name, schema) => connection.models[name] ?? connection.model(name, schema());
+	return {
+		streams: model(modelName, () => new Schema({
+			_id: {
+				type: String,
+				required: true
+			},
+			tenantId: {
+				type: String,
+				required: true
+			},
+			processed: {
+				type: Number,
+				required: true
+			}
+		}, {
+			collection: `${prefix}_streams`,
+			versionKey: false
+		})),
+		verdicts: model(`${modelName}Verdict`, () => {
+			const schema = new Schema({
+				_id: {
+					type: String,
+					required: true
+				},
+				stream: {
+					type: String,
+					required: true
+				},
+				seq: {
+					type: Number,
+					required: true
+				},
+				outcome: {
+					type: String,
+					enum: [
+						"applied",
+						"rejected",
+						"blocked",
+						"resolved"
+					],
+					required: true
+				},
+				code: { type: String },
+				fingerprint: {
+					type: String,
+					required: true
+				},
+				body: { type: String },
+				dependsOn: {
+					type: [String],
+					default: void 0
+				},
+				resolution: {
+					type: {
+						action: String,
+						by: String,
+						at: String,
+						_id: false
+					},
+					default: void 0
+				}
+			}, {
+				collection: `${prefix}_verdicts`,
+				versionKey: false
+			});
+			schema.index({
+				stream: 1,
+				seq: 1
+			}, {
+				unique: true,
+				name: "stream_seq"
+			});
+			schema.index({
+				dependsOn: 1,
+				outcome: 1
+			}, {
+				name: "blocked_on",
+				partialFilterExpression: { outcome: "blocked" }
+			});
+			return schema;
+		}),
+		aliases: model(`${modelName}Alias`, () => {
+			const schema = new Schema({
+				tenantId: {
+					type: String,
+					required: true
+				},
+				localId: {
+					type: String,
+					required: true
+				},
+				serverId: {
+					type: String,
+					required: true
+				}
+			}, {
+				collection: `${prefix}_aliases`,
+				versionKey: false
+			});
+			schema.index({
+				tenantId: 1,
+				localId: 1
+			}, {
+				unique: true,
+				name: "tenant_local"
+			});
+			return schema;
+		})
+	};
+}
+/**
+* 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.
+*/
+function createCommandStreamStore(connection, models, changes) {
+	const { streams, verdicts, aliases } = models;
+	const toVerdict = ({ _id, code, ...rest }) => ({
+		commandId: _id,
+		...rest,
+		...code == null ? {} : { code }
+	});
+	return {
+		changes,
+		transaction: (work) => withTransaction(connection, (session) => work({ session })),
+		async stream({ session }, id) {
+			const row = await streams.findById(id).session(session).lean().exec();
+			return row ? {
+				tenantId: row.tenantId,
+				processed: row.processed
+			} : null;
+		},
+		async advance({ session }, id, tenantId, from, to) {
+			if (from === 0) {
+				if (await streams.exists({ _id: id }).session(session)) return false;
+				await streams.create([{
+					_id: id,
+					tenantId,
+					processed: to
+				}], { session });
+				return true;
+			}
+			return (await streams.updateOne({
+				_id: id,
+				processed: from
+			}, { $set: { processed: to } }, { session }).exec()).modifiedCount === 1;
+		},
+		async verdict({ session }, commandId) {
+			const row = await verdicts.findById(commandId).session(session).lean().exec();
+			return row ? toVerdict(row) : null;
+		},
+		async record({ session }, { commandId, ...rest }) {
+			await verdicts.replaceOne({ _id: commandId }, rest, {
+				upsert: true,
+				session
+			}).exec();
+		},
+		async blockedOn({ session }, commandId) {
+			return (await verdicts.find({
+				outcome: "blocked",
+				dependsOn: commandId
+			}).sort({ seq: 1 }).session(session).lean().exec()).map(toVerdict);
+		},
+		async alias({ session }, { tenantId, localId, serverId }) {
+			const existing = await aliases.findOne({
+				tenantId,
+				localId
+			}).session(session).lean().exec();
+			if (existing) {
+				if (existing.serverId !== serverId) throw new Error(`[mongokit:sync] "${localId}" already names "${existing.serverId}"`);
+				return;
+			}
+			await aliases.create([{
+				tenantId,
+				localId,
+				serverId
+			}], { session });
+		},
+		async aliasOf({ session }, tenantId, localId) {
+			return (await aliases.findOne({
+				tenantId,
+				localId
+			}).session(session).lean().exec())?.serverId ?? null;
+		}
+	};
+}
+//#endregion
+export { createChangeLogModels, createChangeLogStore, createCommandStreamModels, createCommandStreamStore };

package/dist/tenant/index.mjs

@@ -64,6 +64,8 @@ function declareIndexes(schema, tenant, declarations) {
 */
 function injectTenantField(schema, tenant, options = {}) {
 	for (const declaration of options.indexes ?? []) assertIndexDeclaration(declaration, tenant);
+	const declaredNames = new Set(indexEntries(schema).map(([, o]) => o?.name).filter((n) => typeof n === "string"));
+	for (const name of options.skipIndexes ?? []) if (!declaredNames.has(name)) throw new Error(`[mongokit/tenant] skipIndexes names '${name}', but no index on this schema has that name — rename the exemption with the index, or the index silently gets the tenant prefix`);
 	const isObjectId = tenant.fieldType === "objectId";
 	const scoped = isScoped(tenant);
 	schema.add({ [tenant.tenantField]: {

package/dist/testkit/index.d.mts

@@ -1,7 +1,44 @@
-import { n as Repository } from "../Repository-IxI983_m.mjs";
-import { n as CreateRepositoryConfig } from "../create-repository-CRXjDa3N.mjs";
+import { r as Repository } from "../Repository-pnLw1rG5.mjs";
+import { n as CreateRepositoryConfig } from "../create-repository-BUx9vfG9.mjs";
 import { Connection, Model, Schema } from "mongoose";
 import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
+//#region src/testkit/query-plan.d.ts
+interface RecordedCommand {
+  name: string;
+  collection: string | undefined;
+  command: Record<string, unknown>;
+}
+/** Run `fn` and return every command it started on `connection` (in start order). */
+declare function recordCommands<T>(connection: Connection, fn: () => Promise<T>): Promise<{
+  result: T;
+  commands: RecordedCommand[];
+}>;
+interface QueryPlanOptions {
+  connection: Connection;
+  /** Plan stages that fail the gate. Default `['COLLSCAN', 'SORT']` (a scan, an unindexed sort). */
+  forbid?: readonly string[];
+  /** The examined collection must hold at least this many documents. */
+  minDocs: number;
+  /** Every index scan must lead with these keys (directly, or after one equality scope field). */
+  leadingKeys?: readonly string[];
+  /** Only gate commands on these collections (default: every plannable command). */
+  collections?: readonly string[];
+}
+interface PlannedCommand {
+  name: string;
+  collection: string;
+  stages: string[];
+  indexes: string[][];
+}
+/**
+ * Run `run`, explain every read it issued and throw on a forbidden stage, a wrong leading index,
+ * an undersized fixture, or no plannable command at all. Returns what each command used.
+ */
+declare function assertQueryPlan<T>(run: () => Promise<T>, options: QueryPlanOptions): Promise<{
+  result: T;
+  plans: PlannedCommand[];
+}>;
+//#endregion
 //#region src/testkit/index.d.ts
 interface MongoMemoryOptions {
   /**
@@ -132,4 +169,4 @@ interface MongoMemoryBackend {
  */
 declare function mongoMemoryBackend(options?: MongoMemoryOptions): MongoMemoryBackend;
 //#endregion
-export { CreateTestRepositoryOptions, MongoMemoryBackend, MongoMemoryHandle, MongoMemoryOptions, MongoTestContext, TestConnection, TestRepository, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, withMongoMemory };
+export { CreateTestRepositoryOptions, MongoMemoryBackend, MongoMemoryHandle, MongoMemoryOptions, MongoTestContext, type PlannedCommand, type QueryPlanOptions, type RecordedCommand, TestConnection, TestRepository, assertQueryPlan, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, recordCommands, withMongoMemory };

package/dist/testkit/index.mjs

@@ -1,5 +1,116 @@
-import { t as createRepository } from "../create-repository-DOe9E_5F.mjs";
+import { t as createRepository } from "../create-repository-BYyWzLbt.mjs";
 import { createConnection } from "mongoose";
+//#region src/testkit/query-plan.ts
+const PLANNABLE = /* @__PURE__ */ new Set([
+	"find",
+	"aggregate",
+	"count",
+	"distinct"
+]);
+/** Session/transport fields the server refuses inside an `explain`. */
+const STRIP = /* @__PURE__ */ new Set([
+	"lsid",
+	"txnNumber",
+	"autocommit",
+	"startTransaction",
+	"readConcern",
+	"maxTimeMS"
+]);
+function assertMonitored(connection) {
+	if (connection.getClient().options.monitorCommands !== true) throw new Error("[mongokit/testkit] the connection was not opened with { monitorCommands: true }: no command can be observed");
+}
+/** Run `fn` and return every command it started on `connection` (in start order). */
+async function recordCommands(connection, fn) {
+	assertMonitored(connection);
+	const client = connection.getClient();
+	const commands = [];
+	const listener = (event) => {
+		const target = event.command[event.commandName];
+		commands.push({
+			name: event.commandName,
+			collection: typeof target === "string" ? target : void 0,
+			command: event.command
+		});
+	};
+	client.on("commandStarted", listener);
+	try {
+		return {
+			result: await fn(),
+			commands
+		};
+	} finally {
+		client.off("commandStarted", listener);
+	}
+}
+function collectPlanNodes(node, out) {
+	if (Array.isArray(node)) {
+		for (const n of node) collectPlanNodes(n, out);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node;
+	if (typeof obj.stage === "string") out.push(obj);
+	for (const [key, value] of Object.entries(obj)) {
+		if (key === "rejectedPlans" || key === "allPlansExecution") continue;
+		collectPlanNodes(value, out);
+	}
+}
+function explainable(command) {
+	return Object.fromEntries(Object.entries(command).filter(([k]) => !k.startsWith("$") && !STRIP.has(k)));
+}
+/**
+* Run `run`, explain every read it issued and throw on a forbidden stage, a wrong leading index,
+* an undersized fixture, or no plannable command at all. Returns what each command used.
+*/
+async function assertQueryPlan(run, options) {
+	const forbid = options.forbid ?? ["COLLSCAN", "SORT"];
+	const { result, commands } = await recordCommands(options.connection, run);
+	const db = options.connection.db;
+	if (!db) throw new Error("[mongokit/testkit] connection has no db handle");
+	const plannable = commands.filter((c) => PLANNABLE.has(c.name) && c.collection !== void 0 && (!options.collections || options.collections.includes(c.collection)));
+	if (plannable.length === 0) throw new Error(`[mongokit/testkit] assertQueryPlan saw no plannable command (saw: ${commands.map((c) => c.name).join(", ") || "none"})`);
+	const plans = [];
+	const failures = [];
+	for (const c of plannable) {
+		const collection = c.collection;
+		const size = await db.collection(collection).countDocuments({});
+		if (size < options.minDocs) throw new Error(`[mongokit/testkit] '${collection}' holds ${size} documents, below minDocs ${options.minDocs}: the plan would not be representative`);
+		const explained = await db.command({
+			explain: explainable(c.command),
+			verbosity: "executionStats"
+		});
+		const nodes = [];
+		collectPlanNodes(explained.queryPlanner ?? explained.stages ?? explained, nodes);
+		const stages = nodes.map((n) => n.stage);
+		const indexes = nodes.filter((n) => n.keyPattern && typeof n.keyPattern === "object").map((n) => Object.keys(n.keyPattern));
+		plans.push({
+			name: c.name,
+			collection,
+			stages,
+			indexes
+		});
+		for (const stage of forbid) if (stages.includes(stage)) failures.push(`${c.name} on '${collection}': plan contains ${stage}`);
+		if (options.leadingKeys) {
+			const want = options.leadingKeys;
+			const leads = (key, at) => want.every((k, i) => key[at + i] === k);
+			if (indexes.length === 0) failures.push(`${c.name} on '${collection}': no index used, expected (${want.join(",")})`);
+			for (const key of indexes) if (!leads(key, 0) && !leads(key, 1)) failures.push(`${c.name} on '${collection}': index (${key.join(",")}) does not lead with (${want.join(",")})`);
+		}
+	}
+	if (failures.length > 0) {
+		const error = /* @__PURE__ */ new Error(`[mongokit/testkit] query plan gate failed:\n  ${failures.join("\n  ")}`);
+		Object.assign(error, {
+			code: "mongokit.testkit.query_plan",
+			plans
+		});
+		throw error;
+	}
+	return {
+		result,
+		plans
+	};
+}
+//#endregion
 //#region src/testkit/index.ts
 function idempotentStop(server) {
 	let stopped = false;
@@ -136,4 +247,4 @@ function mongoMemoryBackend(options = {}) {
 	} };
 }
 //#endregion
-export { clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, withMongoMemory };
+export { assertQueryPlan, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, recordCommands, withMongoMemory };