@classytic/mongokit 3.11.1 → 3.13.0

package/dist/{validation-chain.plugin-B0VSdcwa.d.mts → validation-chain.plugin-CAPYCj_T.d.mts}

@@ -1,7 +1,10 @@
-import { B as ObjectId, F as Logger, H as OffsetPaginationResult, T as FieldPreset, X as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, ft as SortSpec, l as CacheOptions, lt as SoftDeleteOptions, nt as RepositoryInstance, ot as SelectSpec, q as Plugin, u as CacheStats, xt as ValidatorDefinition } from "./types-Dc2aDVUi.mjs";
+import { B as ObjectId, C as FieldPreset, G as Plugin, J as PopulateSpec, Q as RepositoryContext, _t as ValidationChainOptions, et as RepositoryInstance, it as SelectSpec, j as Logger, l as CascadeOptions, st as SoftDeleteOptions, ut as SortSpec, vt as ValidatorDefinition } from "./types-BbaPZleN.mjs";
 import mongoose from "mongoose";
+import { CacheAdapter as CacheAdapter$1, CacheOptions, RepositoryCacheHandle, RepositoryCachePluginOptions, cachePlugin } from "@classytic/repo-core/cache";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
+import { TenantConfig } from "@classytic/repo-core/tenant";
 
 //#region src/plugins/aggregate-helpers.plugin.d.ts
 /**
@@ -89,12 +92,6 @@ interface AggregateHelpersMethods {
 }
 //#endregion
 //#region src/plugins/audit-log.plugin.d.ts
-/**
- * Audit log plugin that logs all repository operations
- *
- * @example
- * const repo = new Repository(Model, [auditLogPlugin(console)]);
- */
 declare function auditLogPlugin(logger: Logger): Plugin;
 //#endregion
 //#region src/plugins/audit-trail.plugin.d.ts
@@ -119,6 +116,22 @@ interface AuditTrailOptions {
    * These fields are redacted in the `changes` diff.
    */
   excludeFields?: string[];
+  /**
+   * Custom callback fired when an audit write fails. Receives the error
+   * and the entry that failed to land. Default: `console.warn` only.
+   *
+   * **Use this for compliance-grade audit trails (SOC 2 / PCI / HIPAA)
+   * where missing entries must be surfaced upstream** — e.g. forward to
+   * a dead-letter queue, page on-call, or short-circuit the request.
+   * The default `warn` log is appropriate for development and
+   * eventually-consistent observability use cases but is invisible to
+   * compliance review.
+   *
+   * The callback runs on the same fire-and-forget microtask that wrote
+   * the entry, so throwing from here will surface as an unhandled
+   * rejection — handle (or rethrow into your error reporter) inside.
+   */
+  onWriteError?: (error: Error, entry: Omit<AuditEntry, 'timestamp'>) => void;
 }
 type AuditOperation = 'create' | 'update' | 'delete' | 'findOneAndUpdate';
 interface AuditEntry {
@@ -148,7 +161,7 @@ interface AuditQueryOptions {
   limit?: number;
 }
 interface AuditQueryResult {
-  docs: AuditEntry[];
+  data: AuditEntry[];
   page: number;
   limit: number;
   total: number;
@@ -284,64 +297,6 @@ interface BatchOperationsMethods {
   }): Promise<BulkWriteResult>;
 }
 //#endregion
