@classytic/mongokit 3.11.1 → 3.13.0

package/dist/{update-DEJYcgfV.mjs → update-DLcSSa5b.mjs}

@@ -1,6 +1,103 @@
 import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
-import { r as warn } from "./logger-DJ7egMnd.mjs";
+import { n as warn } from "./logger-DprijP5h.mjs";
 import { t as createError } from "./error-B00pI7dV.mjs";
+import { isFilter } from "@classytic/repo-core/filter";
+//#region src/filter/compile.ts
+/**
+* Compile a Filter IR node to a MongoDB query object. Returns `{}`
+* when the node is `TRUE` (or an empty `and`) so callers can merge
+* with other scopes without special-casing.
+*
+* The `input` is typed as `unknown` so callers can pass either a
+* Filter IR node or an already-built Mongo query and we dispatch
+* appropriately. This keeps the portable API ergonomic for apps that
+* write Mongo queries directly today.
+*/
+function compileFilterToMongo(input) {
+	if (!input) return {};
+	if (!isFilter(input)) return input;
+	return compile(input);
+}
+function compile(filter) {
+	switch (filter.op) {
+		case "true": return {};
+		case "false": return { $expr: false };
+		case "eq": return { [filter.field]: filter.value };
+		case "ne": return filter.value === null ? { [filter.field]: { $ne: null } } : { $and: [{ [filter.field]: { $ne: filter.value } }, { [filter.field]: { $ne: null } }] };
+		case "gt": return { [filter.field]: { $gt: filter.value } };
+		case "gte": return { [filter.field]: { $gte: filter.value } };
+		case "lt": return { [filter.field]: { $lt: filter.value } };
+		case "lte": return { [filter.field]: { $lte: filter.value } };
+		case "in":
+			if (filter.values.length === 0) return { $expr: false };
+			return { [filter.field]: { $in: [...filter.values] } };
+		case "nin":
+			if (filter.values.length === 0) return {};
+			return { [filter.field]: { $nin: [...filter.values] } };
+		case "exists": return filter.exists ? { [filter.field]: { $ne: null } } : { [filter.field]: null };
+		case "like": return { [filter.field]: likeToRegex(filter.pattern, filter.caseSensitivity) };
+		case "regex": return { [filter.field]: { $regex: filter.pattern } };
+		case "and": {
+			if (filter.children.length === 0) return {};
+			const parts = filter.children.map(compile);
+			if (parts.length === 1) return parts[0];
+			return { $and: parts };
+		}
+		case "or": {
+			if (filter.children.length === 0) return { $expr: false };
+			const parts = filter.children.map(compile);
+			if (parts.length === 1) return parts[0];
+			return { $or: parts };
+		}
+		case "not": return { $nor: [compile(filter.child)] };
+		case "raw": throw new Error("mongokit/filter: `raw` is a SQL escape hatch and has no safe MongoDB translation. Pass a Mongo query object directly to the filter slot instead.");
+	}
+}
+/**
+* Translate a SQL-style LIKE pattern to a MongoDB regex.
+*
+* SQL semantics:
+*   - `%`  → match zero or more characters (`.*`)
+*   - `_`  → match exactly one character   (`.`)
+*   - `\%` → literal percent  (escape via backslash)
+*   - `\_` → literal underscore
+*   - `\\` → literal backslash
+*   - everything else is literal — regex metacharacters get escaped.
+*
+* The naive implementation `pattern.replace(/%/g, '.*')` is wrong:
+* it also expands escaped `\%` into a wildcard. We walk the pattern
+* char-by-char, honoring backslash escapes, so `like('notes', '50\\% off')`
+* matches the literal string `50% off` instead of `50<anything> off`.
+*
+* Anchored with `^` / `$` so LIKE matches the whole field value, the
+* same way sqlitekit's `LIKE` semantically does.
+*/
+function likeToRegex(pattern, caseSensitivity) {
+	let out = "^";
+	for (let i = 0; i < pattern.length; i++) {
+		const ch = pattern[i];
+		if (ch === "\\" && i + 1 < pattern.length) {
+			const next = pattern[i + 1];
+			if (next === "%" || next === "_" || next === "\\") {
+				out += escapeRegexChar(next);
+				i++;
+				continue;
+			}
+		}
+		if (ch === "%") out += ".*";
+		else if (ch === "_") out += ".";
+		else out += escapeRegexChar(ch);
+	}
+	out += "$";
+	return caseSensitivity === "sensitive" ? { $regex: out } : {
+		$regex: out,
+		$options: "i"
+	};
+}
+function escapeRegexChar(ch) {
+	return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+//#endregion
 //#region src/query/LookupBuilder.ts
 /** Stages that are never valid inside a $lookup pipeline */
 const BLOCKED_PIPELINE_STAGES = [
@@ -191,28 +288,24 @@ var LookupBuilder = class LookupBuilder {
 			const builder = new LookupBuilder(lookup.from).localField(lookup.localField).foreignField(lookup.foreignField);
 			if (lookup.as) builder.as(lookup.as);
 			if (lookup.single) builder.single(lookup.single);
-			if (lookup.select) {
-				let projection;
-				if (typeof lookup.select === "string") {
-					projection = {};
-					for (const field of lookup.select.split(",").map((f) => f.trim())) if (field.startsWith("-")) projection[field.substring(1)] = 0;
-					else projection[field] = 1;
-				} else projection = lookup.select;
-				const joinStage = { $match: { $expr: { $eq: [`$${lookup.foreignField}`, "$$lookupJoinVal"] } } };
-				const existing = lookup.pipeline || [];
-				builder.pipeline([
-					joinStage,
-					...existing,
-					{ $project: projection }
-				]);
+			const stages = [];
+			const appendCallerStages = (raw) => {
+				if (raw.length === 0) return;
+				stages.push(...LookupBuilder.sanitizePipeline(raw));
+			};
+			const compiledWhere = lookup.where ? compileFilterToMongo(lookup.where) : void 0;
+			const hasWhere = !!compiledWhere && Object.keys(compiledWhere).length > 0;
+			if (!!(lookup.select || lookup.pipeline || hasWhere)) {
+				stages.push({ $match: { $expr: { $eq: [`$${lookup.foreignField}`, "$$lookupJoinVal"] } } });
+				if (hasWhere && compiledWhere) appendCallerStages([{ $match: compiledWhere }]);
+				if (lookup.pipeline) appendCallerStages(lookup.pipeline);
+				if (lookup.select) stages.push({ $project: compileSelectToProjection(lookup.select) });
+				builder.pipeline(stages);
 				builder.let({
 					lookupJoinVal: `$${lookup.localField}`,
 					...lookup.let || {}
 				});
 				builder.sanitize(false);
-			} else if (lookup.pipeline) {
-				builder.pipeline(lookup.pipeline);
-				if (lookup.let) builder.let(lookup.let);
 			} else if (lookup.let) builder.let(lookup.let);
 			return builder.build();
 		});
@@ -281,6 +374,38 @@ var LookupBuilder = class LookupBuilder {
 	}
 };
 /**
+* Normalize the three accepted `LookupOptions.select` shapes into a single
+* Mongo `$project` map.
+*
+*  - `string`              → CSV form, leading `-` excludes (`'name,-status'`)
+*  - `readonly string[]`   → array form, leading `-` excludes (`['-status']`)
+*  - `Record<string, 0|1>` → already a projection map, copied as-is
+*
+* The array form mirrors `repo-core`'s `LookupSpec.select` so cross-kit
+* callers (`select: ['name']`) compile identically on mongokit and sqlitekit.
+*/
+function compileSelectToProjection(select) {
+	if (typeof select === "string") {
+		const projection = {};
+		for (const field of select.split(",").map((f) => f.trim())) {
+			if (!field) continue;
+			if (field.startsWith("-")) projection[field.substring(1)] = 0;
+			else projection[field] = 1;
+		}
+		return projection;
+	}
+	if (Array.isArray(select)) {
+		const projection = {};
+		for (const field of select) {
+			if (!field) continue;
+			if (field.startsWith("-")) projection[field.substring(1)] = 0;
+			else projection[field] = 1;
+		}
+		return projection;
+	}
+	return { ...select };
+}
+/**
 * Performance Guidelines for $lookup at Scale:
 *
 * 1. **Index Requirements** (Critical for millions of records):
@@ -350,17 +475,17 @@ async function aggregatePaginate(Model, pipeline, options = {}) {
 	const skip = (page - 1) * limit;
 	if (limit > 1e3) warn(`[mongokit] Large aggregation limit (${limit}). $facet results must be <16MB. Consider using Repository.aggregatePaginate() for safer handling of large datasets.`);
 	const facetPipeline = [...pipeline, { $facet: {
-		docs: [{ $skip: skip }, { $limit: limit }],
+		data: [{ $skip: skip }, { $limit: limit }],
 		total: [{ $count: "count" }]
 	} }];
 	const aggregation = Model.aggregate(facetPipeline);
 	if (options.session) aggregation.session(options.session);
 	const [result] = await aggregation.exec();
-	const docs = result.docs || [];
+	const data = result.data || [];
 	const total = result.total[0]?.count || 0;
 	const pages = Math.ceil(total / limit);
 	return {
-		docs,
+		data,
 		total,
 		page,
 		limit,
@@ -537,54 +662,49 @@ var delete_exports = /* @__PURE__ */ __exportAll({
 	softDelete: () => softDelete
 });
 /**
-* Delete by ID
+* Delete by ID. Returns `null` on miss (matches `update()` convention) —
+* a second delete on the same id is a no-op, not an error.
 */
 async function deleteById(Model, id, options = {}) {
 	const query = {
 		_id: id,
 		...options.query
 	};
-	if (!await Model.findOneAndDelete(query).session(options.session ?? null)) return {
-		success: false,
-		message: "Document not found",
-		id: String(id)
-	};
+	if (!await Model.findOneAndDelete(query).session(options.session ?? null)) return null;
 	return {
-		success: true,
 		message: "Deleted successfully",
 		id: String(id)
 	};
 }
 /**
-* Delete many documents
+* Delete many documents. Always returns a {@link DeleteResult} (never
+* null) — a deleteMany with zero matches is a successful op with
+* `count: 0`, not a miss.
 */
 async function deleteMany(Model, query, options = {}) {
 	return {
-		success: true,
 		count: (await Model.deleteMany(query).session(options.session ?? null)).deletedCount,
 		message: "Deleted successfully"
 	};
 }
 /**
-* Delete by query
+* Delete by query. Returns `null` on miss unless `throwOnNotFound: true`.
 */
 async function deleteByQuery(Model, query, options = {}) {
 	const document = await Model.findOneAndDelete(query).session(options.session ?? null);
 	if (!document) {
 		if (options.throwOnNotFound === true) throw createError(404, "Document not found");
-		return {
-			success: false,
-			message: "Document not found"
-		};
+		return null;
 	}
 	return {
-		success: true,
 		message: "Deleted successfully",
 		id: String(document._id)
 	};
 }
 /**
-* Soft delete (set deleted flag)
+* Soft delete (set deleted flag). Returns `null` on miss for parity with
+* `deleteById`; callers that prefer a throw can wrap or use `throwOnNotFound`
+* pattern at the call site.
 */
 async function softDelete(Model, id, options = {}) {
 	if (!await Model.findByIdAndUpdate(id, {
@@ -594,16 +714,15 @@ async function softDelete(Model, id, options = {}) {
 	}, {
 		returnDocument: "after",
 		session: options.session
-	})) throw createError(404, "Document not found");
+	})) return null;
 	return {
-		success: true,
 		message: "Soft deleted successfully",
 		id: String(id),
 		soft: true
 	};
 }
 /**
-* Restore soft deleted document
+* Restore soft-deleted document. Returns `null` on miss.
 */
 async function restore(Model, id, options = {}) {
 	if (!await Model.findByIdAndUpdate(id, {
@@ -613,9 +732,8 @@ async function restore(Model, id, options = {}) {
 	}, {
 		returnDocument: "after",
 		session: options.session
-	})) throw createError(404, "Document not found");
+	})) return null;
 	return {
-		success: true,
 		message: "Restored successfully",
 		id: String(id)
 	};
