@classytic/mongokit 3.36.0 → 3.39.0

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

@@ -1,6 +1,6 @@
-import { a as PopulateSpec, i as ObjectId, l as SortSpec, o as ReadPreferenceType, r as FilterQuery, s as SelectSpec, t as AnyDocument } from "./core-62oo3N1C.mjs";
+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 { r as DocField } from "./type-utils-CLzRFtIA.mjs";
-import { RepoCapabilities, RepositoryBase } from "@classytic/repo-core/repository";
+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";
@@ -199,6 +199,28 @@ interface RepositoryOptions {
    * ```
    */
   requirePlugins?: readonly RepositoryPluginName[];
+  /**
+   * Declare the collection's shard key so every filter-taking verb
+   * (`getAll`, `findAll`, `getOne`, `count`, `updateMany`, `aggregate`, …)
+   * catches a filter that omits it — the query mongos has to fan out to
+   * every shard. Id-addressed verbs (`getById`, `update`, `delete`,
+   * `claim`) are not checked; their `_id` match is routed, not scattered.
+   *
+   * The check runs AFTER `before:*` hooks, so a tenant field injected by
+   * `multiTenantPlugin` satisfies a `key: 'organizationId'` guard and the
+   * guard only ever fires on the calls that dropped the scope —
+   * `bypassTenant: true`, an unscoped repo, a hand-built cross-tenant
+   * `$or`. List verbs a host legitimately runs cross-shard (a global
+   * dashboard's `aggregate`) in `exemptOperations`.
+   *
+   * `onMissingKey` defaults to `'warn'` — once per operation name through
+   * mongokit's logger (`configureLogger` routes it); pass `onMiss` to
+   * observe every miss yourself, or `'throw'` for hosts where a scatter-
+   * gather is never acceptable. Omit the option entirely and nothing runs.
+   */
+  distribution?: DistributionConfig & {
+    onMiss?: DistributionMissHandler;
+  };
   /**
    * Override the whole runtime capability descriptor.
    *
@@ -295,6 +317,8 @@ interface RepositoryContext {
   limit?: number;
   /** Cursor for next page (keyset pagination) */
   after?: string;
+  /** Cursor for the PREVIOUS page (keyset pagination). Mutually exclusive with `after`. */
+  before?: string;
   /** Search query string */
   search?: string;
   /** Pagination mode */
@@ -303,8 +327,10 @@ interface RepositoryContext {
   hint?: string | Record<string, 1 | -1>;
   /** Maximum execution time in milliseconds */
   maxTimeMS?: number;
-  /** Count strategy for offset pagination */
-  countStrategy?: 'exact' | 'estimated' | 'none';
+  /** Count strategy for offset pagination. See {@link CountStrategy}. */
+  countStrategy?: CountStrategy;
+  /** Ceiling for `countStrategy: 'capped'` (default 10000). */
+  countLimit?: number;
   /** Whether this is a soft delete operation (set by softDeletePlugin) */
   softDeleted?: boolean;
   /** Include soft-deleted documents in queries */

package/dist/tenant/index.d.mts

@@ -0,0 +1,89 @@
+import { Schema } from "mongoose";
+import { ResolvedTenantConfig } from "@classytic/repo-core/tenant";
+//#region src/tenant/index.d.ts
+/** Which read an index serves. Default `'tenant'`. See the module docblock. */
+type IndexScope = 'tenant' | 'global';
+/** Key directions and types a declaration may use. Mirrors what `schema.index()` accepts. */
+type IndexKeyValue = 1 | -1 | 'text' | '2dsphere' | '2d' | 'hashed';
+/**
+ * Index options passed through to `schema.index()`. `name` is the only one this module
+ * reads (to apply and to explain exemptions); everything else is Mongoose's.
+ */
+interface IndexDeclarationOptions {
+  name?: string | undefined;
+  unique?: boolean | undefined;
+  sparse?: boolean | undefined;
+  partialFilterExpression?: Record<string, unknown> | undefined;
+  expireAfterSeconds?: number | undefined;
+  collation?: Record<string, unknown> | undefined;
+  background?: boolean | undefined;
+  [option: string]: unknown;
+}
+/**
+ * One index, declared by a kernel for its own model or by a host through a kernel's
+ * `indexes` seam. The kernel applies it through {@link injectTenantField}, which is what
+ * makes `scope` mean something: a `'tenant'` declaration is prefixed exactly like the
+ * kernel's own indexes, a `'global'` one is kept as written.
+ */
+interface IndexDeclaration {
+  readonly fields: Readonly<Record<string, IndexKeyValue>>;
+  readonly options?: IndexDeclarationOptions | undefined;
+  /** @default 'tenant' */
+  readonly scope?: IndexScope | undefined;
+}
+interface InjectTenantFieldOptions {
+  /**
+   * Index NAMES (the `name` option of `schema.index()`) already on the schema whose key
+   * spec must NOT get the tenant prefix. The escape hatch for a kernel's OWN global
+   * identity index declared inline in its schema builder (`order_event_id_unique`: the
+   * event id is a kernel-generated UUID and the drain's idempotency contract is exactly
+   * one row per event regardless of tenant). Prefer declaring such an index through
+   * `indexes` with `scope: 'global'`; this exists so a schema builder need not know the
+   * tenant config. Unnamed indexes cannot be exempted: give the index a name first.
+   */
+  readonly skipIndexes?: readonly string[] | undefined;
+  /**
+   * Additional declarations, applied AFTER the prepend pass so their `scope` is honoured.
+   * This is where a kernel threads its host's `indexes` seam.
+   */
+  readonly indexes?: readonly IndexDeclaration[] | undefined;
+}
+/**
+ * Refuse a declaration that cannot mean what it says. Called before any schema mutation
+ * so a bad host config fails at DESCRIBE time, with the fix in the message, rather than
+ * building a wrong index on the first bind.
+ */
+declare function assertIndexDeclaration(declaration: IndexDeclaration, tenant: Pick<ResolvedTenantConfig, 'tenantField'>): void;
+/**
+ * Add `declarations` to `schema` honouring each one's scope.
+ *
+ * `'tenant'` declarations are prefixed with the tenant field when scoping is enabled
+ * (unless they already lead with it, so a host that wrote it out is not double-prefixed);
+ * `'global'` ones are added exactly as written. When scoping is disabled every declaration
+ * is added as written, because there is no partition to lead with.
+ *
+ * Exported for kernels whose optional models inject the tenant field on their own path and
+ * only need the host's extra declarations applied afterwards.
+ */
+declare function declareIndexes(schema: Schema, tenant: ResolvedTenantConfig, declarations: readonly IndexDeclaration[] | undefined): void;
+/**
+ * Inject the tenant field into a Mongoose schema and make its indexes tenant-correct.
+ *
+ * 1. Adds the field, typed by `tenant.fieldType` (`ObjectId` with `ref`, or `String`).
+ *    `required` only when scoping is enabled and the config says so: a single-tenant
+ *    deployment still gets the field, because domain verbs reference it in raw queries.
+ * 2. When scoping is enabled, prepends the tenant field to every index already declared
+ *    on the schema, EXCEPT: one that already names the field; a TTL index (MongoDB rejects
+ *    a compound TTL spec outright, and a time-driven sweep has no tenant to give); and any
+ *    index named in `skipIndexes`.
+ * 3. Applies `indexes` through {@link declareIndexes}, so a `'global'` declaration is never
+ *    touched by step 2 whatever order the caller thought about it in.
+ * 4. Guarantees one tenant-leading index. After the prepend any compound serves a
+ *    tenant-only query via the prefix rule, so a bare `{ tenant: 1 }` is added ONLY when
+ *    nothing was prepended: next to a compound it is a redundant prefix paid on every
+ *    insert (PACKAGE_RULES P11.1; the fleet index audit found this pattern behind most of
+ *    86 redundant indexes across 615).
+ */
+declare function injectTenantField(schema: Schema, tenant: ResolvedTenantConfig, options?: InjectTenantFieldOptions): void;
+//#endregion
+export { IndexDeclaration, IndexDeclarationOptions, IndexKeyValue, IndexScope, InjectTenantFieldOptions, assertIndexDeclaration, declareIndexes, injectTenantField };

package/dist/tenant/index.mjs

@@ -0,0 +1,94 @@
+import mongoose from "mongoose";
+//#region src/tenant/index.ts
+/** Mongoose keeps declared indexes on `schema._indexes`; `schema.indexes()` is a copy. */
+function indexEntries(schema) {
+	return schema._indexes ?? [];
+}
+function isScoped(tenant) {
+	return tenant.enabled && tenant.strategy === "field";
+}
+/**
+* Refuse a declaration that cannot mean what it says. Called before any schema mutation
+* so a bad host config fails at DESCRIBE time, with the fix in the message, rather than
+* building a wrong index on the first bind.
+*/
+function assertIndexDeclaration(declaration, tenant) {
+	if (Object.keys(declaration.fields).length === 0) throw new Error("[mongokit/tenant] an index declaration needs at least one field");
+	if (declaration.scope === "global") {
+		if (typeof declaration.options?.name !== "string" || declaration.options.name.length === 0) throw new Error(`[mongokit/tenant] a global index must be named: { fields: ${JSON.stringify(declaration.fields)}, scope: 'global' } has no \`options.name\`. A tenant exemption is deliberate, and an unnamed one cannot be told from an oversight.`);
+		if (declaration.fields[tenant.tenantField] !== void 0) throw new Error(`[mongokit/tenant] index "${declaration.options.name}" is scope 'global' but names the tenant field "${tenant.tenantField}". A global index serves reads that have no tenant to give; drop the field, or declare the index with scope 'tenant'.`);
+	}
+}
+/**
+* Add `declarations` to `schema` honouring each one's scope.
+*
+* `'tenant'` declarations are prefixed with the tenant field when scoping is enabled
+* (unless they already lead with it, so a host that wrote it out is not double-prefixed);
+* `'global'` ones are added exactly as written. When scoping is disabled every declaration
+* is added as written, because there is no partition to lead with.
+*
+* Exported for kernels whose optional models inject the tenant field on their own path and
+* only need the host's extra declarations applied afterwards.
+*/
+function declareIndexes(schema, tenant, declarations) {
+	if (!declarations || declarations.length === 0) return;
+	for (const declaration of declarations) {
+		assertIndexDeclaration(declaration, tenant);
+		const options = declaration.options;
+		const scoped = isScoped(tenant) && declaration.scope !== "global";
+		const leadsWithTenant = Object.keys(declaration.fields)[0] === tenant.tenantField;
+		const fields = scoped && !leadsWithTenant ? {
+			[tenant.tenantField]: 1,
+			...declaration.fields
+		} : { ...declaration.fields };
+		schema.index(fields, options);
+	}
+}
+/**
+* Inject the tenant field into a Mongoose schema and make its indexes tenant-correct.
+*
+* 1. Adds the field, typed by `tenant.fieldType` (`ObjectId` with `ref`, or `String`).
+*    `required` only when scoping is enabled and the config says so: a single-tenant
+*    deployment still gets the field, because domain verbs reference it in raw queries.
+* 2. When scoping is enabled, prepends the tenant field to every index already declared
+*    on the schema, EXCEPT: one that already names the field; a TTL index (MongoDB rejects
+*    a compound TTL spec outright, and a time-driven sweep has no tenant to give); and any
+*    index named in `skipIndexes`.
+* 3. Applies `indexes` through {@link declareIndexes}, so a `'global'` declaration is never
+*    touched by step 2 whatever order the caller thought about it in.
+* 4. Guarantees one tenant-leading index. After the prepend any compound serves a
+*    tenant-only query via the prefix rule, so a bare `{ tenant: 1 }` is added ONLY when
+*    nothing was prepended: next to a compound it is a redundant prefix paid on every
+*    insert (PACKAGE_RULES P11.1; the fleet index audit found this pattern behind most of
+*    86 redundant indexes across 615).
+*/
+function injectTenantField(schema, tenant, options = {}) {
+	for (const declaration of options.indexes ?? []) assertIndexDeclaration(declaration, tenant);
+	const isObjectId = tenant.fieldType === "objectId";
+	const scoped = isScoped(tenant);
+	schema.add({ [tenant.tenantField]: {
+		type: isObjectId ? mongoose.Schema.Types.ObjectId : String,
+		...scoped && tenant.required ? { required: true } : {},
+		...isObjectId && tenant.ref ? { ref: tenant.ref } : {}
+	} });
+	if (!scoped) {
+		declareIndexes(schema, tenant, options.indexes);
+		return;
+	}
+	const skip = new Set(options.skipIndexes ?? []);
+	for (const entry of indexEntries(schema)) {
+		const [fields, indexOptions] = entry;
+		if (fields[tenant.tenantField] !== void 0) continue;
+		if (indexOptions?.expireAfterSeconds !== void 0) continue;
+		const name = indexOptions?.name;
+		if (typeof name === "string" && skip.has(name)) continue;
+		entry[0] = {
+			[tenant.tenantField]: 1,
+			...fields
+		};
+	}
+	declareIndexes(schema, tenant, options.indexes);
+	if (!indexEntries(schema).some(([fields]) => Object.keys(fields)[0] === tenant.tenantField)) schema.index({ [tenant.tenantField]: 1 });
+}
+//#endregion
+export { assertIndexDeclaration, declareIndexes, injectTenantField };

