@classytic/mongokit 3.0.6 → 3.1.1

package/dist/chunks/chunk-SAKSLT47.js

@@ -0,0 +1,470 @@
+import { create_exports } from './chunk-CF6FLC2G.js';
+import { __export, createError } from './chunk-VJXDGP3C.js';
+
+// src/actions/index.ts
+var actions_exports = {};
+__export(actions_exports, {
+  aggregate: () => aggregate_exports,
+  create: () => create_exports,
+  deleteActions: () => delete_exports,
+  read: () => read_exports,
+  update: () => update_exports
+});
+
+// src/actions/read.ts
+var read_exports = {};
+__export(read_exports, {
+  count: () => count,
+  exists: () => exists,
+  getAll: () => getAll,
+  getById: () => getById,
+  getByQuery: () => getByQuery,
+  getOrCreate: () => getOrCreate,
+  tryGetByQuery: () => tryGetByQuery
+});
+function parsePopulate(populate) {
+  if (!populate) return [];
+  if (typeof populate === "string") {
+    return populate.split(",").map((p) => p.trim());
+  }
+  if (Array.isArray(populate)) {
+    return populate.map((p) => typeof p === "string" ? p.trim() : p);
+  }
+  return [populate];
+}
+async function getById(Model, id, options = {}) {
+  const query = options.query ? Model.findOne({ _id: id, ...options.query }) : Model.findById(id);
+  if (options.select) query.select(options.select);
+  if (options.populate) query.populate(parsePopulate(options.populate));
+  if (options.lean) query.lean();
+  if (options.session) query.session(options.session);
+  const document = await query.exec();
+  if (!document && options.throwOnNotFound !== false) {
+    throw createError(404, "Document not found");
+  }
+  return document;
+}
+async function getByQuery(Model, query, options = {}) {
+  const mongoQuery = Model.findOne(query);
+  if (options.select) mongoQuery.select(options.select);
+  if (options.populate) mongoQuery.populate(parsePopulate(options.populate));
+  if (options.lean) mongoQuery.lean();
+  if (options.session) mongoQuery.session(options.session);
+  const document = await mongoQuery.exec();
+  if (!document && options.throwOnNotFound !== false) {
+    throw createError(404, "Document not found");
+  }
+  return document;
+}
+async function tryGetByQuery(Model, query, options = {}) {
+  return getByQuery(Model, query, { ...options, throwOnNotFound: false });
+}
+async function getAll(Model, query = {}, options = {}) {
+  let mongoQuery = Model.find(query);
+  if (options.select) mongoQuery = mongoQuery.select(options.select);
+  if (options.populate) mongoQuery = mongoQuery.populate(parsePopulate(options.populate));
+  if (options.sort) mongoQuery = mongoQuery.sort(options.sort);
+  if (options.limit) mongoQuery = mongoQuery.limit(options.limit);
+  if (options.skip) mongoQuery = mongoQuery.skip(options.skip);
+  mongoQuery = mongoQuery.lean(options.lean !== false);
+  if (options.session) mongoQuery = mongoQuery.session(options.session);
+  return mongoQuery.exec();
+}
+async function getOrCreate(Model, query, createData, options = {}) {
+  return Model.findOneAndUpdate(
+    query,
+    { $setOnInsert: createData },
+    {
+      upsert: true,
+      new: true,
+      runValidators: true,
+      session: options.session,
+      ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
+    }
+  );
+}
+async function count(Model, query = {}, options = {}) {
+  return Model.countDocuments(query).session(options.session ?? null);
+}
+async function exists(Model, query, options = {}) {
+  return Model.exists(query).session(options.session ?? null);
+}
+
+// src/actions/update.ts
+var update_exports = {};
+__export(update_exports, {
+  increment: () => increment,
+  pullFromArray: () => pullFromArray,
+  pushToArray: () => pushToArray,
+  update: () => update,
+  updateByQuery: () => updateByQuery,
+  updateMany: () => updateMany,
+  updateWithConstraints: () => updateWithConstraints,
+  updateWithValidation: () => updateWithValidation
+});
+function assertUpdatePipelineAllowed(update2, updatePipeline) {
+  if (Array.isArray(update2) && updatePipeline !== true) {
+    throw createError(
+      400,
+      "Update pipelines (array updates) are disabled by default; pass `{ updatePipeline: true }` to explicitly allow pipeline-style updates."
+    );
+  }
+}
+function parsePopulate2(populate) {
+  if (!populate) return [];
+  if (typeof populate === "string") {
+    return populate.split(",").map((p) => p.trim());
+  }
+  if (Array.isArray(populate)) {
+    return populate.map((p) => typeof p === "string" ? p.trim() : p);
+  }
+  return [populate];
+}
+async function update(Model, id, data, options = {}) {
+  assertUpdatePipelineAllowed(data, options.updatePipeline);
+  const document = await Model.findByIdAndUpdate(id, data, {
+    new: true,
+    runValidators: true,
+    session: options.session,
+    ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
+  }).select(options.select || "").populate(parsePopulate2(options.populate)).lean(options.lean ?? false);
+  if (!document) {
+    throw createError(404, "Document not found");
+  }
+  return document;
+}
+async function updateWithConstraints(Model, id, data, constraints = {}, options = {}) {
+  assertUpdatePipelineAllowed(data, options.updatePipeline);
+  const query = { _id: id, ...constraints };
+  const document = await Model.findOneAndUpdate(query, data, {
+    new: true,
+    runValidators: true,
+    session: options.session,
+    ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
+  }).select(options.select || "").populate(parsePopulate2(options.populate)).lean(options.lean ?? false);
+  return document;
+}
+async function updateWithValidation(Model, id, data, validationOptions = {}, options = {}) {
+  const { buildConstraints, validateUpdate } = validationOptions;
+  assertUpdatePipelineAllowed(data, options.updatePipeline);
+  if (buildConstraints) {
+    const constraints = buildConstraints(data);
+    const document = await updateWithConstraints(Model, id, data, constraints, options);
+    if (document) {
+      return { success: true, data: document };
+    }
+  }
+  const existing = await Model.findById(id).select(options.select || "").lean();
+  if (!existing) {
+    return {
+      success: false,
+      error: {
+        code: 404,
+        message: "Document not found"
+      }
+    };
+  }
+  if (validateUpdate) {
+    const validation = validateUpdate(existing, data);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          code: 403,
+          message: validation.message || "Update not allowed",
+          violations: validation.violations
+        }
+      };
+    }
+  }
+  const updated = await update(Model, id, data, options);
+  return { success: true, data: updated };
+}
+async function updateMany(Model, query, data, options = {}) {
+  assertUpdatePipelineAllowed(data, options.updatePipeline);
+  const result = await Model.updateMany(query, data, {
+    runValidators: true,
+    session: options.session,
+    ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
+  });
+  return {
+    matchedCount: result.matchedCount,
+    modifiedCount: result.modifiedCount
+  };
+}
+async function updateByQuery(Model, query, data, options = {}) {
+  assertUpdatePipelineAllowed(data, options.updatePipeline);
+  const document = await Model.findOneAndUpdate(query, data, {
+    new: true,
+    runValidators: true,
+    session: options.session,
+    ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
+  }).select(options.select || "").populate(parsePopulate2(options.populate)).lean(options.lean ?? false);
+  if (!document && options.throwOnNotFound !== false) {
+    throw createError(404, "Document not found");
+  }
+  return document;
+}
+async function increment(Model, id, field, value = 1, options = {}) {
+  return update(Model, id, { $inc: { [field]: value } }, options);
+}
+async function pushToArray(Model, id, field, value, options = {}) {
+  return update(Model, id, { $push: { [field]: value } }, options);
+}
+async function pullFromArray(Model, id, field, value, options = {}) {
+  return update(Model, id, { $pull: { [field]: value } }, options);
+}
+
+// src/actions/delete.ts
+var delete_exports = {};
+__export(delete_exports, {
+  deleteById: () => deleteById,
+  deleteByQuery: () => deleteByQuery,
+  deleteMany: () => deleteMany,
+  restore: () => restore,
+  softDelete: () => softDelete
+});
+async function deleteById(Model, id, options = {}) {
+  const document = await Model.findByIdAndDelete(id).session(options.session ?? null);
+  if (!document) {
+    throw createError(404, "Document not found");
+  }
+  return { success: true, message: "Deleted successfully" };
+}
+async function deleteMany(Model, query, options = {}) {
+  const result = await Model.deleteMany(query).session(options.session ?? null);
+  return {
+    success: true,
+    count: result.deletedCount,
+    message: "Deleted successfully"
+  };
+}
+async function deleteByQuery(Model, query, options = {}) {
+  const document = await Model.findOneAndDelete(query).session(options.session ?? null);
+  if (!document && options.throwOnNotFound !== false) {
+    throw createError(404, "Document not found");
+  }
+  return { success: true, message: "Deleted successfully" };
+}
+async function softDelete(Model, id, options = {}) {
+  const document = await Model.findByIdAndUpdate(
+    id,
+    {
+      deleted: true,
+      deletedAt: /* @__PURE__ */ new Date(),
+      deletedBy: options.userId
+    },
+    { new: true, session: options.session }
+  );
+  if (!document) {
+    throw createError(404, "Document not found");
+  }
+  return { success: true, message: "Soft deleted successfully" };
+}
+async function restore(Model, id, options = {}) {
+  const document = await Model.findByIdAndUpdate(
+    id,
+    {
+      deleted: false,
+      deletedAt: null,
+      deletedBy: null
+    },
+    { new: true, session: options.session }
+  );
+  if (!document) {
+    throw createError(404, "Document not found");
+  }
+  return { success: true, message: "Restored successfully" };
+}
+
+// src/actions/aggregate.ts
+var aggregate_exports = {};
+__export(aggregate_exports, {
+  aggregate: () => aggregate,
+  aggregatePaginate: () => aggregatePaginate,
+  average: () => average,
+  countBy: () => countBy,
+  distinct: () => distinct,
+  facet: () => facet,
+  groupBy: () => groupBy,
+  lookup: () => lookup,
+  minMax: () => minMax,
+  sum: () => sum,
+  unwind: () => unwind
+});
+async function aggregate(Model, pipeline, options = {}) {
+  const aggregation = Model.aggregate(pipeline);
+  if (options.session) {
+    aggregation.session(options.session);
+  }
+  return aggregation.exec();
+}
+async function aggregatePaginate(Model, pipeline, options = {}) {
+  const page = parseInt(String(options.page || 1), 10);
+  const limit = parseInt(String(options.limit || 10), 10);
+  const skip = (page - 1) * limit;
+  const SAFE_LIMIT = 1e3;
+  if (limit > SAFE_LIMIT) {
+    console.warn(
+      `[mongokit] Large aggregation limit (${limit}). $facet results must be <16MB. Consider using Repository.aggregatePaginate() for safer handling of large datasets.`
+    );
+  }
+  const facetPipeline = [
+    ...pipeline,
+    {
+      $facet: {
+        docs: [{ $skip: skip }, { $limit: limit }],
+        total: [{ $count: "count" }]
+      }
+    }
+  ];
+  const aggregation = Model.aggregate(facetPipeline);
+  if (options.session) {
+    aggregation.session(options.session);
+  }
+  const [result] = await aggregation.exec();
+  const docs = result.docs || [];
+  const total = result.total[0]?.count || 0;
+  const pages = Math.ceil(total / limit);
+  return {
+    docs,
+    total,
+    page,
+    limit,
+    pages,
+    hasNext: page < pages,
+    hasPrev: page > 1
+  };
+}
+async function groupBy(Model, field, options = {}) {
+  const pipeline = [
+    { $group: { _id: `$${field}`, count: { $sum: 1 } } },
+    { $sort: { count: -1 } }
+  ];
+  if (options.limit) {
+    pipeline.push({ $limit: options.limit });
+  }
+  return aggregate(Model, pipeline, options);
+}
+async function countBy(Model, field, query = {}, options = {}) {
+  const pipeline = [];
+  if (Object.keys(query).length > 0) {
+    pipeline.push({ $match: query });
+  }
+  pipeline.push(
+    { $group: { _id: `$${field}`, count: { $sum: 1 } } },
+    { $sort: { count: -1 } }
+  );
+  return aggregate(Model, pipeline, options);
+}
+async function lookup(Model, lookupOptions) {
+  const { from, localField, foreignField, as, pipeline = [], let: letVars, query = {}, options = {} } = lookupOptions;
+  const aggPipeline = [];
+  if (Object.keys(query).length > 0) {
+    aggPipeline.push({ $match: query });
+  }
+  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 = {}) {
+  const pipeline = [
+    {
+      $unwind: {
+        path: `$${field}`,
+        preserveNullAndEmptyArrays: options.preserveEmpty !== false
+      }
+    }
+  ];
+  return aggregate(Model, pipeline, { session: options.session });
+}
+async function facet(Model, facets, options = {}) {
+  const pipeline = [{ $facet: facets }];
+  return aggregate(Model, pipeline, options);
+}
+async function distinct(Model, field, query = {}, options = {}) {
+  return Model.distinct(field, query).session(options.session ?? null);
+}
+async function sum(Model, field, query = {}, options = {}) {
+  const pipeline = [];
+  if (Object.keys(query).length > 0) {
+    pipeline.push({ $match: query });
+  }
+  pipeline.push({
+    $group: {
+      _id: null,
+      total: { $sum: `$${field}` }
+    }
+  });
+  const result = await aggregate(Model, pipeline, options);
+  return result[0]?.total || 0;
+}
+async function average(Model, field, query = {}, options = {}) {
+  const pipeline = [];
+  if (Object.keys(query).length > 0) {
+    pipeline.push({ $match: query });
+  }
+  pipeline.push({
+    $group: {
+      _id: null,
+      average: { $avg: `$${field}` }
+    }
+  });
+  const result = await aggregate(Model, pipeline, options);
+  return result[0]?.average || 0;
+}
+async function minMax(Model, field, query = {}, options = {}) {
+  const pipeline = [];
+  if (Object.keys(query).length > 0) {
+    pipeline.push({ $match: query });
+  }
+  pipeline.push({
+    $group: {
+      _id: null,
+      min: { $min: `$${field}` },
+      max: { $max: `$${field}` }
+    }
+  });
+  const result = await aggregate(Model, pipeline, options);
+  return result[0] || { min: null, max: null };
+}
+
+export { actions_exports, aggregate, aggregate_exports, count, deleteById, delete_exports, distinct, exists, getById, getByQuery, getOrCreate, read_exports, update, update_exports };

package/dist/chunks/chunk-VJXDGP3C.js

@@ -0,0 +1,14 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/utils/error.ts
+function createError(status, message) {
+  const error = new Error(message);
+  error.status = status;
+  return error;
+}
+
+export { __export, createError };

package/dist/{index-CkwbNdpJ.d.ts → index-C2NCVxJK.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, y as CreateOptions, k as ObjectId, x as OperationOptions, S as SelectSpec, e as PopulateSpec, f as SortSpec, l as UpdateOptions, E as UpdateWithValidationResult, B as UpdateManyResult, z as DeleteResult, a6 as GroupResult, a7 as MinMaxResult } from './types-DA0rs2Jh.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 };