@classytic/mongokit 3.5.2 → 3.5.4

package/README.md

@@ -1172,6 +1172,40 @@ const { crudSchemas } = buildCrudSchemasFromModel(UserModel, {
 // crudSchemas.listQuery   - GET query validation
 ```
 
+#### Soft-required fields (draft-friendly bodies)
+
+Some resources have fields that must be non-null in the DB but should be
+**optional in the HTTP body** — draft journal entries, multi-step wizards,
+or any state-machine resource that's filled out progressively. Marking a
+path `softRequired: true` keeps the Mongoose `required: true` invariant
+(null on save is still rejected) while excluding the field from the
+generated `createBody.required[]` array.
+
+```typescript
+// 1. Per-path flag (when you own the Mongoose schema)
+const JournalEntrySchema = new Schema({
+  label: { type: String, required: true },            // hard required
+  journalType: {
+    type: String,
+    required: true,       // DB invariant — null rejected on save
+    softRequired: true,   // HTTP body — optional in create/update
+    enum: ['sale', 'purchase', 'adjustment'],
+  },
+  date: { type: Date, required: true, softRequired: true },
+});
+
+// 2. Per-build override (when the Mongoose model lives in an upstream package)
+const { createBody } = buildCrudSchemasFromModel(UpstreamModel, {
+  softRequiredFields: ['journalType', 'date'],
+});
+// createBody.required   →  ['label']   (journalType + date excluded)
+// createBody.properties →  still includes journalType + date (validated when present)
+```
+
+The DB-level `required: true` is unaffected — `repo.create()` with `null`
+for a soft-required field still throws a Mongoose ValidationError. The
+flag only changes what HTTP clients must send.
+
 ### Complete Controller Example
 
 ```typescript

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-BjXxDBgx.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-BNpVzw_-.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/ai/index.d.mts

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

package/dist/{index-BjXxDBgx.d.mts → index-BNpVzw_-.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-DK6ELT6o.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-CkE3mOaW.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-DK6ELT6o.mjs";
-import { t as index_d_exports } from "./index-BjXxDBgx.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-CkE3mOaW.mjs";
+import { t as index_d_exports } from "./index-BNpVzw_-.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-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 { 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-BYMZB8dN.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-Dsx3YAAx.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 

package/dist/index.mjs

@@ -2,9 +2,9 @@ import { a as warn, n as parseDuplicateKeyError, r as configureLogger, t as crea
 import { y as LookupBuilder } from "./update-AVfKWNGt.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-vxvcv1dg.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-KjPV_6_N.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 { a as isFieldUpdateAllowed, i as getSystemManagedFields, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-DpjhFfaO.mjs";
 import mongoose from "mongoose";
 //#region src/query/QueryParser.ts
 /**

package/dist/{mongooseToJsonSchema-B6Qyl8BK.mjs → mongooseToJsonSchema-DpjhFfaO.mjs}

@@ -154,6 +154,11 @@ function buildJsonSchemaFromPaths(mongooseSchema, options) {
 	const properties = {};
 	const required = [];
 	const paths = mongooseSchema.paths;
+	const softRequiredSet = new Set(options?.softRequiredFields ?? []);
+	const isSoftRequired = (name, schemaType) => {
+		if (softRequiredSet.has(name)) return true;
+		return schemaType?.options?.softRequired === true;
+	};
 	const rootFields = /* @__PURE__ */ new Map();
 	for (const [path, schemaType] of Object.entries(paths)) {
 		if (path === "_id" || path === "__v") continue;
@@ -167,7 +172,7 @@ function buildJsonSchemaFromPaths(mongooseSchema, options) {
 	for (const [rootField, fieldPaths] of rootFields.entries()) if (fieldPaths.length === 1 && fieldPaths[0].path === rootField) {
 		const schemaType = fieldPaths[0].schemaType;
 		properties[rootField] = schemaTypeToJsonSchema(schemaType);
-		if (schemaType.isRequired) required.push(rootField);
+		if (schemaType.isRequired && !isSoftRequired(rootField, schemaType)) required.push(rootField);
 	} else {
 		const nestedSchema = buildNestedJsonSchema(fieldPaths, rootField);
 		properties[rootField] = nestedSchema.schema;

package/dist/{mongooseToJsonSchema-C78rAP7X.d.mts → mongooseToJsonSchema-Dsx3YAAx.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-DK6ELT6o.mjs";
+import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-CkE3mOaW.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-DK6ELT6o.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-CkE3mOaW.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-DISOoL9A.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-BYMZB8dN.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-vxvcv1dg.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-KjPV_6_N.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-DK6ELT6o.d.mts → types-CkE3mOaW.d.mts}

@@ -457,6 +457,27 @@ interface IResponseFormatter {
 }
 //#endregion
 //#region src/types.d.ts
+/**
+ * MongoKit Type Definitions
+ *
+ * Production-grade types for MongoDB repository pattern with TypeScript
+ *
+ * @module @classytic/mongokit
+ */
+/**
+ * Global declaration merge: adds `softRequired` to Mongoose's SchemaTypeOptions
+ * so consumers can annotate paths type-safely without importing anything.
+ *
+ * A path with `softRequired: true` keeps its DB-level `required: true`
+ * invariant but is excluded from the auto-generated CRUD body `required[]`
+ * array (see buildCrudSchemasFromModel).
+ */
+declare module 'mongoose' {
+  interface SchemaTypeOptions<T, EnforcedDocType = any, THydratedDocumentType = HydratedDocument<EnforcedDocType>> {
+    /** mongokit: omit from auto-generated CRUD body `required` array. */
+    softRequired?: boolean;
+  }
+}
 /** Read Preference Type for replica sets */
 type ReadPreferenceType = 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest' | (string & {});
 /** Re-export mongoose ObjectId */
@@ -684,6 +705,10 @@ type PaginationResult<T = unknown> = OffsetPaginationResult<T> | KeysetPaginatio
 interface SessionOptions {
   /** MongoDB session for transactions */
   session?: ClientSession;
+  /** Organization/tenant ID for multi-tenant plugin scoping */
+  organizationId?: string | ObjectId;
+  /** Extensible — plugins can read custom fields from options */
+  [key: string]: unknown;
 }
 /** Read options — session + readPreference for read-only operations */
 interface ReadOptions extends SessionOptions {
@@ -994,6 +1019,19 @@ interface SchemaBuilderOptions {
     optionalOverrides?: Record<string, boolean>; /** Schema overrides */
     schemaOverrides?: Record<string, unknown>;
   };
+  /**
+   * Field names to mark as soft-required: they remain in the generated body
+   * schema's `properties` (still validated when present) but are excluded
+   * from the `required[]` array so the client may omit them.
+   *
+   * Combines with per-path `softRequired: true` Mongoose schema option.
+   * Use this when the Mongoose model is owned by an upstream package and
+   * you can't annotate the schema directly.
+   *
+   * The DB-level `required: true` invariant is unaffected — Mongoose still
+   * rejects null on save. This flag only affects HTTP body validation.
+   */
+  softRequiredFields?: string[];
   /** Update schema options */
   update?: {
     /** Fields to omit from update schema */omitFields?: string[]; /** Require at least one field to be provided (default: false) */

package/dist/utils/index.d.mts

@@ -1,5 +1,5 @@
-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";
+import { Z as PopulateSpec, pt as SortSpec, st as SelectSpec } from "../types-CkE3mOaW.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-Dsx3YAAx.mjs";
 
 //#region src/utils/cache-keys.d.ts
 /**

package/dist/utils/index.mjs

@@ -1,4 +1,4 @@
 import { r as configureLogger, t as createError } from "../error-Bpbi_NKo.mjs";
 import { a as byIdKey, c as listQueryKey, i as getMongooseProjection, l as modelPattern, n as filterResponseData, o as byQueryKey, r as getFieldsForUser, s as listPattern, t as createFieldPreset, u as versionKey } 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 { a as isFieldUpdateAllowed, i as getSystemManagedFields, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-DpjhFfaO.mjs";
 export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getSystemManagedFields, isFieldUpdateAllowed, listPattern, listQueryKey, modelPattern, validateUpdateBody, versionKey };

package/dist/{validation-chain.plugin-DISOoL9A.d.mts → validation-chain.plugin-BYMZB8dN.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-DK6ELT6o.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-CkE3mOaW.mjs";
 import mongoose, { ClientSession } from "mongoose";
 
 //#region src/plugins/aggregate-helpers.plugin.d.ts

package/dist/{validation-chain.plugin-vxvcv1dg.mjs → validation-chain.plugin-KjPV_6_N.mjs}

@@ -2431,6 +2431,34 @@ function cachePlugin(options) {
 				}
 			}, { priority: HOOK_PRIORITY.CACHE });
 			/**
+			* before:getOne - Same cache logic as getByQuery (single-doc)
+			*/
+			repo.on("before:getOne", async (context) => {
+				if (context.skipCache) return;
+				try {
+					const collectionVersion = await getVersion();
+					const query = context.query || {};
+					const key = byQueryKey(config.prefix, model, collectionVersion, query, {
+						select: context.select,
+						populate: context.populate
+					});
+					const cached = await config.adapter.get(key);
+					if (cached !== null && cached !== void 0) {
+						log(`Cache HIT for getOne: ${key}`);
+						stats.hits++;
+						context._cacheHit = true;
+						context._cachedResult = cached;
+					} else {
+						log(`Cache MISS for getOne: ${key}`);
+						stats.misses++;
+						context._cacheKey = key;
+					}
+				} catch (e) {
+					log(`Cache error for getOne:`, e);
+					stats.errors++;
+				}
+			}, { priority: HOOK_PRIORITY.CACHE });
+			/**
 			* before:getAll - Check cache for list query
 			* Runs at CACHE priority (200) — after policy hooks inject filters
 			*/
@@ -2526,6 +2554,25 @@ function cachePlugin(options) {
 				}
 			});
 			/**
+			* after:getOne - Cache the result (same as getByQuery)
+			*/
+			repo.on("after:getOne", async (payload) => {
+				const { context, result } = payload;
+				if (context._cacheHit || context.skipCache || result === null) return;
+				const collectionVersion = await getVersion();
+				const query = context.query || {};
+				const key = byQueryKey(config.prefix, model, collectionVersion, query, {
+					select: context.select,
+					populate: context.populate
+				});
+				try {
+					await config.adapter.set(key, result, context.cacheTtl ?? config.queryTtl);
+					stats.sets++;
+				} catch (e) {
+					log(`Failed to cache getOne:`, e);
+				}
+			});
+			/**
 			* after:getAll - Cache the result
 			*/
 			repo.on("after:getAll", async (payload) => {
@@ -3193,8 +3240,10 @@ function fieldFilterPlugin(fieldPreset) {
 				else context.select = presetSelect;
 			};
 			repo.on("before:getAll", applyFieldFiltering);
+			repo.on("before:findAll", applyFieldFiltering);
 			repo.on("before:getById", applyFieldFiltering);
 			repo.on("before:getByQuery", applyFieldFiltering);
+			repo.on("before:getOne", applyFieldFiltering);
 		}
 	};
 }
@@ -3480,12 +3529,14 @@ function multiTenantPlugin(options = {}) {
 	const { tenantField = "organizationId", contextKey = "organizationId", required = true, skipOperations = [], skipWhen, resolveContext } = options;
 	const filterOps = [
 		"getAll",
+		"findAll",
 		"aggregatePaginate",
 		"lookupPopulate"
 	];
 	const queryReadOps = [
 		"getById",
 		"getByQuery",
+		"getOne",
 		"count",
 		"exists",
 		"getOrCreate",
@@ -3578,7 +3629,14 @@ const DEFAULT_OPS = [
 	"delete",
 	"getById",
 	"getByQuery",
+	"getOne",
 	"getAll",
+	"findAll",
+	"getOrCreate",
+	"count",
+	"exists",
+	"distinct",
+	"aggregate",
 	"aggregatePaginate",
 	"lookupPopulate"
 ];
@@ -3733,7 +3791,7 @@ function softDeletePlugin(options = {}) {
 					context.softDeleted = true;
 				}
 			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:getAll", (context) => {
+			const injectDeleteFilterToFilters = (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
 					if (Object.keys(deleteFilter).length > 0) context.filters = {
@@ -3741,53 +3799,8 @@ function softDeletePlugin(options = {}) {
 						...deleteFilter
 					};
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:getById", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:getByQuery", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:count", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:exists", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:getOrCreate", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:distinct", (context) => {
+			};
+			const injectDeleteFilterToQuery = (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
 					if (Object.keys(deleteFilter).length > 0) context.query = {
@@ -3795,7 +3808,23 @@ function softDeletePlugin(options = {}) {
 						...deleteFilter
 					};
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
+			};
+			for (const op of [
+				"getAll",
+				"findAll",
+				"aggregatePaginate",
+				"lookupPopulate"
+			]) repo.on(`before:${op}`, injectDeleteFilterToFilters, { priority: HOOK_PRIORITY.POLICY });
+			for (const op of [
+				"getById",
+				"getOne",
+				"getByQuery",
+				"count",
+				"exists",
+				"getOrCreate",
+				"distinct",
+				"aggregate"
+			]) repo.on(`before:${op}`, injectDeleteFilterToQuery, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:updateMany", (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.5.2",
+  "version": "3.5.4",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,