@classytic/mongokit 3.2.0 → 3.2.2

package/dist/aggregate-CCHI7F51.d.mts

@@ -0,0 +1,269 @@
+import { C as GroupResult, F as ObjectId, G as PopulateSpec, K as ReadPreferenceType, N as MinMaxResult, R as OperationOptions, St as LookupOptions, _ as DeleteResult, at as SortSpec, ct as UpdateManyResult, et as SelectSpec, i as AnyDocument, lt as UpdateOptions, p as CreateOptions, ut as UpdateWithValidationResult } from "./types-D-gploPr.mjs";
+import { ClientSession, Model, PipelineStage } from "mongoose";
+
+//#region src/actions/create.d.ts
+declare namespace create_d_exports {
+  export { create, createDefault, createMany, upsert };
+}
+/**
+ * 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 namespace read_d_exports {
+  export { count, exists, getAll, getById, getByQuery, getOrCreate, tryGetByQuery };
+}
+/**
+ * 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;
+  readPreference?: ReadPreferenceType;
+}): 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;
+  readPreference?: ReadPreferenceType;
+}): Promise<number>;
+/**
+ * Check if document exists
+ */
+declare function exists(Model: Model<any>, query: Record<string, unknown>, options?: {
+  session?: ClientSession;
+  readPreference?: ReadPreferenceType;
+}): Promise<{
+  _id: unknown;
+} | null>;
+declare namespace update_d_exports {
+  export { increment, pullFromArray, pushToArray, update, updateByQuery, updateMany, updateWithConstraints, updateWithValidation };
+}
+/**
+ * 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 namespace delete_d_exports {
+  export { deleteById, deleteByQuery, deleteMany, restore, softDelete };
+}
+/**
+ * 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 namespace aggregate_d_exports {
+  export { aggregate, aggregatePaginate, average, countBy, distinct, facet, groupBy, lookup, minMax, sum, unwind };
+}
+/**
+ * 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>;
+//#endregion
+export { create_d_exports as a, read_d_exports as i, delete_d_exports as n, update_d_exports as r, aggregate_d_exports as t };

package/dist/ai/index.d.mts

@@ -0,0 +1,125 @@
+import { H as Plugin } from "../types-D-gploPr.mjs";
+import { ClientSession, PipelineStage } from "mongoose";
+
+//#region src/ai/types.d.ts
+/** Supported similarity metrics for vector search */
+type SimilarityMetric = 'cosine' | 'euclidean' | 'dotProduct';
+/** A single piece of content to embed — text, image, or any media */
+interface EmbeddingInput {
+  /** Text content to embed */
+  text?: string;
+  /** Image URL or base64 data (for multimodal models like CLIP, Jina v3) */
+  image?: string;
+  /** Audio URL or base64 data */
+  audio?: string;
+  /** Arbitrary media — for custom model inputs (video frames, PDFs, etc.) */
+  media?: Record<string, unknown>;
+}
+/**
+ * Unified embedding function — receives structured input, returns vector.
+ * Works for text-only, multimodal, or any custom model.
+ *
+ * @example
+ * ```typescript
+ * // Text-only (OpenAI)
+ * const embed: EmbedFn = async ({ text }) =>
+ *   openai.embeddings.create({ input: text!, model: 'text-embedding-3-small' })
+ *     .then(r => r.data[0].embedding);
+ *
+ * // Multimodal (Jina CLIP v3)
+ * const embed: EmbedFn = async ({ text, image }) =>
+ *   jina.embed({ input: [{ text, image }] }).then(r => r.data[0].embedding);
+ *
+ * // Local model
+ * const embed: EmbedFn = async ({ text }) =>
+ *   fetch('http://localhost:11434/api/embeddings', {
+ *     method: 'POST', body: JSON.stringify({ model: 'nomic-embed-text', prompt: text })
+ *   }).then(r => r.json()).then(j => j.embedding);
+ * ```
+ */
+type EmbedFn = (input: EmbeddingInput) => Promise<number[]>;
+/**
+ * Batch embedding function — same contract, multiple inputs at once.
+ * Falls back to sequential EmbedFn calls if not provided.
+ */
+type BatchEmbedFn = (inputs: EmbeddingInput[]) => Promise<number[][]>;
+/** Vector field configuration for a model */
+interface VectorFieldConfig {
+  /** Field path where the vector is stored (e.g., 'embedding') */
+  path: string;
+  /** Atlas Search index name for this field */
+  index: string;
+  /** Number of dimensions in the embedding */
+  dimensions: number;
+  /** Similarity metric used by the index (informational — the index defines this) */
+  similarity?: SimilarityMetric;
+  /** Text source fields to embed from (e.g., ['title', 'description']) */
+  sourceFields?: string[];
+  /** Image/media source fields (e.g., ['imageUrl', 'thumbnailUrl']) */
+  mediaFields?: string[];
+}
+/** Options for vector search operations */
+interface VectorSearchParams {
+  /** Query — vector, text string, or structured multimodal input */
+  query: number[] | string | EmbeddingInput;
+  /** Maximum number of results */
+  limit?: number;
+  /** Candidates to consider (higher = more accurate, slower). Default: limit * 10 */
+  numCandidates?: number;
+  /** Pre-filter documents before vector search */
+  filter?: Record<string, unknown>;
+  /** Use exact KNN instead of approximate (slower but precise) */
+  exact?: boolean;
+  /** Which vector field config to use (default: first configured) */
+  field?: string;
+  /** MongoDB session for transactions */
+  session?: ClientSession;
+  /** Fields to include/exclude in results */
+  project?: Record<string, 0 | 1>;
+  /** Include similarity score in results */
+  includeScore?: boolean;
+  /** Minimum score threshold (0-1 for cosine) */
+  minScore?: number;
+  /** Additional pipeline stages to append after search */
+  postPipeline?: PipelineStage[];
+}
+/** Vector search result with score */
+interface ScoredResult<T = Record<string, unknown>> {
+  /** The matched document */
+  doc: T;
+  /** Similarity score from vector search */
+  score: number;
+}
+/** Options for the vector search plugin */
+interface VectorPluginOptions {
+  /** Vector field configurations */
+  fields: VectorFieldConfig[];
+  /** Unified embedding function (text, image, multimodal) */
+  embedFn?: EmbedFn;
+  /** Batch embedding function for bulk operations */
+  batchEmbedFn?: BatchEmbedFn;
+  /** Auto-generate embeddings on create/update (requires embedFn) */
+  autoEmbed?: boolean;
+  /**
+   * Called when auto-embed fails (e.g., embedding service down).
+   * If provided, the write operation continues without an embedding.
+   * If not provided, the error propagates and blocks the write.
+   */
+  onEmbedError?: (error: Error, doc: unknown) => void;
+}
+//#endregion
+//#region src/ai/vector.plugin.d.ts
+interface VectorMethods {
+  searchSimilar<T = Record<string, unknown>>(params: VectorSearchParams): Promise<ScoredResult<T>[]>;
+  embed(input: EmbeddingInput | string): Promise<number[]>;
+}
+/**
+ * Builds the $vectorSearch pipeline stage
+ */
+declare function buildVectorSearchPipeline(field: VectorFieldConfig, queryVector: number[], params: VectorSearchParams): PipelineStage[];
+/**
+ * Creates the vector search plugin
+ */
+declare function vectorPlugin(options: VectorPluginOptions): Plugin;
+//#endregion
+export { type BatchEmbedFn, type EmbedFn, type EmbeddingInput, type ScoredResult, type SimilarityMetric, type VectorFieldConfig, type VectorMethods, type VectorPluginOptions, type VectorSearchParams, buildVectorSearchPipeline, vectorPlugin };