-//#region src/plugins/cache.plugin.d.ts
-/**
- * Cache plugin factory
- *
- * @param options - Cache configuration
- * @returns Plugin instance
- */
-declare function cachePlugin(options: CacheOptions): Plugin;
-/**
- * TypeScript interface for cache plugin methods
- *
- * @example
- * ```typescript
- * import type { CacheMethods } from '@classytic/mongokit';
- *
- * type ProductRepoWithCache = ProductRepo & CacheMethods;
- *
- * const productRepo = new ProductRepo(ProductModel, [
- *   methodRegistryPlugin(),
- *   cachePlugin({ adapter: redisAdapter, ttl: 60 }),
- * ]) as ProductRepoWithCache;
- *
- * // TypeScript autocomplete for cache methods
- * await productRepo.invalidateCache(productId);
- * await productRepo.invalidateListCache();
- * await productRepo.invalidateAllCache();
- * const stats = productRepo.getCacheStats();
- * productRepo.resetCacheStats();
- * ```
- */
-interface CacheMethods {
-  /**
-   * Invalidate cache for a specific document
-   * Use when document was updated outside this service
-   * @param id - Document ID to invalidate
-   */
-  invalidateCache(id: string): Promise<void>;
-  /**
-   * Invalidate all list caches for this model
-   * Use when bulk changes happened outside this service
-   */
-  invalidateListCache(): Promise<void>;
-  /**
-   * Invalidate ALL cache entries for this model
-   * Nuclear option - use sparingly
-   */
-  invalidateAllCache(): Promise<void>;
-  /**
-   * Get cache statistics for monitoring
-   * @returns Cache statistics (hits, misses, sets, invalidations)
-   */
-  getCacheStats(): CacheStats;
-  /**
-   * Reset cache statistics
-   */
-  resetCacheStats(): void;
-}
-//#endregion
 //#region src/plugins/cascade.plugin.d.ts
 /**
  * Cascade delete plugin.
@@ -533,6 +488,85 @@ declare function elasticSearchPlugin(options: ElasticSearchOptions): Plugin;
  */
 declare function fieldFilterPlugin(fieldPreset: FieldPreset): Plugin;
 //#endregion
+//#region src/plugins/lease.plugin.d.ts
+interface LeasePluginOptions {
+  /** Field carrying the row's status. @default `'status'` */
+  statusField?: string;
+  /** Field stamping the lease holder. @default `'leasedBy'` */
+  leasedByField?: string;
+  /** Field carrying the lease expiry timestamp. @default `'leaseExpiresAt'` */
+  leaseExpiresAtField?: string;
+  /** Status value an unleased row carries. @default `'pending'` */
+  pendingStatus?: string;
+  /** Status value a leased row carries. @default `'processing'` */
+  processingStatus?: string;
+  /** Status value a successfully released row carries. @default `'done'` */
+  doneStatus?: string;
+  /** Sort fields used to pick the FIFO winner from the lease pool. @default `{ createdAt: 1 }` */
+  sort?: Record<string, 1 | -1>;
+}
+/**
+ * Methods contributed by `leasePlugin()`. Use as a type assertion when
+ * constructing the repo so call sites get autocomplete:
+ *
+ * ```ts
+ * type OutboxRepo = Repository<IOutboxRow> & LeaseMethods<IOutboxRow>;
+ * const repo = new Repository(OutboxModel, [
+ *   methodRegistryPlugin(),
+ *   leasePlugin({ pendingStatus: 'queued' }),
+ * ]) as OutboxRepo;
+ * ```
+ */
+interface LeaseMethods<TDoc> {
+  /**
+   * Atomically claim the next available row. Matches rows that are
+   * either in `pendingStatus` OR have an expired `leaseExpiresAt` (dead
+   * lease recovery). Sets status to `processingStatus`, stamps
+   * `leasedBy`, and pushes `leaseExpiresAt = now + leaseFor`.
+   *
+   * @returns The leased doc, or `null` when no row matches.
+   */
+  lease(opts: {
+    filter?: Record<string, unknown>;
+    leaseFor: number;
+    leasedBy: string;
+    options?: Record<string, unknown>;
+  }): Promise<TDoc | null>;
+  /**
+   * Push a held lease's expiry further. Only succeeds when the lease
+   * is still ours (`leasedBy === leasedBy && leaseExpiresAt > now`).
+   * Returns `null` if the lease was lost — caller should drop the
+   * work, since someone else has already started replaying it.
+   */
+  extend(id: string | ObjectId, opts: {
+    leasedBy: string;
+    leaseFor: number;
+    options?: Record<string, unknown>;
+  }): Promise<TDoc | null>;
+  /**
+   * Release a held lease. CAS-checks `leasedBy === opts.leasedBy` AND
+   * `leaseExpiresAt > now` so only the live lease holder may finalise
+   * the row — symmetrical with `extend()`. A worker whose lease has
+   * been recovered (lease lost) MUST NOT mark someone else's
+   * in-progress work as `done` / `failed`; this method returns `null`
+   * in that race rather than overwriting.
+   *
+   * Sets status to `opts.finalStatus` (default `doneStatus`), clears
+   * `leasedBy` and `leaseExpiresAt`. Use `{ finalStatus: 'failed' }`
+   * for error paths so terminal-status filters (next caller's
+   * `lease()` predicate) skip this row.
+   *
+   * Returns the released doc, or `null` when the CAS lost (lease
+   * expired / held by another worker / row gone).
+   */
+  release(id: string | ObjectId, opts: {
+    leasedBy: string;
+    finalStatus?: string;
+    options?: Record<string, unknown>;
+  }): Promise<TDoc | null>;
+}
+declare function leasePlugin(options?: LeasePluginOptions): Plugin;
+//#endregion
 //#region src/plugins/method-registry.plugin.d.ts
 /**
  * Extended repository interface with method registry
@@ -750,16 +784,50 @@ interface MongoOperationsMethods<TDoc> {
    * });
    */
   atomicUpdate(id: string | ObjectId, operators: Record<string, Record<string, unknown>>, options?: Record<string, unknown>): Promise<TDoc>;
