@classytic/mongokit 3.1.6 → 3.2.0

package/README.md

@@ -12,9 +12,10 @@
 - **Zero dependencies** - Only Mongoose as peer dependency
 - **Smart pagination** - Auto-detects offset vs cursor-based
 - **Event-driven** - Pre/post hooks for all operations
-- **12 built-in plugins** - Caching, soft delete, validation, audit logs, and more
+- **14 built-in plugins** - Caching, soft delete, validation, multi-tenant, observability, and more
+- **Vector search** - MongoDB Atlas `$vectorSearch` with auto-embedding and multimodal support
 - **TypeScript first** - Full type safety with discriminated unions
-- **410+ passing tests** - Battle-tested and production-ready
+- **547 passing tests** - Battle-tested and production-ready
 
 ## Installation
 
@@ -22,7 +23,7 @@
 npm install @classytic/mongokit mongoose
 ```
 
-> Supports Mongoose `^8.0.0` and `^9.0.0`
+> Supports Mongoose `^9.0.0`
 
 ## Quick Start
 
@@ -186,6 +187,8 @@ const repo = new Repository(UserModel, [
 | `batchOperationsPlugin()` | Adds `updateMany`, `deleteMany` |
 | `aggregateHelpersPlugin()` | Adds `groupBy`, `sum`, `average`, etc. |
 | `subdocumentPlugin()` | Manage subdocument arrays |
+| `multiTenantPlugin(opts)` | Auto-inject tenant isolation on all operations |
+| `observabilityPlugin(opts)` | Operation timing, metrics, slow query detection |
 
 ### Soft Delete
 
@@ -297,6 +300,88 @@ const repo = new Repository(UserModel, [
 ]);
 ```
 
+### Multi-Tenant
+
+```javascript
+import { multiTenantPlugin } from '@classytic/mongokit';
+
+const repo = new Repository(UserModel, [
+  multiTenantPlugin({
+    tenantField: 'organizationId',
+    contextKey: 'organizationId',  // reads from context
+    required: true,
+  })
+]);
+
+// All operations are automatically scoped to the tenant
+const users = await repo.getAll({ organizationId: 'org_123' });
+await repo.update(userId, { name: 'New' }, { organizationId: 'org_123' });
+// Cross-tenant update/delete is blocked — returns "not found"
+```
+
+### Observability
+
+```javascript
+import { observabilityPlugin } from '@classytic/mongokit';
+
+const repo = new Repository(UserModel, [
+  observabilityPlugin({
+    onMetric: (metric) => {
+      // Send to DataDog, New Relic, OpenTelemetry, etc.
+      statsd.histogram(`mongokit.${metric.operation}`, metric.duration);
+    },
+    slowThresholdMs: 200,  // log operations slower than 200ms
+  })
+]);
+```
+
+### Vector Search (Atlas)
+
+```javascript
+import { vectorPlugin } from '@classytic/mongokit/ai';
+
+const repo = new Repository(ProductModel, [
+  methodRegistryPlugin(),
+  vectorPlugin({
+    fields: [{
+      path: 'embedding',
+      index: 'vector_index',
+      dimensions: 1536,
+      sourceFields: ['title', 'description'],
+    }],
+    embedFn: async ({ text }) =>
+      openai.embeddings.create({ input: text, model: 'text-embedding-3-small' })
+        .then(r => r.data[0].embedding),
+    autoEmbed: true,
+    onEmbedError: (err) => console.warn('Embed failed:', err.message),
+  }),
+]);
+
+// Search by text (auto-embeds the query)
+const results = await repo.searchSimilar({ query: 'running shoes', limit: 10 });
+
+// Search by vector directly
+const results = await repo.searchSimilar({ query: [0.1, 0.2, ...], limit: 5 });
+
+// Embed manually
+const vector = await repo.embed('some text');
+```
+
+### Logging
+
+```javascript
+import { configureLogger } from '@classytic/mongokit';
+
+// Silence all internal warnings
+configureLogger(false);
+
+// Custom logger
+configureLogger({
+  warn: (msg, ...args) => myLogger.warn(msg, ...args),
+  debug: (msg, ...args) => myLogger.debug(msg, ...args),
+});
+```
+
 ### MongoDB Operations Plugin
 
 The `mongoOperationsPlugin` adds MongoDB-specific atomic operations like `increment`, `upsert`, `pushToArray`, etc.
