@classytic/mongokit 3.2.0 → 3.2.2

package/dist/chunks/chunk-WSFCRVEQ.js

@@ -1,7 +0,0 @@
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-export { __export };

package/dist/index-BDn5fSTE.d.ts

@@ -1,516 +0,0 @@
-import { PipelineStage, ClientSession, Model } from 'mongoose';
-import { A as AnyDocument, v as CreateOptions, j as ObjectId, u as OperationOptions, S as SelectSpec, e as PopulateSpec, f as SortSpec, U as UpdateOptions, y as UpdateWithValidationResult, x as UpdateManyResult, w as DeleteResult, a5 as GroupResult, a6 as MinMaxResult } from './types-Jni1KgkP.js';
-
-/**
- * LookupBuilder - MongoDB $lookup Utility
- *
- * Standalone builder for efficient custom field joins using MongoDB $lookup aggregation.
- * Optimized for millions of records with proper index usage.
- *
- * Features:
- * - Join on custom fields (slugs, SKUs, codes, etc.)
- * - Pipeline support for complex transformations
- * - Index-aware query building
- * - Single vs Array result handling
- * - Nested lookups
- *
- * @example
- * ```typescript
- * // Simple lookup - join employees with departments by slug
- * const lookup = new LookupBuilder('departments')
- *   .localField('departmentSlug')
- *   .foreignField('slug')
- *   .as('department')
- *   .single();  // Unwrap array to single object
- *
- * const pipeline = lookup.build();
- * const results = await Employee.aggregate(pipeline);
- *
- * // Advanced lookup with pipeline
- * const lookup = new LookupBuilder('products')
- *   .localField('productIds')
- *   .foreignField('sku')
- *   .pipeline([
- *     { $match: { status: 'active' } },
- *     { $project: { name: 1, price: 1 } }
- *   ])
- *   .as('products');
- * ```
- */
-
-interface LookupOptions {
-    /** Collection to join with */
-    from: string;
-    /** Field from the input documents */
-    localField: string;
-    /** Field from the documents of the "from" collection */
-    foreignField: string;
-    /** Name of the new array field to add to the input documents */
-    as?: string;
-    /** Whether to unwrap array to single object */
-    single?: boolean;
-    /** Additional pipeline to run on the joined collection */
-    pipeline?: PipelineStage[];
-    /** Optional let variables for pipeline */
-    let?: Record<string, string>;
-    /** Query filter to apply before join (legacy, for aggregate.ts compatibility) */
-    query?: Record<string, unknown>;
-    /** Query options (legacy, for aggregate.ts compatibility) */
-    options?: {
-        session?: ClientSession;
-    };
-    /** Sanitize pipeline stages (default: true). Set false only for trusted server-side pipelines */
-    sanitize?: boolean;
-}
-/**
- * Fluent builder for MongoDB $lookup aggregation stage
- * Optimized for custom field joins at scale
- */
-declare class LookupBuilder {
-    private options;
-    constructor(from?: string);
-    /**
-     * Set the collection to join with
-     */
-    from(collection: string): this;
-    /**
-     * Set the local field (source collection)
-     * IMPORTANT: This field should be indexed for optimal performance
-     */
-    localField(field: string): this;
-    /**
-     * Set the foreign field (target collection)
-     * IMPORTANT: This field should be indexed (preferably unique) for optimal performance
-     */
-    foreignField(field: string): this;
-    /**
-     * Set the output field name
-     * Defaults to the collection name if not specified
-     */
-    as(fieldName: string): this;
-    /**
-     * Mark this lookup as returning a single document
-     * Automatically unwraps the array result to a single object or null
-     */
-    single(isSingle?: boolean): this;
-    /**
-     * Add a pipeline to filter/transform joined documents
-     * Useful for filtering, sorting, or limiting joined results
-     *
-     * @example
-     * ```typescript
-     * lookup.pipeline([
-     *   { $match: { status: 'active' } },
-     *   { $sort: { priority: -1 } },
-     *   { $limit: 5 }
-     * ]);
-     * ```
-     */
-    pipeline(stages: PipelineStage[]): this;
-    /**
-     * Set let variables for use in pipeline
-     * Allows referencing local document fields in the pipeline
-     */
-    let(variables: Record<string, string>): this;
-    /**
-     * Build the $lookup aggregation stage(s)
-     * Returns an array of pipeline stages including $lookup and optional $unwind
-     *
-     * IMPORTANT: MongoDB $lookup has two mutually exclusive forms:
-     * 1. Simple form: { from, localField, foreignField, as }
-     * 2. Pipeline form: { from, let, pipeline, as }
-     *
-     * When pipeline or let is specified, we use the pipeline form.
-     * Otherwise, we use the simpler localField/foreignField form.
-     */
-    build(): PipelineStage[];
-    /**
-     * Build and return only the $lookup stage (without $unwind)
-     * Useful when you want to handle unwrapping yourself
-     */
-    buildLookupOnly(): PipelineStage.Lookup;
-    /**
-     * Static helper: Create a simple lookup in one line
-     */
-    static simple(from: string, localField: string, foreignField: string, options?: {
-        as?: string;
-        single?: boolean;
-    }): PipelineStage[];
-    /**
-     * Static helper: Create multiple lookups at once
-     *
-     * @example
-     * ```typescript
-     * const pipeline = LookupBuilder.multiple([
-     *   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
-     *   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
-     * ]);
-     * ```
-     */
-    static multiple(lookups: LookupOptions[]): PipelineStage[];
-    /**
-     * Static helper: Create a nested lookup (lookup within lookup)
-     * Useful for multi-level joins like Order -> Product -> Category
-     *
-     * @example
-     * ```typescript
-     * // Join orders with products, then products with categories
-     * const pipeline = LookupBuilder.nested([
-     *   { from: 'products', localField: 'productSku', foreignField: 'sku', as: 'product', single: true },
-     *   { from: 'categories', localField: 'product.categorySlug', foreignField: 'slug', as: 'product.category', single: true }
-     * ]);
-     * ```
-     */
-    static nested(lookups: LookupOptions[]): PipelineStage[];
-    /**
-     * Sanitize pipeline stages by blocking dangerous stages and operators.
-     * Used internally by build() and available for external use (e.g., aggregate.ts).
-     */
-    static sanitizePipeline(stages: PipelineStage[]): PipelineStage[];
-    /**
-     * Recursively remove dangerous operators from an expression object.
-     */
-    private static _sanitizeDeep;
-}
-
-/**
- * Create Actions
- * Pure functions for document creation
- */
-
-/**
- * Create single document
- */
-declare function create<TDoc = AnyDocument>(Model: Model<TDoc>, data: Record<string, unknown>, options?: CreateOptions): Promise<TDoc>;
-/**
- * Create multiple documents
- */
-declare function createMany<TDoc = AnyDocument>(Model: Model<TDoc>, dataArray: Record<string, unknown>[], options?: CreateOptions): Promise<TDoc[]>;
-/**
- * Create with defaults (useful for initialization)
- */
-declare function createDefault<TDoc = AnyDocument>(Model: Model<TDoc>, overrides?: Record<string, unknown>, options?: CreateOptions): Promise<TDoc>;
-/**
- * Upsert (create or update)
- */
-declare function upsert<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, data: Record<string, unknown>, options?: {
-    session?: ClientSession;
-    updatePipeline?: boolean;
-}): Promise<TDoc | null>;
-
-declare const create$1_create: typeof create;
-declare const create$1_createDefault: typeof createDefault;
-declare const create$1_createMany: typeof createMany;
-declare const create$1_upsert: typeof upsert;
-declare namespace create$1 {
-  export { create$1_create as create, create$1_createDefault as createDefault, create$1_createMany as createMany, create$1_upsert as upsert };
-}
-
-/**
- * Read Actions
- * Pure functions for document retrieval
- */
-
-/**
- * Get document by ID
- *
- * @param Model - Mongoose model
- * @param id - Document ID
- * @param options - Query options
- * @returns Document or null
- * @throws Error if document not found and throwOnNotFound is true
- */
-declare function getById<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, options?: OperationOptions): Promise<TDoc | null>;
-/**
- * Get document by query
- *
- * @param Model - Mongoose model
- * @param query - MongoDB query
- * @param options - Query options
- * @returns Document or null
- * @throws Error if document not found and throwOnNotFound is true
- */
-declare function getByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, options?: OperationOptions): Promise<TDoc | null>;
-/**
- * Get document by query without throwing (returns null if not found)
- */
-declare function tryGetByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, options?: Omit<OperationOptions, 'throwOnNotFound'>): Promise<TDoc | null>;
-/**
- * Get all documents (basic query without pagination)
- * For pagination, use Repository.paginate() or Repository.stream()
- */
-declare function getAll<TDoc = AnyDocument>(Model: Model<TDoc>, query?: Record<string, unknown>, options?: {
-    select?: SelectSpec;
-    populate?: PopulateSpec;
-    sort?: SortSpec;
-    limit?: number;
-    skip?: number;
-    lean?: boolean;
-    session?: ClientSession;
-}): Promise<TDoc[]>;
-/**
- * Get or create document (upsert)
- */
-declare function getOrCreate<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, createData: Record<string, unknown>, options?: {
-    session?: ClientSession;
-    updatePipeline?: boolean;
-}): Promise<TDoc | null>;
-/**
- * Count documents matching query
- */
-declare function count(Model: Model<any>, query?: Record<string, unknown>, options?: {
-    session?: ClientSession;
-}): Promise<number>;
-/**
- * Check if document exists
- */
-declare function exists(Model: Model<any>, query: Record<string, unknown>, options?: {
-    session?: ClientSession;
-}): Promise<{
-    _id: unknown;
-} | null>;
-
-declare const read_count: typeof count;
-declare const read_exists: typeof exists;
-declare const read_getAll: typeof getAll;
-declare const read_getById: typeof getById;
-declare const read_getByQuery: typeof getByQuery;
-declare const read_getOrCreate: typeof getOrCreate;
-declare const read_tryGetByQuery: typeof tryGetByQuery;
-declare namespace read {
-  export { read_count as count, read_exists as exists, read_getAll as getAll, read_getById as getById, read_getByQuery as getByQuery, read_getOrCreate as getOrCreate, read_tryGetByQuery as tryGetByQuery };
-}
-
-/**
- * Update Actions
- * Pure functions for document updates with optimizations
- */
-
-/**
- * Update by ID
- */
-declare function update<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc>;
-/**
- * Update with query constraints (optimized)
- * Returns null if constraints not met (not an error)
- */
-declare function updateWithConstraints<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, data: Record<string, unknown>, constraints?: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
-/**
- * Validation options for smart update
- */
-interface ValidationOptions {
-    buildConstraints?: (data: Record<string, unknown>) => Record<string, unknown>;
-    validateUpdate?: (existing: Record<string, unknown>, data: Record<string, unknown>) => {
-        valid: boolean;
-        message?: string;
-        violations?: Array<{
-            field: string;
-            reason: string;
-        }>;
-    };
-}
-/**
- * Update with validation (smart optimization)
- * 1-query on success, 2-queries for detailed errors
- */
-declare function updateWithValidation<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, data: Record<string, unknown>, validationOptions?: ValidationOptions, options?: UpdateOptions): Promise<UpdateWithValidationResult<TDoc>>;
-/**
- * Update many documents
- */
-declare function updateMany(Model: Model<unknown>, query: Record<string, unknown>, data: Record<string, unknown>, options?: {
-    session?: ClientSession;
-    updatePipeline?: boolean;
-}): Promise<UpdateManyResult>;
-/**
- * Update by query
- */
-declare function updateByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
-/**
- * Increment field
- */
-declare function increment<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, field: string, value?: number, options?: UpdateOptions): Promise<TDoc>;
-/**
- * Push to array
- */
-declare function pushToArray<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, field: string, value: unknown, options?: UpdateOptions): Promise<TDoc>;
-/**
- * Pull from array
- */
-declare function pullFromArray<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, field: string, value: unknown, options?: UpdateOptions): Promise<TDoc>;
-
-declare const update$1_increment: typeof increment;
-declare const update$1_pullFromArray: typeof pullFromArray;
-declare const update$1_pushToArray: typeof pushToArray;
-declare const update$1_update: typeof update;
-declare const update$1_updateByQuery: typeof updateByQuery;
-declare const update$1_updateMany: typeof updateMany;
-declare const update$1_updateWithConstraints: typeof updateWithConstraints;
-declare const update$1_updateWithValidation: typeof updateWithValidation;
-declare namespace update$1 {
-  export { update$1_increment as increment, update$1_pullFromArray as pullFromArray, update$1_pushToArray as pushToArray, update$1_update as update, update$1_updateByQuery as updateByQuery, update$1_updateMany as updateMany, update$1_updateWithConstraints as updateWithConstraints, update$1_updateWithValidation as updateWithValidation };
-}
-
-/**
- * Delete Actions
- * Pure functions for document deletion
- */
-
-/**
- * Delete by ID
- */
-declare function deleteById(Model: Model<any>, id: string | ObjectId, options?: {
-    session?: ClientSession;
-    query?: Record<string, unknown>;
-}): Promise<DeleteResult>;
-/**
- * Delete many documents
- */
-declare function deleteMany(Model: Model<any>, query: Record<string, unknown>, options?: {
-    session?: ClientSession;
-}): Promise<DeleteResult>;
-/**
- * Delete by query
- */
-declare function deleteByQuery(Model: Model<any>, query: Record<string, unknown>, options?: {
-    session?: ClientSession;
-    throwOnNotFound?: boolean;
-}): Promise<DeleteResult>;
-/**
- * Soft delete (set deleted flag)
- */
-declare function softDelete<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, options?: {
-    session?: ClientSession;
-    userId?: string;
-}): Promise<DeleteResult>;
-/**
- * Restore soft deleted document
- */
-declare function restore<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, options?: {
-    session?: ClientSession;
-}): Promise<DeleteResult>;
-
-declare const _delete_deleteById: typeof deleteById;
-declare const _delete_deleteByQuery: typeof deleteByQuery;
-declare const _delete_deleteMany: typeof deleteMany;
-declare const _delete_restore: typeof restore;
-declare const _delete_softDelete: typeof softDelete;
-declare namespace _delete {
-  export { _delete_deleteById as deleteById, _delete_deleteByQuery as deleteByQuery, _delete_deleteMany as deleteMany, _delete_restore as restore, _delete_softDelete as softDelete };
-}
-
-/**
- * Aggregate Actions
- * MongoDB aggregation pipeline operations
- */
-
-/**
- * Execute aggregation pipeline
- */
-declare function aggregate<TResult = unknown>(Model: Model<any>, pipeline: PipelineStage[], options?: {
-    session?: ClientSession;
-}): Promise<TResult[]>;
-/**
- * Aggregate with pagination using native MongoDB $facet
- * WARNING: $facet results must be <16MB. For larger results (limit >1000),
- * consider using Repository.aggregatePaginate() or splitting into separate queries.
- */
-declare function aggregatePaginate<TDoc = AnyDocument>(Model: Model<TDoc>, pipeline: PipelineStage[], options?: {
-    page?: number;
-    limit?: number;
-    session?: ClientSession;
-}): Promise<{
-    docs: TDoc[];
-    total: number;
-    page: number;
-    limit: number;
-    pages: number;
-    hasNext: boolean;
-    hasPrev: boolean;
-}>;
-/**
- * Group documents by field value
- */
-declare function groupBy(Model: Model<any>, field: string, options?: {
-    limit?: number;
-    session?: ClientSession;
-}): Promise<GroupResult[]>;
-/**
- * Count by field values
- */
-declare function countBy(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
-    session?: ClientSession;
-}): Promise<GroupResult[]>;
-/**
- * Lookup (join) with another collection
- *
- * MongoDB $lookup has two mutually exclusive forms:
- * 1. Simple form: { from, localField, foreignField, as }
- * 2. Pipeline form: { from, let, pipeline, as }
- *
- * This function automatically selects the appropriate form based on parameters.
- */
-declare function lookup<TDoc = AnyDocument>(Model: Model<TDoc>, lookupOptions: LookupOptions): Promise<TDoc[]>;
-/**
- * Unwind array field
- */
-declare function unwind<TDoc = AnyDocument>(Model: Model<TDoc>, field: string, options?: {
-    preserveEmpty?: boolean;
-    session?: ClientSession;
-}): Promise<TDoc[]>;
-/**
- * Facet search (multiple aggregations in one query)
- */
-declare function facet<TResult = Record<string, unknown[]>>(Model: Model<any>, facets: Record<string, PipelineStage[]>, options?: {
-    session?: ClientSession;
-}): Promise<TResult[]>;
-/**
- * Get distinct values
- */
-declare function distinct<T = unknown>(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
-    session?: ClientSession;
-}): Promise<T[]>;
-/**
- * Calculate sum
- */
-declare function sum(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
-    session?: ClientSession;
-}): Promise<number>;
-/**
- * Calculate average
- */
-declare function average(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
-    session?: ClientSession;
-}): Promise<number>;
-/**
- * Min/Max
- */
-declare function minMax(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
-    session?: ClientSession;
-}): Promise<MinMaxResult>;
-
-declare const aggregate$1_aggregate: typeof aggregate;
-declare const aggregate$1_aggregatePaginate: typeof aggregatePaginate;
-declare const aggregate$1_average: typeof average;
-declare const aggregate$1_countBy: typeof countBy;
-declare const aggregate$1_distinct: typeof distinct;
-declare const aggregate$1_facet: typeof facet;
-declare const aggregate$1_groupBy: typeof groupBy;
-declare const aggregate$1_lookup: typeof lookup;
-declare const aggregate$1_minMax: typeof minMax;
-declare const aggregate$1_sum: typeof sum;
-declare const aggregate$1_unwind: typeof unwind;
-declare namespace aggregate$1 {
-  export { aggregate$1_aggregate as aggregate, aggregate$1_aggregatePaginate as aggregatePaginate, aggregate$1_average as average, aggregate$1_countBy as countBy, aggregate$1_distinct as distinct, aggregate$1_facet as facet, aggregate$1_groupBy as groupBy, aggregate$1_lookup as lookup, aggregate$1_minMax as minMax, aggregate$1_sum as sum, aggregate$1_unwind as unwind };
-}
-
-/**
- * Repository Actions
- * Modular, composable data access operations
- */
-
-declare const index_read: typeof read;
-declare namespace index {
-  export { aggregate$1 as aggregate, create$1 as create, _delete as deleteActions, index_read as read, update$1 as update };
-}
-
-export { type LookupOptions as L, _delete as _, LookupBuilder as a, aggregate$1 as b, create$1 as c, index as i, read as r, update$1 as u };