@@ -709,16 +827,37 @@ async function getAll(Model, query = {}, options = {}) {
 	return mongoQuery.exec();
 }
 /**
-* Get or create document (upsert)
+* Get or create document (atomic upsert).
+*
+* Returns `{ doc, created }` so callers can disambiguate the two
+* outcomes without a follow-up read — load-bearing for race-detection
+* in idempotency stores, lock acquisition, and "ensure-exists" flows.
+*
+* `created: true` ⇔ this caller's `createData` won the race and was
+* just inserted; `created: false` ⇔ a doc matching `query` already
+* existed and was returned unchanged.
+*
+* Mongo: `includeResultMetadata: true` returns the raw `ModifyResult`
+* (`{ value, lastErrorObject, ok }`). `lastErrorObject.upserted` is
+* the `_id` of a freshly-inserted row — present iff this call inserted.
 */
 async function getOrCreate(Model, query, createData, options = {}) {
-	return Model.findOneAndUpdate(query, { $setOnInsert: createData }, {
+	const result = await Model.findOneAndUpdate(query, { $setOnInsert: createData }, {
 		upsert: true,
 		returnDocument: "after",
 		runValidators: true,
+		includeResultMetadata: true,
 		session: options.session,
 		...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
 	});
+	if (result && typeof result === "object" && "value" in result) return {
+		doc: result.value,
+		created: result.lastErrorObject?.upserted != null
+	};
+	return {
+		doc: result,
+		created: false
+	};
 }
 /**
 * Count documents matching query
@@ -918,4 +1057,4 @@ async function pullFromArray(Model, id, field, value, options = {}) {
 	return update(Model, id, { $pull: { [field]: value } }, options);
 }
 //#endregion
-export { upsert as _, count as a, LookupBuilder as b, getByQuery as c, deleteById as d, deleteByQuery as f, create_exports as g, createMany as h, update_exports as i, getOrCreate as l, create as m, update as n, exists as o, delete_exports as p, updateByQuery as r, getById as s, findOneAndUpdate as t, read_exports as u, aggregate_exports as v, distinct as y };
+export { upsert as _, count as a, LookupBuilder as b, getByQuery as c, deleteById as d, deleteByQuery as f, create_exports as g, createMany as h, update_exports as i, getOrCreate as l, create as m, update as n, exists as o, delete_exports as p, updateByQuery as r, getById as s, findOneAndUpdate as t, read_exports as u, aggregate_exports as v, compileFilterToMongo as x, distinct as y };

package/dist/utils/index.d.mts

@@ -1,94 +1,5 @@
-import { X as PopulateSpec, ft as SortSpec, ot as SelectSpec } from "../types-Dc2aDVUi.mjs";
-import { a as createFieldPreset, c as getMongooseProjection, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-DXxjFkLB.mjs";
+import { a as createFieldPreset, c as getMongooseProjection, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-BgRAaXX-.mjs";
 
-//#region src/utils/cache-keys.d.ts
-/**
- * Generate cache key for getById operations
- *
- * Includes select/populate/lean in the key so different query shapes
- * (e.g., plain vs populated, lean vs hydrated) never collide.
- *
- * Format: {prefix}:id:{model}:{documentId} (no options)
- * Format: {prefix}:id:{model}:{documentId}:{optionsHash} (with options)
- *
- * @example
- * byIdKey('mk', 'User', '507f1f77bcf86cd799439011')
- * // => 'mk:id:User:507f1f77bcf86cd799439011'
- * byIdKey('mk', 'User', '507f1f77bcf86cd799439011', { select: 'name email' })
- * // => 'mk:id:User:507f1f77bcf86cd799439011:a1b2c3d4'
- */
-declare function byIdKey(prefix: string, model: string, id: string, options?: {
-  select?: SelectSpec;
-  populate?: PopulateSpec;
-  lean?: boolean;
-}): string;
-/**
- * Generate cache key for single-document queries
- *
- * Format: {prefix}:one:{model}:{queryHash}
- *
- * @example
- * byQueryKey('mk', 'User', { email: 'john@example.com' })
- * // => 'mk:one:User:a1b2c3d4'
- */
-declare function byQueryKey(prefix: string, model: string, version: number, query: Record<string, unknown>, options?: {
-  select?: SelectSpec;
-  populate?: PopulateSpec;
-}): string;
-/**
- * Generate cache key for paginated list queries
- *
- * Format: {prefix}:list:{model}:{version}:{queryHash}
- *
- * The version component enables efficient bulk invalidation:
- * - On any mutation, bump the version
- * - All list cache keys become invalid without scanning/deleting each
- *
- * @example
- * listQueryKey('mk', 'User', 1, { filters: { status: 'active' }, page: 1, limit: 20 })
- * // => 'mk:list:User:1:e5f6g7h8'
- */
-declare function listQueryKey(prefix: string, model: string, version: number, params: {
-  filters?: Record<string, unknown>;
-  sort?: SortSpec;
-  page?: number;
-  limit?: number;
-  after?: string;
-  select?: SelectSpec;
-  populate?: PopulateSpec;
-  search?: string;
-  mode?: string;
-  lean?: boolean;
-  readPreference?: string;
-  hint?: string | Record<string, unknown>;
-  maxTimeMS?: number;
-  countStrategy?: string;
-}): string;
-/**
- * Generate cache key for collection version tag
- *
- * Format: {prefix}:ver:{model}
- *
- * Used to track mutation version for list invalidation
- */
-declare function versionKey(prefix: string, model: string): string;
-/**
- * Generate pattern for clearing all cache keys for a model
- *
- * Format: {prefix}:*:{model}:*
- *
- * @example
- * modelPattern('mk', 'User')
- * // => 'mk:*:User:*'
- */
-declare function modelPattern(prefix: string, model: string): string;
-/**
- * Generate pattern for clearing all list cache keys for a model
- *
- * Format: {prefix}:list:{model}:*
- */
-declare function listPattern(prefix: string, model: string): string;
-//#endregion
 //#region src/utils/id-resolution.d.ts
 /**
  * ID Resolution Primitive
@@ -146,4 +57,4 @@ declare function getSchemaIdType(schema?: SchemaLike | null): IdType;
  */
 declare function isValidIdForType(id: unknown, idType: IdType): boolean;
 //#endregion
-export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, listPattern, listQueryKey, modelPattern, versionKey };
+export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType };

package/dist/utils/index.mjs

@@ -1,6 +1,6 @@
-import { t as configureLogger } from "../logger-DJ7egMnd.mjs";
+import { t as configureLogger } from "../logger-DprijP5h.mjs";
 import { t as createError } from "../error-B00pI7dV.mjs";
-import { n as isObjectIdInstance, r as isValidIdForType, t as getSchemaIdType } from "../id-resolution-e4BT9zAV.mjs";
-import { a as byIdKey, c as listQueryKey, i as getMongooseProjection, l as modelPattern, n as filterResponseData, o as byQueryKey, r as getFieldsForUser, s as listPattern, t as createFieldPreset, u as versionKey } from "../field-selection-dI0m4RBs.mjs";
-import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-D1sdCOmj.mjs";
-export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, listPattern, listQueryKey, modelPattern, versionKey };
+import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "../field-selection-Br3WPOEb.mjs";
+import { n as isObjectIdInstance, r as isValidIdForType, t as getSchemaIdType } from "../id-resolution-B0Odvvou.mjs";
+import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-BYbG894y.mjs";
+export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType };