@classytic/mongokit 1.0.2 → 2.1.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 };