@classytic/mongokit 3.5.1 → 3.5.3

package/README.md

@@ -17,7 +17,7 @@
 - **Search governance** - Text index guard (throws `400` if no index), allowlisted sort/filter fields, ReDoS protection
 - **Vector search** - MongoDB Atlas `$vectorSearch` with auto-embedding and multimodal support
 - **TypeScript first** - Full type safety with discriminated unions, typed events, and field autocomplete
-- **1170+ passing tests** - Battle-tested and production-ready
+- **Extensively tested** — battle-tested and production-ready
 
 ## Installation
 
@@ -1423,6 +1423,25 @@ if (dupErr) {
 }
 ```
 
+## Custom ID Field
+
+Use `idField` when your documents use a custom identifier (slug, UUID, code) instead of `_id`:
+
+```typescript
+// Repo-level: all calls use slug
+const productRepo = new Repository(ProductModel, [], {}, { idField: 'slug' });
+await productRepo.getById('laptop');                  // { slug: 'laptop' }
+await productRepo.update('laptop', { price: 999 });   // { slug: 'laptop' }
+await productRepo.delete('laptop');                    // { slug: 'laptop' }
+
+// Per-call override: same repo, different lookups
+const repo = new Repository(ChatModel);
+await repo.getById('507f1f77bcf86cd799439011');              // by _id
+await repo.getById('my-chat-uuid', { idField: 'chatId' });  // by chatId
+```
+
+All plugins respect `idField`: soft-delete, cascade, audit-log, audit-trail, validation-chain, elastic, cache, observability.
+
 ## No Breaking Changes
 
 Extending Repository works exactly the same with Mongoose 8 and 9. The package:
@@ -1430,7 +1449,7 @@ Extending Repository works exactly the same with Mongoose 8 and 9. The package:
 - Uses its own event system (not Mongoose middleware)
 - Defines its own `FilterQuery` type (unaffected by Mongoose 9 rename)
 - Properly gates update pipelines (safe for Mongoose 9's stricter defaults)
-- All 1090+ tests pass on Mongoose 9
+- Full test suite passes on Mongoose 9
 
 ## License
 

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-BjXxDBgx.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-D3ydSXYC.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/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
-import { _ as aggregate_exports, f as delete_exports, h as create_exports, l as read_exports, r as update_exports } from "../update-DcWUpWBk.mjs";
+import { _ as aggregate_exports, f as delete_exports, h as create_exports, l as read_exports, r as update_exports } from "../update-AVfKWNGt.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { J as Plugin } from "../types-DK6ELT6o.mjs";
+import { J as Plugin } from "../types-wCkH8jE3.mjs";
 import { ClientSession, PipelineStage } from "mongoose";
 
 //#region src/ai/types.d.ts

package/dist/{index-BjXxDBgx.d.mts → index-D3ydSXYC.d.mts}

@@ -1,4 +1,4 @@
-import { $ as ReadPreferenceType, At as LookupOptions, D as GroupResult, V as ObjectId, W as OperationOptions, Z as PopulateSpec, _t as UpdateOptions, a as AnyDocument, b as DeleteResult, g as CreateOptions, gt as UpdateManyResult, pt as SortSpec, st as SelectSpec, vt as UpdateWithValidationResult, z as MinMaxResult } from "./types-DK6ELT6o.mjs";
+import { $ as ReadPreferenceType, At as LookupOptions, D as GroupResult, V as ObjectId, W as OperationOptions, Z as PopulateSpec, _t as UpdateOptions, a as AnyDocument, b as DeleteResult, g as CreateOptions, gt as UpdateManyResult, pt as SortSpec, st as SelectSpec, vt as UpdateWithValidationResult, z as MinMaxResult } from "./types-wCkH8jE3.mjs";
 import { ClientSession, Model, PipelineStage } from "mongoose";
 
 //#region src/actions/aggregate.d.ts

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { $ as ReadPreferenceType, A as InferDocument, At as LookupOptions, B as NonNullableFields, C as EventPayload, Ct as WithPlugins, D as GroupResult, Dt as IRequestContext, E as FieldRules, Et as IControllerResponse, F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, I as Logger, J as Plugin, K as PaginationResult, L as LookupPopulateOptions, M as JsonSchema, N as KeysOfType, O as HookMode, Ot as IResponseFormatter, P as KeysetPaginationOptions, Q as ReadOptions, R as LookupPopulateResult, S as EventHandlers, St as ValidatorDefinition, T as FieldPreset, Tt as IController, U as OffsetPaginationResult, V as ObjectId, W as OperationOptions, X as PluginType, Y as PluginFunction, Z as PopulateSpec, _ as CrudSchemas, _t as UpdateOptions, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SessionOptions, d as CacheableOptions, dt as SoftDeleteRepository, et as RepositoryContext, f as CascadeOptions, ft as SortDirection, g as CreateOptions, gt as UpdateManyResult, h as CreateInput, ht as UpdateInput, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupBuilder, l as CacheOptions, lt as SoftDeleteFilterMode, m as CollationOptions, mt as Strict, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SchemaBuilderOptions, p as CascadeRelation, pt as SortSpec, q as PartialBy, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SelectSpec, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteOptions, v as DecodedCursor, vt as UpdateWithValidationResult, w as EventPhase, wt as WithTransactionOptions, x as DocField, xt as ValidationResult, y as DeepPartial, yt as UserContext, z as MinMaxResult } from "./types-DK6ELT6o.mjs";
-import { t as index_d_exports } from "./index-BjXxDBgx.mjs";
+import { $ as ReadPreferenceType, A as InferDocument, At as LookupOptions, B as NonNullableFields, C as EventPayload, Ct as WithPlugins, D as GroupResult, Dt as IRequestContext, E as FieldRules, Et as IControllerResponse, F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, I as Logger, J as Plugin, K as PaginationResult, L as LookupPopulateOptions, M as JsonSchema, N as KeysOfType, O as HookMode, Ot as IResponseFormatter, P as KeysetPaginationOptions, Q as ReadOptions, R as LookupPopulateResult, S as EventHandlers, St as ValidatorDefinition, T as FieldPreset, Tt as IController, U as OffsetPaginationResult, V as ObjectId, W as OperationOptions, X as PluginType, Y as PluginFunction, Z as PopulateSpec, _ as CrudSchemas, _t as UpdateOptions, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SessionOptions, d as CacheableOptions, dt as SoftDeleteRepository, et as RepositoryContext, f as CascadeOptions, ft as SortDirection, g as CreateOptions, gt as UpdateManyResult, h as CreateInput, ht as UpdateInput, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupBuilder, l as CacheOptions, lt as SoftDeleteFilterMode, m as CollationOptions, mt as Strict, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SchemaBuilderOptions, p as CascadeRelation, pt as SortSpec, q as PartialBy, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SelectSpec, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteOptions, v as DecodedCursor, vt as UpdateWithValidationResult, w as EventPhase, wt as WithTransactionOptions, x as DocField, xt as ValidationResult, y as DeepPartial, yt as UserContext, z as MinMaxResult } from "./types-wCkH8jE3.mjs";
+import { t as index_d_exports } from "./index-D3ydSXYC.mjs";
 import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
-import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, R as BulkWriteResult, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, z as batchOperationsPlugin } from "./validation-chain.plugin-DISOoL9A.mjs";
-import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "./mongooseToJsonSchema-C78rAP7X.mjs";
+import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, R as BulkWriteResult, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, z as batchOperationsPlugin } from "./validation-chain.plugin-CGE_mKQr.mjs";
+import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "./mongooseToJsonSchema-BivI9LWt.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { a as warn, n as parseDuplicateKeyError, r as configureLogger, t as createError } from "./error-Bpbi_NKo.mjs";
-import { y as LookupBuilder } from "./update-DcWUpWBk.mjs";
+import { y as LookupBuilder } from "./update-AVfKWNGt.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-DCs-zKwZ.mjs";
-import { A as aggregateHelpersPlugin, C as HOOK_PRIORITY, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, T as AggregationBuilder, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, w as Repository, x as cascadePlugin, y as prefixedId } from "./validation-chain.plugin-DboBJfGs.mjs";
+import { A as aggregateHelpersPlugin, C as HOOK_PRIORITY, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, T as AggregationBuilder, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, w as Repository, x as cascadePlugin, y as prefixedId } from "./validation-chain.plugin-KjPV_6_N.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-reyDRzXf.mjs";
 import { a as isFieldUpdateAllowed, i as getSystemManagedFields, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-B6Qyl8BK.mjs";
 import mongoose from "mongoose";

package/dist/{mongooseToJsonSchema-C78rAP7X.d.mts → mongooseToJsonSchema-BivI9LWt.d.mts}

@@ -1,4 +1,4 @@
-import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-DK6ELT6o.mjs";
+import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-wCkH8jE3.mjs";
 import mongoose, { Schema } from "mongoose";
 
 //#region src/utils/error.d.ts

package/dist/pagination/PaginationEngine.d.mts

@@ -1,4 +1,4 @@
-import { F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, P as KeysetPaginationOptions, U as OffsetPaginationResult, a as AnyDocument, n as AggregatePaginationOptions, r as AggregatePaginationResult } from "../types-DK6ELT6o.mjs";
+import { F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, P as KeysetPaginationOptions, U as OffsetPaginationResult, a as AnyDocument, n as AggregatePaginationOptions, r as AggregatePaginationResult } from "../types-wCkH8jE3.mjs";
 import { Model } from "mongoose";
 
 //#region src/pagination/PaginationEngine.d.ts

package/dist/plugins/index.d.mts

@@ -1,2 +1,2 @@
-import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, y as MethodRegistryRepository, z as batchOperationsPlugin } from "../validation-chain.plugin-DISOoL9A.mjs";
+import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, y as MethodRegistryRepository, z as batchOperationsPlugin } from "../validation-chain.plugin-CGE_mKQr.mjs";
 export { type AggregateHelpersMethods, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type CacheMethods, type CustomIdOptions, type DateSequentialIdOptions, type ElasticSearchOptions, type IdGenerator, type MethodRegistryRepository, type MongoOperationsMethods, type MultiTenantOptions, type ObservabilityOptions, type OperationMetric, type PrefixedIdOptions, type SequentialIdOptions, type SoftDeleteMethods, type SubdocumentMethods, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/plugins/index.mjs

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

package/dist/{types-DK6ELT6o.d.mts → types-wCkH8jE3.d.mts}

@@ -684,6 +684,10 @@ type PaginationResult<T = unknown> = OffsetPaginationResult<T> | KeysetPaginatio
 interface SessionOptions {
   /** MongoDB session for transactions */
   session?: ClientSession;
+  /** Organization/tenant ID for multi-tenant plugin scoping */
+  organizationId?: string | ObjectId;
+  /** Extensible — plugins can read custom fields from options */
+  [key: string]: unknown;
 }
 /** Read options — session + readPreference for read-only operations */
 interface ReadOptions extends SessionOptions {

package/dist/{update-DcWUpWBk.mjs → update-AVfKWNGt.mjs}

@@ -279,6 +279,42 @@ var LookupBuilder = class LookupBuilder {
 		return sanitized;
 	}
 };
+/**
+* Performance Guidelines for $lookup at Scale:
+*
+* 1. **Index Requirements** (Critical for millions of records):
+*    - localField should be indexed on source collection
+*    - foreignField should be indexed on target collection (unique index preferred)
+*
+*    Example:
+*    ```typescript
+*    // Employee collection
+*    employeeSchema.index({ departmentSlug: 1 });
+*
+*    // Department collection
+*    departmentSchema.index({ slug: 1 }, { unique: true });
+*    ```
+*
+* 2. **Query Performance**:
+*    - With proper indexes: O(log n) per lookup
+*    - Without indexes: O(n * m) - AVOID THIS!
+*    - Use explain() to verify index usage: IXSCAN (good) vs COLLSCAN (bad)
+*
+* 3. **Pipeline Optimization**:
+*    - Place $match stages as early as possible
+*    - Use $project to reduce field size before lookups
+*    - Limit joined results with pipeline: [{ $match: {...} }, { $limit: n }]
+*
+* 4. **Memory Considerations**:
+*    - Each lookup creates a new field in memory
+*    - Use $project after lookup to remove unnecessary fields
+*    - Consider allowDiskUse: true for very large datasets
+*
+* 5. **Alternative Approaches**:
+*    - For 1:1 relationships with high read frequency: Consider storing ObjectId + slug
+*    - For read-heavy workloads: Consider caching or materialized views
+*    - For real-time dashboards: Consider separate aggregation collections
+*/
 //#endregion
 //#region src/actions/aggregate.ts
 var aggregate_exports = /* @__PURE__ */ __exportAll({

package/dist/utils/index.d.mts

@@ -1,5 +1,5 @@
-import { Z as PopulateSpec, pt as SortSpec, st as SelectSpec } from "../types-DK6ELT6o.mjs";
-import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "../mongooseToJsonSchema-C78rAP7X.mjs";
+import { Z as PopulateSpec, pt as SortSpec, st as SelectSpec } from "../types-wCkH8jE3.mjs";
+import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "../mongooseToJsonSchema-BivI9LWt.mjs";
 
 //#region src/utils/cache-keys.d.ts
 /**

package/dist/{validation-chain.plugin-DISOoL9A.d.mts → validation-chain.plugin-CGE_mKQr.d.mts}

@@ -1,4 +1,4 @@
-import { I as Logger, J as Plugin, St as ValidatorDefinition, T as FieldPreset, U as OffsetPaginationResult, V as ObjectId, Z as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, l as CacheOptions, nt as RepositoryInstance, pt as SortSpec, st as SelectSpec, u as CacheStats, ut as SoftDeleteOptions } from "./types-DK6ELT6o.mjs";
+import { I as Logger, J as Plugin, St as ValidatorDefinition, T as FieldPreset, U as OffsetPaginationResult, V as ObjectId, Z as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, l as CacheOptions, nt as RepositoryInstance, pt as SortSpec, st as SelectSpec, u as CacheStats, ut as SoftDeleteOptions } from "./types-wCkH8jE3.mjs";
 import mongoose, { ClientSession } from "mongoose";
 
 //#region src/plugins/aggregate-helpers.plugin.d.ts

package/dist/{validation-chain.plugin-DboBJfGs.mjs → validation-chain.plugin-KjPV_6_N.mjs}

@@ -1,5 +1,5 @@
 import { a as warn, i as debug, n as parseDuplicateKeyError, t as createError } from "./error-Bpbi_NKo.mjs";
-import { a as exists, c as getOrCreate, d as deleteByQuery, g as upsert, i as count, m as createMany, n as updateByQuery, o as getById, p as create, s as getByQuery, t as update, u as deleteById, v as distinct, y as LookupBuilder } from "./update-DcWUpWBk.mjs";
+import { a as exists, c as getOrCreate, d as deleteByQuery, g as upsert, i as count, m as createMany, n as updateByQuery, o as getById, p as create, s as getByQuery, t as update, u as deleteById, v as distinct, y as LookupBuilder } from "./update-AVfKWNGt.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-DCs-zKwZ.mjs";
 import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-reyDRzXf.mjs";
 import mongoose from "mongoose";
@@ -79,9 +79,10 @@ function auditLogPlugin(logger) {
 		name: "auditLog",
 		apply(repo) {
 			repo.on("after:create", ({ context, result }) => {
+				const idKey = repo.idField || "_id";
 				logger?.info?.("Document created", {
 					model: context.model || repo.model,
-					id: result?._id,
+					id: result?.[idKey],
 					userId: context.user?._id || context.user?.id,
 					organizationId: context.organizationId
 				});
@@ -89,7 +90,7 @@ function auditLogPlugin(logger) {
 			repo.on("after:update", ({ context, result }) => {
 				logger?.info?.("Document updated", {
 					model: context.model || repo.model,
-					id: context.id || result?._id,
+					id: context.id || result?.[repo.idField || "_id"],
 					userId: context.user?._id || context.user?.id,
 					organizationId: context.organizationId
 				});
@@ -282,10 +283,11 @@ function auditTrailPlugin(options = {}) {
 			const AuditModel = getAuditModel(collectionName, ttlDays);
 			if (opsSet.has("create")) repo.on("after:create", ({ context, result }) => {
 				const doc = toPlainObject(result);
+				const idKey = repo.idField || "_id";
 				writeAudit(AuditModel, {
 					model: context.model || repo.model,
 					operation: "create",
-					documentId: doc?._id,
+					documentId: doc?.[idKey],
 					userId: getUserId(context),
 					orgId: context.organizationId,
 					document: trackDocument ? sanitizeDoc(doc, excludeFields) : void 0,
@@ -313,7 +315,7 @@ function auditTrailPlugin(options = {}) {
 					writeAudit(AuditModel, {
 						model: context.model || repo.model,
 						operation: "update",
-						documentId: context.id || doc?._id,
+						documentId: context.id || doc?.[repo.idField || "_id"],
 						userId: getUserId(context),
 						orgId: context.organizationId,
 						changes,
@@ -1103,6 +1105,52 @@ var AggregationBuilder = class AggregationBuilder {
 		return new AggregationBuilder().match(query);
 	}
 };
+/**
+* Optimized Aggregation Patterns for Scale
+*
+* 1. **Early Filtering** - Always place $match as early as possible:
+*    ```typescript
+*    new AggregationBuilder()
+*      .match({ status: 'active' })  // ✅ Filter first
+*      .lookup(...)                  // Then join
+*      .sort(...)
+*    ```
+*
+* 2. **Index Usage** - Ensure indexes on:
+*    - Fields in $match
+*    - Fields in $sort (especially with $limit)
+*    - Fields in $lookup (both local and foreign)
+*
+* 3. **Projection** - Remove unnecessary fields early:
+*    ```typescript
+*    .project({ password: 0, internalNotes: 0 })  // Remove before joins
+*    .lookup(...)
+*    ```
+*
+* 4. **Faceted Pagination** - Get count and data in one query:
+*    ```typescript
+*    .facet({
+*      metadata: [{ $count: 'total' }],
+*      data: [{ $skip: skip }, { $limit: limit }]
+*    })
+*    ```
+*
+* 5. **allowDiskUse** - For large datasets:
+*    ```typescript
+*    new AggregationBuilder()
+*      .match({ status: 'active' })
+*      .allowDiskUse()
+*      .exec(Model)
+*    ```
+*
+* 6. **Vector Search** - Semantic similarity (Atlas only):
+*    ```typescript
+*    new AggregationBuilder()
+*      .vectorSearch({ index: 'vec_idx', path: 'embedding', queryVector: vec, limit: 10 })
+*      .withVectorScore()
+*      .exec(Model)
+*    ```
+*/
 //#endregion
 //#region src/Repository.ts
 function ensureLookupProjectionIncludesCursorFields(projection, sort) {
@@ -2383,6 +2431,34 @@ function cachePlugin(options) {
 				}
 			}, { priority: HOOK_PRIORITY.CACHE });
 			/**
+			* before:getOne - Same cache logic as getByQuery (single-doc)
+			*/
+			repo.on("before:getOne", async (context) => {
+				if (context.skipCache) return;
+				try {
+					const collectionVersion = await getVersion();
+					const query = context.query || {};
+					const key = byQueryKey(config.prefix, model, collectionVersion, query, {
+						select: context.select,
+						populate: context.populate
+					});
+					const cached = await config.adapter.get(key);
+					if (cached !== null && cached !== void 0) {
+						log(`Cache HIT for getOne: ${key}`);
+						stats.hits++;
+						context._cacheHit = true;
+						context._cachedResult = cached;
+					} else {
+						log(`Cache MISS for getOne: ${key}`);
+						stats.misses++;
+						context._cacheKey = key;
+					}
+				} catch (e) {
+					log(`Cache error for getOne:`, e);
+					stats.errors++;
+				}
+			}, { priority: HOOK_PRIORITY.CACHE });
+			/**
 			* before:getAll - Check cache for list query
 			* Runs at CACHE priority (200) — after policy hooks inject filters
 			*/
@@ -2478,6 +2554,25 @@ function cachePlugin(options) {
 				}
 			});
 			/**
+			* after:getOne - Cache the result (same as getByQuery)
+			*/
+			repo.on("after:getOne", async (payload) => {
+				const { context, result } = payload;
+				if (context._cacheHit || context.skipCache || result === null) return;
+				const collectionVersion = await getVersion();
+				const query = context.query || {};
+				const key = byQueryKey(config.prefix, model, collectionVersion, query, {
+					select: context.select,
+					populate: context.populate
+				});
+				try {
+					await config.adapter.set(key, result, context.cacheTtl ?? config.queryTtl);
+					stats.sets++;
+				} catch (e) {
+					log(`Failed to cache getOne:`, e);
+				}
+			});
+			/**
 			* after:getAll - Cache the result
 			*/
 			repo.on("after:getAll", async (payload) => {
@@ -2726,7 +2821,8 @@ function cascadePlugin(options) {
 			repo.on("before:deleteMany", async (context) => {
 				const query = context.query;
 				if (!query || Object.keys(query).length === 0) return;
-				context._cascadeIds = (await repo.Model.find(query, { _id: 1 }).lean().session(context.session ?? null)).map((doc) => doc._id);
+				const idField = repo.idField || "_id";
+				context._cascadeIds = (await repo.Model.find(query, { [idField]: 1 }).lean().session(context.session ?? null)).map((doc) => doc[idField]);
 			});
 			repo.on("after:deleteMany", async (payload) => {
 				const { context } = payload;
@@ -3093,17 +3189,18 @@ function elasticSearchPlugin(options) {
 					limit,
 					from
 				};
-				const mongoQuery = this.Model.find({ _id: { $in: ids } });
+				const mongoIdField = repo.idField || "_id";
+				const mongoQuery = this.Model.find({ [mongoIdField]: { $in: ids } });
 				if (searchOptions.mongoOptions?.select) mongoQuery.select(searchOptions.mongoOptions.select);
 				if (searchOptions.mongoOptions?.populate) mongoQuery.populate(searchOptions.mongoOptions.populate);
 				if (searchOptions.mongoOptions?.lean !== false) mongoQuery.lean();
 				return {
 					docs: (await mongoQuery.exec()).sort((a, b) => {
-						const aId = String(a._id);
-						const bId = String(b._id);
+						const aId = String(a[mongoIdField]);
+						const bId = String(b[mongoIdField]);
 						return (docsOrder.get(aId) ?? Number.MAX_SAFE_INTEGER) - (docsOrder.get(bId) ?? Number.MAX_SAFE_INTEGER);
 					}).map((doc) => {
-						const strId = String(doc._id);
+						const strId = String(doc[mongoIdField]);
 						if (searchOptions.mongoOptions?.lean !== false) return {
 							...doc,
 							_score: scores.get(strId)
@@ -3143,8 +3240,10 @@ function fieldFilterPlugin(fieldPreset) {
 				else context.select = presetSelect;
 			};
 			repo.on("before:getAll", applyFieldFiltering);
+			repo.on("before:findAll", applyFieldFiltering);
 			repo.on("before:getById", applyFieldFiltering);
 			repo.on("before:getByQuery", applyFieldFiltering);
+			repo.on("before:getOne", applyFieldFiltering);
 		}
 	};
 }
@@ -3430,12 +3529,14 @@ function multiTenantPlugin(options = {}) {
 	const { tenantField = "organizationId", contextKey = "organizationId", required = true, skipOperations = [], skipWhen, resolveContext } = options;
 	const filterOps = [
 		"getAll",
+		"findAll",
 		"aggregatePaginate",
 		"lookupPopulate"
 	];
 	const queryReadOps = [
 		"getById",
 		"getByQuery",
+		"getOne",
 		"count",
 		"exists",
 		"getOrCreate",
@@ -3528,7 +3629,14 @@ const DEFAULT_OPS = [
 	"delete",
 	"getById",
 	"getByQuery",
+	"getOne",
 	"getAll",
+	"findAll",
+	"getOrCreate",
+	"count",
+	"exists",
+	"distinct",
+	"aggregate",
 	"aggregatePaginate",
 	"lookupPopulate"
 ];
@@ -3683,7 +3791,7 @@ function softDeletePlugin(options = {}) {
 					context.softDeleted = true;
 				}
 			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:getAll", (context) => {
+			const injectDeleteFilterToFilters = (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
 					if (Object.keys(deleteFilter).length > 0) context.filters = {
@@ -3691,53 +3799,8 @@ function softDeletePlugin(options = {}) {
 						...deleteFilter
 					};
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:getById", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:getByQuery", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:count", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:exists", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:getOrCreate", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:distinct", (context) => {
+			};
+			const injectDeleteFilterToQuery = (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
 					if (Object.keys(deleteFilter).length > 0) context.query = {
@@ -3745,7 +3808,23 @@ function softDeletePlugin(options = {}) {
 						...deleteFilter
 					};
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
+			};
+			for (const op of [
+				"getAll",
+				"findAll",
+				"aggregatePaginate",
+				"lookupPopulate"
+			]) repo.on(`before:${op}`, injectDeleteFilterToFilters, { priority: HOOK_PRIORITY.POLICY });
+			for (const op of [
+				"getById",
+				"getOne",
+				"getByQuery",
+				"count",
+				"exists",
+				"getOrCreate",
+				"distinct",
+				"aggregate"
+			]) repo.on(`before:${op}`, injectDeleteFilterToQuery, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:updateMany", (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
@@ -4103,12 +4182,13 @@ function uniqueField(field, errorMessage) {
 				warn(`[mongokit] uniqueField('${field}'): getByQuery not available on repo, skipping uniqueness check`);
 				return;
 			}
+			const idKey = repo.idField || "_id";
 			const existing = await getByQuery.call(repo, query, {
-				select: "_id",
+				select: idKey,
 				lean: true,
 				throwOnNotFound: false
 			});
-			if (existing && String(existing._id) !== String(context.id)) throw createError(409, errorMessage || `${field} already exists`);
+			if (existing && String(existing[idKey]) !== String(context.id)) throw createError(409, errorMessage || `${field} already exists`);
 		}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.5.1",
+  "version": "3.5.3",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,