@classytic/mongokit 3.3.2 → 3.4.1

package/dist/sort-C-BJEWUZ.mjs

@@ -0,0 +1,57 @@
+import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
+//#region src/pagination/utils/sort.ts
+var sort_exports = /* @__PURE__ */ __exportAll({
+	getPrimaryField: () => getPrimaryField,
+	normalizeSort: () => normalizeSort,
+	validateKeysetSort: () => validateKeysetSort
+});
+/**
+* Normalizes sort object to ensure stable key order
+* Primary fields first, _id last (not alphabetical)
+*
+* @param sort - Sort specification
+* @returns Normalized sort with stable key order
+*/
+function normalizeSort(sort) {
+	const normalized = {};
+	Object.keys(sort).forEach((key) => {
+		if (key !== "_id") normalized[key] = sort[key];
+	});
+	if (sort._id !== void 0) normalized._id = sort._id;
+	return normalized;
+}
+/**
+* Validates and normalizes sort for keyset pagination
+* Auto-adds _id tie-breaker if needed
+* Ensures _id direction matches primary field
+*
+* @param sort - Sort specification
+* @returns Validated and normalized sort
+* @throws Error if sort is invalid for keyset pagination
+*/
+function validateKeysetSort(sort) {
+	const keys = Object.keys(sort);
+	if (keys.length === 0) throw new Error("Keyset pagination requires at least one sort field");
+	if (keys.length === 1 && keys[0] === "_id") return normalizeSort(sort);
+	for (const key of keys) if (sort[key] !== 1 && sort[key] !== -1) throw new Error(`Invalid sort direction for "${key}": must be 1 or -1, got ${sort[key]}`);
+	const nonIdKeys = keys.filter((k) => k !== "_id");
+	const primaryDirection = sort[nonIdKeys[0]];
+	for (const key of nonIdKeys) if (sort[key] !== primaryDirection) throw new Error("All sort fields must share the same direction for keyset pagination");
+	if (keys.includes("_id") && sort._id !== primaryDirection) throw new Error("_id direction must match primary field direction");
+	if (!keys.includes("_id")) return normalizeSort({
+		...sort,
+		_id: primaryDirection
+	});
+	return normalizeSort(sort);
+}
+/**
+* Extracts primary sort field (first non-_id field)
+*
+* @param sort - Sort specification
+* @returns Primary field name
+*/
+function getPrimaryField(sort) {
+	return Object.keys(sort).find((k) => k !== "_id") || "_id";
+}
+//#endregion
+export { sort_exports as n, validateKeysetSort as r, getPrimaryField as t };

package/dist/{types-pVY0w1Pp.d.mts → types-COINbsdL.d.mts}

@@ -1,4 +1,4 @@
-import * as mongoose$1 from "mongoose";
+import * as _$mongoose from "mongoose";
 import { ClientSession, Document, Model, PipelineStage, PopulateOptions, Types } from "mongoose";
 
 //#region src/query/LookupBuilder.d.ts
