@classytic/mongokit 3.24.0 → 3.28.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://badge.fury.io/js/@classytic%2Fmongokit.svg)](https://www.npmjs.com/package/@classytic/mongokit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
 
 Production-ready repository layer for Mongoose apps: tenant-safe CRUD, soft delete, pagination, hooks, retries, transactions, change streams, and plugins.
 
@@ -212,12 +213,21 @@ const parser = new QueryParser({
   searchMode: 'auto',
 });
 
-const parsed = parser.parse(req.query);
+const parsed = parser.parse(req.query); // throws HttpError(400) on invalid/blocked input
 const result = await invoiceRepo.getAll(parsed);
 ```
 
 Supports common URL operators such as `_gt`, `_gte`, `_lt`, `_lte`, `_in`, `_nin`, `_regex`, geo filters, populate, and schema-aware coercion.
 
+The parser is **fail-closed by default** (`invalidInput: 'throw'`): blocked
+operators, disallowed fields, malformed values, and pathological regex input
+raise HTTP 400 (`code: 'INVALID_QUERY_INPUT'`) instead of being silently
+dropped — dropping a request's *only* filter would broaden the query to every
+record in tenant scope. Literal-semantics input (`search`, `like`/`contains`)
+always escapes rather than rejects, so `?search=c++` never 400s. Trusted
+migration/compat tooling can opt into the legacy warn-and-drop behavior with
+`invalidInput: 'drop'`.
+
 ## Built-In Plugins
 
 | Plugin | Purpose |
@@ -228,7 +238,7 @@ Supports common URL operators such as `_gt`, `_gte`, `_lt`, `_lte`, `_in`, `_nin
 | `timestampPlugin` | `createdAt` / `updatedAt` management |
 | `batchOperationsPlugin` | `bulkWrite` and batch helpers |
 | `cachePlugin` | Pluggable read-through cache |
-| `auditLogPlugin` / `auditTrailPlugin` | Operational and compliance audit trails |
+| `auditLogPlugin` / `auditTrailPlugin` | Audit trails — `auditTrailPlugin({ mode: 'transactional' })` gives session-joined entries that are atomic inside `withTransaction` (compliance-grade); the default `'best-effort'` mode is fire-and-forget observability. Call `ensureAuditTrailReady()` at boot so collection/index creation doesn't happen inside the first transaction |
 | `observabilityPlugin` | Metrics hook points |
 | `cascadePlugin` | Hook-routed cascade delete |
 | `customIdPlugin` | Prefixed or sequential public IDs |

package/dist/{PaginationEngine-BnZ24ehC.d.mts → PaginationEngine-CBS1XGzp.d.mts}

@@ -1,4 +1,5 @@
-import { A as KeysetPaginationOptions, U as PaginationConfig, V as OffsetPaginationOptions, i as AnyDocument, n as AggregatePaginationOptions } from "./types-BtMuhoX5.mjs";
+import { t as AnyDocument } from "./core-62oo3N1C.mjs";
+import { c as PaginationConfig, o as KeysetPaginationOptions, s as OffsetPaginationOptions, t as AggregatePaginationOptions } from "./pagination-jSUdrACK.mjs";
 import { Model } from "mongoose";
 import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
 //#region src/pagination/PaginationEngine.d.ts

package/dist/{Repository-ClOraFjT.mjs → Repository-BFBTAMlA.mjs}

@@ -1,4 +1,4 @@
-import { i as isValidIdForType, t as getSchemaIdType } from "./id-resolution-P2OzcyRl.mjs";
+import { i as isValidIdForType, t as getSchemaIdType } from "./id-resolution-BqDrk0S2.mjs";
 import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-1Lq9OMD2.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
