@classytic/mongokit 3.4.4 → 3.5.0

package/README.md

@@ -17,7 +17,7 @@
 - **Search governance** - Text index guard (throws `400` if no index), allowlisted sort/filter fields, ReDoS protection
 - **Vector search** - MongoDB Atlas `$vectorSearch` with auto-embedding and multimodal support
 - **TypeScript first** - Full type safety with discriminated unions, typed events, and field autocomplete
-- **1150+ passing tests** - Battle-tested and production-ready
+- **1170+ passing tests** - Battle-tested and production-ready
 
 ## Installation
 
@@ -125,6 +125,7 @@ UserSchema.index({ organizationId: 1, createdAt: -1, _id: -1 });
 | `createMany(data[], opts)`       | `CreateOptions`      | Create multiple documents          |
 | `getById(id, opts)`              | `CacheableOptions`   | Find by ID                         |
 | `getByQuery(query, opts)`        | `CacheableOptions`   | Find one by query                  |
+| `getOne(filter, opts)`           | `CacheableOptions`   | Find one by compound filter        |
 | `getAll(params, opts)`           | `CacheableOptions`   | Paginated list (auto-detects mode) |
 | `findAll(filters, opts)`         | `OperationOptions`   | All docs without pagination        |
 | `getOrCreate(query, data, opts)` | `SessionOptions`     | Find or create                     |

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-DxNyLB2w.mjs";
+import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-BjXxDBgx.mjs";
 export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };

package/dist/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
-import { c as read_exports, h as aggregate_exports, n as update_exports, p as create_exports, u as delete_exports } from "../update-D6FFSUUO.mjs";
+import { _ as aggregate_exports, f as delete_exports, h as create_exports, l as read_exports, r as update_exports } from "../update-DcWUpWBk.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { J as Plugin } from "../types-sOh6QSzc.mjs";
+import { J as Plugin } from "../types-DK6ELT6o.mjs";
 import { ClientSession, PipelineStage } from "mongoose";
 
 //#region src/ai/types.d.ts

package/dist/{index-DxNyLB2w.d.mts → index-BjXxDBgx.d.mts}