@@ -13,6 +13,8 @@ interface LookupOptions {
   as?: string;
   /** Whether to unwrap array to single object */
   single?: boolean;
+  /** Field selection on the joined collection (shorthand for $project pipeline) */
+  select?: string | Record<string, 0 | 1>;
   /** Additional pipeline to run on the joined collection */
   pipeline?: PipelineStage[];
   /** Optional let variables for pipeline */
@@ -76,6 +78,11 @@ declare class LookupBuilder {
    * Allows referencing local document fields in the pipeline
    */
   let(variables: Record<string, string>): this;
+  /**
+   * Control pipeline sanitization (default: true)
+   * Set to false for auto-generated pipelines that are known safe
+   */
+  sanitize(enabled: boolean): this;
   /**
    * Build the $lookup aggregation stage(s)
    * Returns an array of pipeline stages including $lookup and optional $unwind
@@ -451,7 +458,7 @@ interface IResponseFormatter {
 //#endregion
 //#region src/types.d.ts
 /** Read Preference Type for replica sets */
-type ReadPreferenceType = "primary" | "primaryPreferred" | "secondary" | "secondaryPreferred" | "nearest" | (string & {});
+type ReadPreferenceType = 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest' | (string & {});
 /** Re-export mongoose ObjectId */
 type ObjectId = Types.ObjectId;
 /** Generic document type */
@@ -514,10 +521,10 @@ type NonNullableFields<T> = { [K in keyof T]: NonNullable<T[K]> };
 /**
  * Create/Update input types from document
  */
-type CreateInput<TDoc> = Omit<TDoc, "_id" | "createdAt" | "updatedAt" | "__v">;
-type UpdateInput<TDoc> = Partial<Omit<TDoc, "_id" | "createdAt" | "__v">>;
+type CreateInput<TDoc> = Omit<TDoc, '_id' | 'createdAt' | 'updatedAt' | '__v'>;
+type UpdateInput<TDoc> = Partial<Omit<TDoc, '_id' | 'createdAt' | '__v'>>;
 /** Hook execution mode */
-type HookMode = "sync" | "async";
+type HookMode = 'sync' | 'async';
 /** Repository options */
 interface RepositoryOptions {
   /** Whether repository event hooks are awaited */
@@ -538,10 +545,21 @@ interface PaginationConfig {
   /** Use estimatedDocumentCount for faster counts on large collections */
   useEstimatedCount?: boolean;
 }
+/** MongoDB collation options for locale-aware string comparison */
+interface CollationOptions {
+  locale: string;
+  caseLevel?: boolean;
+  caseFirst?: 'upper' | 'lower' | 'off';
+  strength?: 1 | 2 | 3 | 4 | 5;
+  numericOrdering?: boolean;
+  alternate?: 'non-ignorable' | 'shifted';
+  maxVariable?: 'punct' | 'space';
+  backwards?: boolean;
+}
 /** Base pagination options */
 interface BasePaginationOptions {
   /** Pagination mode (explicit override) */
-  mode?: "offset" | "keyset";
+  mode?: 'offset' | 'keyset';
   /** MongoDB query filters */
   filters?: FilterQuery<AnyDocument>;
   /** Sort specification */
@@ -562,13 +580,15 @@ interface BasePaginationOptions {
   maxTimeMS?: number;
   /** Read preference for replica sets (e.g. 'secondaryPreferred') */
   readPreference?: ReadPreferenceType;
+  /** Collation for locale-aware string comparison and case-insensitive sorting */
+  collation?: CollationOptions;
 }
 /** Offset pagination options */
 interface OffsetPaginationOptions extends BasePaginationOptions {
   /** Page number (1-indexed) */
   page?: number;
   /** Count strategy for filtered queries (default: 'exact') */
-  countStrategy?: "exact" | "estimated" | "none";
+  countStrategy?: 'exact' | 'estimated' | 'none';
 }
 /** Keyset (cursor) pagination options */
 interface KeysetPaginationOptions extends BasePaginationOptions {
@@ -591,17 +611,19 @@ interface AggregatePaginationOptions {
   hint?: string | Record<string, 1 | -1>;
   /** Maximum execution time in milliseconds */
   maxTimeMS?: number;
-  /** Count strategy (default: 'exact' via $facet) */
-  countStrategy?: "exact" | "estimated" | "none";
+  /** Count strategy (default: 'exact' via $facet).
+   * 'estimated' is accepted but treated as 'exact' in aggregation context
+   * since estimatedDocumentCount is not available inside pipelines. */
+  countStrategy?: 'exact' | 'estimated' | 'none';
   /** Pagination mode (reserved for API consistency) */
-  mode?: "offset";
+  mode?: 'offset';
   /** Read preference for replica sets (e.g. 'secondaryPreferred') */
   readPreference?: ReadPreferenceType;
 }
 /** Offset pagination result */
 interface OffsetPaginationResult<T = unknown> {
   /** Pagination method used */
-  method: "offset";
+  method: 'offset';
   /** Array of documents */
   docs: T[];
   /** Current page number */
@@ -622,7 +644,7 @@ interface OffsetPaginationResult<T = unknown> {
 /** Keyset pagination result */
 interface KeysetPaginationResult<T = unknown> {
   /** Pagination method used */
-  method: "keyset";
+  method: 'keyset';
   /** Array of documents */
   docs: T[];
   /** Documents per page */
@@ -635,7 +657,7 @@ interface KeysetPaginationResult<T = unknown> {
 /** Aggregate pagination result */
 interface AggregatePaginationResult<T = unknown> {
   /** Pagination method used */
-  method: "aggregate";
+  method: 'aggregate';
   /** Array of documents */
   docs: T[];
   /** Current page number */
@@ -670,7 +692,7 @@ interface OperationOptions {
   /** Additional query filters (e.g., for soft delete) */
   query?: Record<string, unknown>;
   /** Read preference for replica sets (e.g. 'secondaryPreferred') */
-  readPreference?: "primary" | "primaryPreferred" | "secondary" | "secondaryPreferred" | "nearest" | string;
+  readPreference?: 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest' | string;
 }
 /** withTransaction options */
 interface WithTransactionOptions {
@@ -679,7 +701,7 @@ interface WithTransactionOptions {
   /** Optional hook to observe fallback triggers */
   onFallback?: (error: Error) => void;
   /** MongoDB transaction options (readConcern, writeConcern, readPreference, maxCommitTimeMS) */
-  transactionOptions?: mongoose$1.mongo.TransactionOptions;
+  transactionOptions?: _$mongoose.mongo.TransactionOptions;
 }
 /** Create operation options */
 interface CreateOptions {
@@ -726,7 +748,7 @@ type UpdateWithValidationResult<T> = {
   error: {
     code: number;
     message: string;
-    violations?: ValidationResult["violations"];
+    violations?: ValidationResult['violations'];
   };
 };
 /** User context for operations */
@@ -777,13 +799,13 @@ interface RepositoryContext {
   /** Search query string */
   search?: string;
   /** Pagination mode */
-  mode?: "offset" | "keyset";
+  mode?: 'offset' | 'keyset';
   /** Query hint */
   hint?: string | Record<string, 1 | -1>;
   /** Maximum execution time in milliseconds */
   maxTimeMS?: number;
   /** Count strategy for offset pagination */
-  countStrategy?: "exact" | "estimated" | "none";
+  countStrategy?: 'exact' | 'estimated' | 'none';
   /** Whether this is a soft delete operation (set by softDeletePlugin) */
   softDeleted?: boolean;
   /** Include soft-deleted documents in queries */
@@ -831,16 +853,22 @@ interface RepositoryInstance {
   removeAllListeners(event?: string): this;
   emit(event: string, data: unknown): void;
   emitAsync(event: string, data: unknown): Promise<void>;
-  registerMethod?(name: string, fn: Function): void;
+  registerMethod?(name: string, fn: (...args: any[]) => any): void;
   hasMethod?(name: string): boolean;
+  _buildContext(operation: string, options: Record<string, unknown>): Promise<RepositoryContext>;
+  _handleError(error: Error): HttpError;
+  update(id: string | ObjectId, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+  aggregate(pipeline: PipelineStage[], options?: Record<string, unknown>): Promise<unknown[]>;
+  getByQuery(query: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+  _executeQuery<T>(buildQuery: (Model: Model<any>) => Promise<T>): Promise<T>;
   [key: string]: unknown;
 }
 /** Repository operation names */
-type RepositoryOperation = "create" | "createMany" | "update" | "updateMany" | "delete" | "deleteMany" | "getById" | "getByQuery" | "getAll" | "getOrCreate" | "count" | "exists" | "distinct" | "aggregate" | "aggregatePaginate" | "lookupPopulate" | "bulkWrite";
+type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'delete' | 'deleteMany' | 'getById' | 'getByQuery' | 'getAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'lookupPopulate' | 'bulkWrite';
 /** Event lifecycle phases */
-type EventPhase = "before" | "after" | "error";
+type EventPhase = 'before' | 'after' | 'error';
 /** Repository event names (generated from template literals) */
-type RepositoryEvent = `${EventPhase}:${RepositoryOperation}` | "method:registered" | "error:hook";
+type RepositoryEvent = `${EventPhase}:${RepositoryOperation}` | 'method:registered' | 'error:hook';
 /**
  * Type-safe event handler map
  *
@@ -890,7 +918,7 @@ interface SchemaBuilderOptions {
   /** Strict additional properties (default: false) */
   strictAdditionalProperties?: boolean;
   /** Date format: 'date' | 'datetime' */
-  dateAs?: "date" | "datetime";
+  dateAs?: 'date' | 'datetime';
   /** Create schema options */
   create?: {
     /** Fields to omit from create schema */omitFields?: string[]; /** Override required status */
@@ -940,7 +968,7 @@ interface CrudSchemas {
 }
 /** Decoded cursor */
 interface DecodedCursor {
-  /** Primary sort field value (rehydrated) */
+  /** Primary sort field value (rehydrated) — legacy compat */
   value: unknown;
   /** Document ID (rehydrated) */
   id: ObjectId | string;
@@ -948,13 +976,15 @@ interface DecodedCursor {
   sort: SortSpec;
   /** Cursor version */
   version: number;
+  /** All sort field values (rehydrated) — for compound sort */
+  values?: Record<string, unknown>;
 }
 /** Validator definition */
 interface ValidatorDefinition {
   /** Validator name */
   name: string;
   /** Operations to apply validator to */
-  operations?: Array<"create" | "createMany" | "update" | "delete">;
+  operations?: Array<'create' | 'createMany' | 'update' | 'delete'>;
   /** Validation function */
   validate: (context: RepositoryContext, repo?: RepositoryInstance) => void | Promise<void>;
 }
@@ -971,7 +1001,7 @@ interface Logger {
   debug?(message: string, meta?: Record<string, unknown>): void;
 }
 /** Filter mode for soft delete queries */
-type SoftDeleteFilterMode = "null" | "exists";
+type SoftDeleteFilterMode = 'null' | 'exists';
 /** Soft delete plugin options */
 interface SoftDeleteOptions {
   /** Field name for deletion timestamp (default: 'deletedAt') */
@@ -1264,4 +1294,4 @@ type AllPluginMethods<TDoc> = {
  */
 type WithPlugins<TDoc, TRepo extends RepositoryInstance = RepositoryInstance> = TRepo & AllPluginMethods<TDoc>;
 //#endregion
-export { SchemaBuilderOptions as $, KeysetPaginationOptions as A, PaginationResult as B, GroupResult as C, InferRawDoc as D, InferDocument as E, ObjectId as F, PopulateSpec as G, Plugin as H, OffsetPaginationOptions as I, RepositoryEvent as J, ReadPreferenceType as K, OffsetPaginationResult as L, Logger as M, MinMaxResult as N, JsonSchema as O, NonNullableFields as P, RequiredBy as Q, OperationOptions as R, FieldRules as S, LookupOptions as St, HttpError as T, PluginFunction as U, PartialBy as V, PluginType as W, RepositoryOperation as X, RepositoryInstance as Y, RepositoryOptions as Z, DeleteResult as _, IController as _t, AnyModel as a, SortSpec as at, EventPhase as b, IResponseFormatter as bt, CacheOptions as c, UpdateManyResult as ct, CascadeRelation as d, UserContext as dt, SelectSpec as et, CreateInput as f, ValidationChainOptions as ft, DeepPartial as g, WithTransactionOptions as gt, DecodedCursor as h, WithPlugins as ht, AnyDocument as i, SortDirection as it, KeysetPaginationResult as j, KeysOfType as k, CacheStats as l, UpdateOptions as lt, CrudSchemas as m, ValidatorDefinition as mt, AggregatePaginationResult as n, SoftDeleteOptions as nt, CacheAdapter as o, Strict as ot, CreateOptions as p, ValidationResult as pt, RepositoryContext as q, AllPluginMethods as r, SoftDeleteRepository as rt, CacheOperationOptions as s, UpdateInput as st, AggregatePaginationOptions as t, SoftDeleteFilterMode as tt, CascadeOptions as u, UpdateWithValidationResult as ut, EventHandlers as v, IControllerResponse as vt, HookMode as w, FieldPreset as x, LookupBuilder as xt, EventPayload as y, IRequestContext as yt, PaginationConfig as z };
+export { RequiredBy as $, KeysOfType as A, PaginationConfig as B, FieldRules as C, LookupOptions as Ct, InferDocument as D, HttpError as E, NonNullableFields as F, PluginType as G, PartialBy as H, ObjectId as I, RepositoryContext as J, PopulateSpec as K, OffsetPaginationOptions as L, KeysetPaginationResult as M, Logger as N, InferRawDoc as O, MinMaxResult as P, RepositoryOptions as Q, OffsetPaginationResult as R, FieldPreset as S, LookupBuilder as St, HookMode as T, Plugin as U, PaginationResult as V, PluginFunction as W, RepositoryInstance as X, RepositoryEvent as Y, RepositoryOperation as Z, DeepPartial as _, WithTransactionOptions as _t, AnyModel as a, SortDirection as at, EventPayload as b, IRequestContext as bt, CacheOptions as c, UpdateInput as ct, CascadeRelation as d, UpdateWithValidationResult as dt, SchemaBuilderOptions as et, CollationOptions as f, UserContext as ft, DecodedCursor as g, WithPlugins as gt, CrudSchemas as h, ValidatorDefinition as ht, AnyDocument as i, SoftDeleteRepository as it, KeysetPaginationOptions as j, JsonSchema as k, CacheStats as l, UpdateManyResult as lt, CreateOptions as m, ValidationResult as mt, AggregatePaginationResult as n, SoftDeleteFilterMode as nt, CacheAdapter as o, SortSpec as ot, CreateInput as p, ValidationChainOptions as pt, ReadPreferenceType as q, AllPluginMethods as r, SoftDeleteOptions as rt, CacheOperationOptions as s, Strict as st, AggregatePaginationOptions as t, SelectSpec as tt, CascadeOptions as u, UpdateOptions as ut, DeleteResult as v, IController as vt, GroupResult as w, EventPhase as x, IResponseFormatter as xt, EventHandlers as y, IControllerResponse as yt, OperationOptions as z };