@classytic/mongokit 3.5.1 → 3.5.2

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.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/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-vxvcv1dg.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/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-vxvcv1dg.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/{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/{validation-chain.plugin-DboBJfGs.mjs → validation-chain.plugin-vxvcv1dg.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) {
@@ -2726,7 +2774,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 +3142,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)
@@ -4103,12 +4153,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.2",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,