@@ -764,7 +849,7 @@ Extending Repository works exactly the same with Mongoose 8 and 9. The package:
 - Uses its own event system (not Mongoose middleware)
 - Defines its own `FilterQuery` type (unaffected by Mongoose 9 rename)
 - Properly gates update pipelines (safe for Mongoose 9's stricter defaults)
-- All 194 tests pass on both Mongoose 8 and 9
+- All 547 tests pass on Mongoose 9
 
 ## License
 

package/dist/actions/index.d.ts

@@ -1,3 +1,3 @@
-export { b as aggregate, c as create, _ as deleteActions, r as read, u as update } from '../index-BXSSv1pW.js';
+export { b as aggregate, c as create, _ as deleteActions, r as read, u as update } from '../index-BDn5fSTE.js';
 import 'mongoose';
-import '../types-B5Uv6Ak7.js';
+import '../types-Jni1KgkP.js';

package/dist/actions/index.js

@@ -1,3 +1,5 @@
-export { aggregate_exports as aggregate, delete_exports as deleteActions, read_exports as read, update_exports as update } from '../chunks/chunk-SAKSLT47.js';
-export { create_exports as create } from '../chunks/chunk-CF6FLC2G.js';
-import '../chunks/chunk-VJXDGP3C.js';
+export { aggregate_exports as aggregate, delete_exports as deleteActions, read_exports as read, update_exports as update } from '../chunks/chunk-VWKIKZYF.js';
+export { create_exports as create } from '../chunks/chunk-I7CWNAJB.js';
+import '../chunks/chunk-URLJFIR7.js';
+import '../chunks/chunk-JWUAVZ3L.js';
+import '../chunks/chunk-WSFCRVEQ.js';

package/dist/ai/index.d.ts

@@ -0,0 +1,175 @@
+import { ClientSession, PipelineStage } from 'mongoose';
+import { g as Plugin } from '../types-Jni1KgkP.js';
+
+/**
+ * AI/Vector Search Type Definitions
+ *
+ * Types for vector embedding storage, search, and similarity operations.
+ * Requires MongoDB Atlas for `$vectorSearch` aggregation.
+ */
+
+/** 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;
+}
+
+/**
+ * Vector Search Plugin
+ *
+ * Adds semantic similarity search to any repository using MongoDB Atlas Vector Search.
+ * Supports auto-embedding on write, text-to-vector search, and scored results.
+ *
+ * **Requires MongoDB Atlas** — `$vectorSearch` is an Atlas-only aggregation stage.
+ * Running on standalone or self-hosted MongoDB will throw an
+ * `Unrecognized pipeline stage name: '$vectorSearch'` error.
+ *
+ * @example
+ * ```typescript
+ * import { vectorPlugin } from '@classytic/mongokit/ai';
+ *
+ * // Text-only (OpenAI)
+ * const repo = new Repository(Product, [
+ *   methodRegistryPlugin(),
+ *   vectorPlugin({
+ *     fields: [{ path: 'embedding', index: 'vec_idx', dimensions: 1536, similarity: 'cosine', sourceFields: ['title', 'description'] }],
+ *     embedFn: async ({ text }) => openai.embeddings.create({ input: text!, model: 'text-embedding-3-small' }).then(r => r.data[0].embedding),
+ *     autoEmbed: true,
+ *   }),
+ * ]);
+ *
+ * // Multimodal (Jina CLIP v3 — text + images in one call)
+ * const repo = new Repository(Product, [
+ *   methodRegistryPlugin(),
+ *   vectorPlugin({
+ *     fields: [{ path: 'embedding', index: 'vec_idx', dimensions: 1024, similarity: 'cosine', sourceFields: ['title'], mediaFields: ['imageUrl'] }],
+ *     embedFn: async ({ text, image }) => jina.embed({ input: [{ text, image }] }).then(r => r.data[0].embedding),
+ *     autoEmbed: true,
+ *   }),
+ * ]);
+ *
+ * // Search by text
+ * const results = await repo.searchSimilar({ query: 'running shoes', limit: 10 });
+ *
+ * // Search by image + text (multimodal)
+ * const results = await repo.searchSimilar({ query: { text: 'red sneakers', image: 'https://...' }, limit: 10 });
+ *
+ * // Search by vector directly
+ * const results = await repo.searchSimilar({ query: [0.1, 0.2, ...], limit: 5 });
+ * ```
+ */
+
+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;
+
+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.js

@@ -0,0 +1,206 @@
+import '../chunks/chunk-WSFCRVEQ.js';
+
+// src/ai/vector.plugin.ts
+var MAX_NUM_CANDIDATES = 1e4;
+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];
+}
+function toEmbeddingInput(query) {
+  return typeof query === "string" ? { text: query } : query;
+}
+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];
+    return void 0;
+  }, obj);
+}
+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;
+}
+function hasContent(input) {
+  return !!(input.text?.trim() || input.image || input.audio || input.media && Object.keys(input.media).length);
+}
+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 }
+    }
+  });
+  const needsScore = params.includeScore !== false || params.minScore != null;
+  if (needsScore) {
+    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;
+}
+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");
+          }
+          const input = toEmbeddingInput(params.query);
+          queryVector = await embedFn(input);
+        }
+        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);
+        const results = await agg.exec();
+        return results.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;
+          }
+        });
+      }
+    }
+  };
+}
+
+export { buildVectorSearchPipeline, vectorPlugin };

