@classytic/mongokit 2.0.0 → 3.0.0

package/dist/types-Nxhmi1aI.d.ts

@@ -0,0 +1,510 @@
+import { Document, PopulateOptions, ClientSession, PipelineStage, Model, Types } from 'mongoose';
+
+/**
+ * MongoKit Type Definitions
+ *
+ * Production-grade types for MongoDB repository pattern with TypeScript
+ *
+ * @module @classytic/mongokit
+ */
+
+/** Re-export mongoose ObjectId */
+type ObjectId = Types.ObjectId;
+/** Generic document type */
+type AnyDocument = Document & Record<string, unknown>;
+/** Generic model type */
+type AnyModel = Model<AnyDocument>;
+/** Sort direction */
+type SortDirection = 1 | -1;
+/** Sort specification */
+type SortSpec = Record<string, SortDirection>;
+/** Populate specification */
+type PopulateSpec = string | string[] | PopulateOptions | PopulateOptions[];
+/** Select specification */
+type SelectSpec = string | string[] | Record<string, 0 | 1>;
+/** Filter query type for MongoDB queries (compatible with Mongoose 8 & 9) */
+type FilterQuery<T> = Record<string, unknown>;
+/** Pagination configuration */
+interface PaginationConfig {
+    /** Default number of documents per page (default: 10) */
+    defaultLimit?: number;
+    /** Maximum allowed limit (default: 100) */
+    maxLimit?: number;
+    /** Maximum allowed page number (default: 10000) */
+    maxPage?: number;
+    /** Page number that triggers performance warning (default: 100) */
+    deepPageThreshold?: number;
+    /** Cursor version for forward compatibility (default: 1) */
+    cursorVersion?: number;
+    /** Use estimatedDocumentCount for faster counts on large collections */
+    useEstimatedCount?: boolean;
+}
+/** Base pagination options */
+interface BasePaginationOptions {
+    /** MongoDB query filters */
+    filters?: FilterQuery<AnyDocument>;
+    /** Sort specification */
+    sort?: SortSpec;
+    /** Number of documents per page */
+    limit?: number;
+    /** Fields to select */
+    select?: SelectSpec;
+    /** Fields to populate */
+    populate?: PopulateSpec;
+    /** Return plain JavaScript objects */
+    lean?: boolean;
+    /** MongoDB session for transactions */
+    session?: ClientSession;
+}
+/** Offset pagination options */
+interface OffsetPaginationOptions extends BasePaginationOptions {
+    /** Page number (1-indexed) */
+    page?: number;
+}
+/** Keyset (cursor) pagination options */
+interface KeysetPaginationOptions extends BasePaginationOptions {
+    /** Cursor token for next page */
+    after?: string;
+    /** Sort is required for keyset pagination */
+    sort: SortSpec;
+}
+/** Aggregate pagination options */
+interface AggregatePaginationOptions {
+    /** Aggregation pipeline stages */
+    pipeline?: PipelineStage[];
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Number of documents per page */
+    limit?: number;
+    /** MongoDB session for transactions */
+    session?: ClientSession;
+}
+/** Offset pagination result */
+interface OffsetPaginationResult<T = unknown> {
+    /** Pagination method used */
+    method: 'offset';
+    /** Array of documents */
+    docs: T[];
+    /** Current page number */
+    page: number;
+    /** Documents per page */
+    limit: number;
+    /** Total document count */
+    total: number;
+    /** Total page count */
+    pages: number;
+    /** Whether next page exists */
+    hasNext: boolean;
+    /** Whether previous page exists */
+    hasPrev: boolean;
+    /** Performance warning for deep pagination */
+    warning?: string;
+}
+/** Keyset pagination result */
+interface KeysetPaginationResult<T = unknown> {
+    /** Pagination method used */
+    method: 'keyset';
+    /** Array of documents */
+    docs: T[];
+    /** Documents per page */
+    limit: number;
+    /** Whether more documents exist */
+    hasMore: boolean;
+    /** Cursor token for next page */
+    next: string | null;
+}
+/** Aggregate pagination result */
+interface AggregatePaginationResult<T = unknown> {
+    /** Pagination method used */
+    method: 'aggregate';
+    /** Array of documents */
+    docs: T[];
+    /** Current page number */
+    page: number;
+    /** Documents per page */
+    limit: number;
+    /** Total document count */
+    total: number;
+    /** Total page count */
+    pages: number;
+    /** Whether next page exists */
+    hasNext: boolean;
+    /** Whether previous page exists */
+    hasPrev: boolean;
+    /** Performance warning for deep pagination */
+    warning?: string;
+}
+/** Union type for all pagination results */
+type PaginationResult<T = unknown> = OffsetPaginationResult<T> | KeysetPaginationResult<T> | AggregatePaginationResult<T>;
+/** Repository operation options */
+interface OperationOptions {
+    /** MongoDB session for transactions */
+    session?: ClientSession;
+    /** Fields to select */
+    select?: SelectSpec;
+    /** Fields to populate */
+    populate?: PopulateSpec;
+    /** Return plain JavaScript objects */
+    lean?: boolean;
+    /** Throw error if document not found (default: true) */
+    throwOnNotFound?: boolean;
+    /** Additional query filters (e.g., for soft delete) */
+    query?: Record<string, unknown>;
+}
+/** Create operation options */
+interface CreateOptions {
+    /** MongoDB session for transactions */
+    session?: ClientSession;
+    /** Keep insertion order on error (default: true) */
+    ordered?: boolean;
+}
+/** Update operation options */
+interface UpdateOptions extends OperationOptions {
+    /** Enable update pipeline syntax */
+    updatePipeline?: boolean;
+}
+/** Delete result */
+interface DeleteResult {
+    success: boolean;
+    message: string;
+    count?: number;
+}
+/** Update many result */
+interface UpdateManyResult {
+    matchedCount: number;
+    modifiedCount: number;
+}
+/** Validation result */
+interface ValidationResult {
+    valid: boolean;
+    violations?: Array<{
+        field: string;
+        reason: string;
+    }>;
+    message?: string;
+}
+/** Update with validation result */
+type UpdateWithValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: {
+        code: number;
+        message: string;
+        violations?: ValidationResult['violations'];
+    };
+};
+/** User context for operations */
+interface UserContext {
+    _id?: ObjectId | string;
+    id?: string;
+    roles?: string | string[];
+    [key: string]: unknown;
+}
+/** Repository operation context */
+interface RepositoryContext {
+    /** Operation name */
+    operation: string;
+    /** Model name */
+    model: string;
+    /** Document data (for create/update) */
+    data?: Record<string, unknown>;
+    /** Array of documents (for createMany) */
+    dataArray?: Record<string, unknown>[];
+    /** Document ID (for update/delete/getById) */
+    id?: string | ObjectId;
+    /** Query filters */
+    query?: FilterQuery<AnyDocument>;
+    /** User making the request */
+    user?: UserContext;
+    /** Organization ID for multi-tenancy */
+    organizationId?: string | ObjectId;
+    /** Fields to select */
+    select?: SelectSpec;
+    /** Fields to populate */
+    populate?: PopulateSpec;
+    /** Return lean documents */
+    lean?: boolean;
+    /** MongoDB session */
+    session?: ClientSession;
+    /** Include soft-deleted documents */
+    includeDeleted?: boolean;
+    /** Custom context data from plugins */
+    [key: string]: unknown;
+}
+/** Plugin interface */
+interface Plugin {
+    /** Plugin name */
+    name: string;
+    /** Apply plugin to repository */
+    apply(repo: RepositoryInstance): void;
+}
+/** Plugin function signature */
+type PluginFunction = (repo: RepositoryInstance) => void;
+/** Plugin type (object or function) */
+type PluginType = Plugin | PluginFunction;
+/** Repository instance for plugin type reference */
+interface RepositoryInstance {
+    Model: Model<any>;
+    model: string;
+    _hooks: Map<string, Array<(data: any) => void | Promise<void>>>;
+    _pagination: unknown;
+    use(plugin: PluginType): this;
+    on(event: string, listener: (data: any) => void | Promise<void>): this;
+    emit(event: string, data: unknown): void;
+    registerMethod?(name: string, fn: Function): void;
+    hasMethod?(name: string): boolean;
+    [key: string]: unknown;
+}
+/** Repository event names */
+type RepositoryEvent = 'before:create' | 'after:create' | 'error:create' | 'before:createMany' | 'after:createMany' | 'error:createMany' | 'before:update' | 'after:update' | 'error:update' | 'before:updateMany' | 'after:updateMany' | 'error:updateMany' | 'before:delete' | 'after:delete' | 'error:delete' | 'before:deleteMany' | 'after:deleteMany' | 'error:deleteMany' | 'before:getById' | 'after:getById' | 'before:getByQuery' | 'after:getByQuery' | 'before:getAll' | 'after:getAll' | 'before:aggregatePaginate' | 'method:registered';
+/** Event payload */
+interface EventPayload {
+    context: RepositoryContext;
+    result?: unknown;
+    error?: Error;
+}
+/** Field preset configuration */
+interface FieldPreset {
+    /** Fields visible to everyone */
+    public: string[];
+    /** Additional fields for authenticated users */
+    authenticated?: string[];
+    /** Additional fields for admins */
+    admin?: string[];
+}
+/** Parsed query result */
+interface ParsedQuery {
+    filters: FilterQuery<AnyDocument>;
+    limit: number;
+    sort: SortSpec | undefined;
+    populate: string | undefined;
+    search: string | undefined;
+    page?: number;
+    after?: string;
+}
+/** Field rules for schema building */
+interface FieldRules {
+    [fieldName: string]: {
+        /** Field cannot be updated */
+        immutable?: boolean;
+        /** Alias for immutable */
+        immutableAfterCreate?: boolean;
+        /** System-only field (omitted from create/update) */
+        systemManaged?: boolean;
+        /** Remove from required array */
+        optional?: boolean;
+    };
+}
+/** Schema builder options */
+interface SchemaBuilderOptions {
+    /** Field rules for create/update */
+    fieldRules?: FieldRules;
+    /** Strict additional properties (default: false) */
+    strictAdditionalProperties?: boolean;
+    /** Date format: 'date' | 'datetime' */
+    dateAs?: 'date' | 'datetime';
+    /** Create schema options */
+    create?: {
+        /** Fields to omit from create schema */
+        omitFields?: string[];
+        /** Override required status */
+        requiredOverrides?: Record<string, boolean>;
+        /** Override optional status */
+        optionalOverrides?: Record<string, boolean>;
+        /** Schema overrides */
+        schemaOverrides?: Record<string, unknown>;
+    };
+    /** Update schema options */
+    update?: {
+        /** Fields to omit from update schema */
+        omitFields?: string[];
+    };
+    /** Query schema options */
+    query?: {
+        /** Filterable fields */
+        filterableFields?: Record<string, {
+            type: string;
+        } | unknown>;
+    };
+}
+/** JSON Schema type */
+interface JsonSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean | unknown;
+    items?: unknown;
+    enum?: string[];
+    format?: string;
+    pattern?: string;
+}
+/** CRUD schemas result */
+interface CrudSchemas {
+    createBody: JsonSchema;
+    updateBody: JsonSchema;
+    params: JsonSchema;
+    listQuery: JsonSchema;
+    crudSchemas: {
+        create: {
+            body: JsonSchema;
+        };
+        update: {
+            body: JsonSchema;
+            params: JsonSchema;
+        };
+        get: {
+            params: JsonSchema;
+        };
+        list: {
+            query: JsonSchema;
+        };
+        remove: {
+            params: JsonSchema;
+        };
+    };
+}
+/** Decoded cursor */
+interface DecodedCursor {
+    /** Primary sort field value (rehydrated) */
+    value: unknown;
+    /** Document ID (rehydrated) */
+    id: ObjectId | string;
+    /** Sort specification */
+    sort: SortSpec;
+    /** Cursor version */
+    version: number;
+}
+/** Validator definition */
+interface ValidatorDefinition {
+    /** Validator name */
+    name: string;
+    /** Operations to apply validator to */
+    operations?: Array<'create' | 'createMany' | 'update' | 'delete'>;
+    /** Validation function */
+    validate: (context: RepositoryContext, repo?: RepositoryInstance) => void | Promise<void>;
+}
+/** Validation chain options */
+interface ValidationChainOptions {
+    /** Stop on first validation error (default: true) */
+    stopOnFirstError?: boolean;
+}
+/** Logger interface for audit plugin */
+interface Logger {
+    info?(message: string, meta?: Record<string, unknown>): void;
+    error?(message: string, meta?: Record<string, unknown>): void;
+    warn?(message: string, meta?: Record<string, unknown>): void;
+    debug?(message: string, meta?: Record<string, unknown>): void;
+}
+/** Soft delete plugin options */
+interface SoftDeleteOptions {
+    /** Field name for deletion timestamp (default: 'deletedAt') */
+    deletedField?: string;
+    /** Field name for deleting user (default: 'deletedBy') */
+    deletedByField?: string;
+    /** Enable soft delete (default: true) */
+    soft?: boolean;
+}
+/** Lookup options for aggregate */
+interface LookupOptions {
+    /** Collection to join */
+    from: string;
+    /** Local field to match */
+    localField: string;
+    /** Foreign field to match */
+    foreignField: string;
+    /** Output array field name */
+    as: string;
+    /** Additional pipeline stages */
+    pipeline?: PipelineStage[];
+    /** Initial match query */
+    query?: FilterQuery<AnyDocument>;
+    /** Operation options */
+    options?: {
+        session?: ClientSession;
+    };
+}
+/** Group result */
+interface GroupResult {
+    _id: unknown;
+    count: number;
+}
+/** Min/Max result */
+interface MinMaxResult {
+    min: unknown;
+    max: unknown;
+}
+/**
+ * Cache adapter interface - bring your own cache implementation
+ * Works with Redis, Memcached, in-memory, or any key-value store
+ *
+ * @example Redis implementation:
+ * ```typescript
+ * const redisCache: CacheAdapter = {
+ *   async get(key) { return JSON.parse(await redis.get(key) || 'null'); },
+ *   async set(key, value, ttl) { await redis.setex(key, ttl, JSON.stringify(value)); },
+ *   async del(key) { await redis.del(key); },
+ *   async clear(pattern) {
+ *     const keys = await redis.keys(pattern || '*');
+ *     if (keys.length) await redis.del(...keys);
+ *   }
+ * };
+ * ```
+ */
+interface CacheAdapter {
+    /** Get value by key, returns null if not found or expired */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Set value with TTL in seconds */
+    set<T = unknown>(key: string, value: T, ttl: number): Promise<void>;
+    /** Delete single key */
+    del(key: string): Promise<void>;
+    /** Clear keys matching pattern (optional, used for bulk invalidation) */
+    clear?(pattern?: string): Promise<void>;
+}
+/** Cache plugin options */
+interface CacheOptions {
+    /** Cache adapter implementation (required) */
+    adapter: CacheAdapter;
+    /** Default TTL in seconds (default: 60) */
+    ttl?: number;
+    /** TTL for byId queries in seconds (default: same as ttl) */
+    byIdTtl?: number;
+    /** TTL for query/list results in seconds (default: same as ttl) */
+    queryTtl?: number;
+    /** Key prefix for namespacing (default: 'mk') */
+    prefix?: string;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /**
+     * Skip caching for queries with these characteristics:
+     * - largeLimit: Skip if limit > value (default: 100)
+     */
+    skipIf?: {
+        largeLimit?: number;
+    };
+}
+/** Options for cache-aware operations */
+interface CacheOperationOptions {
+    /** Skip cache for this operation (read from DB directly) */
+    skipCache?: boolean;
+    /** Custom TTL for this operation in seconds */
+    cacheTtl?: number;
+}
+/** Cache statistics (for debugging/monitoring) */
+interface CacheStats {
+    hits: number;
+    misses: number;
+    sets: number;
+    invalidations: number;
+}
+/** HTTP Error with status code */
+interface HttpError extends Error {
+    status: number;
+    validationErrors?: Array<{
+        validator: string;
+        error: string;
+    }>;
+}
+
+export type { AnyDocument as A, SoftDeleteOptions as B, CreateOptions as C, DeleteResult as D, EventPayload as E, FieldPreset as F, LookupOptions as G, HttpError as H, GroupResult as I, JsonSchema as J, KeysetPaginationOptions as K, Logger as L, MinMaxResult as M, CacheAdapter as N, OffsetPaginationOptions as O, PaginationConfig as P, CacheOptions as Q, RepositoryContext as R, SelectSpec as S, CacheOperationOptions as T, UpdateOptions as U, ValidationResult as V, CacheStats as W, OffsetPaginationResult as a, KeysetPaginationResult as b, AggregatePaginationOptions as c, AggregatePaginationResult as d, PluginType as e, PopulateSpec as f, SortSpec as g, ObjectId as h, AnyModel as i, SortDirection as j, PaginationResult as k, OperationOptions as l, UpdateManyResult as m, UpdateWithValidationResult as n, UserContext as o, Plugin as p, PluginFunction as q, RepositoryInstance as r, RepositoryEvent as s, ParsedQuery as t, FieldRules as u, SchemaBuilderOptions as v, CrudSchemas as w, DecodedCursor as x, ValidatorDefinition as y, ValidationChainOptions as z };

