@classytic/mongokit 3.2.0 → 3.2.2

package/dist/{mongooseToJsonSchema-CaRF_bCN.d.ts → mongooseToJsonSchema-Wbvjfwkn.d.mts}

@@ -1,27 +1,7 @@
-import { z as UserContext, Q as FieldPreset, H as HttpError, a7 as CacheAdapter, X as SchemaBuilderOptions, Z as CrudSchemas, V as ValidationResult } from './types-Jni1KgkP.js';
-import mongoose__default, { Schema } from 'mongoose';
-
-/**
- * Field Selection Utilities
- *
- * Provides explicit, performant field filtering using Mongoose projections.
- *
- * Philosophy:
- * - Explicit is better than implicit
- * - Filter at DB level (10x faster than in-memory)
- * - Progressive disclosure (show more fields as trust increases)
- *
- * @example
- * ```typescript
- * // For Mongoose queries (PREFERRED - 90% of cases)
- * const projection = getMongooseProjection(request.user, fieldPresets.gymPlans);
- * const plans = await GymPlan.find().select(projection).lean();
- *
- * // For complex data (10% of cases - aggregations, multiple sources)
- * const filtered = filterResponseData(complexData, fieldPresets.gymPlans, request.user);
- * ```
- */
+import { $ as SchemaBuilderOptions, T as HttpError, dt as UserContext, m as CrudSchemas, o as CacheAdapter, pt as ValidationResult, x as FieldPreset } from "./types-D-gploPr.mjs";
+import mongoose, { Schema } from "mongoose";
 
+//#region src/utils/field-selection.d.ts
 /**
  * Get allowed fields for a user based on their context
  *
@@ -88,13 +68,8 @@ declare function filterResponseData<T extends Record<string, unknown>>(data: T |
  * });
  */
 declare function createFieldPreset(config: Partial<FieldPreset>): FieldPreset;
-
-/**
- * Error Utilities
- *
- * HTTP-compatible error creation for repository operations
- */
-
+//#endregion
+//#region src/utils/error.d.ts
 /**
  * Creates an error with HTTP status code
  *
@@ -108,7 +83,8 @@ declare function createFieldPreset(config: Partial<FieldPreset>): FieldPreset;
  * throw createError(403, 'Access denied');
  */
 declare function createError(status: number, message: string): HttpError;
-
+//#endregion
+//#region src/utils/logger.d.ts
 /**
  * Internal Logger
  *
@@ -131,34 +107,16 @@ declare function createError(status: number, message: string): HttpError;
  */
 type LogFn = (message: string, ...args: unknown[]) => void;
 interface LoggerConfig {
-    warn: LogFn;
-    debug: LogFn;
+  warn: LogFn;
+  debug: LogFn;
 }
 /**
  * Configure the internal logger.
  * Pass `false` to silence all output.
  */
 declare function configureLogger(config: Partial<LoggerConfig> | false): void;
-
-/**
- * In-Memory Cache Adapter
- *
- * Simple cache adapter for development and testing.
- * NOT recommended for production - use Redis or similar.
- *
- * @example
- * ```typescript
- * import { cachePlugin, createMemoryCache } from '@classytic/mongokit';
- *
- * const repo = new Repository(UserModel, [
- *   cachePlugin({
- *     adapter: createMemoryCache(),
- *     ttl: 60,
- *   })
- * ]);
- * ```
- */
-
+//#endregion
+//#region src/utils/memory-cache.d.ts
 /**
  * Creates an in-memory cache adapter
  *
@@ -170,39 +128,8 @@ declare function configureLogger(config: Partial<LoggerConfig> | false): void;
  * @param maxEntries - Maximum cache entries before oldest are evicted (default: 1000)
  */
 declare function createMemoryCache(maxEntries?: number): CacheAdapter;
