@classytic/mongokit 3.0.6 → 3.1.0

package/README.md

@@ -320,10 +320,12 @@ repo.on('error:create', ({ context, error }) => {
 ### Query Parser
 
 ```javascript
-import { queryParser } from '@classytic/mongokit/utils';
+import { QueryParser } from '@classytic/mongokit';
+
+const queryParser = new QueryParser();
 
 app.get('/users', async (req, res) => {
-  const { filters, limit, page, sort } = queryParser.parseQuery(req.query);
+  const { filters, limit, page, sort } = queryParser.parse(req.query);
   const result = await userRepo.getAll({ filters, limit, page, sort });
   res.json(result);
 });

package/dist/actions/index.d.ts

@@ -1,3 +1,3 @@
-export { a as aggregate, c as create, _ as deleteActions, r as read, u as update } from '../index-CkwbNdpJ.js';
+export { b as aggregate, c as create, _ as deleteActions, r as read, u as update } from '../index-3Nkm_Brq.js';
 import 'mongoose';
-import '../types-DDDYo18H.js';
+import '../types-CrSoCuWu.js';

package/dist/actions/index.js

@@ -403,20 +403,51 @@ async function countBy(Model, field, query = {}, options = {}) {
   return aggregate(Model, pipeline, options);
 }
 async function lookup(Model, lookupOptions) {
-  const { from, localField, foreignField, as, pipeline = [], query = {}, options = {} } = lookupOptions;
+  const { from, localField, foreignField, as, pipeline = [], let: letVars, query = {}, options = {} } = lookupOptions;
   const aggPipeline = [];
   if (Object.keys(query).length > 0) {
     aggPipeline.push({ $match: query });
   }
-  aggPipeline.push({
-    $lookup: {
-      from,
-      localField,
-      foreignField,
-      as,
-      ...pipeline.length > 0 ? { pipeline } : {}
+  const usePipelineForm = pipeline.length > 0 || letVars;
+  if (usePipelineForm) {
+    if (pipeline.length === 0 && localField && foreignField) {
+      const autoPipeline = [
+        {
+          $match: {
+            $expr: {
+              $eq: [`$${foreignField}`, `$$${localField}`]
+            }
+          }
+        }
+      ];
+      aggPipeline.push({
+        $lookup: {
+          from,
+          let: { [localField]: `$${localField}`, ...letVars || {} },
+          pipeline: autoPipeline,
+          as
+        }
+      });
+    } else {
+      aggPipeline.push({
+        $lookup: {
+          from,
+          ...letVars && { let: letVars },
+          pipeline,
+          as
+        }
+      });
     }
-  });
+  } else {
+    aggPipeline.push({
+      $lookup: {
+        from,
+        localField,
+        foreignField,
+        as
+      }
+    });
+  }
   return aggregate(Model, aggPipeline, options);
 }
 async function unwind(Model, field, options = {}) {

package/dist/{index-CkwbNdpJ.d.ts → index-3Nkm_Brq.d.ts}

@@ -1,5 +1,166 @@
-import { Model, ClientSession, PipelineStage } from 'mongoose';
-import { A as AnyDocument, C as CreateOptions, h as ObjectId, n as OperationOptions, S as SelectSpec, e as PopulateSpec, f as SortSpec, U as UpdateOptions, p as UpdateWithValidationResult, o as UpdateManyResult, D as DeleteResult, X as GroupResult, T as LookupOptions, Y as MinMaxResult } from './types-DDDYo18H.js';
+import { PipelineStage, ClientSession, Model } from 'mongoose';
+import { A as AnyDocument, r as CreateOptions, k as ObjectId, q as OperationOptions, S as SelectSpec, e as PopulateSpec, f as SortSpec, l as UpdateOptions, t as UpdateWithValidationResult, s as UpdateManyResult, D as DeleteResult, Q as GroupResult, T as MinMaxResult } from './types-CrSoCuWu.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;
+    };
+}
+/**
+ * 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[];
+}
 
 /**
  * Create Actions
@@ -269,6 +430,12 @@ declare function countBy(Model: Model<any>, field: string, query?: Record<string
 }): 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[]>;
 /**
@@ -334,4 +501,4 @@ declare namespace index {
   export { aggregate$1 as aggregate, create$1 as create, _delete as deleteActions, index_read as read, update$1 as update };
 }
 
-export { _delete as _, aggregate$1 as a, create$1 as c, index as i, read as r, update$1 as u };
+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 };