@@ -1,4 +1,4 @@
-import { $ as ReadPreferenceType, At as LookupOptions, D as GroupResult, V as ObjectId, W as OperationOptions, Z as PopulateSpec, _t as UpdateOptions, a as AnyDocument, b as DeleteResult, g as CreateOptions, gt as UpdateManyResult, pt as SortSpec, st as SelectSpec, vt as UpdateWithValidationResult, z as MinMaxResult } from "./types-sOh6QSzc.mjs";
+import { $ as ReadPreferenceType, At as LookupOptions, D as GroupResult, V as ObjectId, W as OperationOptions, Z as PopulateSpec, _t as UpdateOptions, a as AnyDocument, b as DeleteResult, g as CreateOptions, gt as UpdateManyResult, pt as SortSpec, st as SelectSpec, vt as UpdateWithValidationResult, z as MinMaxResult } from "./types-DK6ELT6o.mjs";
 import { ClientSession, Model, PipelineStage } from "mongoose";
 
 //#region src/actions/aggregate.d.ts

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { $ as ReadPreferenceType, A as InferDocument, At as LookupOptions, B as NonNullableFields, C as EventPayload, Ct as WithPlugins, D as GroupResult, Dt as IRequestContext, E as FieldRules, Et as IControllerResponse, F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, I as Logger, J as Plugin, K as PaginationResult, L as LookupPopulateOptions, M as JsonSchema, N as KeysOfType, O as HookMode, Ot as IResponseFormatter, P as KeysetPaginationOptions, Q as ReadOptions, R as LookupPopulateResult, S as EventHandlers, St as ValidatorDefinition, T as FieldPreset, Tt as IController, U as OffsetPaginationResult, V as ObjectId, W as OperationOptions, X as PluginType, Y as PluginFunction, Z as PopulateSpec, _ as CrudSchemas, _t as UpdateOptions, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SessionOptions, d as CacheableOptions, dt as SoftDeleteRepository, et as RepositoryContext, f as CascadeOptions, ft as SortDirection, g as CreateOptions, gt as UpdateManyResult, h as CreateInput, ht as UpdateInput, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupBuilder, l as CacheOptions, lt as SoftDeleteFilterMode, m as CollationOptions, mt as Strict, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SchemaBuilderOptions, p as CascadeRelation, pt as SortSpec, q as PartialBy, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SelectSpec, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteOptions, v as DecodedCursor, vt as UpdateWithValidationResult, w as EventPhase, wt as WithTransactionOptions, x as DocField, xt as ValidationResult, y as DeepPartial, yt as UserContext, z as MinMaxResult } from "./types-sOh6QSzc.mjs";
-import { t as index_d_exports } from "./index-DxNyLB2w.mjs";
+import { $ as ReadPreferenceType, A as InferDocument, At as LookupOptions, B as NonNullableFields, C as EventPayload, Ct as WithPlugins, D as GroupResult, Dt as IRequestContext, E as FieldRules, Et as IControllerResponse, F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, I as Logger, J as Plugin, K as PaginationResult, L as LookupPopulateOptions, M as JsonSchema, N as KeysOfType, O as HookMode, Ot as IResponseFormatter, P as KeysetPaginationOptions, Q as ReadOptions, R as LookupPopulateResult, S as EventHandlers, St as ValidatorDefinition, T as FieldPreset, Tt as IController, U as OffsetPaginationResult, V as ObjectId, W as OperationOptions, X as PluginType, Y as PluginFunction, Z as PopulateSpec, _ as CrudSchemas, _t as UpdateOptions, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SessionOptions, d as CacheableOptions, dt as SoftDeleteRepository, et as RepositoryContext, f as CascadeOptions, ft as SortDirection, g as CreateOptions, gt as UpdateManyResult, h as CreateInput, ht as UpdateInput, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupBuilder, l as CacheOptions, lt as SoftDeleteFilterMode, m as CollationOptions, mt as Strict, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SchemaBuilderOptions, p as CascadeRelation, pt as SortSpec, q as PartialBy, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SelectSpec, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteOptions, v as DecodedCursor, vt as UpdateWithValidationResult, w as EventPhase, wt as WithTransactionOptions, x as DocField, xt as ValidationResult, y as DeepPartial, yt as UserContext, z as MinMaxResult } from "./types-DK6ELT6o.mjs";
+import { t as index_d_exports } from "./index-BjXxDBgx.mjs";
 import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