-
-/**
- * Mongoose to JSON Schema Converter with Field Rules
- *
- * Generates Fastify JSON schemas from Mongoose models with declarative field rules.
- *
- * Field Rules (options.fieldRules):
- * - immutable: Field cannot be updated (omitted from update schema)
- * - immutableAfterCreate: Alias for immutable
- * - systemManaged: System-only field (omitted from create/update)
- * - optional: Remove from required array
- *
- * Additional Options:
- * - strictAdditionalProperties: Set to true to add "additionalProperties: false" to schemas
- *   This makes Fastify reject unknown fields at validation level (default: false for backward compatibility)
- * - update.requireAtLeastOne: Set to true to add "minProperties: 1" to update schema
- *   This prevents empty update payloads (default: false)
- *
- * @example
- * buildCrudSchemasFromModel(Model, {
- *   strictAdditionalProperties: true, // Reject unknown fields
- *   fieldRules: {
- *     organizationId: { immutable: true },
- *     status: { systemManaged: true },
- *   },
- *   create: { omitFields: ['verifiedAt'] },
- *   update: {
- *     omitFields: ['customerId'],
- *     requireAtLeastOne: true // Reject empty updates
- *   }
- * })
- */
-
+//#endregion
+//#region src/utils/mongooseToJsonSchema.d.ts
 /**
  * Build CRUD schemas from Mongoose schema
  */
@@ -210,7 +137,7 @@ declare function buildCrudSchemasFromMongooseSchema(mongooseSchema: Schema, opti
 /**
  * Build CRUD schemas from Mongoose model
  */
-declare function buildCrudSchemasFromModel(mongooseModel: mongoose__default.Model<unknown>, options?: SchemaBuilderOptions): CrudSchemas;
+declare function buildCrudSchemasFromModel(mongooseModel: mongoose.Model<unknown>, options?: SchemaBuilderOptions): CrudSchemas;
 /**
  * Get fields that are immutable (cannot be updated)
  */
@@ -227,5 +154,5 @@ declare function isFieldUpdateAllowed(fieldName: string, options?: SchemaBuilder
  * Validate update body against field rules
  */
 declare function validateUpdateBody(body?: Record<string, unknown>, options?: SchemaBuilderOptions): ValidationResult;
-
-export { getMongooseProjection as a, buildCrudSchemasFromMongooseSchema as b, createFieldPreset as c, buildCrudSchemasFromModel as d, getImmutableFields as e, filterResponseData as f, getFieldsForUser as g, getSystemManagedFields as h, isFieldUpdateAllowed as i, createError as j, configureLogger as k, createMemoryCache as l, validateUpdateBody as v };
+//#endregion
+export { isFieldUpdateAllowed as a, configureLogger as c, filterResponseData as d, getFieldsForUser as f, getSystemManagedFields as i, createError as l, buildCrudSchemasFromMongooseSchema as n, validateUpdateBody as o, getMongooseProjection as p, getImmutableFields as r, createMemoryCache as s, buildCrudSchemasFromModel as t, createFieldPreset as u };

package/dist/pagination/PaginationEngine.d.mts

@@ -0,0 +1,93 @@
+import { A as KeysetPaginationOptions, I as OffsetPaginationOptions, L as OffsetPaginationResult, i as AnyDocument, j as KeysetPaginationResult, n as AggregatePaginationResult, t as AggregatePaginationOptions, z as PaginationConfig } from "../types-D-gploPr.mjs";
+import { Model } from "mongoose";
+
+//#region src/pagination/PaginationEngine.d.ts
+/**
+ * Internal pagination config with required values
+ */
+interface ResolvedPaginationConfig {
+  defaultLimit: number;
+  maxLimit: number;
+  maxPage: number;
+  deepPageThreshold: number;
+  cursorVersion: number;
+  useEstimatedCount: boolean;
+}
+/**
+ * Production-grade pagination engine for MongoDB
+ * Supports offset, keyset (cursor), and aggregate pagination
+ */
+declare class PaginationEngine<TDoc = AnyDocument> {
+  readonly Model: Model<TDoc>;
+  readonly config: ResolvedPaginationConfig;
+  /**
+   * Create a new pagination engine
+   *
+   * @param Model - Mongoose model to paginate
+   * @param config - Pagination configuration
+   */
+  constructor(Model: Model<TDoc, any, any, any>, config?: PaginationConfig);
+  /**
+   * 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);
+   */
+  paginate(options?: OffsetPaginationOptions): Promise<OffsetPaginationResult<TDoc>>;
+  /**
+   * 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
+   * });
+   */
+  stream(options: KeysetPaginationOptions): Promise<KeysetPaginationResult<TDoc>>;
+  /**
+   * 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
+   * });
+   */
+  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+}
+//#endregion
+export { PaginationEngine };

package/dist/pagination/PaginationEngine.mjs

@@ -0,0 +1,196 @@
+import { i as createError, r as warn } from "../logger-D8ily-PP.mjs";
+import { a as validatePage, c as validateKeysetSort, d as validateCursorSort, f as validateCursorVersion, i as validateLimit, l as decodeCursor, n as calculateTotalPages, o as buildKeysetFilter, r as shouldWarnDeepPagination, s as getPrimaryField, t as calculateSkip, u as encodeCursor } from "../limits-DsNeCx4D.mjs";
+
+//#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);
+		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(sanitizedLimit).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 total = 0;
+		if (countStrategy === "estimated" || useEstimated && countStrategy !== "exact") total = await 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);
+			total = await countQuery;
+		}
+		const [docs] = await Promise.all([query.exec()]);
+		const totalPages = countStrategy === "none" ? 0 : calculateTotalPages(total, sanitizedLimit);
+		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: countStrategy === "none" ? docs.length === sanitizedLimit : sanitizedPage < totalPages,
+			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 facetStages = { docs: [{ $skip: calculateSkip(sanitizedPage, sanitizedLimit) }, { $limit: sanitizedLimit }] };
+		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);
+		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: countStrategy === "none" ? docs.length === sanitizedLimit : sanitizedPage < totalPages,
+			hasPrev: sanitizedPage > 1,
+			...warning && { warning }
+		};
+	}
+};
+
+//#endregion
+export { PaginationEngine };

