@classytic/mongokit 3.13.0 → 3.13.2

package/README.md

@@ -284,6 +284,58 @@ Each plugin is tree-shakeable. Import only what you use.
 
 ---
 
+## Composing with mongoose-level plugins
+
+mongokit deliberately doesn't reabsorb mongoose plugins that already work via `schema.plugin(...)`. They compose cleanly: the mongoose plugin attaches to the schema before the model lands at mongokit, both layers fire on every write.
+
+Canonical examples — install + wire as documented by the upstream package, then hand the model to mongokit:
+
+```ts
+import mongoose from 'mongoose';
+import { Repository, multiTenantPlugin } from '@classytic/mongokit';
+import timelineAuditPlugin from 'mongoose-timeline-audit';
+import slugPlugin from 'mongoose-slug-plugin';
+
+const orderSchema = new mongoose.Schema({
+  customerId: { type: mongoose.Schema.Types.ObjectId, ref: 'Customer' },
+  status: String,
+  title: String,
+});
+
+// 1. Wire mongoose-level plugins on the schema
+orderSchema.plugin(timelineAuditPlugin, {
+  ownerField: 'customerId',
+  eventLimits: { 'order.updated': 20 },
+});
+orderSchema.plugin(slugPlugin, { tmpl: '<%=title%>' });
+
+// 2. Build the model
+const Order = mongoose.model('Order', orderSchema);
+
+// 3. Hand the model to mongokit — kit plugins layer on top
+const orderRepo = new Repository(Order, [
+  multiTenantPlugin({ tenantField: 'organizationId' }),
+]);
+
+// Now every write fires BOTH layers:
+//   - mongoose pre('save') / post('save') (timeline-audit, slug)
+//   - mongokit before:create / after:create (multi-tenant, audit, cache)
+await orderRepo.create({ customerId, status: 'pending', title: 'New order' });
+```
+
+**Why this composition over absorbing into mongokit:** mongoose plugins hook `schema.add()` + `pre('save')`; mongokit plugins hook `before:create` / `after:update`. Different event models, different concerns. Wrapping a mongoose plugin as a mongokit plugin would be a fork, not a wrapper — and the mongoose plugin already works without mongokit being involved at all. Keeping the layers separate also lets each package version independently.
+
+**When to use which audit surface:**
+
+| Need | Reach for |
+|---|---|
+| Per-doc UX timeline visible to end users (`order.timeline = [{event, actor, at}, ...]`) | `mongoose-timeline-audit` (mongoose plugin) — embedded array on the doc |
+| Compliance audit ledger across models, immutable, queryable | `auditTrailPlugin` (mongokit, ships in this package) — separate collection |
+
+The two are complementary, not alternatives. A typical app wires both — timeline for the customer-facing order page, auditTrail for the compliance officer's quarterly export.
+
+---
+
 ## QueryParser (URL → filter)
 
 Turn Express / Fastify query strings into sanitized Mongo filters + sort + pagination.

package/dist/{Repository-BY40uhcv.mjs → Repository-DwJFh3XA.mjs}

@@ -1,4 +1,4 @@
-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-DLcSSa5b.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-C-3viiw1.mjs";
 import { n as warn } from "./logger-DprijP5h.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-B00pI7dV.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CfQRM1yz.mjs";
