@classytic/mongokit 3.2.0 → 3.2.2

package/dist/limits-DsNeCx4D.mjs

@@ -0,0 +1,299 @@
+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.
+*/
+/**
+* Encodes document values and sort metadata into a base64 cursor token
+*
+* @param doc - Document to extract cursor values from
+* @param primaryField - Primary sort field name
+* @param sort - Normalized sort specification
+* @param version - Cursor version for forward compatibility
+* @returns Base64-encoded cursor token
+*/
+function encodeCursor(doc, primaryField, sort, version = 1) {
+	const primaryValue = doc[primaryField];
+	const idValue = doc._id;
+	const payload = {
+		v: serializeValue(primaryValue),
+		t: getValueType(primaryValue),
+		id: serializeValue(idValue),
+		idType: getValueType(idValue),
+		sort,
+		ver: version
+	};
+	return Buffer.from(JSON.stringify(payload)).toString("base64");
+}
+/**
+* Decodes a cursor token back into document values and sort metadata
+*
+* @param token - Base64-encoded cursor token
+* @returns Decoded cursor data
+* @throws Error if token is invalid or malformed
+*/
+function decodeCursor(token) {
+	let json;
+	try {
+		json = Buffer.from(token, "base64").toString("utf-8");
+	} catch {
+		throw new Error("Invalid cursor token: not valid base64");
+	}
+	let payload;
+	try {
+		payload = JSON.parse(json);
+	} catch {
+		throw new Error("Invalid cursor token: not valid JSON");
+	}
+	if (!payload || typeof payload !== "object" || !("v" in payload) || !("t" in payload) || !("id" in payload) || !("idType" in payload) || !payload.sort || typeof payload.sort !== "object" || typeof payload.ver !== "number") throw new Error("Invalid cursor token: malformed payload structure");
+	const VALID_TYPES = [
+		"date",
+		"objectid",
+		"boolean",
+		"number",
+		"string",
+		"null",
+		"unknown"
+	];
+	if (!VALID_TYPES.includes(payload.t) || !VALID_TYPES.includes(payload.idType)) throw new Error("Invalid cursor token: unrecognized value type");
+	try {
+		return {
+			value: rehydrateValue(payload.v, payload.t),
+			id: rehydrateValue(payload.id, payload.idType),
+			sort: payload.sort,
+			version: payload.ver
+		};
+	} catch {
+		throw new Error("Invalid cursor token: failed to rehydrate values");
+	}
+}
+/**
+* Validates that cursor sort matches current query sort
+*
+* @param cursorSort - Sort specification from cursor
+* @param currentSort - Sort specification from query
+* @throws Error if sorts don't match
+*/
+function validateCursorSort(cursorSort, currentSort) {
+	if (JSON.stringify(cursorSort) !== JSON.stringify(currentSort)) throw new Error("Cursor sort does not match current query sort");
+}
+/**
+* Validates cursor version matches expected version
+*
+* @param cursorVersion - Version from cursor
+* @param expectedVersion - Expected version from config
+* @throws Error if versions don't match
+*/
+function validateCursorVersion(cursorVersion, expectedVersion) {
+	if (cursorVersion !== expectedVersion) throw new Error(`Cursor version ${cursorVersion} does not match expected version ${expectedVersion}`);
+}
+/**
+* Serializes a value for cursor storage
+*/
+function serializeValue(value) {
+	if (value === null || value === void 0) return null;
+	if (value instanceof Date) return value.toISOString();
+	if (value instanceof mongoose.Types.ObjectId) return value.toString();
+	return value;
+}
+/**
+* Gets the type identifier for a value
+*/
+function getValueType(value) {
+	if (value === null || value === void 0) return "null";
+	if (value instanceof Date) return "date";
+	if (value instanceof mongoose.Types.ObjectId) return "objectid";
+	if (typeof value === "boolean") return "boolean";
+	if (typeof value === "number") return "number";
+	if (typeof value === "string") return "string";
+	return "unknown";
+}
+/**
+* Rehydrates a serialized value back to its original type
+*/
+function rehydrateValue(serialized, type) {
+	if (type === "null" || serialized === null) return null;
+	switch (type) {
+		case "date": return new Date(serialized);
+		case "objectid": return new mongoose.Types.ObjectId(serialized);
+		case "boolean": return Boolean(serialized);
+		case "number": return Number(serialized);
+		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
+/**
+* Builds MongoDB filter for keyset pagination
+* Creates compound $or condition for proper cursor-based filtering
+*
+* @param baseFilters - Existing query filters
+* @param sort - Normalized sort specification
+* @param cursorValue - Primary field value from cursor
+* @param cursorId - _id value from cursor
+* @returns MongoDB filter with keyset condition
+*
+* @example
+* buildKeysetFilter(
+*   { status: 'active' },
+*   { createdAt: -1, _id: -1 },
+*   new Date('2024-01-01'),
+*   new ObjectId('...')
+* )
+* // Returns:
+* // {
+* //   status: 'active',
+* //   $or: [
+* //     { createdAt: { $lt: Date('2024-01-01') } },
+* //     { createdAt: Date('2024-01-01'), _id: { $lt: ObjectId('...') } }
+* //   ]
+* // }
+*/
+function buildKeysetFilter(baseFilters, sort, cursorValue, cursorId) {
+	const primaryField = Object.keys(sort).find((k) => k !== "_id") || "_id";
+	const direction = sort[primaryField];
+	const operator = direction === 1 ? "$gt" : "$lt";
+	if (cursorValue === null || cursorValue === void 0) if (direction === 1) return {
+		...baseFilters,
+		$or: [{
+			[primaryField]: null,
+			_id: { $gt: cursorId }
+		}, { [primaryField]: { $ne: null } }]
+	};
+	else return {
+		...baseFilters,
+		[primaryField]: null,
+		_id: { $lt: cursorId }
+	};
+	return {
+		...baseFilters,
+		$or: [{ [primaryField]: { [operator]: cursorValue } }, {
+			[primaryField]: cursorValue,
+			_id: { [operator]: cursorId }
+		}]
+	};
+}
+
+//#endregion
+//#region src/pagination/utils/limits.ts
+/**
+* Validates and sanitizes limit value
+* Parses strings to numbers and prevents NaN bugs
+*
+* @param limit - Requested limit
+* @param config - Pagination configuration
+* @returns Sanitized limit between 1 and maxLimit
+*/
+function validateLimit(limit, config) {
+	const parsed = Number(limit);
+	if (!Number.isFinite(parsed) || parsed < 1) return config.defaultLimit || 10;
+	return Math.min(Math.floor(parsed), config.maxLimit || 100);
+}
+/**
+* Validates and sanitizes page number
+* Parses strings to numbers and prevents NaN bugs
+*
+* @param page - Requested page (1-indexed)
+* @param config - Pagination configuration
+* @returns Sanitized page number >= 1
+* @throws Error if page exceeds maxPage
+*/
+function validatePage(page, config) {
+	const parsed = Number(page);
+	if (!Number.isFinite(parsed) || parsed < 1) return 1;
+	const sanitized = Math.floor(parsed);
+	if (sanitized > (config.maxPage || 1e4)) throw new Error(`Page ${sanitized} exceeds maximum ${config.maxPage || 1e4}`);
+	return sanitized;
+}
+/**
+* Checks if page number should trigger deep pagination warning
+*
+* @param page - Current page number
+* @param threshold - Warning threshold
+* @returns True if warning should be shown
+*/
+function shouldWarnDeepPagination(page, threshold) {
+	return page > threshold;
+}
+/**
+* Calculates number of documents to skip for offset pagination
+*
+* @param page - Page number (1-indexed)
+* @param limit - Documents per page
+* @returns Number of documents to skip
+*/
+function calculateSkip(page, limit) {
+	return (page - 1) * limit;
+}
+/**
+* Calculates total number of pages
+*
+* @param total - Total document count
+* @param limit - Documents per page
+* @returns Total number of pages
+*/
+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 };

package/dist/logger-D8ily-PP.mjs

@@ -0,0 +1,51 @@
+//#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 = {
+	warn: console.warn.bind(console),
+	debug: noop
+};
+/**
+* Configure the internal logger.
+* Pass `false` to silence all output.
+*/
+function configureLogger(config) {
+	if (config === false) current = {
+		warn: noop,
+		debug: noop
+	};
+	else current = {
+		...current,
+		...config
+	};
+}
+/** Emit a warning — security blocks, config issues, performance hints */
+function warn(message, ...args) {
+	current.warn(message, ...args);
+}
+/** Emit debug info — only visible when debug is enabled */
+function debug(message, ...args) {
+	current.debug(message, ...args);
+}
+
+//#endregion
+export { createError as i, debug as n, warn as r, configureLogger as t };