package/dist/utils/index.d.ts

@@ -0,0 +1,189 @@
+export { b as createError, c as createFieldPreset, d as createMemoryCache, f as filterResponseData, g as getFieldsForUser, a as getMongooseProjection } from '../memory-cache-DG2oSSbx.js';
+import { t as ParsedQuery, v as SchemaBuilderOptions, w as CrudSchemas, V as ValidationResult, S as SelectSpec, f as PopulateSpec, g as SortSpec } from '../types-Nxhmi1aI.js';
+import mongoose__default, { Schema } from 'mongoose';
+
+/**
+ * Query Parser
+ *
+ * Parses HTTP query parameters into MongoDB-compatible query objects.
+ * Supports operators, pagination, sorting, and filtering.
+ */
+
+declare class QueryParser {
+    private operators;
+    /**
+     * Dangerous MongoDB operators that should never be accepted from user input
+     * Security: Prevent NoSQL injection attacks
+     */
+    private dangerousOperators;
+    /**
+     * Parse query parameters into MongoDB query format
+     */
+    parseQuery(query: Record<string, unknown> | null | undefined): ParsedQuery;
+    /**
+     * Parse sort parameter
+     * Converts string like '-createdAt' to { createdAt: -1 }
+     * Handles multiple sorts: '-createdAt,name' → { createdAt: -1, name: 1 }
+     */
+    private _parseSort;
+    /**
+     * Parse standard filter parameter (filter[field]=value)
+     */
+    private _parseFilters;
+    /**
+     * Handle operator syntax: field[operator]=value
+     */
+    private _handleOperatorSyntax;
+    /**
+     * Handle bracket syntax with object value
+     */
+    private _handleBracketSyntax;
+    /**
+     * Convert operator to MongoDB format
+     */
+    private _toMongoOperator;
+    /**
+     * Convert values based on operator type
+     */
+    private _convertValue;
+    /**
+     * Parse $or conditions
+     */
+    private _parseOr;
+    /**
+     * Enhance filters with between operator
+     */
+    private _enhanceWithBetween;
+}
+declare const _default: QueryParser;
+
+/**
+ * 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)
+ *
+ * @example
+ * buildCrudSchemasFromModel(Model, {
+ *   strictAdditionalProperties: true, // Reject unknown fields
+ *   fieldRules: {
+ *     organizationId: { immutable: true },
+ *     status: { systemManaged: true },
+ *   },
+ *   create: { omitFields: ['verifiedAt'] },
+ *   update: { omitFields: ['customerId'] }
+ * })
+ */
+
+/**
+ * Build CRUD schemas from Mongoose schema
+ */
+declare function buildCrudSchemasFromMongooseSchema(mongooseSchema: Schema, options?: SchemaBuilderOptions): CrudSchemas;
+/**
+ * Build CRUD schemas from Mongoose model
+ */
+declare function buildCrudSchemasFromModel(mongooseModel: mongoose__default.Model<unknown>, options?: SchemaBuilderOptions): CrudSchemas;
+/**
+ * Get fields that are immutable (cannot be updated)
+ */
+declare function getImmutableFields(options?: SchemaBuilderOptions): string[];
+/**
+ * Get fields that are system-managed (cannot be set by users)
+ */
+declare function getSystemManagedFields(options?: SchemaBuilderOptions): string[];
+/**
+ * Check if field is allowed in update
+ */
+declare function isFieldUpdateAllowed(fieldName: string, options?: SchemaBuilderOptions): boolean;
+/**
+ * Validate update body against field rules
+ */
+declare function validateUpdateBody(body?: Record<string, unknown>, options?: SchemaBuilderOptions): ValidationResult;
+
+/**
+ * Cache Key Utilities
+ *
+ * Generates deterministic, collision-free cache keys for MongoDB queries.
+ * Key design inspired by Next.js cache tags and best practices from Stripe/Meta.
+ */
+
+/**
+ * Generate cache key for getById operations
+ *
+ * Format: {prefix}:id:{model}:{documentId}
+ *
+ * @example
+ * byIdKey('mk', 'User', '507f1f77bcf86cd799439011')
+ * // => 'mk:id:User:507f1f77bcf86cd799439011'
+ */
+declare function byIdKey(prefix: string, model: string, id: string): 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, 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;
+}): 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;
+
+export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, listPattern, listQueryKey, modelPattern, _default as queryParser, validateUpdateBody, versionKey };