@@ -2934,8 +2934,11 @@ var Repository = class extends RepositoryBase {
 	* `context.filter`, which is merged into the pre-aggregate `$match`
 	* before compilation.
 	*/
-	async aggregate(req) {
-		const context = await this._buildContext("aggregate", { aggRequest: req });
+	async aggregate(req, options = {}) {
+		const context = await this._buildContext("aggregate", {
+			aggRequest: req,
+			...options
+		});
 		const cached = this._cachedValue(context);
 		if (cached !== void 0) {
 			await this._emitHook("after:aggregate", {
@@ -2988,8 +2991,11 @@ var Repository = class extends RepositoryBase {
 	*   `after`. Scales to arbitrary group counts because the planner
 	*   uses `(sort_keys) > (cursor)` instead of `OFFSET N`.
 	*/
-	async aggregatePaginate(req) {
-		const context = await this._buildContext("aggregatePaginate", { aggRequest: req });
+	async aggregatePaginate(req, options = {}) {
+		const context = await this._buildContext("aggregatePaginate", {
+			aggRequest: req,
+			...options
+		});
 		const limit = Math.max(1, Math.min(req.limit ?? 20, 1e3));
 		const session = context.session;
 		const useKeyset = isKeysetMode(req);

package/dist/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
-import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-DLcSSa5b.mjs";
+import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-C-3viiw1.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

package/dist/better-auth/index.mjs

@@ -1,4 +1,4 @@
-import { n as Repository } from "../Repository-BY40uhcv.mjs";
+import { n as Repository } from "../Repository-DwJFh3XA.mjs";
 import { n as createMongooseAdapter } from "../adapter-DTDMnUOH.mjs";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";
 //#region src/better-auth/index.ts

package/dist/index.d.mts

@@ -7,11 +7,34 @@ import { n as SchemaIndexes } from "./indexes-CgOF7Wjd.mjs";
 import { a as createFieldPreset, c as getMongooseProjection, d as parseDuplicateKeyError, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel, u as isDuplicateKeyError } from "./mongooseToJsonSchema-BgRAaXX-.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
-import { AggPaginationRequest, AggRequest, AggResult, KeysetAggPaginationResult, RepositoryBase } from "@classytic/repo-core/repository";
+import { AggPaginationRequest, AggRequest, AggResult, KeysetAggPaginationResult, QueryOptions, RepositoryBase } from "@classytic/repo-core/repository";
 import { UpdateInput } from "@classytic/repo-core/update";
 import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, OffsetPaginationResultCore } from "@classytic/repo-core/pagination";
 import { HttpError } from "@classytic/repo-core/errors";
 
+//#region src/filter/compile.d.ts
+/**
+ * Filter IR → MongoDB query compiler.
+ *
+ * Mirrors sqlitekit's `compileFilterToDrizzle`: takes a repo-core
+ * `Filter` tree and emits a MongoDB query object. Used by `groupBy` /
+ * `groupByPaginate` to translate the portable AggRequest's `filter`
+ * + `having` into `$match` stages.
+ *
+ * Scope: the same operator set sqlitekit supports (`eq`, `ne`, `gt`,
+ * `gte`, `lt`, `lte`, `in`, `nin`, `exists`, `like`, `regex`, `and`,
+ * `or`, `not`, `raw`). Anything else throws so we fail loud instead
+ * of silently dropping predicates.
+ *
+ * Why only this op set here and not everywhere in mongokit? Historic
+ * reason: mongokit pre-dates repo-core's Filter IR, so its existing
+ * policy plugins (multi-tenant, soft-delete) speak MongoDB query
+ * language directly. Converting mongokit's entire filter pipeline
+ * to Filter IR is out-of-scope for this change — we introduce the
+ * compiler only where the new portable `groupBy` IR needs it.
+ */
+declare function compileFilterToMongo(input: unknown): Record<string, unknown>;
+//#endregion
 //#region src/operations.d.ts
 /**
  * Where a plugin should inject its scoping filter (multi-tenant scope,
@@ -1616,7 +1639,7 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * `context.filter`, which is merged into the pre-aggregate `$match`
    * before compilation.
    */
-  aggregate<TRow extends Record<string, unknown> = Record<string, unknown>>(req: AggRequest): Promise<AggResult<TRow>>;
+  aggregate<TRow extends Record<string, unknown> = Record<string, unknown>>(req: AggRequest, options?: QueryOptions): Promise<AggResult<TRow>>;
   /**
    * Invalidate every aggregate-cache entry tagged with ANY of the
    * given tags. Delegates to the unified cache plugin's handle
@@ -1647,7 +1670,7 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    *   `after`. Scales to arbitrary group counts because the planner
    *   uses `(sort_keys) > (cursor)` instead of `OFFSET N`.
    */
-  aggregatePaginate<TRow extends Record<string, unknown> = Record<string, unknown>>(req: AggPaginationRequest): Promise<OffsetPaginationResultCore<TRow> | KeysetAggPaginationResult<TRow>>;
+  aggregatePaginate<TRow extends Record<string, unknown> = Record<string, unknown>>(req: AggPaginationRequest, options?: QueryOptions): Promise<OffsetPaginationResultCore<TRow> | KeysetAggPaginationResult<TRow>>;
   /**
    * Internal: the actual aggregate-paginate execution body. Extracted
    * so `aggregatePaginate` can wrap it in the cache layer without
@@ -2114,4 +2137,4 @@ declare function createOptionsExtractor<TCtx extends Record<string, unknown>>(fi
  */
 declare function createRepository<TDoc>(Model: _$mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 //#endregion
-export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BasePaginationOptions, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheOperationOptions, type CacheOptions, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CursorPayload, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, HOOK_PRIORITY, type HookMode, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type KeysOfType, type KeysetPaginationOptions, type LeaseMethods, type LeasePluginOptions, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MUTATING_OPERATIONS, type Middleware, type MiddlewareContext, type MinMaxResult, type MinimalRepoView, type MongoOperationsMethods, type MongoOperatorUpdate, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OperationDescriptor, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, type PrioritizedHook, QueryParser, type QueryParserOptions, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type UpdateManyResult, type UpdateOptions, type UpdatePatch, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidatorDefinition, type ValueType, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BasePaginationOptions, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheOperationOptions, type CacheOptions, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CursorPayload, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, HOOK_PRIORITY, type HookMode, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type KeysOfType, type KeysetPaginationOptions, type LeaseMethods, type LeasePluginOptions, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MUTATING_OPERATIONS, type Middleware, type MiddlewareContext, type MinMaxResult, type MinimalRepoView, type MongoOperationsMethods, type MongoOperatorUpdate, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OperationDescriptor, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, type PrioritizedHook, QueryParser, type QueryParserOptions, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type UpdateManyResult, type UpdateOptions, type UpdatePatch, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidatorDefinition, type ValueType, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };

package/dist/index.mjs

@@ -1,10 +1,10 @@
-import { b as LookupBuilder } from "./update-DLcSSa5b.mjs";
+import { b as LookupBuilder, x as compileFilterToMongo } from "./update-C-3viiw1.mjs";
 import { n as warn, t as configureLogger } from "./logger-DprijP5h.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-B00pI7dV.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-BY40uhcv.mjs";
+import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-DwJFh3XA.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CfQRM1yz.mjs";
-import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, f as adminBypass, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "./validation-chain.plugin-_-WuNml2.mjs";
+import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, f as adminBypass, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "./validation-chain.plugin-Pj2aD17U.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-Br3WPOEb.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
@@ -1224,4 +1224,4 @@ function createRepository(Model, plugins = [], paginationConfig = {}, options =
 }
 var src_default = Repository;
 //#endregion
-export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };

package/dist/lock/index.d.mts

@@ -0,0 +1,28 @@
+import { Connection } from "mongoose";
+import { BaseLockAdapterOptions, LockAdapter } from "@classytic/repo-core/lock";
+
+//#region src/lock/index.d.ts
+/** Adapter-construction options. */
+interface MongoLockAdapterOptions extends BaseLockAdapterOptions {
+  /**
+   * Mongoose connection. Defaults to `mongoose.connection` (the
+   * default global connection) — most apps connect once via
+   * `mongoose.connect()` and want every primitive to share that
+   * handle. Apps using a named connection
+   * (`mongoose.createConnection(...)`) pass it explicitly.
+   */
+  connection?: Connection;
+  /** Collection name. Default `mongo_locks`. */
+  collectionName?: string;
+  /** Override the Mongoose model name. Default `MongoLock`. */
+  modelName?: string;
+}
+/**
+ * Build a Mongo-backed lock adapter. Idempotent — the underlying
+ * model is registered once per `(connection, modelName)` pair, so
+ * calling this multiple times with the same options shares the same
+ * collection (no duplicate-model errors).
+ */
+declare function createMongoLockAdapter(options?: MongoLockAdapterOptions): LockAdapter;
+//#endregion
+export { MongoLockAdapterOptions, createMongoLockAdapter };

package/dist/lock/index.mjs

@@ -0,0 +1,92 @@
+import mongoose, { Schema } from "mongoose";
+//#region src/lock/index.ts
+/**
+* Build a Mongo-backed lock adapter. Idempotent — the underlying
+* model is registered once per `(connection, modelName)` pair, so
+* calling this multiple times with the same options shares the same
+* collection (no duplicate-model errors).
+*/
+function createMongoLockAdapter(options = {}) {
+	const { connection, collectionName = "mongo_locks", modelName = "MongoLock", defaultLeaseMs = 3e4 } = options;
+	const model = getOrCreateModel(connection ?? mongoose, modelName, collectionName);
+	return {
+		async tryAcquire(name, holderId, leaseMs) {
+			const ms = leaseMs > 0 ? leaseMs : defaultLeaseMs;
+			const now = /* @__PURE__ */ new Date();
+			const expiresAt = new Date(now.getTime() + ms);
+			try {
+				const result = await model.findOneAndUpdate({
+					_id: name,
+					$or: [{ expiresAt: { $lt: now } }, { holder: holderId }]
+				}, {
+					$set: {
+						holder: holderId,
+						expiresAt
+					},
+					$setOnInsert: { acquiredAt: now }
+				}, {
+					upsert: true,
+					returnDocument: "after",
+					setDefaultsOnInsert: true
+				}).lean();
+				return !!result && result.holder === holderId;
+			} catch (err) {
+				if (err?.code === 11e3) return false;
+				throw err;
+			}
+		},
+		async release(name, holderId) {
+			return !!await model.findOneAndDelete({
+				_id: name,
+				holder: holderId
+			}).lean();
+		},
+		async inspect(name) {
+			const doc = await model.findById(name).lean();
+			if (!doc) return null;
+			if (doc.expiresAt.getTime() <= Date.now()) return null;
+			return {
+				name,
+				holder: doc.holder,
+				expiresAt: doc.expiresAt,
+				acquiredAt: doc.acquiredAt
+			};
+		}
+	};
+}
+/**
+* Idempotent model registration. Mongoose throws OverwriteModelError
+* if `model('Name', schema)` is called twice with the same name on
+* the same connection — this guard makes the adapter safe to
+* construct multiple times in tests / hot-reload setups.
+*/
+function getOrCreateModel(conn, modelName, collectionName) {
+	const existing = "models" in conn ? conn.models[modelName] : void 0;
+	if (existing) return existing;
+	const schema = new Schema({
+		_id: {
+			type: String,
+			required: true
+		},
+		holder: {
+			type: String,
+			required: true
+		},
+		expiresAt: {
+			type: Date,
+			required: true
+		},
+		acquiredAt: {
+			type: Date,
+			required: true
+		}
+	}, {
+		versionKey: false,
+		timestamps: false,
+		_id: false
+	});
+	schema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+	return conn.model(modelName, schema, collectionName);
+}
+//#endregion
+export { createMongoLockAdapter };

package/dist/plugins/index.mjs

@@ -1,2 +1,2 @@
-import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "../validation-chain.plugin-_-WuNml2.mjs";
+import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "../validation-chain.plugin-Pj2aD17U.mjs";
 export { AuditTrailQuery, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/{update-DLcSSa5b.mjs → update-C-3viiw1.mjs}

@@ -13,9 +13,79 @@ import { isFilter } from "@classytic/repo-core/filter";
 * appropriately. This keeps the portable API ergonomic for apps that
 * write Mongo queries directly today.
 */
+/**
+* Operator shorthands arc propagates from bracket-syntax URL params.
+* Fastify parses `?createdAt[gte]=...&createdAt[lte]=...` into
+* `{ createdAt: { gte: '...', lte: '...' } }` — without `$` prefixes.
+* Arc intentionally forwards these as-is ("the kit's filter compiler
+* handles them"). This set covers every operator the arc aggregation
+* guard accepts in `parseDateRange` and `hasFilterOnField`.
+*/
+const SHORTHAND_OPS = new Set([
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"nin",
+	"exists",
+	"regex",
+	"mod"
+]);
+/** Range operators whose string values should be coerced to Date. */
+const RANGE_OPS = new Set([
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+]);
+/** ISO-8601 date-only or datetime string pattern. */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}/;
+/**
+* Coerce a string value to a Date when it looks like an ISO-8601 date.
+* Needed because MongoDB won't match a BSON Date field against a string
+* value even when using range operators — BSON type comparison treats
+* Date (type 9) and String (type 2) as distinct, so `{ createdAt: {
+* $gte: "2026-05-01" } }` never matches a Date-typed field.
+*/
+function tryCoerceDate(value) {
+	if (typeof value === "string" && ISO_DATE_RE.test(value)) {
+		const d = new Date(value);
+		return Number.isNaN(d.getTime()) ? value : d;
+	}
+	return value;
+}
+/**
+* Expand operator shorthand values in a plain Mongo-style query object.
+* Only expands nested objects whose keys are ALL in `SHORTHAND_OPS` — so
+* real nested documents (e.g. `address: { city: 'Dhaka' }`) pass through
+* unchanged, while `createdAt: { gte: '2026-04-01', lte: '2026-05-01' }`
+* becomes `createdAt: { $gte: Date(2026-04-01), $lte: Date(2026-05-01) }`.
+* String values on range operators are coerced to Date when they match the
+* ISO-8601 pattern, so BSON Date fields in MongoDB are compared correctly.
+*/
+function expandShorthands(obj) {
+	const out = {};
+	for (const [key, value] of Object.entries(obj)) {
+		if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+			const nested = value;
+			const keys = Object.keys(nested);
+			if (keys.length > 0 && keys.every((k) => !k.startsWith("$") && SHORTHAND_OPS.has(k))) {
+				const expanded = {};
+				for (const [op, opVal] of Object.entries(nested)) expanded[`$${op}`] = RANGE_OPS.has(op) ? tryCoerceDate(opVal) : opVal;
+				out[key] = expanded;
+				continue;
+			}
+		}
+		out[key] = value;
+	}
+	return out;
+}
 function compileFilterToMongo(input) {
 	if (!input) return {};
-	if (!isFilter(input)) return input;
+	if (!isFilter(input)) return expandShorthands(input);
 	return compile(input);
 }
 function compile(filter) {

package/dist/{validation-chain.plugin-_-WuNml2.mjs → validation-chain.plugin-Pj2aD17U.mjs}

@@ -1,7 +1,7 @@
-import { _ as upsert } from "./update-DLcSSa5b.mjs";
+import { _ as upsert } from "./update-C-3viiw1.mjs";
 import { n as warn } from "./logger-DprijP5h.mjs";
 import { t as createError } from "./error-B00pI7dV.mjs";
-import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-BY40uhcv.mjs";
+import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-DwJFh3XA.mjs";
 import { r as getFieldsForUser } from "./field-selection-Br3WPOEb.mjs";
 import mongoose from "mongoose";
 import { cachePlugin } from "@classytic/repo-core/cache";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.13.0",
+  "version": "3.13.2",
   "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
   "type": "module",
   "sideEffects": false,
@@ -40,6 +40,10 @@
       "types": "./dist/better-auth/index.d.mts",
       "default": "./dist/better-auth/index.mjs"
     },
+    "./lock": {
+      "types": "./dist/lock/index.d.mts",
+      "default": "./dist/lock/index.mjs"
+    },
     "./query/primitives/geo": {
       "types": "./dist/query/primitives/geo.d.mts",
       "default": "./dist/query/primitives/geo.mjs"