package/dist/mongooseToJsonSchema-COdDEkIJ.mjs

@@ -0,0 +1,317 @@
+import mongoose, { Schema } from "mongoose";
+
+//#region src/utils/memory-cache.ts
+/**
+* Creates an in-memory cache adapter
+* 
+* Features:
+* - Automatic TTL expiration
+* - Pattern-based clearing (simple glob with *)
+* - Max entries limit to prevent memory leaks
+* 
+* @param maxEntries - Maximum cache entries before oldest are evicted (default: 1000)
+*/
+function createMemoryCache(maxEntries = 1e3) {
+	const cache = /* @__PURE__ */ new Map();
+	let lastCleanup = Date.now();
+	const CLEANUP_INTERVAL_MS = 6e4;
+	function cleanupIfNeeded() {
+		const now = Date.now();
+		if (now - lastCleanup < CLEANUP_INTERVAL_MS) return;
+		lastCleanup = now;
+		for (const [key, entry] of cache) if (entry.expiresAt < now) cache.delete(key);
+	}
+	function evictOldest() {
+		while (cache.size >= maxEntries) {
+			const firstKey = cache.keys().next().value;
+			if (firstKey) cache.delete(firstKey);
+			else break;
+		}
+	}
+	return {
+		async get(key) {
+			const entry = cache.get(key);
+			if (!entry) return null;
+			if (entry.expiresAt < Date.now()) {
+				cache.delete(key);
+				return null;
+			}
+			cache.delete(key);
+			cache.set(key, entry);
+			return entry.value;
+		},
+		async set(key, value, ttl) {
+			cache.delete(key);
+			if (cache.size >= maxEntries) {
+				cleanupIfNeeded();
+				evictOldest();
+			}
+			cache.set(key, {
+				value,
+				expiresAt: Date.now() + ttl * 1e3
+			});
+		},
+		async del(key) {
+			cache.delete(key);
+		},
+		async clear(pattern) {
+			if (!pattern) {
+				cache.clear();
+				return;
+			}
+			const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+			const regex = new RegExp("^" + escaped + "$");
+			for (const key of cache.keys()) if (regex.test(key)) cache.delete(key);
+		}
+	};
+}
+
+//#endregion
+//#region src/utils/mongooseToJsonSchema.ts
+/**
+* Build CRUD schemas from Mongoose schema
+*/
+function buildCrudSchemasFromMongooseSchema(mongooseSchema, options = {}) {
+	const jsonCreate = buildJsonSchemaFromPaths(mongooseSchema, options);
+	return {
+		createBody: jsonCreate,
+		updateBody: buildJsonSchemaForUpdate(jsonCreate, options),
+		params: {
+			type: "object",
+			properties: { id: {
+				type: "string",
+				pattern: "^[0-9a-fA-F]{24}$"
+			} },
+			required: ["id"]
+		},
+		listQuery: buildJsonSchemaForQuery(mongooseSchema?.obj || {}, options)
+	};
+}
+/**
+* Build CRUD schemas from Mongoose model
+*/
+function buildCrudSchemasFromModel(mongooseModel, options = {}) {
+	if (!mongooseModel || !mongooseModel.schema) throw new Error("Invalid mongoose model");
+	return buildCrudSchemasFromMongooseSchema(mongooseModel.schema, options);
+}
+/**
+* Get fields that are immutable (cannot be updated)
+*/
+function getImmutableFields(options = {}) {
+	const immutable = [];
+	const fieldRules = options?.fieldRules || {};
+	Object.entries(fieldRules).forEach(([field, rules]) => {
+		if (rules.immutable || rules.immutableAfterCreate) immutable.push(field);
+	});
+	(options?.update?.omitFields || []).forEach((f) => {
+		if (!immutable.includes(f)) immutable.push(f);
+	});
+	return immutable;
+}
+/**
+* Get fields that are system-managed (cannot be set by users)
+*/
+function getSystemManagedFields(options = {}) {
+	const systemManaged = [];
+	const fieldRules = options?.fieldRules || {};
+	Object.entries(fieldRules).forEach(([field, rules]) => {
+		if (rules.systemManaged) systemManaged.push(field);
+	});
+	return systemManaged;
+}
+/**
+* Check if field is allowed in update
+*/
+function isFieldUpdateAllowed(fieldName, options = {}) {
+	const immutableFields = getImmutableFields(options);
+	const systemManagedFields = getSystemManagedFields(options);
+	return !immutableFields.includes(fieldName) && !systemManagedFields.includes(fieldName);
+}
+/**
+* Validate update body against field rules
+*/
+function validateUpdateBody(body = {}, options = {}) {
+	const violations = [];
+	const immutableFields = getImmutableFields(options);
+	const systemManagedFields = getSystemManagedFields(options);
+	Object.keys(body).forEach((field) => {
+		if (immutableFields.includes(field)) violations.push({
+			field,
+			reason: "Field is immutable"
+		});
+		else if (systemManagedFields.includes(field)) violations.push({
+			field,
+			reason: "Field is system-managed"
+		});
+	});
+	return {
+		valid: violations.length === 0,
+		violations
+	};
+}
+/**
+* Build JSON schema from Mongoose schema.paths (accurate type information)
+*/
+function buildJsonSchemaFromPaths(mongooseSchema, options) {
+	const properties = {};
+	const required = [];
+	const paths = mongooseSchema.paths;
+	const rootFields = /* @__PURE__ */ new Map();
+	for (const [path, schemaType] of Object.entries(paths)) {
+		if (path === "_id" || path === "__v") continue;
+		const rootField = path.split(".")[0];
+		if (!rootFields.has(rootField)) rootFields.set(rootField, []);
+		rootFields.get(rootField).push({
+			path,
+			schemaType
+		});
+	}
+	for (const [rootField, fieldPaths] of rootFields.entries()) if (fieldPaths.length === 1 && fieldPaths[0].path === rootField) {
+		const schemaType = fieldPaths[0].schemaType;
+		properties[rootField] = schemaTypeToJsonSchema(schemaType);
+		if (schemaType.isRequired) required.push(rootField);
+	} else {
+		const nestedSchema = buildNestedJsonSchema(fieldPaths, rootField);
+		properties[rootField] = nestedSchema.schema;
+		if (nestedSchema.required) required.push(rootField);
+	}
+	const schema = {
+		type: "object",
+		properties
+	};
+	if (required.length) schema.required = required;
+	const fieldsToOmit = new Set([
+		"createdAt",
+		"updatedAt",
+		"__v"
+	]);
+	(options?.create?.omitFields || []).forEach((f) => fieldsToOmit.add(f));
+	const fieldRules = options?.fieldRules || {};
+	Object.entries(fieldRules).forEach(([field, rules]) => {
+		if (rules.systemManaged) fieldsToOmit.add(field);
+	});
+	fieldsToOmit.forEach((field) => {
+		if (schema.properties?.[field]) delete schema.properties[field];
+		if (schema.required) schema.required = schema.required.filter((k) => k !== field);
+	});
+	const reqOv = options?.create?.requiredOverrides || {};
+	const optOv = options?.create?.optionalOverrides || {};
+	schema.required = schema.required || [];
+	for (const [k, v] of Object.entries(reqOv)) if (v && !schema.required.includes(k)) schema.required.push(k);
+	for (const [k, v] of Object.entries(optOv)) if (v && schema.required) schema.required = schema.required.filter((x) => x !== k);
+	Object.entries(fieldRules).forEach(([field, rules]) => {
+		if (rules.optional && schema.required) schema.required = schema.required.filter((x) => x !== field);
+	});
+	const schemaOverrides = options?.create?.schemaOverrides || {};
+	for (const [k, override] of Object.entries(schemaOverrides)) if (schema.properties?.[k]) schema.properties[k] = override;
+	if (options?.strictAdditionalProperties === true) schema.additionalProperties = false;
+	return schema;
+}
+/**
+* Build nested JSON schema from dot-notation paths
+*/
+function buildNestedJsonSchema(fieldPaths, rootField) {
+	const properties = {};
+	const required = [];
+	let hasRequiredFields = false;
+	for (const { path, schemaType } of fieldPaths) {
+		const parts = path.substring(rootField.length + 1).split(".");
+		if (parts.length === 1) {
+			properties[parts[0]] = schemaTypeToJsonSchema(schemaType);
+			if (schemaType.isRequired) {
+				required.push(parts[0]);
+				hasRequiredFields = true;
+			}
+		} else {
+			const fieldName = parts[0];
+			if (!properties[fieldName]) properties[fieldName] = {
+				type: "object",
+				properties: {}
+			};
+			const nestedObj = properties[fieldName];
+			if (!nestedObj.properties) nestedObj.properties = {};
+			const deepPath = parts.slice(1).join(".");
+			nestedObj.properties[deepPath] = schemaTypeToJsonSchema(schemaType);
+		}
+	}
+	const schema = {
+		type: "object",
+		properties
+	};
+	if (required.length) schema.required = required;
+	return {
+		schema,
+		required: hasRequiredFields
+	};
+}
+/**
+* Convert Mongoose SchemaType to JSON Schema
+*/
+function schemaTypeToJsonSchema(schemaType) {
+	const result = {};
+	const instance = schemaType.instance;
+	const options = schemaType.options || {};
+	if (instance === "String") {
+		result.type = "string";
+		if (typeof options.minlength === "number") result.minLength = options.minlength;
+		if (typeof options.maxlength === "number") result.maxLength = options.maxlength;
+		if (options.match instanceof RegExp) result.pattern = options.match.source;
+		if (options.enum && Array.isArray(options.enum)) result.enum = options.enum;
+	} else if (instance === "Number") {
+		result.type = "number";
+		if (typeof options.min === "number") result.minimum = options.min;
+		if (typeof options.max === "number") result.maximum = options.max;
+	} else if (instance === "Boolean") result.type = "boolean";
+	else if (instance === "Date") {
+		result.type = "string";
+		result.format = "date-time";
+	} else if (instance === "ObjectId" || instance === "ObjectID") {
+		result.type = "string";
+		result.pattern = "^[0-9a-fA-F]{24}$";
+	} else if (instance === "Array") {
+		result.type = "array";
+		result.items = { type: "string" };
+	} else {
+		result.type = "object";
+		result.additionalProperties = true;
+	}
+	return result;
+}
+function buildJsonSchemaForUpdate(createJson, options) {
+	const clone = JSON.parse(JSON.stringify(createJson));
+	delete clone.required;
+	const fieldsToOmit = /* @__PURE__ */ new Set();
+	(options?.update?.omitFields || []).forEach((f) => fieldsToOmit.add(f));
+	const fieldRules = options?.fieldRules || {};
+	Object.entries(fieldRules).forEach(([field, rules]) => {
+		if (rules.immutable || rules.immutableAfterCreate) fieldsToOmit.add(field);
+	});
+	fieldsToOmit.forEach((field) => {
+		if (clone.properties?.[field]) delete clone.properties[field];
+	});
+	if (options?.strictAdditionalProperties === true) clone.additionalProperties = false;
+	if (options?.update?.requireAtLeastOne === true) clone.minProperties = 1;
+	return clone;
+}
+function buildJsonSchemaForQuery(_tree, options) {
+	const basePagination = {
+		type: "object",
+		properties: {
+			page: { type: "string" },
+			limit: { type: "string" },
+			sort: { type: "string" },
+			populate: { type: "string" },
+			search: { type: "string" },
+			select: { type: "string" },
+			lean: { type: "string" },
+			includeDeleted: { type: "string" }
+		},
+		additionalProperties: true
+	};
+	const filterable = options?.query?.filterableFields || {};
+	for (const [k, v] of Object.entries(filterable)) if (basePagination.properties) basePagination.properties[k] = v && typeof v === "object" && "type" in v ? v : { type: "string" };
+	return basePagination;
+}
+
+//#endregion
+export { isFieldUpdateAllowed as a, getSystemManagedFields as i, buildCrudSchemasFromMongooseSchema as n, validateUpdateBody as o, getImmutableFields as r, createMemoryCache as s, buildCrudSchemasFromModel as t };