package/dist/ai/index.mjs

@@ -0,0 +1,203 @@
+//#region src/ai/vector.plugin.ts
+/** Maximum numCandidates allowed by Atlas Vector Search */
+const MAX_NUM_CANDIDATES = 1e4;
+/**
+* Resolves which vector field config to use
+*/
+function resolveField(fields, fieldPath) {
+	if (fieldPath) {
+		const found = fields.find((f) => f.path === fieldPath);
+		if (!found) throw new Error(`[mongokit] Vector field '${fieldPath}' not configured`);
+		return found;
+	}
+	return fields[0];
+}
+/**
+* Normalizes query input to EmbeddingInput
+*/
+function toEmbeddingInput(query) {
+	return typeof query === "string" ? { text: query } : query;
+}
+/**
+* Resolves a potentially dot-notated path from an object (e.g. 'metadata.title')
+*/
+function getNestedValue(obj, path) {
+	if (path in obj) return obj[path];
+	return path.split(".").reduce((cur, key) => {
+		if (cur != null && typeof cur === "object") return cur[key];
+	}, obj);
+}
+/**
+* Builds EmbeddingInput from document source fields
+*/
+function buildInputFromDoc(data, field) {
+	const input = {};
+	if (field.sourceFields?.length) {
+		const text = field.sourceFields.map((f) => getNestedValue(data, f)).filter(Boolean).join(" ");
+		if (text.trim()) input.text = text;
+	}
+	if (field.mediaFields?.length) {
+		const firstImageField = field.mediaFields[0];
+		const imageValue = getNestedValue(data, firstImageField);
+		if (typeof imageValue === "string") input.image = imageValue;
+		if (field.mediaFields.length > 1) {
+			input.media = {};
+			for (const mf of field.mediaFields) {
+				const val = getNestedValue(data, mf);
+				if (val != null) input.media[mf] = val;
+			}
+		}
+	}
+	return input;
+}
+/**
+* Checks if an EmbeddingInput has any content worth embedding
+*/
+function hasContent(input) {
+	return !!(input.text?.trim() || input.image || input.audio || input.media && Object.keys(input.media).length);
+}
+/**
+* Builds the $vectorSearch pipeline stage
+*/
+function buildVectorSearchPipeline(field, queryVector, params) {
+	const limit = params.limit ?? 10;
+	const stages = [];
+	const rawCandidates = params.numCandidates ?? Math.max(limit * 10, 100);
+	const numCandidates = Math.min(Math.max(rawCandidates, limit), MAX_NUM_CANDIDATES);
+	stages.push({ $vectorSearch: {
+		index: field.index,
+		path: field.path,
+		queryVector,
+		numCandidates,
+		limit,
+		...params.filter && { filter: params.filter },
+		...params.exact && { exact: true }
+	} });
+	if (params.includeScore !== false || params.minScore != null) stages.push({ $addFields: { _score: { $meta: "vectorSearchScore" } } });
+	if (params.minScore != null) stages.push({ $match: { _score: { $gte: params.minScore } } });
+	if (params.project) stages.push({ $project: {
+		...params.project,
+		_score: 1
+	} });
+	if (params.postPipeline?.length) stages.push(...params.postPipeline);
+	return stages;
+}
+/**
+* Creates the vector search plugin
+*/
+function vectorPlugin(options) {
+	const { fields, autoEmbed = false } = options;
+	if (!fields?.length) throw new Error("[mongokit] vectorPlugin requires at least one field config");
+	const { embedFn, batchEmbedFn } = options;
+	return {
+		name: "vector",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("[mongokit] vectorPlugin requires methodRegistryPlugin");
+			repo.registerMethod("searchSimilar", async function searchSimilar(params) {
+				const field = resolveField(fields, params.field);
+				let queryVector;
+				if (Array.isArray(params.query)) queryVector = params.query;
+				else {
+					if (!embedFn) throw new Error("[mongokit] Non-vector queries require embedFn in vectorPlugin options");
+					queryVector = await embedFn(toEmbeddingInput(params.query));
+				}
+				if (queryVector.length !== field.dimensions) throw new Error(`[mongokit] Query vector has ${queryVector.length} dimensions, expected ${field.dimensions}`);
+				const pipeline = buildVectorSearchPipeline(field, queryVector, params);
+				const agg = repo.Model.aggregate(pipeline);
+				if (params.session) agg.session(params.session);
+				return (await agg.exec()).map((doc) => {
+					const score = doc._score ?? 0;
+					const { _score, ...rest } = doc;
+					return {
+						doc: rest,
+						score
+					};
+				});
+			});
+			repo.registerMethod("embed", async function embed(input) {
+				if (!embedFn) throw new Error("[mongokit] embed requires embedFn in vectorPlugin options");
+				return embedFn(typeof input === "string" ? { text: input } : input);
+			});
+			if (autoEmbed && embedFn) {
+				const { onEmbedError } = options;
+				const safeEmbed = async (input, doc) => {
+					try {
+						return await embedFn(input);
+					} catch (err) {
+						if (onEmbedError) {
+							onEmbedError(err, doc);
+							return null;
+						}
+						throw err;
+					}
+				};
+				const embedFromSource = async (data, field) => {
+					if (data[field.path] && Array.isArray(data[field.path])) return;
+					const input = buildInputFromDoc(data, field);
+					if (!hasContent(input)) return;
+					const vector = await safeEmbed(input, data);
+					if (vector) data[field.path] = vector;
+				};
+				const embedBatchFromSource = async (dataArray, field) => {
+					const toEmbed = [];
+					for (let i = 0; i < dataArray.length; i++) {
+						const data = dataArray[i];
+						if (data[field.path] && Array.isArray(data[field.path])) continue;
+						const input = buildInputFromDoc(data, field);
+						if (hasContent(input)) toEmbed.push({
+							idx: i,
+							input
+						});
+					}
+					if (!toEmbed.length) return;
+					if (batchEmbedFn) try {
+						const vectors = await batchEmbedFn(toEmbed.map((e) => e.input));
+						for (let i = 0; i < toEmbed.length; i++) dataArray[toEmbed[i].idx][field.path] = vectors[i];
+					} catch (err) {
+						if (onEmbedError) {
+							onEmbedError(err, dataArray);
+							return;
+						}
+						throw err;
+					}
+					else for (const entry of toEmbed) {
+						const vector = await safeEmbed(entry.input, dataArray[entry.idx]);
+						if (vector) dataArray[entry.idx][field.path] = vector;
+					}
+				};
+				repo.on("before:create", async (context) => {
+					if (!context.data) return;
+					for (const field of fields) await embedFromSource(context.data, field);
+				});
+				repo.on("before:createMany", async (context) => {
+					if (!context.dataArray?.length) return;
+					for (const field of fields) await embedBatchFromSource(context.dataArray, field);
+				});
+				repo.on("before:update", async (context) => {
+					if (!context.data) return;
+					const fieldsToEmbed = fields.filter((field) => {
+						const allFields = [...field.sourceFields ?? [], ...field.mediaFields ?? []];
+						return allFields.length > 0 && allFields.some((f) => f in context.data);
+					});
+					if (!fieldsToEmbed.length) return;
+					const existing = await repo.Model.findById(context.id).lean().session(context.session ?? null);
+					if (!existing) return;
+					for (const field of fieldsToEmbed) {
+						const merged = {
+							...existing,
+							...context.data
+						};
+						delete merged[field.path];
+						const input = buildInputFromDoc(merged, field);
+						if (!hasContent(input)) continue;
+						const vector = await safeEmbed(input, merged);
+						if (vector) context.data[field.path] = vector;
+					}
+				});
+			}
+		}
+	};
+}
+
+//#endregion
+export { buildVectorSearchPipeline, vectorPlugin };