@@ -16,20 +16,56 @@ import { decodeAggCursor, encodeAggCursor, isKeysetMode, normalizeGroupBy, valid
 * predicate the purge targets.
 */
 function createMongoPurgePort(repo, field, value, session) {
-	const filter = { [field]: value };
+	return createKeysetPurgePort(repo, { [field]: value }, session);
+}
+/**
+* Build a `PurgePort` bound to a repository + a pre-compiled Mongo filter
+* (the repository compiles Filter IR via `compileFilterToMongo` before
+* calling this) — the range/filter-scoped sibling of
+* {@link createMongoPurgePort}.
+*
+* The per-strategy chunk logic is IDENTICAL to the equality-bound port; the
+* only difference is the base predicate — an arbitrary compiled filter (a
+* `civilDate` window, a retention cutoff, a compound cohort) instead of
+* `{ [field]: value }`. The narrowed write is re-asserted on
+* `{ _id: { $in: ids }, ...filter }`, the same defense the equality port
+* uses, so a row that leaves the matching set between the id select and the
+* write is never touched.
+*
+* Mirrors `createMongoArchivePort`, which likewise binds a pre-compiled
+* filter rather than a `field/value` pair.
+*/
+function createMongoPurgePortFromFilter(repo, filter, session) {
+	return createKeysetPurgePort(repo, filter, session);
+}
+/**
+* Shared keyset-progressed port both public factories delegate to. The
+* closure's `cursor` is the port's single-run progression state.
+*/
+function createKeysetPurgePort(repo, baseFilter, session) {
 	const baseOpts = {
 		session,
 		bypassTenant: true
 	};
+	let cursor = null;
+	const selectFilter = () => cursor == null ? baseFilter : {
+		...baseFilter,
+		_id: { $gt: cursor }
+	};
 	return { async purgeChunk(strategy, limit) {
 		if (strategy.type === "anonymize") {
-			if (Object.values(strategy.fields).some((v) => typeof v === "function")) return purgeAnonymizeFunctional(repo, filter, strategy.fields, limit, session);
+			if (Object.values(strategy.fields).some((v) => typeof v === "function")) {
+				const { processed, lastId } = await purgeAnonymizeFunctional(repo, selectFilter(), strategy.fields, limit, session);
+				if (lastId != null) cursor = lastId;
+				return processed;
+			}
 		}
-		const idDocs = await repo.Model.find(filter, { _id: 1 }).limit(limit).session(session ?? null).lean().exec();
+		const idDocs = await repo.Model.find(selectFilter(), { _id: 1 }).sort({ _id: 1 }).limit(limit).session(session ?? null).lean().exec();
 		if (idDocs.length === 0) return 0;
+		const ids = idDocs.map((d) => d._id);
 		const chunkFilter = {
-			_id: { $in: idDocs.map((d) => d._id) },
-			[field]: value
+			...baseFilter,
+			_id: { $in: ids }
 		};
 		switch (strategy.type) {
 			case "hard":
@@ -37,17 +73,19 @@ function createMongoPurgePort(repo, field, value, session) {
 					...baseOpts,
 					mode: "hard"
 				});
-				return idDocs.length;
+				break;
 			case "soft":
 				await repo.updateMany(chunkFilter, { $set: {
 					[strategy.deletedField ?? "deleted"]: true,
 					[strategy.deletedAtField ?? "deletedAt"]: /* @__PURE__ */ new Date()
 				} }, baseOpts);
-				return idDocs.length;
+				break;
 			case "anonymize":
 				await repo.updateMany(chunkFilter, { $set: strategy.fields }, baseOpts);
-				return idDocs.length;
+				break;
 		}
+		cursor = ids[ids.length - 1];
+		return idDocs.length;
 	} };
 }
 /**
@@ -56,13 +94,20 @@ function createMongoPurgePort(repo, field, value, session) {
 * heterogeneous `updateOne` ops. Two round-trips per chunk regardless
 * of N — vs the N+1 of per-doc `update()` fan-out.
 *
+* Selection is `_id`-ascending against the caller's keyset-narrowed
+* filter; returns the chunk's last `_id` so the port can advance its
+* cursor after the write commits.
+*
 * Mongo's `bulkWrite` is ordered: false → independent failures don't
 * abort the batch. For idempotent anonymize (same row anonymized twice
 * is the same write), this matches the at-least-once contract.
 */