+  /**
+   * Atomic conditional increment — increments the field only when it is
+   * strictly below `ceiling`. Returns the updated document on success,
+   * `null` when already at/above the ceiling.
+   *
+   * Single-round-trip CAS via `findOneAndUpdate({ _id, field: { $lt:
+   * ceiling }}, { $inc: { field: by }})`. Use for per-document
+   * concurrency limits, quotas, and capacity caps where a read-then-
+   * write loop would race.
+   *
+   * @param id - Document ID
+   * @param field - Numeric field to increment
+   * @param ceiling - Increment only when the field is `< ceiling`
+   * @param by - Increment delta (default `1`; pass negative to decrement-with-floor by inverting the predicate via the call site)
+   * @param options - Operation options (session, etc.)
+   * @returns The updated document, or `null` when at/above ceiling
+   *
+   * @example Per-tenant concurrency limit
+   * ```ts
+   * const claimed = await repo.incrementIfBelow(tenantId, 'activeRuns', 10);
+   * if (!claimed) throw new ConcurrencyLimitExceeded();
+   * try { await runWorkflow(); } finally {
+   *   await repo.decrement(tenantId, 'activeRuns');
+   * }
+   * ```
+   */
+  incrementIfBelow(id: string | ObjectId, field: string, ceiling: number, by?: number, options?: Record<string, unknown>): Promise<TDoc | null>;
 }
 //#endregion
 //#region src/plugins/multi-tenant.plugin.d.ts