package/dist/testkit/index.d.mts

@@ -1,5 +1,5 @@
-import { n as Repository } from "../Repository-BdSkQ8vc.mjs";
-import { n as CreateRepositoryConfig } from "../create-repository-BU4x9Kb0.mjs";
+import { n as Repository } from "../Repository-IxI983_m.mjs";
+import { n as CreateRepositoryConfig } from "../create-repository-CRXjDa3N.mjs";
 import { Connection, Model, Schema } from "mongoose";
 import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
 //#region src/testkit/index.d.ts

package/dist/testkit/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRepository } from "../create-repository-CPNbktFG.mjs";
+import { t as createRepository } from "../create-repository-DOe9E_5F.mjs";
 import { createConnection } from "mongoose";
 //#region src/testkit/index.ts
 function idempotentStop(server) {

package/dist/{timestamp.plugin-BEc6TANm.mjs → timestamp.plugin-B5eiaItQ.mjs}

@@ -1,4 +1,4 @@
-import { c as ALL_OPERATIONS, t as HOOK_PRIORITY, u as OP_REGISTRY } from "./Repository-BArvU32x.mjs";
+import { c as ALL_OPERATIONS, t as HOOK_PRIORITY, u as OP_REGISTRY } from "./Repository-D7fDpyFx.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";
 import mongoose from "mongoose";
@@ -795,30 +795,53 @@ function sequentialId(options) {
 *   }),
 * })
 * ```
+*
+* @example Per-tenant numbering in a shared database
+* ```typescript
+* customIdPlugin({
+*   field: 'orderNumber',
+*   generator: dateSequentialId({ prefix: 'ORD', model: OrderModel, scope: 'tenant' }),
+* })
+* // org-a: ORD-2026-02-0001, ORD-2026-02-0002 …   org-b: ORD-2026-02-0001 …
+* ```
 */
 function dateSequentialId(options) {
-	const { prefix, model, partition = "monthly", padding = 4, separator = "-" } = options;
+	const { prefix, model, partition = "monthly", padding = 4, separator = "-", scope = "global", tenantKey = "organizationId", timezone = "local" } = options;
+	/** Per-generator, not module-level — two generators warn independently. */
+	const overflowWarned = /* @__PURE__ */ new Set();
+	const paddingCeiling = 10 ** padding;
 	return async (context) => {
 		const now = /* @__PURE__ */ new Date();
-		const year = String(now.getFullYear());
-		const month = String(now.getMonth() + 1).padStart(2, "0");
-		const day = String(now.getDate()).padStart(2, "0");
+		const utc = timezone === "utc";
+		const year = String(utc ? now.getUTCFullYear() : now.getFullYear());
+		const month = String((utc ? now.getUTCMonth() : now.getMonth()) + 1).padStart(2, "0");
+		const day = String(utc ? now.getUTCDate() : now.getDate()).padStart(2, "0");
+		let keyBase = model.modelName;
+		if (scope === "tenant") {
+			const tenantId = context[tenantKey];
+			if (tenantId === void 0 || tenantId === null || tenantId === "") throw new Error(`[mongokit] dateSequentialId: scope 'tenant' requires '${tenantKey}' in context for '${model.modelName}' create, but none was provided. Pass it per call (repo.create(data, { ${tenantKey}: '<id>' })) or resolve it ambiently; the generator never falls back to the global counter.`);
+			keyBase = `${model.modelName}:${String(tenantId)}`;
+		}
 		let datePart;
 		let counterKey;
 		switch (partition) {
 			case "yearly":
 				datePart = year;
-				counterKey = `${model.modelName}:${year}`;
+				counterKey = `${keyBase}:${year}`;
 				break;
 			case "daily":
 				datePart = `${year}${separator}${month}${separator}${day}`;
-				counterKey = `${model.modelName}:${year}-${month}-${day}`;
+				counterKey = `${keyBase}:${year}-${month}-${day}`;
 				break;
 			default:
 				datePart = `${year}${separator}${month}`;
-				counterKey = `${model.modelName}:${year}-${month}`;
+				counterKey = `${keyBase}:${year}-${month}`;
 		}
 		const seq = await getNextSequence(counterKey, 1, context._counterConnection, context.session);
+		if (seq >= paddingCeiling && !overflowWarned.has(counterKey)) {
+			overflowWarned.add(counterKey);
+			warn(`[mongokit] dateSequentialId: '${model.modelName}' sequence ${seq} exceeds padding ${padding} (max ${paddingCeiling - 1}) for period '${counterKey}'. Ids remain unique but no longer sort lexically — raise \`padding\` for new periods, or use a finer \`partition\`.`);
+		}
 		return `${prefix}${separator}${datePart}${separator}${String(seq).padStart(padding, "0")}`;
 	};
 }