-async function purgeAnonymizeFunctional(repo, filter, fields, limit, session) {
-	const docs = await repo.Model.find(filter).limit(limit).session(session ?? null).lean().exec();
-	if (docs.length === 0) return 0;
+async function purgeAnonymizeFunctional(repo, selectFilter, fields, limit, session) {
+	const docs = await repo.Model.find(selectFilter).sort({ _id: 1 }).limit(limit).session(session ?? null).lean().exec();
+	if (docs.length === 0) return {
+		processed: 0,
+		lastId: null
+	};
 	const operations = docs.map((doc) => {
 		const set = {};
 		for (const [k, v] of Object.entries(fields)) set[k] = typeof v === "function" ? v(doc) : v;
@@ -75,7 +120,10 @@ async function purgeAnonymizeFunctional(repo, filter, fields, limit, session) {
 		ordered: false,
 		session: session ?? void 0
 	});
-	return docs.length;
+	return {
+		processed: docs.length,
+		lastId: docs[docs.length - 1]?._id ?? null
+	};
 }
 //#endregion
 //#region src/capabilities.ts
@@ -97,6 +145,7 @@ const MONGOKIT_CAPABILITIES = {
 	getOrCreate: true,
 	countAndExists: true,
 	purgeByField: true,
+	purgeByFilter: true,
 	archiveByFilter: true,
 	arrayOperators: true,
 	regexFilter: true,
@@ -543,7 +592,7 @@ function buildAggPipeline(req) {
 		const match = compileFilterToMongo(baseFilter);
 		if (Object.keys(match).length > 0) stages.push({ $match: match });
 	}
-	if (req.lookups && req.lookups.length > 0) appendLookupStages(stages, req.lookups);
+	if (req.lookups && req.lookups.length > 0) appendLookupStages$1(stages, req.lookups);
 	if (joinedFilter !== void 0) {
 		const match = compileFilterToMongo(joinedFilter);
 		if (Object.keys(match).length > 0) stages.push({ $match: match });
@@ -698,7 +747,7 @@ function validateBucketAliases(bucketAliases, groupCols, measures) {
 function safeIdKey(field) {
 	return field.includes(".") ? field.replace(/\./g, "__") : field;
 }
-function appendLookupStages(stages, lookups) {
+function appendLookupStages$1(stages, lookups) {
 	const asLookupOptions = lookups;
 	stages.push(...LookupBuilder.multiple(asLookupOptions));
 	for (const lookup of lookups) if (lookup.single) {
@@ -1470,6 +1519,59 @@ var AggregationBuilder = class AggregationBuilder {
 *    ```
 */
 //#endregion
+//#region src/repository/lookup-populate.ts
+/**
+* Inclusion projections must carry the keyset sort fields (plus `_id`) or
+* cursor encoding has no values to serialize. No-op for exclusion
+* projections and cursor-less calls.
+*/
+function ensureLookupProjectionIncludesCursorFields(projection, sort) {
+	if (!projection || !sort) return projection;
+	if (!Object.values(projection).some((value) => value === 1)) return projection;
+	const nextProjection = { ...projection };
+	for (const field of [...Object.keys(sort), "_id"]) nextProjection[field] = 1;
+	return nextProjection;
+}
+/**
+* Build the `$project` map from a caller's select spec (string / array /
+* inclusion-exclusion record). For inclusion projections, every lookup's
+* `as` field is auto-included so `$project` doesn't strip the joined data.
+* Returns a fresh object (callers may add fields for cursor encoding).
+*/
+function buildLookupProjection(selectSpec, lookups) {
+	if (!selectSpec) return void 0;
+	let projection;
+	if (typeof selectSpec === "string") {
+		projection = {};
+		for (const field of selectSpec.split(",").map((f) => f.trim())) if (field.startsWith("-")) projection[field.substring(1)] = 0;
+		else projection[field] = 1;
+	} else if (Array.isArray(selectSpec)) {
+		projection = {};
+		for (const field of selectSpec) if (field.startsWith("-")) projection[field.substring(1)] = 0;
+		else projection[field] = 1;
+	} else projection = { ...selectSpec };
+	if (Object.values(projection).some((v) => v === 1)) for (const lookup of lookups) {
+		const asField = lookup.as || lookup.from;
+		if (!(asField in projection)) projection[asField] = 1;
+	}
+	return projection;
+}
+/**
+* Append the shared pipeline tail: `$lookup` stages, `$ifNull` coalescing
+* for `single` lookups, and the final `$project` (with cursor fields kept
+* when a keyset sort is active). Mutates `pipeline` in place — it is the
+* tail-builder both the keyset and offset modes share.
+*/
+function appendLookupStages(pipeline, lookups, projection, keysetSort) {
+	pipeline.push(...LookupBuilder.multiple(lookups));
+	for (const lookup of lookups) if (lookup.single) {
+		const asField = lookup.as || lookup.from;
+		pipeline.push({ $addFields: { [asField]: { $ifNull: [`$${asField}`, null] } } });
+	}
+	const finalProjection = ensureLookupProjectionIncludesCursorFields(projection, keysetSort);
+	if (finalProjection) pipeline.push({ $project: finalProjection });
+}
+//#endregion
 //#region src/tx-bound.ts
 /**
 * Map of session-aware method name → positional index of the `{ session }`
@@ -1678,15 +1780,35 @@ function isTransactionUnsupported(error) {
 	const message = (error.message || "").toLowerCase();
 	return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("transaction is not supported") || message.includes("does not support retryable writes");
 }
+/**
+* PROACTIVELY report whether a connection's deployment supports multi-document
+* transactions — the read-side companion to {@link isTransactionUnsupported}
+* (which classifies a FAILED attempt). Single source of truth for the topology
+* check so callers don't hand-roll `client.topology.description.type` probing.
+*
+* Returns `false` ONLY when the topology is positively a standalone (`'Single'`)
+* server; an unknown/undefined topology (not yet connected, non-standard
+* connection object) returns `true` — optimistic, because a genuine failure is
+* still caught reactively by `isTransactionUnsupported`. Lets a caller skip a
+* doomed transaction attempt on standalone dev Mongo rather than starting one
+* just to catch the error.
+*
+* Accepts a Mongoose `Connection` (or anything exposing `getClient()`/`client`
+* with a driver `topology`), so it stays decoupled from mongoose types.
+*/
+function supportsTransactions(connection) {
+	const probe = connection;
+	if (!probe) return true;
+	let client;
+	try {
+		client = probe.getClient?.() ?? probe.client ?? void 0;
+	} catch {
+		return true;
+	}
+	return client?.topology?.description?.type !== "Single";
+}
 //#endregion
 //#region src/Repository.ts
-function ensureLookupProjectionIncludesCursorFields(projection, sort) {
-	if (!projection || !sort) return projection;
-	if (!Object.values(projection).some((value) => value === 1)) return projection;
-	const nextProjection = { ...projection };
-	for (const field of [...Object.keys(sort), "_id"]) nextProjection[field] = 1;
-	return nextProjection;
-}
 /**
 * Validates that an update patch is homogeneous — either all top-level
 * keys are `$`-prefixed Mongo operators OR none are. Mixed shapes (e.g.
@@ -3395,6 +3517,24 @@ var Repository = class extends RepositoryBase {
 		return runChunkedPurge(strategy, options, createMongoPurgePort(this, field, value, options.session));
 	}
 	/**
+	* Range/filter-scoped purge — see `StandardRepo.purgeByFilter` for the
+	* cross-kit contract. The compliance primitive for "purge/anonymize a
+	* slice across a RANGE while retaining measures" (redact a PII dimension
+	* across a `civilDate` window, hard-delete past a retention cutoff): the
+	* base predicate is an arbitrary compiled filter, not `field = value`.
+	*
+	* Composes the kit-agnostic `runChunkedPurge` orchestrator (loop, signal,
+	* progress, result envelope) with `createMongoPurgePortFromFilter` (the
+	* filter-bound sibling of `createMongoPurgePort`). Accepts Filter IR or a
+	* Mongo-shaped filter record — compiled once via `compileFilterToMongo`,
+	* the same dual-dialect rule as `archiveByFilter` and every other verb.
+	* See [actions/purge.ts](./actions/purge.ts) for the port.
+	*/
+	async purgeByFilter(filter, strategy, options = {}) {
+		const compiled = compileFilterToMongo(filter);
+		return runChunkedPurge(strategy, options, createMongoPurgePortFromFilter(this, compiled, options.session));
+	}
+	/**
 	* Chunked cold-storage extraction — see `StandardRepo.archiveByFilter`
 	* for the cross-kit contract (write-before-delete, at-least-once,
 	* duplicate-tolerant sinks). Mongokit composes the kit-agnostic
@@ -3423,6 +3563,15 @@ var Repository = class extends RepositoryBase {
 	* Routes through the hook system for policy enforcement
 	* (multi-tenant, soft-delete).
 	*
+	* The pipeline parameter also accepts `readonly unknown[]` (3.25.0):
+	* real-world stage arrays are assembled from exported fragment builders
+	* and spreads whose element type degrades to `unknown` — mongoose's
+	* `PipelineStage` union can't be satisfied without an `as` at every
+	* such call site. Runtime validation is MongoDB's job either way; the
+	* single documented widening lives HERE instead of N host-side casts
+	* (spine PACKAGE_RULES §7.1). Literal arrays still get full
+	* `PipelineStage` contextual checking via the first union member.
+	*
 	* @param pipeline - MongoDB aggregation stage array
 	* @param options  - Aggregation options including governance controls
 	*/
@@ -3748,34 +3897,8 @@ var Repository = class extends RepositoryBase {
 				const pageFromContext = context.page ?? options.page;
 				const isKeyset = !!after || !pageFromContext && !!sort;
 				const countStrategy = context.countStrategy ?? options.countStrategy ?? "exact";
-				const selectSpec = context.select ?? options.select;
-				let projection;
-				if (selectSpec) {
-					if (typeof selectSpec === "string") {
-						projection = {};
-						for (const field of selectSpec.split(",").map((f) => f.trim())) if (field.startsWith("-")) projection[field.substring(1)] = 0;
-						else projection[field] = 1;
-					} else if (Array.isArray(selectSpec)) {
-						projection = {};
-						for (const field of selectSpec) if (field.startsWith("-")) projection[field.substring(1)] = 0;
-						else projection[field] = 1;
-					} else projection = { ...selectSpec };
-					if (projection) {
-						if (Object.values(projection).some((v) => v === 1)) for (const lookup of lookups) {
-							const asField = lookup.as || lookup.from;
-							if (!(asField in projection)) projection[asField] = 1;
-						}
-					}
-				}
-				const appendLookupStages = (pipeline) => {
-					pipeline.push(...LookupBuilder.multiple(lookups));
-					for (const lookup of lookups) if (lookup.single) {
-						const asField = lookup.as || lookup.from;
-						pipeline.push({ $addFields: { [asField]: { $ifNull: [`$${asField}`, null] } } });
-					}
-					const finalProjection = ensureLookupProjectionIncludesCursorFields(projection, isKeyset && sort ? this._parseSort(sort) : void 0);
-					if (finalProjection) pipeline.push({ $project: finalProjection });
-				};
+				const projection = buildLookupProjection(context.select ?? options.select, lookups);
+				const appendLookupStages$2 = (pipeline) => appendLookupStages(pipeline, lookups, projection, isKeyset && sort ? this._parseSort(sort) : void 0);
 				if (isKeyset && sort) {
 					const parsedSort = this._parseSort(sort);
 					const { validateKeysetSort } = await import("./PaginationEngine-CczbvCAq.mjs").then((n) => n.n);
@@ -3794,7 +3917,7 @@ var Repository = class extends RepositoryBase {
 					if (Object.keys(matchFilters).length > 0) pipeline.push({ $match: matchFilters });
 					pipeline.push({ $sort: normalizedSort });
 					pipeline.push({ $limit: limit + 1 });
-					appendLookupStages(pipeline);
+					appendLookupStages$2(pipeline);
 					const aggregation = this.Model.aggregate(pipeline).session(session || null);
 					if (collation) aggregation.collation(collation);
 					if (readPref) aggregation.read(readPref);
@@ -3823,7 +3946,7 @@ var Repository = class extends RepositoryBase {
 				if (sort) dataPipeline.push({ $sort: this._parseSort(sort) });
 				if (countStrategy === "none") {
 					dataPipeline.push({ $skip: skip }, { $limit: limit + 1 });
-					appendLookupStages(dataPipeline);
+					appendLookupStages$2(dataPipeline);
 					const aggregation = this.Model.aggregate(dataPipeline).session(session || null);
 					if (collation) aggregation.collation(collation);
 					if (readPref) aggregation.read(readPref);
@@ -3847,7 +3970,7 @@ var Repository = class extends RepositoryBase {
 					return result;
 				}
 				dataPipeline.push({ $skip: skip }, { $limit: limit });
-				appendLookupStages(dataPipeline);
+				appendLookupStages$2(dataPipeline);
 				const countPipeline = [];
 				if (filters && Object.keys(filters).length > 0) countPipeline.push({ $match: filters });
 				countPipeline.push({ $count: "total" });
@@ -4180,4 +4303,4 @@ var Repository = class extends RepositoryBase {
 	}
 };
 //#endregion
-export { withTransaction as a, MUTATING_OPERATIONS as c, operationsByPolicyKey as d, MONGOKIT_CAPABILITIES as f, isTransactionUnsupported as i, OP_REGISTRY as l, Repository as n, AggregationBuilder as o, createMongoPurgePort as p, batchTransaction as r, ALL_OPERATIONS as s, HOOK_PRIORITY$1 as t, READ_OPERATIONS as u };
+export { supportsTransactions as a, ALL_OPERATIONS as c, READ_OPERATIONS as d, operationsByPolicyKey as f, isTransactionUnsupported as i, MUTATING_OPERATIONS as l, createMongoPurgePort as m, Repository as n, withTransaction as o, MONGOKIT_CAPABILITIES as p, batchTransaction as r, AggregationBuilder as s, HOOK_PRIORITY$1 as t, OP_REGISTRY as u };

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-DLQ6pjal.mjs";
+import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-DceInCTX.mjs";
 export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };

package/dist/adapter/index.d.mts

@@ -59,7 +59,7 @@ interface MongooseAdapterOptions<TDoc = unknown> {
  * `@classytic/repo-core/adapter`.
  */
 declare class MongooseAdapter<TDoc = unknown> implements DataAdapter<TDoc> {
-  readonly type: 'mongoose';
+  readonly type: "mongoose";
   readonly name: string;
   readonly model: Model<TDoc>;
   readonly repository: RepositoryLike<TDoc>;

package/dist/adapter/index.mjs

@@ -1,2 +1,2 @@
-import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-BWgJ_Jdc.mjs";
+import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-CLvUHiTW.mjs";
 export { MongooseAdapter, createMongooseAdapter, isMongooseModel };

package/dist/{adapter-BWgJ_Jdc.mjs → adapter-CLvUHiTW.mjs}

@@ -1,5 +1,5 @@
 import { n as warn } from "./logger-K7dPmu2U.mjs";
-import { t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-CVnrKFDq.mjs";
+import { t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-CByt1VhQ.mjs";
 import { matchesRecordFilter } from "@classytic/repo-core/filter";
 import { mergeFieldRuleConstraints } from "@classytic/repo-core/schema";
 import { asRepositoryLike, isRepository } from "@classytic/repo-core/adapter";

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { G as Plugin } from "../types-BtMuhoX5.mjs";
+import { l as Plugin } from "../repository-DCHRWRXw.mjs";
 import { PipelineStage } from "mongoose";
 //#region src/ai/types.d.ts
 /** Supported similarity metrics for vector search */

package/dist/better-auth/index.mjs

@@ -1,5 +1,5 @@
-import { n as Repository } from "../Repository-ClOraFjT.mjs";
-import { n as createMongooseAdapter } from "../adapter-BWgJ_Jdc.mjs";
+import { n as Repository } from "../Repository-BFBTAMlA.mjs";
+import { n as createMongooseAdapter } from "../adapter-CLvUHiTW.mjs";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";
 //#region src/better-auth/index.ts
 /**

package/dist/core-62oo3N1C.d.mts

@@ -0,0 +1,50 @@
+import { Document, Model, PopulateOptions, Types } from "mongoose";
+//#region src/types/core.d.ts
+/**
+ * Core query/document primitives shared across every mongokit module —
+ * sort/select/populate/filter specs and the mongoose-facing aliases.
+ *
+ * Also the home of the `softRequired` Mongoose declaration merge (this file
+ * is loaded by every module, so the augmentation is always in the program).
+ */
+/**
+ * Global declaration merge: adds `softRequired` to Mongoose's SchemaTypeOptions
+ * so consumers can annotate paths type-safely without importing anything.
+ *
+ * A path with `softRequired: true` keeps its DB-level `required: true`
+ * invariant but is excluded from the auto-generated CRUD body `required[]`
+ * array (see buildCrudSchemasFromModel).
+ */
+declare module 'mongoose' {
+  interface SchemaTypeOptions<T, EnforcedDocType = any, THydratedDocumentType = HydratedDocument<EnforcedDocType>> {
+    /** mongokit: omit from auto-generated CRUD body `required` array. */
+    softRequired?: boolean;
+  }
+}
+/** Read Preference Type for replica sets */
+type ReadPreferenceType = 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest' | (string & {});
+/** Re-export mongoose ObjectId */
+type ObjectId = Types.ObjectId;
+/** Generic document type */
+type AnyDocument = Document & Record<string, unknown>;
+/** Generic model type */
+type AnyModel = Model<AnyDocument>;
+/** Sort direction */
+type SortDirection = 1 | -1;
+/** Sort specification for MongoDB queries */
+type SortSpec = Record<string, SortDirection>;
+/** Populate specification */
+type PopulateSpec = string | string[] | PopulateOptions | PopulateOptions[];
+/**
+ * Select specification. `readonly string[]` widens the legacy `string[]`
+ * form to also accept the immutable variant repo-core's contract uses
+ * (`LookupPopulateOptions.select: readonly string[] | Record<string, 0
+ * | 1>`), so `Repository<TDoc>` assigns to `StandardRepo<TDoc>` without
+ * TS2322 on the `select` field. Any existing mutable-array caller stays
+ * compatible — `string[]` is assignable to `readonly string[]`.
+ */
+type SelectSpec = string | readonly string[] | Record<string, 0 | 1>;
+/** Filter query type for MongoDB queries (compatible with Mongoose 8 & 9) */
+type FilterQuery<_T = unknown> = Record<string, unknown>;
+//#endregion
+export { PopulateSpec as a, SortDirection as c, ObjectId as i, SortSpec as l, AnyModel as n, ReadPreferenceType as o, FilterQuery as r, SelectSpec as s, AnyDocument as t };

package/dist/{create-repository-CVupgeRG.mjs → create-repository-2DMwkYVz.mjs}

@@ -1,5 +1,5 @@
-import { n as Repository } from "./Repository-ClOraFjT.mjs";
-import { a as methodRegistryPlugin, d as cachePlugin, f as batchOperationsPlugin, h as auditLogPlugin, i as multiTenantPlugin, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, t as timestampPlugin } from "./timestamp.plugin-BhSX0Lu_.mjs";
+import { n as Repository } from "./Repository-BFBTAMlA.mjs";
+import { a as methodRegistryPlugin, d as cachePlugin, f as batchOperationsPlugin, g as auditLogPlugin, i as multiTenantPlugin, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, t as timestampPlugin } from "./timestamp.plugin-ennbatTW.mjs";
 //#region src/create-repository.ts
 function isLoggerAudit(value) {
 	const v = value;

package/dist/{create-repository-Cn1LkvL7.d.mts → create-repository-D4ZU94b3.d.mts}

@@ -1,12 +1,16 @@
-import { At as LookupOptions, B as ObjectId, H as OperationOptions, J as PopulateSpec, M as LookupPopulateOptions, N as LookupPopulateResult, P as Middleware, Q as RepositoryContext, U as PaginationConfig, X as ReadOptions, Y as PrioritizedHook, Z as ReadPreferenceType, _ as DeleteManyResult, at as SessionOptions, c as CacheableOptions, d as CollationOptions, ft as UpdateManyResult, it as SelectSpec, j as Logger, kt as LookupBuilder, n as AggregatePaginationOptions, nt as RepositoryOptions, p as CreateOptions, pt as UpdateOptions, q as PluginType, st as SoftDeleteOptions, t as AggregateOptions, ut as SortSpec$1, v as DeleteResult, w as FindOneAndUpdateOptions, xt as WithTransactionOptions } from "./types-BtMuhoX5.mjs";
-import { _ as RepositoryCachePluginOptions, i as CustomIdOptions, t as MultiTenantOptions, w as AuditTrailOptions } from "./multi-tenant.plugin-BjXXuc_g.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-BnZ24ehC.mjs";
+import { _ as WithTransactionOptions, a as DeleteManyResult, f as OperationOptions, g as UpdateOptions, h as UpdateManyResult, i as CreateOptions, l as LookupPopulateOptions, m as SessionOptions, o as DeleteResult, p as ReadOptions, r as CacheableOptions, s as FindOneAndUpdateOptions, t as AggregateOptions, u as LookupPopulateResult, v as LookupBuilder, y as LookupOptions } from "./operations-C8IcCHF9.mjs";
+import { a as PopulateSpec, i as ObjectId, l as SortSpec$1, o as ReadPreferenceType, s as SelectSpec } from "./core-62oo3N1C.mjs";
+import { c as PaginationConfig, r as CollationOptions, t as AggregatePaginationOptions } from "./pagination-jSUdrACK.mjs";
+import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-DCHRWRXw.mjs";
+import { T as AuditTrailOptions, _ as RepositoryCachePluginOptions, i as CustomIdOptions, t as MultiTenantOptions } from "./multi-tenant.plugin-DVyVGREb.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CBS1XGzp.mjs";
+import { i as Logger, o as SoftDeleteOptions } from "./plugin-options-vFufQZMZ.mjs";
 import { AggPaginationRequest, AggRequest, AggResult, ArchiveOptions, ArchiveResult, ArchiveSink, ChangeEvent, FilterInput, KeysetAggPaginationResult, QueryOptions, RepoCapabilities, RepositoryBase, TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy, WatchOptions } from "@classytic/repo-core/repository";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 import { Filter } from "@classytic/repo-core/filter";
 import { UpdateInput } from "@classytic/repo-core/update";
-import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, OffsetPaginationResultCore } from "@classytic/repo-core/pagination";
 import { HttpError } from "@classytic/repo-core/errors";
+import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, OffsetPaginationResultCore } from "@classytic/repo-core/pagination";
 //#region src/query/AggregationBuilder.d.ts
 /** Options for $vectorSearch stage (Atlas only) */
 interface VectorSearchOptions {
@@ -1458,6 +1462,21 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * the port implementation.
    */
   purgeByField(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
+  /**
+   * Range/filter-scoped purge — see `StandardRepo.purgeByFilter` for the
+   * cross-kit contract. The compliance primitive for "purge/anonymize a
+   * slice across a RANGE while retaining measures" (redact a PII dimension
+   * across a `civilDate` window, hard-delete past a retention cutoff): the
+   * base predicate is an arbitrary compiled filter, not `field = value`.
+   *
+   * Composes the kit-agnostic `runChunkedPurge` orchestrator (loop, signal,
+   * progress, result envelope) with `createMongoPurgePortFromFilter` (the
+   * filter-bound sibling of `createMongoPurgePort`). Accepts Filter IR or a
+   * Mongo-shaped filter record — compiled once via `compileFilterToMongo`,
+   * the same dual-dialect rule as `archiveByFilter` and every other verb.
+   * See [actions/purge.ts](./actions/purge.ts) for the port.
+   */
+  purgeByFilter(filter: Record<string, unknown> | Filter, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
   /**
    * Chunked cold-storage extraction — see `StandardRepo.archiveByFilter`
    * for the cross-kit contract (write-before-delete, at-least-once,
@@ -1486,10 +1505,19 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * Routes through the hook system for policy enforcement
    * (multi-tenant, soft-delete).
    *
+   * The pipeline parameter also accepts `readonly unknown[]` (3.25.0):
+   * real-world stage arrays are assembled from exported fragment builders
+   * and spreads whose element type degrades to `unknown` — mongoose's
+   * `PipelineStage` union can't be satisfied without an `as` at every
+   * such call site. Runtime validation is MongoDB's job either way; the
+   * single documented widening lives HERE instead of N host-side casts
+   * (spine PACKAGE_RULES §7.1). Literal arrays still get full
+   * `PipelineStage` contextual checking via the first union member.
+   *
    * @param pipeline - MongoDB aggregation stage array
    * @param options  - Aggregation options including governance controls
    */
-  aggregatePipeline<TResult = unknown>(pipeline: PipelineStage[], options?: AggregateOptions): Promise<TResult[]>;
+  aggregatePipeline<TResult = unknown>(pipeline: PipelineStage[] | readonly unknown[], options?: AggregateOptions): Promise<TResult[]>;
   /**
    * Paginated kit-native aggregation pipeline. Same mongo-specific
    * scope as `aggregatePipeline` — reach for this when you need

package/dist/{id-resolution-P2OzcyRl.mjs → id-resolution-BqDrk0S2.mjs}

@@ -15,6 +15,17 @@ import mongoose from "mongoose";
 * Design: no `this`, no Model, no DB calls. Only reads `schema.paths._id.instance`.
 */
 /**
+* Null-tolerant `id → ObjectId` coercion — the single seam for optional
+* reference/audit-stamp fields (`approvedBy`, `submittedBy`, …) where an
+* absent actor is a legitimate `null`, not an error. Invalid non-empty
+* strings still throw (mongoose's own constructor validation) — this helper
+* only absorbs the absent case, never bad input. Hosts were hand-rolling
+* this identically at every approval-hook write; import it instead.
+*/
+function toObjectId(id) {
+	return id ? new mongoose.Types.ObjectId(id) : null;
+}
+/**
 * Check if a Mongoose SchemaType `instance` string is an ObjectId variant.
 * Mongoose 9.x uses `'ObjectId'`, older versions use `'ObjectID'`. This
 * is the single source of truth — use it instead of inline
@@ -103,4 +114,4 @@ function idVariants(id) {
 	return [id];
 }
 //#endregion
-export { isValidIdForType as i, idVariants as n, isObjectIdInstance as r, getSchemaIdType as t };
+export { toObjectId as a, isValidIdForType as i, idVariants as n, isObjectIdInstance as r, getSchemaIdType as t };

package/dist/{index-DLQ6pjal.d.mts → index-DceInCTX.d.mts}

@@ -1,4 +1,6 @@
-import { At as LookupOptions, B as ObjectId, H as OperationOptions, I as MinMaxResult, J as PopulateSpec, T as GroupResult, Z as ReadPreferenceType, ft as UpdateManyResult, ht as UpdateWithValidationResult, i as AnyDocument, it as SelectSpec, p as CreateOptions, pt as UpdateOptions, ut as SortSpec, v as DeleteResult, w as FindOneAndUpdateOptions } from "./types-BtMuhoX5.mjs";
+import { c as GroupResult, d as MinMaxResult, f as OperationOptions, g as UpdateOptions, h as UpdateManyResult, i as CreateOptions, o as DeleteResult, s as FindOneAndUpdateOptions, y as LookupOptions } from "./operations-C8IcCHF9.mjs";
+import { a as PopulateSpec, i as ObjectId, l as SortSpec, o as ReadPreferenceType, s as SelectSpec, t as AnyDocument } from "./core-62oo3N1C.mjs";
+import { p as UpdateWithValidationResult } from "./type-utils-CLzRFtIA.mjs";
 import { Model, PipelineStage } from "mongoose";
 declare namespace aggregate_d_exports {
   export { aggregate, aggregatePaginate, average, countBy, distinct, facet, groupBy, lookup, minMax, sum, unwind };