package/dist/chunks/{chunk-M2XHQGZB.js → chunk-44KXLGPO.js}

@@ -1,4 +1,4 @@
-import { createError } from './chunk-VJXDGP3C.js';
+import { createError } from './chunk-JWUAVZ3L.js';
 import mongoose from 'mongoose';
 
 function encodeCursor(doc, primaryField, sort, version = 1) {
@@ -18,6 +18,13 @@ function decodeCursor(token) {
   try {
     const json = Buffer.from(token, "base64").toString("utf-8");
     const payload = JSON.parse(json);
+    if (!payload || typeof payload !== "object" || !("v" in payload) || !("t" in payload) || !("id" in payload) || !("idType" in payload) || !payload.sort || typeof payload.sort !== "object" || typeof payload.ver !== "number") {
+      throw new Error("Malformed cursor payload");
+    }
+    const VALID_TYPES = ["date", "objectid", "boolean", "number", "string", "null", "unknown"];
+    if (!VALID_TYPES.includes(payload.t) || !VALID_TYPES.includes(payload.idType)) {
+      throw new Error("Invalid cursor value type");
+    }
     return {
       value: rehydrateValue(payload.v, payload.t),
       id: rehydrateValue(payload.id, payload.idType),
@@ -41,11 +48,13 @@ function validateCursorVersion(cursorVersion, expectedVersion) {
   }
 }
 function serializeValue(value) {
+  if (value === null || value === void 0) return null;
   if (value instanceof Date) return value.toISOString();
   if (value instanceof mongoose.Types.ObjectId) return value.toString();
   return value;
 }
 function getValueType(value) {
+  if (value === null || value === void 0) return "null";
   if (value instanceof Date) return "date";
   if (value instanceof mongoose.Types.ObjectId) return "objectid";
   if (typeof value === "boolean") return "boolean";
@@ -54,6 +63,7 @@ function getValueType(value) {
   return "unknown";
 }
 function rehydrateValue(serialized, type) {
+  if (type === "null" || serialized === null) return null;
   switch (type) {
     case "date":
       return new Date(serialized);
@@ -113,6 +123,23 @@ function buildKeysetFilter(baseFilters, sort, cursorValue, cursorId) {
   const primaryField = Object.keys(sort).find((k) => k !== "_id") || "_id";
   const direction = sort[primaryField];
   const operator = direction === 1 ? "$gt" : "$lt";
+  if (cursorValue === null || cursorValue === void 0) {
+    if (direction === 1) {
+      return {
+        ...baseFilters,
+        $or: [
+          { [primaryField]: null, _id: { $gt: cursorId } },
+          { [primaryField]: { $ne: null } }
+        ]
+      };
+    } else {
+      return {
+        ...baseFilters,
+        [primaryField]: null,
+        _id: { $lt: cursorId }
+      };
+    }
+  }
   return {
     ...baseFilters,
     $or: [