@classytic/mongokit 3.3.2 → 3.4.0

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
-- **700+ passing tests** - Battle-tested and production-ready
+- **940+ passing tests** - Battle-tested and production-ready
 
 ## Installation
 
@@ -210,7 +210,7 @@ const repo = new Repository(UserModel, [
 | `cascadePlugin(opts)`               | Auto-delete related documents                             |
 | `methodRegistryPlugin()`            | Dynamic method registration (required by plugins below)   |
 | `mongoOperationsPlugin()`           | Adds `increment`, `pushToArray`, `upsert`, etc.           |
-| `batchOperationsPlugin()`           | Adds `updateMany`, `deleteMany`                           |
+| `batchOperationsPlugin()`           | Adds `updateMany`, `deleteMany`, `bulkWrite`              |
 | `aggregateHelpersPlugin()`          | Adds `groupBy`, `sum`, `average`, etc.                    |
 | `subdocumentPlugin()`               | Manage subdocument arrays                                 |
 | `multiTenantPlugin(opts)`           | Auto-inject tenant isolation on all operations            |
@@ -223,14 +223,82 @@ const repo = new Repository(UserModel, [
 
 ```javascript
 const repo = new Repository(UserModel, [
+  methodRegistryPlugin(),
+  batchOperationsPlugin(),
   softDeletePlugin({ deletedField: "deletedAt" }),
 ]);
 
-await repo.delete(id); // Marks as deleted
+await repo.delete(id); // Marks as deleted (sets deletedAt)
 await repo.getAll(); // Excludes deleted
 await repo.getAll({ includeDeleted: true }); // Includes deleted
+
+// Batch operations respect soft-delete automatically
+await repo.deleteMany({ status: "draft" }); // Soft-deletes matching docs
+await repo.updateMany({ status: "active" }, { $set: { featured: true } }); // Skips soft-deleted
+```
+
+### Populate via URL (Array Refs + Field Selection)
+
+Populate arrays of ObjectIds with field selection, filtering, and sorting — all from URL query params:
+
+```bash
+# Populate all products in an order
+GET /orders?populate=products
+
+# Only name and price from each product
+GET /orders?populate[products][select]=name,price
+
+# Exclude fields
+GET /orders?populate[products][select]=-internalNotes,-cost
+
+# Filter: only active products
+GET /orders?populate[products][match][status]=active
+
+# Limit + sort populated items
+GET /orders?populate[products][limit]=5&populate[products][sort]=-price
+
+# Combined
+GET /orders?populate[products][select]=name,price&populate[products][match][status]=active&populate[products][limit]=10
 ```
 
+```typescript
+// Express route — 3 lines
+const parsed = parser.parse(req.query);
+const result = await orderRepo.getAll(
+  { filters: parsed.filters, sort: parsed.sort, limit: parsed.limit },
+  { populateOptions: parsed.populateOptions, populate: parsed.populate },
+);
+```
+
+### Lookup Joins via URL (No Refs Needed)
+
+Join collections by any field (slug, code, SKU) using `$lookup` — no `ref` in schema required. Faster than `populate` for non-ref joins.
+
+```bash
+# Join products with categories by slug
+GET /products?lookup[category][from]=categories&lookup[category][localField]=categorySlug&lookup[category][foreignField]=slug&lookup[category][single]=true
+
+# With field selection on joined collection (only bring name + slug)
+GET /products?lookup[category][...same]&lookup[category][select]=name,slug
+
+# Combined with filter + sort + root select
+GET /products?status=active&sort=-price&select=name,price,category&lookup[category][...same]&lookup[category][select]=name
+```
+
+```typescript
+// Express route — getAll auto-routes to $lookup when lookups are present
+const parsed = parser.parse(req.query);
+const result = await repo.getAll({
+  filters: parsed.filters,
+  sort: parsed.sort,
+  lookups: parsed.lookups,   // auto-routes to lookupPopulate
+  select: parsed.select,
+  limit: parsed.limit,
+});
+```
+
+> **Populate vs Lookup:** Use `populate` for `ref` fields (ObjectId arrays). Use `lookup` for joining by any field (slugs, codes, SKUs) — it runs a server-side `$lookup` aggregation, which is faster than client-side population for non-ref joins.
+
 ### Caching
 
 ```javascript
@@ -854,7 +922,46 @@ repo.on("error:create", ({ context, error }) => {
 });
 ```
 
-**Events:** `before:*`, `after:*`, `error:*` for `create`, `createMany`, `update`, `delete`, `getById`, `getByQuery`, `getAll`, `aggregatePaginate`
+**Events:** `before:*`, `after:*`, `error:*` for `create`, `createMany`, `update`, `delete`, `deleteMany`, `updateMany`, `getById`, `getByQuery`, `getAll`, `aggregatePaginate`
+
+### Microservice Integration (Kafka / RabbitMQ / Redis Pub-Sub)
+
+Use `after:*` hooks to publish events to message brokers — zero additional libraries needed:
+
+```typescript
+import { HOOK_PRIORITY } from "@classytic/mongokit";
+
+// Publish to Kafka after every create
+repo.on("after:create", async ({ context, result }) => {
+  await kafka.publish("orders.created", {
+    operation: context.operation,
+    model: context.model,
+    document: result,
+    userId: context.user?._id,
+    tenantId: context.organizationId,
+    timestamp: Date.now(),
+  });
+}, { priority: HOOK_PRIORITY.OBSERVABILITY });
+
+// Redis Pub-Sub on updates
+repo.on("after:update", async ({ context, result }) => {
+  await redis.publish("order:updated", JSON.stringify({
+    id: result._id,
+    changes: context.data,
+  }));
+}, { priority: HOOK_PRIORITY.OBSERVABILITY });
+
+// RabbitMQ on deletes (including soft-deletes)
+repo.on("after:delete", async ({ context, result }) => {
+  await rabbitMQ.sendToQueue("order.deleted", {
+    id: result.id,
+    soft: result.soft,
+    tenantId: context.organizationId,
+  });
+}, { priority: HOOK_PRIORITY.OBSERVABILITY });
+```
+
+**Hook priority order:** `POLICY (100)` → `CACHE (200)` → `OBSERVABILITY (300)` → `DEFAULT (500)`. Event publishing at `OBSERVABILITY` ensures it runs after policy enforcement and cache invalidation.
 
 ## Building REST APIs
 
@@ -1240,6 +1347,29 @@ const userRepo = createRepository(UserModel, [timestampPlugin()], {
 });
 ```
 
+## Error Handling
+
+MongoKit translates MongoDB and Mongoose errors into HTTP-compatible errors with proper status codes:
+
+| Error Type | Status | Example |
+|---|---|---|
+| Duplicate key (E11000) | **409** | `Duplicate value for email (email: "dup@test.com")` |
+| Validation error | **400** | `Validation Error: name is required` |
+| Cast error | **400** | `Invalid _id: not-a-valid-id` |
+| Document not found | **404** | `Document not found` |
+| Other errors | **500** | `Internal Server Error` |
+
+```typescript
+import { parseDuplicateKeyError } from "@classytic/mongokit";
+
+// Use in custom error handlers
+const dupErr = parseDuplicateKeyError(error);
+if (dupErr) {
+  // dupErr.status === 409
+  // dupErr.message includes field name and value
+}
+```
+
 ## No Breaking Changes
 
 Extending Repository works exactly the same with Mongoose 8 and 9. The package:
@@ -1247,7 +1377,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 700+ tests pass on Mongoose 9
+- All 940+ tests pass on Mongoose 9
 
 ## License
 

package/dist/{limits-s1-d8rWb.mjs → PaginationEngine-PLyDhrO7.mjs}

@@ -1,9 +1,9 @@
+import { a as warn, t as createError } from "./error-Bpbi_NKo.mjs";
 import mongoose from "mongoose";
-
 //#region src/pagination/utils/cursor.ts
 /**
 * Cursor Utilities
-* 
+*
 * Encoding and decoding of cursor tokens for keyset pagination.
 * Cursors are base64-encoded JSON containing position data and metadata.
 */
@@ -125,61 +125,6 @@ function rehydrateValue(serialized, type) {
 		default: return serialized;
 	}
 }
-
-//#endregion
-//#region src/pagination/utils/sort.ts
-/**
-* Normalizes sort object to ensure stable key order
-* Primary fields first, _id last (not alphabetical)
-*
-* @param sort - Sort specification
-* @returns Normalized sort with stable key order
-*/
-function normalizeSort(sort) {
-	const normalized = {};
-	Object.keys(sort).forEach((key) => {
-		if (key !== "_id") normalized[key] = sort[key];
-	});
-	if (sort._id !== void 0) normalized._id = sort._id;
-	return normalized;
-}
-/**
-* Validates and normalizes sort for keyset pagination
-* Auto-adds _id tie-breaker if needed
-* Ensures _id direction matches primary field
-*
-* @param sort - Sort specification
-* @returns Validated and normalized sort
-* @throws Error if sort is invalid for keyset pagination
-*/
-function validateKeysetSort(sort) {
-	const keys = Object.keys(sort);
-	if (keys.length === 1 && keys[0] !== "_id") {
-		const field = keys[0];
-		const direction = sort[field];
-		return normalizeSort({
-			[field]: direction,
-			_id: direction
-		});
-	}
-	if (keys.length === 1 && keys[0] === "_id") return normalizeSort(sort);
-	if (keys.length === 2) {
-		if (!keys.includes("_id")) throw new Error("Keyset pagination requires _id as tie-breaker");
-		if (sort[keys.find((k) => k !== "_id")] !== sort._id) throw new Error("_id direction must match primary field direction");
-		return normalizeSort(sort);
-	}
-	throw new Error("Keyset pagination only supports single field + _id");
-}
-/**
-* Extracts primary sort field (first non-_id field)
-*
-* @param sort - Sort specification
-* @returns Primary field name
-*/
-function getPrimaryField(sort) {
-	return Object.keys(sort).find((k) => k !== "_id") || "_id";
-}
-
 //#endregion
 //#region src/pagination/utils/filter.ts
 /**
@@ -232,7 +177,6 @@ function buildKeysetFilter(baseFilters, sort, cursorValue, cursorId) {
 		}]
 	};
 }
-
 //#endregion
 //#region src/pagination/utils/limits.ts
 /**
@@ -294,6 +238,262 @@ function calculateSkip(page, limit) {
 function calculateTotalPages(total, limit) {
 	return Math.ceil(total / limit);
 }
-
 //#endregion
-export { validatePage as a, validateKeysetSort as c, validateCursorSort as d, validateCursorVersion as f, validateLimit as i, decodeCursor as l, calculateTotalPages as n, buildKeysetFilter as o, shouldWarnDeepPagination as r, getPrimaryField as s, calculateSkip as t, encodeCursor as u };
+//#region src/pagination/utils/sort.ts
+/**
+* Normalizes sort object to ensure stable key order
+* Primary fields first, _id last (not alphabetical)
+*
+* @param sort - Sort specification
+* @returns Normalized sort with stable key order
+*/
+function normalizeSort(sort) {
+	const normalized = {};
+	Object.keys(sort).forEach((key) => {
+		if (key !== "_id") normalized[key] = sort[key];
+	});
+	if (sort._id !== void 0) normalized._id = sort._id;
+	return normalized;
+}
+/**
+* Validates and normalizes sort for keyset pagination
+* Auto-adds _id tie-breaker if needed
+* Ensures _id direction matches primary field
+*
+* @param sort - Sort specification
+* @returns Validated and normalized sort
+* @throws Error if sort is invalid for keyset pagination
+*/
+function validateKeysetSort(sort) {
+	const keys = Object.keys(sort);
+	if (keys.length === 1 && keys[0] !== "_id") {
+		const field = keys[0];
+		const direction = sort[field];
+		return normalizeSort({
+			[field]: direction,
+			_id: direction
+		});
+	}
+	if (keys.length === 1 && keys[0] === "_id") return normalizeSort(sort);
+	if (keys.length === 2) {
+		if (!keys.includes("_id")) throw new Error("Keyset pagination requires _id as tie-breaker");
+		if (sort[keys.find((k) => k !== "_id")] !== sort._id) throw new Error("_id direction must match primary field direction");
+		return normalizeSort(sort);
+	}
+	throw new Error("Keyset pagination only supports single field + _id");
+}
+/**
+* Extracts primary sort field (first non-_id field)
+*
+* @param sort - Sort specification
+* @returns Primary field name
+*/
+function getPrimaryField(sort) {
+	return Object.keys(sort).find((k) => k !== "_id") || "_id";
+}
+//#endregion
+//#region src/pagination/PaginationEngine.ts
+/**
+* Production-grade pagination engine for MongoDB
+* Supports offset, keyset (cursor), and aggregate pagination
+*/
+var PaginationEngine = class {
+	Model;
+	config;
+	/**
+	* Create a new pagination engine
+	*
+	* @param Model - Mongoose model to paginate
+	* @param config - Pagination configuration
+	*/
+	constructor(Model, config = {}) {
+		this.Model = Model;
+		this.config = {
+			defaultLimit: config.defaultLimit || 10,
+			maxLimit: config.maxLimit || 100,
+			maxPage: config.maxPage || 1e4,
+			deepPageThreshold: config.deepPageThreshold || 100,
+			cursorVersion: config.cursorVersion || 1,
+			useEstimatedCount: config.useEstimatedCount || false
+		};
+	}
+	/**
+	* Offset-based pagination using skip/limit
+	* Best for small datasets and when users need random page access
+	* O(n) performance - slower for deep pages
+	*
+	* @param options - Pagination options
+	* @returns Pagination result with total count
+	*
+	* @example
+	* const result = await engine.paginate({
+	*   filters: { status: 'active' },
+	*   sort: { createdAt: -1 },
+	*   page: 1,
+	*   limit: 20
+	* });
+	* console.log(result.docs, result.total, result.hasNext);
+	*/
+	async paginate(options = {}) {
+		const { filters = {}, sort = { _id: -1 }, page = 1, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, maxTimeMS, countStrategy = "exact", readPreference } = options;
+		const sanitizedPage = validatePage(page, this.config);
+		const sanitizedLimit = validateLimit(limit, this.config);
+		const skip = calculateSkip(sanitizedPage, sanitizedLimit);
+		const fetchLimit = countStrategy === "none" ? sanitizedLimit + 1 : sanitizedLimit;
+		let query = this.Model.find(filters);
+		if (select) query = query.select(select);
+		if (populate && (Array.isArray(populate) ? populate.length : populate)) query = query.populate(populate);
+		query = query.sort(sort).skip(skip).limit(fetchLimit).lean(lean);
+		if (session) query = query.session(session);
+		if (hint) query = query.hint(hint);
+		if (maxTimeMS) query = query.maxTimeMS(maxTimeMS);
+		if (readPreference) query = query.read(readPreference);
+		const hasFilters = Object.keys(filters).length > 0;
+		const useEstimated = this.config.useEstimatedCount && !hasFilters;
+		let countPromise;
+		if (countStrategy === "estimated" || useEstimated && countStrategy !== "exact") countPromise = this.Model.estimatedDocumentCount();
+		else if (countStrategy === "exact") {
+			const countQuery = this.Model.countDocuments(filters).session(session ?? null);
+			if (hint) countQuery.hint(hint);
+			if (maxTimeMS) countQuery.maxTimeMS(maxTimeMS);
+			if (readPreference) countQuery.read(readPreference);
+			countPromise = countQuery.exec();
+		} else countPromise = Promise.resolve(0);
+		const [docs, total] = await Promise.all([query.exec(), countPromise]);
+		const totalPages = countStrategy === "none" ? 0 : calculateTotalPages(total, sanitizedLimit);
+		let hasNext;
+		if (countStrategy === "none") {
+			hasNext = docs.length > sanitizedLimit;
+			if (hasNext) docs.pop();
+		} else hasNext = sanitizedPage < totalPages;
+		const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination (page ${sanitizedPage}). Consider getAll({ after, sort, limit }) for better performance.` : void 0;
+		return {
+			method: "offset",
+			docs,
+			page: sanitizedPage,
+			limit: sanitizedLimit,
+			total,
+			pages: totalPages,
+			hasNext,
+			hasPrev: sanitizedPage > 1,
+			...warning && { warning }
+		};
+	}
+	/**
+	* Keyset (cursor-based) pagination for high-performance streaming
+	* Best for large datasets, infinite scroll, real-time feeds
+	* O(1) performance - consistent speed regardless of position
+	*
+	* @param options - Pagination options (sort is required)
+	* @returns Pagination result with next cursor
+	*
+	* @example
+	* // First page
+	* const page1 = await engine.stream({
+	*   sort: { createdAt: -1 },
+	*   limit: 20
+	* });
+	*
+	* // Next page using cursor
+	* const page2 = await engine.stream({
+	*   sort: { createdAt: -1 },
+	*   after: page1.next,
+	*   limit: 20
+	* });
+	*/
+	async stream(options) {
+		const { filters = {}, sort, after, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, maxTimeMS, readPreference } = options;
+		if (!sort) throw createError(400, "sort is required for keyset pagination");
+		const sanitizedLimit = validateLimit(limit, this.config);
+		const normalizedSort = validateKeysetSort(sort);
+		const filterKeys = Object.keys(filters).filter((k) => !k.startsWith("$"));
+		const sortFields = Object.keys(normalizedSort);
+		if (filterKeys.length > 0 && sortFields.length > 0) {
+			const indexFields = [...filterKeys.map((f) => `${f}: 1`), ...sortFields.map((f) => `${f}: ${normalizedSort[f]}`)];
+			warn(`[mongokit] Keyset pagination with filters [${filterKeys.join(", ")}] and sort [${sortFields.join(", ")}] requires a compound index for O(1) performance. Ensure index exists: { ${indexFields.join(", ")} }`);
+		}
+		let query = { ...filters };
+		if (after) {
+			const cursor = decodeCursor(after);
+			validateCursorVersion(cursor.version, this.config.cursorVersion);
+			validateCursorSort(cursor.sort, normalizedSort);
+			query = buildKeysetFilter(query, normalizedSort, cursor.value, cursor.id);
+		}
+		let mongoQuery = this.Model.find(query);
+		if (select) mongoQuery = mongoQuery.select(select);
+		if (populate && (Array.isArray(populate) ? populate.length : populate)) mongoQuery = mongoQuery.populate(populate);
+		mongoQuery = mongoQuery.sort(normalizedSort).limit(sanitizedLimit + 1).lean(lean);
+		if (session) mongoQuery = mongoQuery.session(session);
+		if (hint) mongoQuery = mongoQuery.hint(hint);
+		if (maxTimeMS) mongoQuery = mongoQuery.maxTimeMS(maxTimeMS);
+		if (readPreference) mongoQuery = mongoQuery.read(readPreference);
+		const docs = await mongoQuery.exec();
+		const hasMore = docs.length > sanitizedLimit;
+		if (hasMore) docs.pop();
+		const primaryField = getPrimaryField(normalizedSort);
+		return {
+			method: "keyset",
+			docs,
+			limit: sanitizedLimit,
+			hasMore,
+			next: hasMore && docs.length > 0 ? encodeCursor(docs[docs.length - 1], primaryField, normalizedSort, this.config.cursorVersion) : null
+		};
+	}
+	/**
+	* Aggregate pipeline with pagination
+	* Best for complex queries requiring aggregation stages
+	* Uses $facet to combine results and count in single query
+	*
+	* @param options - Aggregation options
+	* @returns Pagination result with total count
+	*
+	* @example
+	* const result = await engine.aggregatePaginate({
+	*   pipeline: [
+	*     { $match: { status: 'active' } },
+	*     { $group: { _id: '$category', count: { $sum: 1 } } },
+	*     { $sort: { count: -1 } }
+	*   ],
+	*   page: 1,
+	*   limit: 20
+	* });
+	*/
+	async aggregatePaginate(options = {}) {
+		const { pipeline = [], page = 1, limit = this.config.defaultLimit, session, hint, maxTimeMS, countStrategy = "exact", readPreference } = options;
+		const sanitizedPage = validatePage(page, this.config);
+		const sanitizedLimit = validateLimit(limit, this.config);
+		const skip = calculateSkip(sanitizedPage, sanitizedLimit);
+		const fetchLimit = countStrategy === "none" ? sanitizedLimit + 1 : sanitizedLimit;
+		const facetStages = { docs: [{ $skip: skip }, { $limit: fetchLimit }] };
+		if (countStrategy !== "none") facetStages.total = [{ $count: "count" }];
+		const facetPipeline = [...pipeline, { $facet: facetStages }];
+		const aggregation = this.Model.aggregate(facetPipeline);
+		if (session) aggregation.session(session);
+		if (hint) aggregation.hint(hint);
+		if (maxTimeMS) aggregation.option({ maxTimeMS });
+		if (readPreference) aggregation.read(readPreference);
+		const [result] = await aggregation.exec();
+		const docs = result.docs;
+		const total = result.total?.[0]?.count || 0;
+		const totalPages = countStrategy === "none" ? 0 : calculateTotalPages(total, sanitizedLimit);
+		let hasNext;
+		if (countStrategy === "none") {
+			hasNext = docs.length > sanitizedLimit;
+			if (hasNext) docs.pop();
+		} else hasNext = sanitizedPage < totalPages;
+		const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination in aggregate (page ${sanitizedPage}). Uses $skip internally.` : void 0;
+		return {
+			method: "aggregate",
+			docs,
+			page: sanitizedPage,
+			limit: sanitizedLimit,
+			total,
+			pages: totalPages,
+			hasNext,
+			hasPrev: sanitizedPage > 1,
+			...warning && { warning }
+		};
+	}
+};
+//#endregion
+export { PaginationEngine as t };

package/dist/actions/index.d.mts

@@ -1,9 +1,2 @@
-import "../types-pVY0w1Pp.mjs";
-import { a as create_d_exports, i as read_d_exports, n as delete_d_exports, r as update_d_exports, t as aggregate_d_exports } from "../aggregate-BkOG9qwr.mjs";
-
-//#region src/actions/index.d.ts
-declare namespace index_d_exports {
-  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 };
-}
-//#endregion
-export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, index_d_exports as t, update_d_exports as update };
+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-Df3ernpC.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,6 +1,5 @@
-import { t as __exportAll } from "../chunk-DQk6qfdC.mjs";
-import { a as delete_exports, g as create_exports, p as read_exports, s as update_exports, t as aggregate_exports } from "../aggregate-BClp040M.mjs";
-
+import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
+import { c as read_exports, h as aggregate_exports, n as update_exports, p as create_exports, u as delete_exports } from "../update-DXwVh6M1.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,
@@ -9,6 +8,5 @@ var actions_exports = /* @__PURE__ */ __exportAll({
 	read: () => read_exports,
 	update: () => update_exports
 });
-
 //#endregion
-export { aggregate_exports as aggregate, create_exports as create, delete_exports as deleteActions, read_exports as read, actions_exports as t, update_exports as update };
+export { aggregate_exports as aggregate, create_exports as create, delete_exports as deleteActions, read_exports as read, actions_exports as t, update_exports as update };

package/dist/ai/index.d.mts

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

package/dist/ai/index.mjs

@@ -198,6 +198,5 @@ function vectorPlugin(options) {
 		}
 	};
 }
-
 //#endregion
-export { buildVectorSearchPipeline, vectorPlugin };
+export { buildVectorSearchPipeline, vectorPlugin };

package/dist/chunk-CfYAbeIz.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/{logger-D8ily-PP.mjs → error-Bpbi_NKo.mjs}

@@ -1,23 +1,3 @@
-//#region src/utils/error.ts
-/**
-* Creates an error with HTTP status code
-*
-* @param status - HTTP status code
-* @param message - Error message
-* @returns Error with status property
-* 
-* @example
-* throw createError(404, 'Document not found');
-* throw createError(400, 'Invalid input');
-* throw createError(403, 'Access denied');
-*/
-function createError(status, message) {
-	const error = new Error(message);
-	error.status = status;
-	return error;
-}
-
-//#endregion
 //#region src/utils/logger.ts
 const noop = () => {};
 let current = {
@@ -46,6 +26,38 @@ function warn(message, ...args) {
 function debug(message, ...args) {
 	current.debug(message, ...args);
 }
-
 //#endregion
-export { createError as i, debug as n, warn as r, configureLogger as t };
+//#region src/utils/error.ts
+/**
+* Creates an error with HTTP status code
+*
+* @param status - HTTP status code
+* @param message - Error message
+* @returns Error with status property
+*
+* @example
+* throw createError(404, 'Document not found');
+* throw createError(400, 'Invalid input');
+* throw createError(403, 'Access denied');
+*/
+function createError(status, message) {
+	const error = new Error(message);
+	error.status = status;
+	return error;
+}
+/**
+* Detect and convert a MongoDB E11000 duplicate-key error into
+* a 409 HttpError with an actionable message.
+*
+* Returns `null` when the error is not a duplicate-key error.
+*/
+function parseDuplicateKeyError(error) {
+	if (!error || typeof error !== "object") return null;
+	const mongoErr = error;
+	if (mongoErr.code !== 11e3) return null;
+	const fields = mongoErr.keyPattern ? Object.keys(mongoErr.keyPattern) : [];
+	const values = mongoErr.keyValue ? Object.entries(mongoErr.keyValue).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ") : "";
+	return createError(409, fields.length ? `Duplicate value for ${fields.join(", ")}${values ? ` (${values})` : ""}` : "Duplicate key error");
+}
+//#endregion
+export { warn as a, debug as i, parseDuplicateKeyError as n, configureLogger as r, createError as t };