package/dist/plugins/index.d.mts

@@ -0,0 +1,3 @@
+import "../types-D-gploPr.mjs";
+import { A as blockIf, B as timestampPlugin, C as AggregateHelpersMethods, D as MongoOperationsMethods, E as batchOperationsPlugin, F as MethodRegistryRepository, I as methodRegistryPlugin, L as SoftDeleteMethods, M as requireField, N as uniqueField, O as mongoOperationsPlugin, P as validationChainPlugin, R as softDeletePlugin, S as subdocumentPlugin, T as BatchOperationsMethods, V as fieldFilterPlugin, _ as multiTenantPlugin, a as SequentialIdOptions, b as cachePlugin, c as getNextSequence, d as ElasticSearchOptions, f as elasticSearchPlugin, g as MultiTenantOptions, h as observabilityPlugin, i as PrefixedIdOptions, j as immutableField, k as autoInject, l as prefixedId, m as OperationMetric, n as DateSequentialIdOptions, o as customIdPlugin, p as ObservabilityOptions, r as IdGenerator, s as dateSequentialId, t as CustomIdOptions, u as sequentialId, v as cascadePlugin, w as aggregateHelpersPlugin, x as SubdocumentMethods, y as CacheMethods, z as auditLogPlugin } from "../custom-id.plugin-BzZI4gnE.mjs";
+export { type AggregateHelpersMethods, 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, 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

@@ -0,0 +1,3 @@
+import { C as auditLogPlugin, S as softDeletePlugin, T as fieldFilterPlugin, _ as immutableField, a as sequentialId, b as validationChainPlugin, c as multiTenantPlugin, d as subdocumentPlugin, f as aggregateHelpersPlugin, g as blockIf, h as autoInject, i as prefixedId, l as cascadePlugin, m as mongoOperationsPlugin, n as dateSequentialId, o as elasticSearchPlugin, p as batchOperationsPlugin, r as getNextSequence, s as observabilityPlugin, t as customIdPlugin, u as cachePlugin, v as requireField, w as timestampPlugin, x as methodRegistryPlugin, y as uniqueField } from "../custom-id.plugin-B_zIs6gE.mjs";
+
+export { aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };