@classytic/mongokit 3.6.3 → 3.7.0

package/dist/{validation-chain.plugin-7A5qGEQq.mjs → validation-chain.plugin-CEyJssZl.mjs}

@@ -1,10 +1,12 @@
-import { a as warn, i as debug, n as parseDuplicateKeyError, t as createError } from "./error-Bpbi_NKo.mjs";
-import { a as exists, c as getOrCreate, d as deleteByQuery, g as upsert, i as count, m as createMany, n as updateByQuery, o as getById, p as create, s as getByQuery, t as update, u as deleteById, v as distinct, y as LookupBuilder } from "./update-AVfKWNGt.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-CunXkR9p.mjs";
+import { n as debug, r as warn } from "./logger-DJ7egMnd.mjs";
+import { a as exists, c as getOrCreate, d as deleteByQuery, g as upsert, i as count, m as createMany, n as updateByQuery, o as getById, p as create, s as getByQuery, t as update, u as deleteById, v as distinct, y as LookupBuilder } from "./update-BDsQ3cdy.mjs";
+import { n as parseDuplicateKeyError, t as createError } from "./error-Lw9GEAro.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CPmZv7Ds.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
-import { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-LZ-cCwR5.mjs";
-import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-C5o7jyyA.mjs";
+import { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-e4BT9zAV.mjs";
+import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-dI0m4RBs.mjs";
 import mongoose from "mongoose";
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/plugins/aggregate-helpers.plugin.ts
 /**
 * Aggregate helpers plugin
@@ -1228,6 +1230,40 @@ function ensureLookupProjectionIncludesCursorFields(projection, sort) {
 	return nextProjection;
 }
 /**
+* Ordered pairs that produce wrong behavior when registered out of order.
+* Each tuple is `[mustComeFirst, mustComeAfter, reason]`.
+*
+* Plugin names are read from `plugin.name` (Plugin objects). Plain-function
+* plugins without a name are skipped — no false positives.
+*/
+const PLUGIN_ORDER_CONSTRAINTS = [[
+	"soft-delete",
+	"batch-operations",
+	"soft-delete must precede batch-operations so bulk deletes/updates see the soft-delete filter"
+], [
+	"multi-tenant",
+	"cache",
+	"multi-tenant must precede cache so tenant scoping is baked into cache keys (prevents cross-tenant cache poisoning)"
+]];
+function pluginName(plugin) {
+	if (!plugin || typeof plugin === "function") return void 0;
+	const name = plugin.name;
+	return typeof name === "string" ? name : void 0;
+}
+function validatePluginOrder(plugins, modelName, mode) {
+	if (mode === "off") return;
+	const names = plugins.map(pluginName);
+	for (const [first, after, reason] of PLUGIN_ORDER_CONSTRAINTS) {
+		const firstIdx = names.indexOf(first);
+		const afterIdx = names.indexOf(after);
+		if (firstIdx === -1 || afterIdx === -1) continue;
+		if (firstIdx < afterIdx) continue;
+		const message = `[mongokit] Repository "${modelName}": plugin order issue — ${reason}. Got: [..., '${after}' at index ${afterIdx}, '${first}' at index ${firstIdx}]. Swap them, or pass { pluginOrderChecks: 'off' } to silence.`;
+		if (mode === "throw") throw new Error(message);
+		warn(message);
+	}
+}
+/**
 * Plugin phase priorities (lower = runs first)
 * Policy hooks (multi-tenant, soft-delete, validation) MUST run before cache
 * to ensure filters are injected before cache keys are computed.
@@ -1262,6 +1298,7 @@ var Repository = class {
 		this.searchMode = options.searchMode ?? "text";
 		this.searchFields = options.searchFields;
 		if (this.searchMode === "regex" && (!this.searchFields || this.searchFields.length === 0)) warn(`[mongokit] Repository "${this.model}" configured with searchMode: 'regex' but no searchFields provided. getAll({ search }) will throw until searchFields is set.`);
+		validatePluginOrder(plugins, this.model, options.pluginOrderChecks ?? "warn");
 		plugins.forEach((plugin) => {
 			this.use(plugin);
 		});
@@ -2063,12 +2100,13 @@ var Repository = class {
 			};
 			if (isKeyset && sort) {
 				const parsedSort = this._parseSort(sort);
-				const { validateKeysetSort } = await import("./sort-C-BJEWUZ.mjs").then((n) => n.n);
-				const { encodeCursor, resolveCursorFilter } = await import("./cursor-CHToazHy.mjs").then((n) => n.t);
-				const { getPrimaryField } = await import("./sort-C-BJEWUZ.mjs").then((n) => n.n);
-				const normalizedSort = validateKeysetSort(parsedSort);
+				const { validateKeysetSort } = await import("./sort-ffe-9JBg.mjs").then((n) => n.n);
+				const { encodeCursor, resolveCursorFilter } = await import("./cursor-DZ9JSoMM.mjs").then((n) => n.t);
+				const { getPrimaryField } = await import("./sort-ffe-9JBg.mjs").then((n) => n.n);
+				const normalizedSort = validateKeysetSort(parsedSort, this._pagination.config.strictKeysetSortFields);
 				const cursorVersion = this._pagination.config.cursorVersion ?? 1;
-				const matchFilters = after ? resolveCursorFilter(after, normalizedSort, cursorVersion, { ...filters || {} }) : { ...filters || {} };
+				const minCursorVersion = this._pagination.config.minCursorVersion ?? 1;
+				const matchFilters = after ? resolveCursorFilter(after, normalizedSort, cursorVersion, { ...filters || {} }, minCursorVersion) : { ...filters || {} };
 				if (projection) {
 					if (Object.values(projection).some((v) => v === 1)) {
 						for (const sortField of Object.keys(normalizedSort)) if (!(sortField in projection)) projection[sortField] = 1;
@@ -2415,6 +2453,28 @@ var Repository = class {
 * ```
 */
 /**
+* Resolve the user's jitter config into a deterministic `ttl -> ttl` function.
+*
+* - `undefined` / `0`: identity (no jitter).
+* - number in (0, 1]: symmetric fractional jitter. `0.1` → uniform in [0.9, 1.1].
+* - function: used as-is; caller owns the math. Clamped to >= 1s below.
+*
+* The final TTL is always clamped to a whole second >= 1 so adapters that
+* treat 0 as "no expiry" (Redis SETEX semantics) don't accidentally persist
+* entries forever.
+*/
+function resolveJitter(jitter) {
+	if (!jitter) return (ttl) => ttl;
+	if (typeof jitter === "function") return (ttl) => Math.max(1, Math.round(jitter(ttl)));
+	const fraction = Math.min(1, Math.max(0, jitter));
+	if (fraction === 0) return (ttl) => ttl;
+	return (ttl) => {
+		const delta = ttl * fraction;
+		const jittered = ttl - delta + Math.random() * 2 * delta;
+		return Math.max(1, Math.round(jittered));
+	};
+}
+/**
 * Cache plugin factory
 *
 * @param options - Cache configuration
@@ -2428,7 +2488,8 @@ function cachePlugin(options) {
 		queryTtl: options.queryTtl ?? options.ttl ?? 60,
 		prefix: options.prefix ?? "mk",
 		debug: options.debug ?? false,
-		skipIfLargeLimit: options.skipIf?.largeLimit ?? 100
+		skipIfLargeLimit: options.skipIf?.largeLimit ?? 100,
+		applyJitter: resolveJitter(options.jitter)
 	};
 	const stats = {
 		hits: 0,
@@ -2468,7 +2529,7 @@ function cachePlugin(options) {
 			async function bumpVersion() {
 				const newVersion = Date.now();
 				try {
-					await config.adapter.set(versionKey(config.prefix, model), newVersion, config.ttl * 10);
+					await config.adapter.set(versionKey(config.prefix, model), newVersion, config.applyJitter(config.ttl * 10));
 					stats.invalidations++;
 					log(`Bumped version for ${model} to:`, newVersion);
 				} catch (e) {
@@ -2647,7 +2708,7 @@ function cachePlugin(options) {
 					populate: context.populate,
 					lean: context.lean
 				});
-				const ttl = context.cacheTtl ?? config.byIdTtl;
+				const ttl = config.applyJitter(context.cacheTtl ?? config.byIdTtl);
 				try {
 					await config.adapter.set(key, result, ttl);
 					trackByIdKey(id, key);
@@ -2671,7 +2732,7 @@ function cachePlugin(options) {
 					select: context.select,
 					populate: context.populate
 				});
-				const ttl = context.cacheTtl ?? config.queryTtl;
+				const ttl = config.applyJitter(context.cacheTtl ?? config.queryTtl);
 				try {
 					await config.adapter.set(key, result, ttl);
 					stats.sets++;
@@ -2693,7 +2754,7 @@ function cachePlugin(options) {
 					populate: context.populate
 				});
 				try {
-					await config.adapter.set(key, result, context.cacheTtl ?? config.queryTtl);
+					await config.adapter.set(key, result, config.applyJitter(context.cacheTtl ?? config.queryTtl));
 					stats.sets++;
 				} catch (e) {
 					log(`Failed to cache getOne:`, e);
@@ -2726,7 +2787,7 @@ function cachePlugin(options) {
 					countStrategy: context.countStrategy
 				};
 				const key = listQueryKey(config.prefix, model, collectionVersion, params);
-				const ttl = context.cacheTtl ?? config.queryTtl;
+				const ttl = config.applyJitter(context.cacheTtl ?? config.queryTtl);
 				try {
 					await config.adapter.set(key, result, ttl);
 					stats.sets++;
@@ -4215,6 +4276,57 @@ function subdocumentPlugin() {
 	};
 }
 //#endregion
+//#region src/plugins/tenant-context.ts
+/**
+* Request-scoped tenant context via AsyncLocalStorage.
+*
+* The multi-tenant plugin already accepts a `resolveContext` callback for
+* reading tenant ID from an external store. This helper wraps Node's
+* `AsyncLocalStorage` into a tiny, batteries-included API so apps don't need
+* to wire the plumbing by hand — a common source of cross-tenant leaks.
+*
+* @example
+*   import { createTenantContext, multiTenantPlugin } from '@classytic/mongokit';
+*
+*   const tenantContext = createTenantContext();
+*
+*   // In your HTTP middleware (Express / Fastify / NestJS):
+*   app.use((req, _res, next) => {
+*     tenantContext.run({ tenantId: req.auth.organizationId }, next);
+*   });
+*
+*   // In your repository definition:
+*   const repo = new Repository(Invoice, [
+*     multiTenantPlugin({
+*       tenantField: 'organizationId',
+*       resolveContext: () => tenantContext.getTenantId(),
+*     }),
+*   ]);
+*
+*   // In your handler — no need to pass organizationId manually:
+*   await repo.getAll({ filters: { status: 'paid' } });
+*/
+function createTenantContext() {
+	const storage = new AsyncLocalStorage();
+	return {
+		storage,
+		run(store, fn) {
+			return storage.run(store, fn);
+		},
+		getStore() {
+			return storage.getStore();
+		},
+		getTenantId() {
+			return storage.getStore()?.tenantId;
+		},
+		requireTenantId() {
+			const id = storage.getStore()?.tenantId;
+			if (!id) throw new Error("[mongokit] No tenant context active. Wrap the request in tenantContext.run({ tenantId }, fn).");
+			return id;
+		}
+	};
+}
+//#endregion
 //#region src/plugins/timestamp.plugin.ts
 /**
 * Timestamp plugin that auto-injects timestamps
@@ -4388,4 +4500,4 @@ function uniqueField(field, errorMessage) {
 	};
 }
 //#endregion
-export { auditTrailPlugin as A, HOOK_PRIORITY as C, AggregationBuilder as D, withTransaction as E, aggregateHelpersPlugin as M, batchOperationsPlugin as O, cachePlugin as S, isTransactionUnsupported as T, dateSequentialId as _, uniqueField as a, sequentialId as b, subdocumentPlugin as c, multiTenantPlugin as d, mongoOperationsPlugin as f, customIdPlugin as g, elasticSearchPlugin as h, requireField as i, auditLogPlugin as j, AuditTrailQuery as k, softDeletePlugin as l, fieldFilterPlugin as m, blockIf as n, validationChainPlugin as o, methodRegistryPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, observabilityPlugin as u, getNextSequence as v, Repository as w, cascadePlugin as x, prefixedId as y };
+export { AuditTrailQuery as A, cachePlugin as C, withTransaction as D, isTransactionUnsupported as E, auditLogPlugin as M, aggregateHelpersPlugin as N, AggregationBuilder as O, cascadePlugin as S, Repository as T, customIdPlugin as _, uniqueField as a, prefixedId as b, createTenantContext as c, observabilityPlugin as d, multiTenantPlugin as f, elasticSearchPlugin as g, fieldFilterPlugin as h, requireField as i, auditTrailPlugin as j, batchOperationsPlugin as k, subdocumentPlugin as l, methodRegistryPlugin as m, blockIf as n, validationChainPlugin as o, mongoOperationsPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, softDeletePlugin as u, dateSequentialId as v, HOOK_PRIORITY as w, sequentialId as x, getNextSequence as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.6.3",
+  "version": "3.7.0",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,
@@ -101,8 +101,12 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run --project unit --project integration",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:e2e": "vitest run --project e2e",
+    "test:all": "vitest run --project unit --project integration --project e2e",
+    "test:watch": "vitest --project unit --project integration",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "lint": "biome check src/",
@@ -124,6 +128,7 @@
     "@vitest/coverage-v8": "^3.2.4",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
+    "dotenv": "^17.4.2",
     "knip": "^6.3.0",
     "mongodb-memory-server": "^10.4.3",
     "mongoose": "^9.4.1",

package/dist/error-Bpbi_NKo.mjs

@@ -1,63 +0,0 @@
-//#region src/utils/logger.ts
-const noop = () => {};
-let current = {
-	warn: console.warn.bind(console),
-	debug: noop
-};
-/**
-* Configure the internal logger.
-* Pass `false` to silence all output.
-*/
-function configureLogger(config) {
-	if (config === false) current = {
-		warn: noop,
-		debug: noop
-	};
-	else current = {
-		...current,
-		...config
-	};
-}
-/** Emit a warning — security blocks, config issues, performance hints */
-function warn(message, ...args) {
-	current.warn(message, ...args);
-}
-/** Emit debug info — only visible when debug is enabled */
-function debug(message, ...args) {
-	current.debug(message, ...args);
-}
-//#endregion
-//#region src/utils/error.ts
-/**
-* Creates an error with HTTP status code
-*
-* @param status - HTTP status code
-* @param message - Error message
-* @returns Error with status property
-*
-* @example
-* throw createError(404, 'Document not found');
-* throw createError(400, 'Invalid input');
-* throw createError(403, 'Access denied');
-*/
-function createError(status, message) {
-	const error = new Error(message);
-	error.status = status;
-	return error;
-}
-/**
-* Detect and convert a MongoDB E11000 duplicate-key error into
-* a 409 HttpError with an actionable message.
-*
-* Returns `null` when the error is not a duplicate-key error.
-*/
-function parseDuplicateKeyError(error) {
-	if (!error || typeof error !== "object") return null;
-	const mongoErr = error;
-	if (mongoErr.code !== 11e3) return null;
-	const fields = mongoErr.keyPattern ? Object.keys(mongoErr.keyPattern) : [];
-	const values = mongoErr.keyValue ? Object.entries(mongoErr.keyValue).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ") : "";
-	return createError(409, fields.length ? `Duplicate value for ${fields.join(", ")}${values ? ` (${values})` : ""}` : "Duplicate key error");
-}
-//#endregion
-export { warn as a, debug as i, parseDuplicateKeyError as n, configureLogger as r, createError as t };