@classytic/mongokit 3.41.0 → 3.43.0

package/README.md

@@ -292,6 +292,33 @@ always escapes rather than rejects, so `?search=c++` never 400s. Trusted
 migration/compat tooling can opt into the legacy warn-and-drop behavior with
 `invalidInput: 'drop'`.
 
+### Prefix search (search-as-you-type, indexed)
+
+`searchMode: 'prefix'` finds documents where every query word starts a word of
+`searchFields` (`moh ali` finds "Mohammed Al-Ali"), served by a multikey index
+instead of an unanchored regex scan. The repository writes the normalised word
+tokens into `searchKeysField` (default `_searchKeys`) on every write path.
+Normalisation: lower-case, NFKD with diacritics stripped, Arabic folding
+(tashkeel/tatweel removed, `أ إ آ → ا`, `ى → ي`, `ة → ه`), split on
+whitespace/punctuation.
+
+```ts
+import { rebuildSearchKeys, searchKeysIndex, searchKeysPath } from '@classytic/mongokit';
+
+schema.add({ _searchKeys: searchKeysPath() }); // string[], select: false
+// Serves getAll({ search }) prefix search.
+schema.index(searchKeysIndex().fields, searchKeysIndex().options);
+
+const repo = new Repository(Person, [], {}, { searchMode: 'prefix', searchFields: ['name', 'email'] });
+await rebuildSearchKeys(repo, { onlyMissing: true }); // backfill rows written before
+await repo.getAll({ search: 'moh', page: 1 }); // composes with filters, tenant scope, keyset/offset, counts
+```
+
+Clients highlight with the same rules from the mongoose-free subpath:
+`import { findSearchMatches } from '@classytic/mongokit/search'`. Writes that
+bypass the repository (raw `Model.updateOne`, Better Auth's adapter) write the
+keys with `buildSearchKeys(doc, fields)`.
+
 ## Built-In Plugins
 
 | Plugin | Purpose |
@@ -300,6 +327,7 @@ migration/compat tooling can opt into the legacy warn-and-drop behavior with
 | `multiTenantPlugin` | Tenant scoping and tenant stamping |
 | `softDeletePlugin` | Soft delete, restore, deleted-list queries, TTL |
 | `timestampPlugin` | `createdAt` / `updatedAt` management |
+| `searchKeysPlugin` | Prefix-search keys on every write (auto-installed by `searchMode: 'prefix'`) |
 | `batchOperationsPlugin` | `bulkWrite` and batch helpers |
 | `cachePlugin` | Pluggable read-through cache |
 | `auditLogPlugin` / `auditTrailPlugin` | Audit trails — `auditTrailPlugin({ mode: 'transactional' })` gives session-joined entries that are atomic inside `withTransaction` (compliance-grade); the default `'best-effort'` mode is fire-and-forget observability. Call `ensureAuditTrailReady()` at boot so collection/index creation doesn't happen inside the first transaction |

package/dist/{Repository-DlhPbXlG.mjs → Repository-Dj6xqPxJ.mjs}

@@ -7,6 +7,7 @@ import { i as applyToQuery, n as applyCursorTimeoutMode, r as applyToAggregate,
 import { o as withTransaction, p as resolveMongoCapabilities, s as createTxBoundRepo } from "./transaction-DmiB4k2P.mjs";
 import { _ as resolveCursorSecrets, d as withGroupTiebreak, f as withIdTiebreak, g as attachSignature, i as validateKeysetSort, l as assertOffsetWithinCap, n as getPrimaryField, o as encodeCursor, s as resolveCursorFilter, t as PaginationEngine, u as cursorScope, v as verifySignature } from "./PaginationEngine-DZnkbSrr.mjs";
 import { calculateTotalPages } from "./pagination/utils/limits.mjs";
+import { a as insertValues, c as writeKeys, d as buildSearchKeys, f as prefixSearchFilter, i as fieldValuesOf, n as SearchKeysWriteError, o as keysFromValues, r as analyzeUpdate, s as unresolvedForUpdate, t as SEARCH_KEYS_ERROR_CODES } from "./derive-DRBiegRH.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
 import { a as scopeJoins, r as markGoverned } from "./join-scope-DSAznE8E.mjs";
 import { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, RepositoryBase, bulkUpsertOptionsError, createDistributionGuard, runChunkedArchive, runChunkedPurge, summarizeBulkUpsert, throwIfAborted, validatePluginOrder, withRetry } from "@classytic/repo-core/repository";
@@ -1569,6 +1570,117 @@ async function executeUpserts(model, ops, options) {
 	return results;
 }
 //#endregion
+//#region src/plugins/search-keys.plugin.ts
+/**
+* Search-keys plugin: keeps the `searchMode: 'prefix'` keys field in step with
+* its source fields on EVERY write path, inside the same write.
+*
+*   create / createMany / bulkWrite insertOne / replaceOne → keys of the document
+*   getOrCreate                                            → keys of filter equalities + insert data
+*   update / findOneAndUpdate / claim / claimVersion /
+*   bulkWrite updateOne / bulkUpsert                       → keys of the new values; a write that
+*                                                            sets only SOME search fields reads the
+*                                                            others from the matched document first
+*   updateMany / bulkWrite updateMany                      → keys of the new values; setting only
+*                                                            some search fields is refused (400),
+*                                                            the rest differ per document
+*
+* Caller-supplied values for the keys field are always dropped: the keys are
+* derived, never client-settable. Runs after every default-priority hook, so it
+* sees the payload other plugins (validation, defaults, tenant) produced.
+*
+* `Repository` installs this automatically for `searchMode: 'prefix'`; install
+* it by hand only to keep keys on a repository that searches some other way.
+*
+* Writes that bypass the repository (raw `Model.updateOne`, another driver such
+* as Better Auth's adapter) must write the keys themselves with
+* `buildSearchKeys`, or be repaired with `rebuildSearchKeys`.
+*/
+const isDoc = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** After every default-priority (user) hook: derive from the final payload. */
+const PRIORITY = HOOK_PRIORITY.DEFAULT + 100;
+function searchKeysPlugin(options) {
+	const fields = [...options.fields];
+	const keysField = options.keysField ?? "_searchKeys";
+	if (fields.length === 0) throw new TypeError("[mongokit] searchKeysPlugin: `fields` must name at least one source field");
+	const projection = Object.fromEntries(fields.map((f) => [f, 1]));
+	const stampDoc = (doc) => {
+		if (isDoc(doc)) doc[keysField] = buildSearchKeys(doc, fields);
+	};
+	/** Derive the keys for ONE update in place. `load` reads the matched document's current values. */
+	const deriveOne = async (update, filter, upsert, load) => {
+		if (!isDoc(update) && !Array.isArray(update)) return;
+		const effect = analyzeUpdate(update, filter, fields, keysField);
+		if (!isDoc(update)) return;
+		if (!(Object.keys(effect.updated).length > 0)) {
+			if (upsert && Object.keys(effect.onInsert).length > 0) writeKeys(update, keysField, keysFromValues(insertValues(effect), fields), "$setOnInsert");
+			return;
+		}
+		const missing = unresolvedForUpdate(effect, fields);
+		if (missing.length === 0) {
+			writeKeys(update, keysField, keysFromValues({
+				...effect.pinned,
+				...effect.updated
+			}, fields));
+			return;
+		}
+		if (!load) throw new SearchKeysWriteError(`[mongokit] search keys: a multi-document update sets ${Object.keys(effect.updated).join(", ")} but not ${missing.join(", ")}; the keys would differ per document. Set every search field (${fields.join(", ")}) in this update, or update per document, or call rebuildSearchKeys afterwards`, SEARCH_KEYS_ERROR_CODES.PARTIAL_MULTI_UPDATE);
+		const current = await load();
+		let values;
+		if (current) values = {
+			...fieldValuesOf(current, fields),
+			...effect.pinned,
+			...effect.updated
+		};
+		else if (upsert) values = insertValues(effect);
+		else return;
+		writeKeys(update, keysField, keysFromValues(values, fields));
+	};
+	return {
+		name: "search-keys",
+		apply(repo) {
+			const Model = repo.Model;
+			const findOne = (filter, ctx, sort) => async () => {
+				let q = Model.findOne(filter, projection, { session: ctx.session });
+				if (sort) q = q.sort(sort);
+				return await q.lean();
+			};
+			const byTarget = (ctx) => typeof ctx.loadTarget === "function" ? () => ctx.loadTarget.call(ctx) : void 0;
+			repo.on("before:create", (ctx) => stampDoc(ctx.data), { priority: PRIORITY });
+			repo.on("before:createMany", (ctx) => {
+				for (const doc of ctx.dataArray ?? []) stampDoc(doc);
+			}, { priority: PRIORITY });
+			repo.on("before:getOrCreate", async (ctx) => {
+				if (!isDoc(ctx.data)) return;
+				const effect = analyzeUpdate({ $setOnInsert: ctx.data }, ctx.query, fields, keysField);
+				ctx.data[keysField] = keysFromValues(insertValues(effect), fields);
+			}, { priority: PRIORITY });
+			for (const op of [
+				"update",
+				"claim",
+				"claimVersion"
+			]) repo.on(`before:${op}`, (ctx) => deriveOne(ctx.data, ctx.query, ctx.upsert === true, byTarget(ctx)), { priority: PRIORITY });
+			repo.on("before:findOneAndUpdate", (ctx) => deriveOne(ctx.data, ctx.query, ctx.upsert === true, findOne(ctx.query, ctx, ctx.sort)), { priority: PRIORITY });
+			repo.on("before:updateMany", (ctx) => deriveOne(ctx.data, ctx.query, ctx.upsert === true, void 0), { priority: PRIORITY });
+			const deriveBulk = async (ctx) => {
+				for (const subOp of ctx.operations ?? []) {
+					if (!isDoc(subOp)) continue;
+					const insert = subOp.insertOne;
+					if (insert) stampDoc(insert.document);
+					const replace = subOp.replaceOne;
+					if (replace) stampDoc(replace.replacement);
+					const one = subOp.updateOne;
+					if (one) await deriveOne(one.update, one.filter, one.upsert === true, findOne(one.filter, ctx));
+					const many = subOp.updateMany;
+					if (many) await deriveOne(many.update, many.filter, many.upsert === true, void 0);
+				}
+			};
+			repo.on("before:bulkWrite", deriveBulk, { priority: PRIORITY });
+			repo.on("before:bulkUpsert", deriveBulk, { priority: PRIORITY });
+		}
+	};
+}
+//#endregion
 //#region src/query/AggregationBuilder.ts
 /**
 * Normalize SortSpec to MongoDB's strict format (1 | -1)
@@ -2334,6 +2446,8 @@ var Repository = class extends RepositoryBase {
 	versionField;
 	searchMode;
 	searchFields;
+	/** Field holding the prefix-search keys (`searchMode: 'prefix'`). Default `'_searchKeys'`. */
+	searchKeysField;
 	_hasTextIndex = null;
 	/**
 	* Wrap-style middleware chain. Composed around every `_runOp`
@@ -2381,12 +2495,14 @@ var Repository = class extends RepositoryBase {
 		this.versionField = options.versionField ?? "__v";
 		this.searchMode = options.searchMode ?? "text";
 		this.searchFields = options.searchFields;
+		this.searchKeysField = options.searchKeysField ?? "_searchKeys";
 		this._wireStrictQueryStripDiagnostic(options.warnOnStrictQueryStrip === true);
 		this._checkDistribution = options.distribution ? createDistributionGuard(options.distribution, options.distribution.onMiss ?? ((info) => {
 			warn(`[mongokit] Repository "${this.model}": ${info.operation} filter omits the distribution key "${info.key}" — this fans out across every shard. Include the key, list the op in distribution.exemptOperations, or set onMissingKey: 'off'.`);
 		})) : void 0;
 		this._guardIdAddressed = options.distribution !== void 0 && options.distribution.key !== this.idField;
 		if (this.searchMode === "regex" && (!this.searchFields || this.searchFields.length === 0)) warn(`[mongokit] Repository "${this.model}" configured with searchMode: 'regex' but no searchFields provided. getAll({ search }) will throw until searchFields is set.`);
+		if (this.searchMode === "prefix") plugins = [...plugins, ...this._prefixSearchPlugins(plugins)];
 		for (const plugin of plugins) this.use(plugin);
 		if (options.requirePlugins && options.requirePlugins.length > 0) {
 			const installedNames = new Set(plugins.map((p) => p?.name).filter(Boolean));
@@ -5074,6 +5190,22 @@ var Repository = class extends RepositoryBase {
 		return sort !== "-createdAt" && !!(context.sort ?? params.sort);
 	}
 	/**
+	* `searchMode: 'prefix'` preconditions + its write plugin. Throws when the keys could never
+	* be written (no `searchFields`, or a strict schema that would strip the keys field); warns
+	* when no index includes the keys field (every search would then scan).
+	*/
+	_prefixSearchPlugins(plugins) {
+		const field = this.searchKeysField;
+		if (!this.searchFields || this.searchFields.length === 0) throw new TypeError(`[mongokit] Repository "${this.model}" configured with searchMode: 'prefix' but no searchFields: name the source fields whose words the search keys are built from.`);
+		const schema = this.Model.schema;
+		if (schema.get("strict") !== false && !schema.path(field)) throw new TypeError(`[mongokit] Repository "${this.model}" (searchMode: 'prefix'): the schema has no '${field}' path, so a strict schema would silently strip the search keys. Add it: schema.add({ '${field}': searchKeysPath() }).`);
+		if (!schema.indexes().some((idx) => field in (idx[0] ?? {}))) warn(`[mongokit] Repository "${this.model}" (searchMode: 'prefix'): no index includes '${field}', so every search scans the collection. Declare one: schema.index(searchKeysIndex('${field}').fields).`);
+		return plugins.some((p) => p?.name === "search-keys") ? [] : [searchKeysPlugin({
+			fields: this.searchFields,
+			keysField: field
+		})];
+	}
+	/**
 	* Build the MongoDB query filter with search merged in. Handles text
 	* search ($text), regex search ($or of $regex), and the search-resolver
 	* plugin contract (search already cleared by a before:getAll hook).
@@ -5081,6 +5213,21 @@ var Repository = class extends RepositoryBase {
 	_buildSearchQuery(filters, search) {
 		const query = { ...filters };
 		if (!search) return query;
+		if (this.searchMode === "prefix") {
+			const cond = prefixSearchFilter(String(search), { keysField: this.searchKeysField });
+			if (!cond) return query;
+			const arms = Array.isArray(cond.$and) ? cond.$and : [cond];
+			if (arms.length === 1 && !(this.searchKeysField in query)) return {
+				...query,
+				...cond
+			};
+			const existingAnd = Array.isArray(query.$and) ? query.$and : [];
+			const { $and: _existing, ...rest } = query;
+			return {
+				...rest,
+				$and: [...existingAnd, ...arms]
+			};
+		}
 		if (this._hasTextIndex === null) this._hasTextIndex = this.Model.schema.indexes().some((idx) => idx[0] && Object.values(idx[0]).includes("text"));
 		let effectiveMode = this.searchMode === "regex" ? "regex" : "text";
 		if (this.searchMode === "auto") effectiveMode = this._hasTextIndex ? "text" : "regex";
@@ -5246,4 +5393,4 @@ var Repository = class extends RepositoryBase {
 	}
 };
 //#endregion
-export { MUTATING_OPERATIONS as a, operationsByPolicyKey as c, ALL_OPERATIONS as i, createMongoPurgePort as l, Repository as n, OP_REGISTRY as o, AggregationBuilder as r, READ_OPERATIONS as s, HOOK_PRIORITY$1 as t };
+export { ALL_OPERATIONS as a, READ_OPERATIONS as c, searchKeysPlugin as i, operationsByPolicyKey as l, Repository as n, MUTATING_OPERATIONS as o, AggregationBuilder as r, OP_REGISTRY as s, HOOK_PRIORITY$1 as t, createMongoPurgePort as u };

package/dist/{Repository-pnLw1rG5.d.mts → Repository-DnL4xk5w.d.mts}

@@ -1,6 +1,6 @@
 import { S as LookupOptions, _ as SessionOptions, b as WithTransactionOptions, c as DeleteResult, f as LookupPopulateOptions, g as ReadOptions, h as OperationOptions, i as CacheableOptions, l as FindOneAndUpdateOptions, n as AggregateOptions, o as CreateOptions, p as LookupPopulateResult, s as DeleteManyResult, t as AggregateCallOptions, u as GetByIdsOptions, v as UpdateManyResult, x as LookupBuilder, y as UpdateOptions } from "./operations-XiFgG5US.mjs";
 import { A as ObjectId, F as SortSpec$1, M as ReadPreferenceType, N as SelectSpec, c as MongokitPageExtras, i as CountStrategy, j as PopulateSpec, r as CollationOptions, t as AggregatePaginationOptions, u as PaginationConfig } from "./pagination-D6psses0.mjs";
-import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-DNHfjAZX.mjs";
+import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-MqAP409e.mjs";
 import { n as PaginationEngine } from "./PaginationEngine-CRHyuUtw.mjs";
 import { AggPaginationRequest, AggRequest, AggResult, ArchiveOptions, ArchiveResult, ArchiveSink, BulkUpsertOptions, BulkUpsertResult, ChangeEvent, FilterInput, KeysetAggPaginationResult, QueryOptions, RepoCapabilities, RepositoryBase, TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy, WatchOptions } from "@classytic/repo-core/repository";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
@@ -599,8 +599,10 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   readonly idField: string;
   /** Version field for `ifVersion` CAS writes. Default '__v'. */
   readonly versionField: string;
-  readonly searchMode: 'text' | 'regex' | 'auto';
+  readonly searchMode: 'text' | 'regex' | 'auto' | 'prefix';
   readonly searchFields: string[] | undefined;
+  /** Field holding the prefix-search keys (`searchMode: 'prefix'`). Default `'_searchKeys'`. */
+  readonly searchKeysField: string;
   [key: string]: unknown;
   private _hasTextIndex;
   /**
@@ -1896,6 +1898,12 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * sort with no page means the caller wants a cursor).
    */
   private _detectPaginationMode;
+  /**
+   * `searchMode: 'prefix'` preconditions + its write plugin. Throws when the keys could never
+   * be written (no `searchFields`, or a strict schema that would strip the keys field); warns
+   * when no index includes the keys field (every search would then scan).
+   */
+  private _prefixSearchPlugins;
   /**
    * Build the MongoDB query filter with search merged in. Handles text
    * search ($text), regex search ($or of $regex), and the search-resolver

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { l as Plugin } from "../repository-DNHfjAZX.mjs";
+import { l as Plugin } from "../repository-MqAP409e.mjs";
 import { PipelineStage } from "mongoose";
 //#region src/ai/types.d.ts
 /** Supported similarity metrics for vector search */

package/dist/better-auth/index.mjs

@@ -1,4 +1,4 @@
-import { n as Repository } from "../Repository-DlhPbXlG.mjs";
+import { n as Repository } from "../Repository-Dj6xqPxJ.mjs";
 import { n as createMongooseAdapter } from "../adapter-CkMoMF83.mjs";
 import { asReadOnlyRepo } from "@classytic/repo-core/repository";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";

package/dist/{create-repository-BUx9vfG9.d.mts → create-repository-CJtVdwig.d.mts}

@@ -1,8 +1,8 @@
 import { u as PaginationConfig } from "./pagination-D6psses0.mjs";
-import { _ as RepositoryOptions, d as PluginType } from "./repository-DNHfjAZX.mjs";
-import { D as AuditTrailOptions, i as CustomIdOptions, t as MultiTenantOptions, y as RepositoryCachePluginOptions } from "./multi-tenant.plugin-a3UhQARj.mjs";
-import { r as Repository } from "./Repository-pnLw1rG5.mjs";
-import { i as Logger, o as SoftDeleteOptions } from "./plugin-options-CRhIvSzx.mjs";
+import { _ as RepositoryOptions, d as PluginType } from "./repository-MqAP409e.mjs";
+import { D as AuditTrailOptions, i as CustomIdOptions, t as MultiTenantOptions, y as RepositoryCachePluginOptions } from "./multi-tenant.plugin-B_q9NUHc.mjs";
+import { r as Repository } from "./Repository-DnL4xk5w.mjs";
+import { i as Logger, o as SoftDeleteOptions } from "./plugin-options-Cirmb4Kp.mjs";
 import { Model } from "mongoose";
 //#region src/create-repository.d.ts
 /**

package/dist/{create-repository-Bg0H5rte.mjs → create-repository-UjwPWR1z.mjs}

@@ -1,5 +1,5 @@
-import { n as Repository } from "./Repository-DlhPbXlG.mjs";
-import { b as auditLogPlugin, g as cachePlugin, i as multiTenantPlugin, l as customIdPlugin, n as softDeletePlugin, t as timestampPlugin, v as auditTrailPlugin } from "./timestamp.plugin-DvZlnKEc.mjs";
+import { n as Repository } from "./Repository-Dj6xqPxJ.mjs";
+import { b as auditLogPlugin, g as cachePlugin, i as multiTenantPlugin, l as customIdPlugin, n as softDeletePlugin, t as timestampPlugin, v as auditTrailPlugin } from "./timestamp.plugin-DpOWavVI.mjs";
 import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-C63pGn1d.mjs";
 //#region src/create-repository.ts
 function isLoggerAudit(value) {