-import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, R as BulkWriteResult, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, z as batchOperationsPlugin } from "./validation-chain.plugin-nJtqOI-E.mjs";
-import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "./mongooseToJsonSchema-C374oVAV.mjs";
+import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, R as BulkWriteResult, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, z as batchOperationsPlugin } from "./validation-chain.plugin-DISOoL9A.mjs";
+import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "./mongooseToJsonSchema-C78rAP7X.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 
@@ -773,6 +773,7 @@ declare class Repository<TDoc = unknown> {
   readonly _hooks: Map<string, PrioritizedHook[]>;
   readonly _pagination: PaginationEngine<TDoc>;
   private readonly _hookMode;
+  readonly idField: string;
   [key: string]: unknown;
   private _hasTextIndex;
   constructor(Model: Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions);
@@ -826,6 +827,15 @@ declare class Repository<TDoc = unknown> {
    * Get single document by query
    */
   getByQuery(query: Record<string, unknown>, options?: CacheableOptions): Promise<TDoc | null>;
+  /**
+   * Get single document by arbitrary filter.
+   * Unlike getByQuery, this method is designed for Arc/controller use where
+   * compound filters (org scope + policy + id) are pre-built.
+   *
+   * @example
+   * const product = await repo.getOne({ slug: 'laptop', organizationId: 'org_1' });
+   */
+  getOne(query: Record<string, unknown>, options?: CacheableOptions): Promise<TDoc | null>;
   /**
    * Fetch ALL documents matching filters without pagination.
    * Use for background jobs, exports, batch processing where you need every doc.
@@ -904,7 +914,9 @@ declare class Repository<TDoc = unknown> {
   /**
    * Delete document by ID
    */
-  delete(id: string | ObjectId, options?: SessionOptions): Promise<DeleteResult>;
+  delete(id: string | ObjectId, options?: SessionOptions & {
+    idField?: string;
+  }): Promise<DeleteResult>;
   /**
    * Execute aggregation pipeline
    * Routes through hook system for policy enforcement (multi-tenant, soft-delete)

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { a as warn, n as parseDuplicateKeyError, r as configureLogger, t as createError } from "./error-Bpbi_NKo.mjs";
-import { _ as LookupBuilder } from "./update-D6FFSUUO.mjs";
+import { y as LookupBuilder } from "./update-DcWUpWBk.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-DCs-zKwZ.mjs";
-import { A as aggregateHelpersPlugin, C as HOOK_PRIORITY, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, T as AggregationBuilder, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, w as Repository, x as cascadePlugin, y as prefixedId } from "./validation-chain.plugin-7Pa1wIsD.mjs";
+import { A as aggregateHelpersPlugin, C as HOOK_PRIORITY, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, T as AggregationBuilder, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, w as Repository, x as cascadePlugin, y as prefixedId } from "./validation-chain.plugin-C4D1sc18.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-reyDRzXf.mjs";
 import { a as isFieldUpdateAllowed, i as getSystemManagedFields, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-B6Qyl8BK.mjs";
 import mongoose from "mongoose";

package/dist/{mongooseToJsonSchema-C374oVAV.d.mts → mongooseToJsonSchema-C78rAP7X.d.mts}

@@ -1,4 +1,4 @@
-import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-sOh6QSzc.mjs";
+import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-DK6ELT6o.mjs";
 import mongoose, { Schema } from "mongoose";
 
 //#region src/utils/error.d.ts

package/dist/pagination/PaginationEngine.d.mts

@@ -1,4 +1,4 @@
-import { F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, P as KeysetPaginationOptions, U as OffsetPaginationResult, a as AnyDocument, n as AggregatePaginationOptions, r as AggregatePaginationResult } from "../types-sOh6QSzc.mjs";
+import { F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, P as KeysetPaginationOptions, U as OffsetPaginationResult, a as AnyDocument, n as AggregatePaginationOptions, r as AggregatePaginationResult } from "../types-DK6ELT6o.mjs";
 import { Model } from "mongoose";
 
 //#region src/pagination/PaginationEngine.d.ts

package/dist/plugins/index.d.mts

@@ -1,2 +1,2 @@
-import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, y as MethodRegistryRepository, z as batchOperationsPlugin } from "../validation-chain.plugin-nJtqOI-E.mjs";
+import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, y as MethodRegistryRepository, z as batchOperationsPlugin } from "../validation-chain.plugin-DISOoL9A.mjs";
 export { type AggregateHelpersMethods, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type CacheMethods, type CustomIdOptions, type DateSequentialIdOptions, type ElasticSearchOptions, type IdGenerator, type MethodRegistryRepository, type MongoOperationsMethods, type MultiTenantOptions, type ObservabilityOptions, type OperationMetric, type PrefixedIdOptions, type SequentialIdOptions, type SoftDeleteMethods, type SubdocumentMethods, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/plugins/index.mjs

@@ -1,2 +1,2 @@
-import { A as aggregateHelpersPlugin, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, x as cascadePlugin, y as prefixedId } from "../validation-chain.plugin-7Pa1wIsD.mjs";
+import { A as aggregateHelpersPlugin, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, x as cascadePlugin, y as prefixedId } from "../validation-chain.plugin-C4D1sc18.mjs";
 export { AuditTrailQuery, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/{types-sOh6QSzc.d.mts → types-DK6ELT6o.d.mts}

@@ -529,6 +529,9 @@ type HookMode = 'sync' | 'async';
 interface RepositoryOptions {
   /** Whether repository event hooks are awaited */
   hooks?: HookMode;
+  /** Custom ID field used by getById/update/delete (default: '_id').
+   * Set to 'slug', 'code', 'chatId', etc. for non-ObjectId lookups. */
+  idField?: string;
 }
 /** Pagination configuration */
 interface PaginationConfig {
@@ -699,6 +702,9 @@ interface OperationOptions extends ReadOptions {
   lean?: boolean;
   /** Throw error if document not found (default: true) */
   throwOnNotFound?: boolean;
+  /** Override the ID field for this call (default: repo.idField or '_id').
+   * Use when the same repo sometimes queries by _id and sometimes by slug/code. */
+  idField?: string;
   /** Additional query filters (e.g., for soft delete) */
   query?: Record<string, unknown>;
 }
@@ -926,7 +932,7 @@ interface RepositoryInstance {
   [key: string]: unknown;
 }
 /** Repository operation names */
-type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'delete' | 'deleteMany' | 'getById' | 'getByQuery' | 'getAll' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'lookupPopulate' | 'bulkWrite';
+type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'delete' | 'deleteMany' | 'getById' | 'getByQuery' | 'getOne' | 'getAll' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'lookupPopulate' | 'bulkWrite';
 /** Event lifecycle phases */
 type EventPhase = 'before' | 'after' | 'error';
 /** Repository event names (generated from template literals) */

package/dist/{update-D6FFSUUO.mjs → update-DcWUpWBk.mjs}

@@ -842,4 +842,4 @@ async function pullFromArray(Model, id, field, value, options = {}) {
 	return update(Model, id, { $pull: { [field]: value } }, options);
 }
 //#endregion
-export { LookupBuilder as _, getById as a, read_exports as c, create as d, createMany as f, distinct as g, aggregate_exports as h, exists as i, deleteById as l, upsert as m, update_exports as n, getByQuery as o, create_exports as p, count as r, getOrCreate as s, update as t, delete_exports as u };
+export { aggregate_exports as _, exists as a, getOrCreate as c, deleteByQuery as d, delete_exports as f, upsert as g, create_exports as h, count as i, read_exports as l, createMany as m, updateByQuery as n, getById as o, create as p, update_exports as r, getByQuery as s, update as t, deleteById as u, distinct as v, LookupBuilder as y };

package/dist/utils/index.d.mts

@@ -1,5 +1,5 @@
-import { Z as PopulateSpec, pt as SortSpec, st as SelectSpec } from "../types-sOh6QSzc.mjs";
-import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "../mongooseToJsonSchema-C374oVAV.mjs";
+import { Z as PopulateSpec, pt as SortSpec, st as SelectSpec } from "../types-DK6ELT6o.mjs";
+import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "../mongooseToJsonSchema-C78rAP7X.mjs";
 
 //#region src/utils/cache-keys.d.ts
 /**

package/dist/{validation-chain.plugin-7Pa1wIsD.mjs → validation-chain.plugin-C4D1sc18.mjs}

@@ -1,5 +1,5 @@
 import { a as warn, i as debug, n as parseDuplicateKeyError, t as createError } from "./error-Bpbi_NKo.mjs";
-import { _ as LookupBuilder, a as getById, d as create, f as createMany, g as distinct, i as exists, l as deleteById, m as upsert, o as getByQuery, r as count, s as getOrCreate, t as update } from "./update-D6FFSUUO.mjs";
+import { a as exists, c as getOrCreate, d as deleteByQuery, g as upsert, i as count, m as createMany, n as updateByQuery, o as getById, p as create, s as getByQuery, t as update, u as deleteById, v as distinct, y as LookupBuilder } from "./update-DcWUpWBk.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-DCs-zKwZ.mjs";
 import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-reyDRzXf.mjs";
 import mongoose from "mongoose";
@@ -1133,6 +1133,7 @@ var Repository = class {
 	_hooks;
 	_pagination;
 	_hookMode;
+	idField;
 	_hasTextIndex = null;
 	constructor(Model, plugins = [], paginationConfig = {}, options = {}) {
 		this.Model = Model;
@@ -1140,6 +1141,7 @@ var Repository = class {
 		this._hooks = /* @__PURE__ */ new Map();
 		this._pagination = new PaginationEngine(Model, paginationConfig);
 		this._hookMode = options.hooks ?? "async";
+		this.idField = options.idField ?? "_id";
 		plugins.forEach((plugin) => {
 			this.use(plugin);
 		});
@@ -1302,6 +1304,18 @@ var Repository = class {
 			return cachedResult;
 		}
 		try {
+			const effectiveIdField = options.idField ?? this.idField;
+			if (effectiveIdField !== "_id") {
+				const result = await getByQuery(this.Model, {
+					[effectiveIdField]: id,
+					...context.query || {}
+				}, context);
+				await this._emitHook("after:getById", {
+					context,
+					result
+				});
+				return result;
+			}
 			if (typeof id === "string" && !mongoose.Types.ObjectId.isValid(id)) {
 				if (context.throwOnNotFound === false || options.throwOnNotFound === false) return null;
 				throw createError(404, "Document not found");
@@ -1356,6 +1370,46 @@ var Repository = class {
 		}
 	}
 	/**
+	* Get single document by arbitrary filter.
+	* Unlike getByQuery, this method is designed for Arc/controller use where
+	* compound filters (org scope + policy + id) are pre-built.
+	*
+	* @example
+	* const product = await repo.getOne({ slug: 'laptop', organizationId: 'org_1' });
+	*/
+	async getOne(query, options = {}) {
+		const populateSpec = options.populateOptions || options.populate;
+		const context = await this._buildContext("getOne", {
+			query,
+			...options,
+			populate: populateSpec
+		});
+		if (context._cacheHit) {
+			const cachedResult = context._cachedResult;
+			await this._emitHook("after:getOne", {
+				context,
+				result: cachedResult,
+				fromCache: true
+			});
+			return cachedResult;
+		}
+		const finalQuery = context.query || query;
+		try {
+			const result = await getByQuery(this.Model, finalQuery, context);
+			await this._emitHook("after:getOne", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:getOne", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
 	* Fetch ALL documents matching filters without pagination.
 	* Use for background jobs, exports, batch processing where you need every doc.
 	*
@@ -1628,7 +1682,16 @@ var Repository = class {
 			...options
 		});
 		try {
-			const result = await update(this.Model, id, context.data || data, context);
+			let result;
+			const effectiveIdField = options.idField ?? this.idField;
+			if (effectiveIdField !== "_id") {
+				const updated = await updateByQuery(this.Model, {
+					[effectiveIdField]: id,
+					...context.query || {}
+				}, context.data || data, context);
+				if (!updated) throw createError(404, "Document not found");
+				result = updated;
+			} else result = await update(this.Model, id, context.data || data, context);
 			await this._emitHook("after:update", {
 				context,
 				result
@@ -1664,7 +1727,12 @@ var Repository = class {
 				});
 				return result;
 			}
-			const result = await deleteById(this.Model, id, {
+			const effectiveIdField = options.idField ?? this.idField;
+			const deleteQuery = effectiveIdField !== "_id" ? {
+				[effectiveIdField]: id,
+				...context.query || {}
+			} : void 0;
+			const result = deleteQuery ? await deleteByQuery(this.Model, deleteQuery, { session: options.session }) : await deleteById(this.Model, id, {
 				session: options.session,
 				query: context.query
 			});
@@ -3599,7 +3667,7 @@ function softDeletePlugin(options = {}) {
 					const updateData = { [deletedField]: /* @__PURE__ */ new Date() };
 					if (context.user) updateData[deletedByField] = context.user._id || context.user.id;
 					const deleteQuery = {
-						_id: context.id,
+						[repo.idField || "_id"]: context.id,
 						...context.query || {}
 					};
 					if (!await repo.Model.findOneAndUpdate(deleteQuery, updateData, { session: context.session })) {

package/dist/{validation-chain.plugin-nJtqOI-E.d.mts → validation-chain.plugin-DISOoL9A.d.mts}

@@ -1,4 +1,4 @@
-import { I as Logger, J as Plugin, St as ValidatorDefinition, T as FieldPreset, U as OffsetPaginationResult, V as ObjectId, Z as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, l as CacheOptions, nt as RepositoryInstance, pt as SortSpec, st as SelectSpec, u as CacheStats, ut as SoftDeleteOptions } from "./types-sOh6QSzc.mjs";
+import { I as Logger, J as Plugin, St as ValidatorDefinition, T as FieldPreset, U as OffsetPaginationResult, V as ObjectId, Z as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, l as CacheOptions, nt as RepositoryInstance, pt as SortSpec, st as SelectSpec, u as CacheStats, ut as SoftDeleteOptions } from "./types-DK6ELT6o.mjs";
 import mongoose, { ClientSession } from "mongoose";
 
 //#region src/plugins/aggregate-helpers.plugin.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.4.4",
+  "version": "3.5.0",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,
@@ -109,6 +109,7 @@
     "@biomejs/biome": "^2.4.10",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "knip": "^6.3.0",
     "mongodb-memory-server": "^10.4.3",
     "mongoose": "^9.1.3",
     "tsdown": "^0.21.7",