@@ -1290,6 +1313,50 @@ function softDeletePlugin(options = {}) {
 					};
 				}
 			}, { priority: HOOK_PRIORITY.POLICY });
+			/**
+			* Hook: before:bulkWrite — every sub-op gets what its standalone form gets.
+			*
+			* This was skipped as "not a single filter we can scope", but a sub-op DOES carry
+			* its own filter — the tenant plugin walks exactly these keys. Skipping it meant a
+			* soft-delete repository's `bulkWrite` updated rows it had already deleted, and
+			* HARD-deleted through `deleteOne`/`deleteMany`, destroying data the model says is
+			* recoverable. The suite's own header claimed this was covered.
+			*
+			* `deleteMode: 'hard'` still bypasses, exactly as the single-doc path does — a purge
+			* is a deliberate physical delete, and it reaches the driver directly anyway.
+			*/
+			repo.on("before:bulkWrite", (context) => {
+				if (options.soft === false || context.deleteMode === "hard") return;
+				const ops = context.operations;
+				if (!Array.isArray(ops)) return;
+				const notDeleted = buildDeletedFilter(deletedField, filterMode, false);
+				for (const subOp of ops) {
+					if (!subOp || typeof subOp !== "object") continue;
+					for (const key of [
+						"updateOne",
+						"updateMany",
+						"replaceOne"
+					]) {
+						const body = subOp[key];
+						if (body?.filter) body.filter = {
+							...body.filter,
+							...notDeleted
+						};
+					}
+					for (const [key, target] of [["deleteOne", "updateOne"], ["deleteMany", "updateMany"]]) {
+						const body = subOp[key];
+						if (!body?.filter) continue;
+						subOp[target] = {
+							filter: {
+								...body.filter,
+								...notDeleted
+							},
+							update: { $set: { [deletedField]: /* @__PURE__ */ new Date() } }
+						};
+						delete subOp[key];
+					}
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:deleteMany", async (context) => {
 				if (context.deleteMode === "hard") return;
 				if (options.soft !== false) {

package/dist/{to-plain-Dyz_qvuo.d.mts → to-plain-B8ufk3Qz.d.mts}

@@ -1,5 +1,5 @@
-import { v as UserContext } from "./repository-H_ffGgpE.mjs";
-import { r as FieldPreset } from "./plugin-options-DXnlKM3B.mjs";
+import { v as UserContext } from "./repository-ZbLtL7Nk.mjs";
+import { r as FieldPreset } from "./plugin-options-BuvtOSZf.mjs";
 import mongoose, { Schema } from "mongoose";
 import { CacheAdapter } from "@classytic/repo-core/cache";
 import { HttpError } from "@classytic/repo-core/errors";

package/dist/{update-jSXp3nu3.mjs → update-c_01A0if.mjs}

@@ -2,6 +2,99 @@ import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
 import { coerceFilterDates, isFilter } from "@classytic/repo-core/filter";
+//#region src/actions/create.ts
+var create_exports = /* @__PURE__ */ __exportAll({
+	create: () => create,
+	createDefault: () => createDefault,
+	createMany: () => createMany,
+	isCreateManyPartialError: () => isCreateManyPartialError,
+	upsert: () => upsert
+});
+/**
+* Create single document
+*/
+async function create(Model, data, options = {}) {
+	const document = new Model(data);
+	await document.save({ session: options.session });
+	return document;
+}
+/** Narrow a caught error to one carrying a partial-write report. */
+function isCreateManyPartialError(err) {
+	return err instanceof Error && typeof err.partial === "object" && err.partial !== null;
+}
+/** Pull the positional failures out of a driver bulk-write error. */
+function readFailures(err, dataArray) {
+	const raw = err.writeErrors;
+	return (Array.isArray(raw) ? raw : raw ? [raw] : []).map((entry) => {
+		const e = entry;
+		const inner = e.err ?? e;
+		const index = Number(inner.index ?? e.index ?? -1);
+		return {
+			index,
+			doc: dataArray[index] ?? {},
+			...typeof inner.code === "number" ? { code: inner.code } : {},
+			message: String(inner.errmsg ?? inner.message ?? e.message ?? "write failed")
+		};
+	});
+}
+/**
+* Create multiple documents.
+*
+* **A rejection does NOT mean nothing was written.** Neither ordering does:
+* `ordered: true` stops at the first failure and keeps everything before it,
+* `ordered: false` keeps everything valid. Measured on a six-document batch
+* with a conflict in the middle — ordered wrote 3, unordered wrote 5. Only a
+* transaction gives all-or-nothing.
+*
+* So the rejection carries a `partial` report naming what landed and what did
+* not, because the alternative is a caller retrying the whole batch and
+* double-writing everything that had already succeeded. Use it to retry only
+* `failed`, or to reconcile — and prefer a unique index or an idempotency key
+* for anything that will be retried automatically.
+*/
+async function createMany(Model, dataArray, options = {}) {
+	try {
+		return await Model.insertMany(dataArray, {
+			session: options.session,
+			ordered: options.ordered === true
+		});
+	} catch (err) {
+		const inserted = err.insertedDocs;
+		const failed = readFailures(err, dataArray);
+		if (Array.isArray(inserted) || failed.length > 0) err.partial = {
+			inserted: Array.isArray(inserted) ? inserted : [],
+			failed
+		};
+		throw err;
+	}
+}
+/**
+* Create with defaults (useful for initialization)
+*/
+async function createDefault(Model, overrides = {}, options = {}) {
+	const defaults = {};
+	Model.schema.eachPath((path, schemaType) => {
+		const schemaOptions = schemaType.options;
+		if (schemaOptions.default !== void 0 && path !== "_id") defaults[path] = typeof schemaOptions.default === "function" ? schemaOptions.default() : schemaOptions.default;
+	});
+	return create(Model, {
+		...defaults,
+		...overrides
+	}, options);
+}
+/**
+* Upsert (create or update)
+*/
+async function upsert(Model, query, data, options = {}) {
+	return Model.findOneAndUpdate(query, { $setOnInsert: data }, {
+		upsert: true,
+		returnDocument: "after",
+		runValidators: true,
+		session: options.session,
+		...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
+	});
+}
+//#endregion
 //#region src/filter/compile.ts
 /**
 * Compile a Filter IR node to a MongoDB query object. Returns `{}`
@@ -611,24 +704,35 @@ async function aggregate(Model, pipeline, options = {}) {
 	return aggregation.exec();
 }
 /**
-* Aggregate with pagination using native MongoDB $facet
-* WARNING: $facet results must be <16MB. For larger results (limit >1000),
-* consider using Repository.aggregatePaginate() or splitting into separate queries.
+* Aggregate with pagination.
+*
+* Page and count run as TWO concurrent pipelines rather than one `$facet`.
+* `$facet` bundles every returned document plus the count into a SINGLE output
+* document, and no stage may exceed 16MB — so a page of large documents failed
+* with `BSONObjectTooLarge` instead of paginating, and the only defence was a
+* warning above an arbitrary limit of 1000 that told the caller to go
+* elsewhere. `$facet` also cannot use an index for the stages inside it.
+*
+* The trade: two reads, so a concurrent write between them can leave `total`
+* a document out of step with `data` — the same trade `PaginationEngine`
+* already makes on both its offset and aggregate paths.
 */
 async function aggregatePaginate(Model, pipeline, options = {}) {
 	const page = parseInt(String(options.page || 1), 10);
 	const limit = parseInt(String(options.limit || 10), 10);
 	const skip = (page - 1) * limit;
-	if (limit > 1e3) warn(`[mongokit] Large aggregation limit (${limit}). $facet results must be <16MB. Consider using Repository.aggregatePaginate() for safer handling of large datasets.`);
-	const facetPipeline = [...pipeline, { $facet: {
-		data: [{ $skip: skip }, { $limit: limit }],
-		total: [{ $count: "count" }]
-	} }];
-	const aggregation = Model.aggregate(facetPipeline);
-	if (options.session) aggregation.session(options.session);
-	const [result] = await aggregation.exec();
-	const data = result.data || [];
-	const total = result.total[0]?.count || 0;
+	const run = (stages) => {
+		const aggregation = Model.aggregate(stages);
+		if (options.session) aggregation.session(options.session);
+		return aggregation.exec();
+	};
+	const [dataRows, countRows] = await Promise.all([run([
+		...pipeline,
+		{ $skip: skip },
+		{ $limit: limit }
+	]), run([...pipeline, { $count: "count" }])]);
+	const data = dataRows || [];
+	const total = countRows[0]?.count || 0;
 	const pages = Math.ceil(total / limit);
 	return {
 		data,
@@ -748,57 +852,6 @@ async function minMax(Model, field, query = {}, options = {}) {
 	};
 }
 //#endregion
-//#region src/actions/create.ts
-var create_exports = /* @__PURE__ */ __exportAll({
-	create: () => create,
-	createDefault: () => createDefault,
-	createMany: () => createMany,
-	upsert: () => upsert
-});
-/**
-* Create single document
-*/
-async function create(Model, data, options = {}) {
-	const document = new Model(data);
-	await document.save({ session: options.session });
-	return document;
-}
-/**
-* Create multiple documents
-*/
-async function createMany(Model, dataArray, options = {}) {
-	return Model.insertMany(dataArray, {
-		session: options.session,
-		ordered: options.ordered === true
-	});
-}
-/**
-* Create with defaults (useful for initialization)
-*/
-async function createDefault(Model, overrides = {}, options = {}) {
-	const defaults = {};
-	Model.schema.eachPath((path, schemaType) => {
-		const schemaOptions = schemaType.options;
-		if (schemaOptions.default !== void 0 && path !== "_id") defaults[path] = typeof schemaOptions.default === "function" ? schemaOptions.default() : schemaOptions.default;
-	});
-	return create(Model, {
-		...defaults,
-		...overrides
-	}, options);
-}
-/**
-* Upsert (create or update)
-*/
-async function upsert(Model, query, data, options = {}) {
-	return Model.findOneAndUpdate(query, { $setOnInsert: data }, {
-		upsert: true,
-		returnDocument: "after",
-		runValidators: true,
-		session: options.session,
-		...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
-	});
-}
-//#endregion
 //#region src/actions/delete.ts
 var delete_exports = /* @__PURE__ */ __exportAll({
 	deleteById: () => deleteById,
@@ -813,8 +866,8 @@ var delete_exports = /* @__PURE__ */ __exportAll({
 */
 async function deleteById(Model, id, options = {}) {
 	const query = {
-		_id: id,
-		...options.query
+		...options.query,
+		_id: id
 	};
 	if (!await Model.findOneAndDelete(query).session(options.session ?? null)) return null;
 	return {
@@ -1053,8 +1106,8 @@ function parsePopulate(populate) {
 async function update(Model, id, data, options = {}) {
 	assertUpdatePipelineAllowed(data, options.updatePipeline);
 	const query = {
-		_id: id,
-		...options.query
+		...options.query,
+		_id: id
 	};
 	return await Model.findOneAndUpdate(query, data, {
 		returnDocument: "after",
@@ -1071,8 +1124,8 @@ async function update(Model, id, data, options = {}) {
 async function updateWithConstraints(Model, id, data, constraints = {}, options = {}) {
 	assertUpdatePipelineAllowed(data, options.updatePipeline);
 	const query = {
-		_id: id,
-		...constraints
+		...constraints,
+		_id: id
 	};
 	return await Model.findOneAndUpdate(query, data, {
 		returnDocument: "after",
@@ -1097,8 +1150,8 @@ async function updateWithValidation(Model, id, data, validationOptions = {}, opt
 		};
 	}
 	const findQuery = {
-		_id: id,
-		...options.query
+		...options.query,
+		_id: id
 	};
 	const existing = await Model.findOne(findQuery).select(options.select || "").session(options.session ?? null).lean();
 	if (!existing) return {
@@ -1204,4 +1257,4 @@ async function pullFromArray(Model, id, field, value, options = {}) {
 	return update(Model, id, { $pull: { [field]: value } }, options);
 }
 //#endregion
-export { upsert as _, count as a, LookupBuilder as b, getByQuery as c, deleteById as d, deleteByQuery as f, create_exports as g, createMany as h, update_exports as i, getOrCreate as l, create as m, update as n, exists as o, delete_exports as p, updateByQuery as r, getById as s, findOneAndUpdate as t, read_exports as u, aggregate_exports as v, compileFilterToMongo as x, distinct as y };
+export { upsert as S, compileFilterToMongo as _, count as a, create_exports as b, getByQuery as c, deleteById as d, deleteByQuery as f, LookupBuilder as g, distinct as h, update_exports as i, getOrCreate as l, aggregate_exports as m, update as n, exists as o, delete_exports as p, updateByQuery as r, getById as s, findOneAndUpdate as t, read_exports as u, create as v, isCreateManyPartialError as x, createMany as y };

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-Dyz_qvuo.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-B8ufk3Qz.mjs";
 import { ClientSession, Model } from "mongoose";
 //#region src/utils/id-chunks.d.ts
 /**

package/dist/{validation-chain.plugin-CyK1s9Ze.mjs → validation-chain.plugin-Bju1D1Sn.mjs}

@@ -1,6 +1,6 @@
 import { n as collectIds, r as idChunks, t as DEFAULT_ID_CHUNK } from "./id-chunks-BmAwsqNk.mjs";
-import { c as ALL_OPERATIONS, u as OP_REGISTRY } from "./Repository-BArvU32x.mjs";
-import { _ as upsert } from "./update-jSXp3nu3.mjs";
+import { c as ALL_OPERATIONS, u as OP_REGISTRY } from "./Repository-D7fDpyFx.mjs";
+import { S as upsert } from "./update-c_01A0if.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
 import { r as getFieldsForUser } from "./field-selection-FSQFLpsU.mjs";