-interface MultiTenantOptions {
-  /** Field name used for tenant isolation (default: 'organizationId') */
-  tenantField?: string;
-  /** Context key to read tenant ID from (default: 'organizationId') */
-  contextKey?: string;
-  /** Throw if tenant ID is missing from context (default: true) */
-  required?: boolean;
+/**
+ * Static tenant fields are picked from `@classytic/repo-core/tenant` so the
+ * vocabulary (`tenantField`, `contextKey`, `required`, `fieldType`) stays
+ * locked to the org-wide canonical source. Mongokit-specific runtime
+ * callbacks (`skipWhen`, `resolveContext`, `skipOperations`,
+ * `allowDataInjection`) extend on top — those genuinely differ from
+ * sqlitekit's runtime shape because mongokit's `RepositoryContext` carries
+ * Mongoose-specific bits the resolver may inspect.
+ *
+ * Mongokit defaults `fieldType` to `'string'` (not repo-core's `'objectId'`)
+ * for back-compat — pre-3.x stored tenant ids as raw strings; flipping the
+ * default would silently change cast behavior for existing apps.
+ */
+interface MultiTenantOptions extends Pick<TenantConfig, 'tenantField' | 'contextKey' | 'required' | 'fieldType'> {
   /** Operations to skip tenant injection (e.g., for admin/system queries) */
   skipOperations?: string[];
   /**
@@ -785,39 +853,101 @@ interface MultiTenantOptions {
    */
   resolveContext?: () => string | undefined;
   /**
-   * How to store/query the tenant ID.
-   *
-   * - `'string'` (default): inject the tenant ID as-is (raw string).
-   * - `'objectId'`: cast to `mongoose.Types.ObjectId` before injecting.
-   *
-   * Choose `'objectId'` when the schema declares the tenant field as
-   * `Schema.Types.ObjectId` (e.g., Flow, accounting). This enables
-   * `$lookup` and `.populate()` against the referenced collection.
-   */
-  fieldType?: 'string' | 'objectId';
-  /**
-   * When `true` (default), bypass the `required` throw if the operation's
-   * policy target already carries the tenant field. This lets hosts that
-   * stamp the tenant into the payload themselves (e.g., `data[tenantField]`
+   * When `true`, bypass the `required` throw if the operation's policy
+   * target already carries the tenant field. This lets hosts that stamp
+   * the tenant into the payload themselves (e.g., `data[tenantField]`
    * on writes, `filters[tenantField]` on paginated reads) use the plugin
    * without having to hand-roll a `skipWhen` that duplicates this check.
    *
-   * Set to `false` to restore the pre-data-injection strict behavior: the
-   * tenant MUST come from `context` or `resolveContext`, otherwise the
-   * plugin throws (when `required: true`).
+   * **Default: `false` (secure / fail-closed).** Tenant scope MUST come
+   * from `context` or `resolveContext`, otherwise the plugin throws
+   * (when `required: true`). This is the right posture for a security-
+   * sensitive boundary: caller-supplied scope on the payload cannot be
+   * trusted as authentication. If a host control-plane has already
+   * authenticated the tenant out-of-band and stamps it onto every
+   * write/read, set this to `true` explicitly — making the trust model
+   * visible at the call site.
+   *
+   * **Migration from < 4.0:** the prior default was `true`. To preserve
+   * the old behavior verbatim, set `allowDataInjection: true`. To get
+   * the new secure default, leave it unset.
    *
-   * Composition: a user-supplied `skipWhen` still runs first and can always
-   * opt out. This option controls the behavior after `skipWhen` and
-   * `resolveContext` have had their turn.
+   * Composition: a user-supplied `skipWhen` still runs first and can
+   * always opt out. This option controls the behavior after `skipWhen`
+   * and `resolveContext` have had their turn.
    *
-   * Safety: when the payload supplies the tenant, the plugin skips its own
-   * injection (it does not overwrite). Cross-tenant isolation is therefore
-   * only as strong as the caller's own stamping — same guarantee as a
-   * hand-rolled `skipWhen`.
+   * Safety: when the payload supplies the tenant AND this is `true`,
+   * the plugin skips its own injection (it does not overwrite). Cross-
+   * tenant isolation is therefore only as strong as the caller's own
+   * stamping — same guarantee as a hand-rolled `skipWhen`.
    */
   allowDataInjection?: boolean;
 }
 declare function multiTenantPlugin(options?: MultiTenantOptions): Plugin;
+/**
+ * Build the canonical `skipWhen` callback for role-based tenant
+ * bypass — replaces the hand-rolled
+ * `(ctx) => ctx.role === 'superadmin'` callback that ~6 packages
+ * across the classytic codebase carry as boilerplate. Eliminates the
+ * "I forgot to include 'platform_admin'" drift class — the role
+ * vocabulary lives in one place.
+ *
+ * **Composes with `bypassTenant: true` per-call**, doesn't replace
+ * it. `bypassTenant` is the deliberate per-call form for migration
+ * scripts and one-off admin queries; `adminBypass` is the
+ * always-on role-based bypass for users whose JWT / session carries
+ * a privileged role.
+ *
+ * **NOT a substitute for authentication or RBAC.** This factory only
+ * answers "should the tenant scope hook fire for this call?" — it
+ * does NOT validate that the caller is authenticated, that their
+ * role claim is genuine, or that the requested operation is
+ * permitted. Always run auth + RBAC before the call reaches the
+ * repository layer; this is the LAST gate, not the only one.
+ *
+ * @example Single role
+ * ```ts
+ * import { adminBypass, multiTenantPlugin } from '@classytic/mongokit';
+ *
+ * const repo = new Repository(InvoiceModel, [
+ *   multiTenantPlugin({
+ *     tenantField: 'organizationId',
+ *     skipWhen: adminBypass({ adminRoles: ['superadmin'] }),
+ *   }),
+ * ]);
+ *
+ * await repo.getAll({}, { role: 'superadmin' }); // sees all orgs
+ * await repo.getAll({}, { role: 'user', organizationId: 'org-1' }); // scoped
+ * ```
+ *
+ * @example Multiple admin roles + custom field name
+ * ```ts
+ * skipWhen: adminBypass({
+ *   roleField: 'principalRole',                  // ctx.principalRole, not ctx.role
+ *   adminRoles: ['superadmin', 'platform_admin', 'support'],
+ * }),
+ * ```
+ *
+ * @example Composing with custom logic
+ * ```ts
+ * // adminBypass for the role check, then your own additional logic:
+ * const adminCheck = adminBypass({ adminRoles: ['superadmin'] });
+ * skipWhen: (ctx, op) => adminCheck(ctx, op) || ctx.internalSystemFlag === true,
+ * ```
+ *
+ * @param options.roleField - Path on the context to read the role
+ *   from. Defaults to `'role'`. Top-level keys only — for nested
+ *   shapes (e.g. `ctx.user.role`), wrap your own `(ctx) => …` callback
+ *   instead.
+ * @param options.adminRoles - Role values that grant the bypass. The
+ *   factory does an exact-match `includes` check — case-sensitive,
+ *   no fuzzy matching. Lowercase your role vocabulary upstream.
+ * @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
+ */
+declare function adminBypass(options: {
+  roleField?: string;
+  adminRoles: readonly string[];
+}): (context: RepositoryContext, operation: string) => boolean;
 //#endregion
 //#region src/plugins/observability.plugin.d.ts
 interface OperationMetric {
@@ -1090,4 +1220,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-export { aggregateHelpersPlugin as $, PrefixedIdOptions as A, BatchOperationsMethods as B, methodRegistryPlugin as C, CustomIdOptions as D, elasticSearchPlugin as E, prefixedId as F, AuditQueryOptions as G, batchOperationsPlugin as H, sequentialId as I, AuditTrailOptions as J, AuditQueryResult as K, cascadePlugin as L, customIdPlugin as M, dateSequentialId as N, DateSequentialIdOptions as O, getNextSequence as P, AggregateHelpersMethods as Q, CacheMethods as R, MethodRegistryRepository as S, ElasticSearchOptions as T, AuditEntry as U, BulkWriteResult as V, AuditOperation as W, auditTrailPlugin as X, AuditTrailQuery as Y, auditLogPlugin as Z, observabilityPlugin as _, uniqueField as a, MongoOperationsMethods as b, TenantContext as c, SubdocumentMethods as d, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, SequentialIdOptions as j, IdGenerator as k, TenantStore as l, softDeletePlugin as m, blockIf as n, validationChainPlugin as o, SoftDeleteMethods as p, AuditTrailMethods as q, immutableField as r, timestampPlugin as s, autoInject as t, createTenantContext as u, MultiTenantOptions as v, fieldFilterPlugin as w, mongoOperationsPlugin as x, multiTenantPlugin as y, cachePlugin as z };
+export { AuditQueryResult as $, elasticSearchPlugin as A, sequentialId as B, MethodRegistryRepository as C, leasePlugin as D, LeasePluginOptions as E, SequentialIdOptions as F, RepositoryCachePluginOptions as G, CacheAdapter$1 as H, customIdPlugin as I, BulkWriteResult as J, cachePlugin as K, dateSequentialId as L, DateSequentialIdOptions as M, IdGenerator as N, fieldFilterPlugin as O, PrefixedIdOptions as P, AuditQueryOptions as Q, getNextSequence as R, mongoOperationsPlugin as S, LeaseMethods as T, CacheOptions as U, cascadePlugin as V, RepositoryCacheHandle as W, AuditEntry as X, batchOperationsPlugin as Y, AuditOperation as Z, observabilityPlugin as _, uniqueField as a, AggregateHelpersMethods as at, multiTenantPlugin as b, TenantContext as c, SubdocumentMethods as d, AuditTrailMethods as et, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, auditLogPlugin as it, CustomIdOptions as j, ElasticSearchOptions as k, TenantStore as l, softDeletePlugin as m, blockIf as n, AuditTrailQuery as nt, validationChainPlugin as o, aggregateHelpersPlugin as ot, SoftDeleteMethods as p, BatchOperationsMethods as q, immutableField as r, auditTrailPlugin as rt, timestampPlugin as s, autoInject as t, AuditTrailOptions as tt, createTenantContext as u, MultiTenantOptions as v, methodRegistryPlugin as w, MongoOperationsMethods as x, adminBypass as y, prefixedId as z };