@classytic/mongokit 3.21.0 → 3.22.1

package/dist/usage/index.mjs

@@ -0,0 +1,67 @@
+import { n as isDuplicateKeyError } from "../error-BuByZwKU.mjs";
+import mongoose, { Schema } from "mongoose";
+//#region src/usage/index.ts
+/**
+* Build a Mongo-backed usage store. Idempotent — the underlying model
+* is registered once per `(connection, modelName)` pair.
+*/
+function createMongoUsageStore(options = {}) {
+	const { connection, collectionName = "usage_counters", modelName = "MongoUsageCounter" } = options;
+	const model = getOrCreateModel(connection ?? mongoose, modelName, collectionName);
+	return {
+		name: "mongo",
+		async increment(bucket, amount) {
+			const filter = {
+				actor: bucket.actor,
+				period: bucket.period,
+				kind: bucket.kind
+			};
+			try {
+				await model.updateOne(filter, { $inc: { count: amount } }, { upsert: true });
+			} catch (err) {
+				if (!isDuplicateKeyError(err)) throw err;
+				await model.updateOne(filter, { $inc: { count: amount } }, { upsert: true });
+			}
+		},
+		async summary(actor, period) {
+			const rows = await model.find({
+				actor,
+				period
+			}).select("kind count").lean();
+			const out = {};
+			for (const row of rows) out[row.kind] = row.count;
+			return out;
+		}
+	};
+}
+function getOrCreateModel(conn, modelName, collectionName) {
+	const existing = "models" in conn ? conn.models[modelName] : void 0;
+	if (existing) return existing;
+	const schema = new Schema({
+		actor: {
+			type: String,
+			required: true
+		},
+		period: {
+			type: String,
+			required: true
+		},
+		kind: {
+			type: String,
+			required: true
+		},
+		count: {
+			type: Number,
+			required: true,
+			default: 0
+		}
+	}, { versionKey: false });
+	schema.index({
+		actor: 1,
+		period: 1,
+		kind: 1
+	}, { unique: true });
+	return conn.model(modelName, schema, collectionName);
+}
+//#endregion
+export { createMongoUsageStore };

package/dist/utils/index.d.mts

@@ -1,2 +1,2 @@
-import { a as IdType, c as isObjectIdInstance, d as filterResponseData, f as getFieldsForUser, i as configureLogger, l as isValidIdForType, m as createError, n as buildCrudSchemasFromMongooseSchema, o as getSchemaIdType, p as getMongooseProjection, r as createMemoryCache, t as buildCrudSchemasFromModel, u as createFieldPreset } from "../mongooseToJsonSchema-D2CyAMIC.mjs";
-export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType };
+import { a as configureLogger, d as createFieldPreset, f as filterResponseData, h as createError, i as createMemoryCache, l as isObjectIdInstance, m as getMongooseProjection, n as buildCrudSchemasFromModel, o as IdType, p as getFieldsForUser, r as buildCrudSchemasFromMongooseSchema, s as getSchemaIdType, t as toPlain, u as isValidIdForType } from "../to-plain-qzKeAC6z.mjs";
+export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toPlain };

package/dist/utils/index.mjs

@@ -2,6 +2,6 @@ import { i as isValidIdForType, r as isObjectIdInstance, t as getSchemaIdType }
 import { t as configureLogger } from "../logger-K7dPmu2U.mjs";
 import { t as createError } from "../error-BuByZwKU.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "../field-selection-FSQFLpsU.mjs";
-import { t as createMemoryCache } from "../memory-cache-DI1jb4dz.mjs";
+import { n as createMemoryCache, t as toPlain } from "../to-plain-vksRrLtc.mjs";
 import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-CVnrKFDq.mjs";
-export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType };
+export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toPlain };

package/dist/{validation-chain.plugin-buy3uvyk.d.mts → validation-chain.plugin-D-EjrYpR.d.mts}

@@ -1,4 +1,4 @@
-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-DNFMofHy.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-BnRqAJVa.mjs";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
@@ -87,6 +87,26 @@ interface AggregateHelpersMethods {
   max(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
 }
 //#endregion
+//#region src/plugins/append-only.plugin.d.ts
+interface AppendOnlyPluginOptions {
+  /**
+   * Mutating ops to permit besides `create` / `createMany`. Use for a
+   * domain's ONE legitimate mutation path (e.g. GDPR `deleteMany`) —
+   * every allowed op still flows through the rest of the plugin stack
+   * (tenant scope, audit) as usual.
+   */
+  allow?: readonly string[] | undefined;
+  /**
+   * Hook priority for the fence. Default `HOOK_PRIORITY.POLICY` (100).
+   * Ledger repos that want the append-only refusal to win over other
+   * policy errors (e.g. a missing-tenant throw) register BELOW policy —
+   * flow's StockEvent uses `50` so the violation always reads
+   * "append-only", never "missing organizationId".
+   */
+  priority?: number | undefined;
+}
+declare function appendOnlyPlugin(options?: AppendOnlyPluginOptions): Plugin;
+//#endregion
 //#region src/plugins/audit-log.plugin.d.ts
 declare function auditLogPlugin(logger: Logger): Plugin;
 //#endregion
@@ -163,6 +183,47 @@ declare function elasticSearchPlugin(options: ElasticSearchOptions): Plugin;
  */
 declare function fieldFilterPlugin(fieldPreset: FieldPreset): Plugin;
 //#endregion
+//#region src/plugins/immutable-states.plugin.d.ts
+/** The slice of a `before:claim` context `allowClaim` predicates see. */
+interface ImmutableClaimView {
+  id: unknown;
+  transition: {
+    from?: unknown | readonly unknown[];
+    to?: unknown;
+    field?: string;
+    where?: Record<string, unknown>;
+  };
+  /** Operator-form patch (`{ $set: {...}, ... }`). */
+  data: Record<string, unknown> | undefined;
+}
+interface ImmutableStatesPluginOptions {
+  /** States in which the document is frozen (e.g. `['posted']`). */
+  states: readonly string[];
+  /** State field on the doc — dotted paths supported. Default `'state'`. */
+  field?: string | undefined;
+  /**
+   * Context flag the OWNING ENGINE's verbs set to pass the guard
+   * (private handshake — see module doc). Default `'_immutableInternal'`.
+   */
+  internalFlag?: string | undefined;
+  /** Tenant field used to scope state lookups (mirrors the repo's scope). */
+  tenantField?: string | undefined;
+  /**
+   * Exempt specific claim shapes that legitimately touch frozen rows
+   * (audit-trail stamps like ledger's reverse-mark). Return `true` to
+   * allow. Runs only after the claim was determined to reach a frozen
+   * state — keep the predicate a strict fingerprint.
+   */
+  allowClaim?: ((view: ImmutableClaimView) => boolean) | undefined;
+  /** Domain error to throw. Default: 403 `IMMUTABLE_STATE_VIOLATION`. */
+  errorFactory?: ((ctx: {
+    id: unknown;
+    operation: string;
+    state?: string | undefined;
+  }) => Error) | undefined;
+}
+declare function immutableStatesPlugin(options: ImmutableStatesPluginOptions): Plugin;
+//#endregion
 //#region src/plugins/lease.plugin.d.ts
 interface LeasePluginOptions {
   /** Field carrying the row's status. @default `'status'` */
@@ -759,4 +820,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-export { BulkWriteResult as A, LeasePluginOptions as C, elasticSearchPlugin as D, ElasticSearchOptions as E, auditLogPlugin as M, AggregateHelpersMethods as N, cascadePlugin as O, aggregateHelpersPlugin as P, LeaseMethods as S, fieldFilterPlugin as T, observabilityPlugin as _, uniqueField as a, MethodRegistryRepository as b, TenantContext as c, SubdocumentMethods as d, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, batchOperationsPlugin as j, BatchOperationsMethods as k, TenantStore as l, softDeletePlugin as m, blockIf as n, validationChainPlugin as o, SoftDeleteMethods as p, immutableField as r, timestampPlugin as s, autoInject as t, createTenantContext as u, MongoOperationsMethods as v, leasePlugin as w, methodRegistryPlugin as x, mongoOperationsPlugin as y };
+export { elasticSearchPlugin as A, LeasePluginOptions as C, immutableStatesPlugin as D, ImmutableStatesPluginOptions as E, auditLogPlugin as F, AppendOnlyPluginOptions as I, appendOnlyPlugin as L, BatchOperationsMethods as M, BulkWriteResult as N, fieldFilterPlugin as O, batchOperationsPlugin as P, AggregateHelpersMethods as R, LeaseMethods as S, ImmutableClaimView as T, observabilityPlugin as _, uniqueField as a, MethodRegistryRepository as b, TenantContext as c, SubdocumentMethods as d, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, cascadePlugin as j, ElasticSearchOptions as k, TenantStore as l, softDeletePlugin as m, blockIf as n, validationChainPlugin as o, SoftDeleteMethods as p, immutableField as r, timestampPlugin as s, autoInject as t, createTenantContext as u, MongoOperationsMethods as v, leasePlugin as w, methodRegistryPlugin as x, mongoOperationsPlugin as y, aggregateHelpersPlugin as z };

package/dist/{validation-chain.plugin-Dn_wZYLA.mjs → validation-chain.plugin-D6qWMH5d.mjs}

@@ -1,9 +1,10 @@
-import { s as ALL_OPERATIONS } from "./Repository-dbbgOGjK.mjs";
+import { l as OP_REGISTRY, s as ALL_OPERATIONS } from "./Repository-Dr1MDAen.mjs";
 import { _ as upsert } from "./update-1Lq9OMD2.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
 import { r as getFieldsForUser } from "./field-selection-FSQFLpsU.mjs";
 import mongoose from "mongoose";
+import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/plugins/aggregate-helpers.plugin.ts
 /**
@@ -69,6 +70,90 @@ function aggregateHelpersPlugin() {
 	};
 }
 //#endregion
+//#region src/plugins/append-only.plugin.ts
+/**
+* Append-Only Plugin
+*
+* Turns a repository into an immutable-facts ledger: inserts land,
+* everything else is refused at POLICY priority. The enforcement
+* layer for event-sourced planes — flow's `StockEvent`,
+* manufacturing's `ProductionEvent`, audit sinks, outbox archives —
+* where a mutable row would silently corrupt the audit/time-travel
+* story that the whole collection exists to provide.
+*
+* Grep-proof by construction: hand-fenced `update()`/`delete()`
+* overrides only cover the verbs someone remembered to override; this
+* plugin derives coverage from `OP_REGISTRY`, so every mutating op —
+* including `claim`, `claimVersion`, `restore`, `bulkWrite`, and any
+* op added to the registry later — is refused automatically.
+*
+* Allowed by default: `create`, `createMany` (appends). `getOrCreate`
+* is registry-classified as a read and stays available — it can only
+* INSERT or return the existing row, never mutate one, which is
+* append-safe by definition (idempotency stores rely on it).
+* Refused by default: `update`, `findOneAndUpdate`, `updateMany`,
+* `delete`, `deleteMany`, `restore`, `claim`, `claimVersion`,
+* `bulkWrite` (wholesale — mixed insert/update batches are ambiguous;
+* append via `createMany` instead). Composed methods from other
+* plugins (`incrementIfBelow`, lease ops) decompose into these
+* registry ops internally, so the fence catches them too.
+*
+* TTL indexes are unaffected (server-side GC never touches the repo
+* layer) — TTL-expiring an idempotency ledger still works. Raw
+* `Model.*` driver calls bypass every plugin, this one included —
+* the org-wide "never drop to Model.deleteOne" rule is what covers
+* that hole, same as for tenant scope.
+*
+* **Escape hatches** (both audited via `after:append-only-bypass`):
+*   - Plugin-level `allow` — ops the DOMAIN legitimately needs, wired
+*     once at construction (e.g. `allow: ['deleteMany']` for a
+*     GDPR-erasure path the host gates behind admin roles).
+*   - Per-call `bypassAppendOnly: true` — deliberate one-off
+*     maintenance (backfill repair, migration), grep-auditable at the
+*     call site.
+*
+* `skipPlugins` is deliberately IGNORED — same policy as tenant scope
+* and soft delete: integrity fences don't have a convenience bypass.
+*
+* @example
+* const events = new Repository(StockEventModel, [
+*   multiTenantPlugin({ ... }),
+*   appendOnlyPlugin(),
+* ]);
+* await events.create({ ... });            // OK
+* await events.update(id, { ... });        // throws 405 APPEND_ONLY_VIOLATION
+* await events.deleteMany({ ... }, { bypassAppendOnly: true }); // audited bypass
+*/
+const ALWAYS_ALLOWED = /* @__PURE__ */ new Set(["create", "createMany"]);
+function appendOnlyPlugin(options = {}) {
+	const allowed = /* @__PURE__ */ new Set([...ALWAYS_ALLOWED, ...options.allow ?? []]);
+	return {
+		name: "appendOnly",
+		apply(repo) {
+			const modelName = repo.Model?.modelName ?? "model";
+			for (const [op, meta] of Object.entries(OP_REGISTRY)) {
+				if (!meta.mutates || allowed.has(op)) continue;
+				repo.on(`before:${op}`, (context) => {
+					if (context.bypassAppendOnly === true) {
+						repo.emit("after:append-only-bypass", {
+							operation: op,
+							context
+						});
+						return;
+					}
+					throw createError(405, `${modelName} is append-only: '${op}' is not permitted. Rows on this collection are immutable facts (event ledger). Append a compensating row instead; for deliberate maintenance pass bypassAppendOnly: true (audited via 'after:append-only-bypass').`, {
+						code: "APPEND_ONLY_VIOLATION",
+						meta: {
+							operation: op,
+							model: modelName
+						}
+					});
+				}, { priority: options.priority ?? HOOK_PRIORITY.POLICY });
+			}
+		}
+	};
+}
+//#endregion
 //#region src/plugins/cascade.plugin.ts
 /**
 * Cascade Delete Plugin
@@ -391,6 +476,140 @@ function fieldFilterPlugin(fieldPreset) {
 	};
 }
 //#endregion
+//#region src/plugins/immutable-states.plugin.ts
+/** Ops this plugin has an explicit strategy for (see module doc). */
+const STRATEGY_OPS = /* @__PURE__ */ new Set([
+	"create",
+	"createMany",
+	"update",
+	"delete",
+	"claimVersion",
+	"restore",
+	"findOneAndUpdate",
+	"updateMany",
+	"deleteMany",
+	"bulkWrite",
+	"claim"
+]);
+function immutableStatesPlugin(options) {
+	const field = options.field ?? "state";
+	const internalFlag = options.internalFlag ?? "_immutableInternal";
+	const frozen = new Set(options.states);
+	const throwViolation = (ctx) => {
+		if (options.errorFactory) throw options.errorFactory(ctx);
+		throw createError(403, `Document ${String(ctx.id)} is in immutable state${ctx.state !== void 0 ? ` '${ctx.state}'` : ""} — '${ctx.operation}' is not permitted. Frozen rows change only through the owning engine's transition verbs.`, {
+			code: "IMMUTABLE_STATE_VIOLATION",
+			meta: { ...ctx }
+		});
+	};
+	return {
+		name: "immutableStates",
+		apply(repo) {
+			const unhandled = Object.entries(OP_REGISTRY).filter(([op, meta]) => meta.mutates && !STRATEGY_OPS.has(op)).map(([op]) => op);
+			if (unhandled.length > 0) throw createError(500, `immutableStatesPlugin has no strategy for mutating op(s): ${unhandled.join(", ")}. Mongokit added write ops this plugin predates — extend the plugin before using it.`, {
+				code: "IMMUTABLE_STATES_UNHANDLED_OPS",
+				meta: { unhandled }
+			});
+			const Model = repo.Model;
+			const getState = (doc) => field.split(".").reduce((acc, key) => acc?.[key], doc);
+			const scoped = (base, ctx) => {
+				const q = { ...base };
+				if (options.tenantField && ctx.query && options.tenantField in ctx.query) q[options.tenantField] = ctx.query[options.tenantField];
+				return q;
+			};
+			/** Raw-Model read — never re-enters the repo hook pipeline. */
+			const readStateById = async (ctx) => {
+				if (ctx.id === void 0 || ctx.id === null) return void 0;
+				const doc = await Model.findOne(scoped({ _id: ctx.id }, ctx)).select({ [field]: 1 }).lean();
+				return doc ? getState(doc) : void 0;
+			};
+			const guardById = (op) => async (ctx) => {
+				if (ctx[internalFlag]) return;
+				const state = await readStateById(ctx);
+				if (state !== void 0 && frozen.has(state)) throwViolation({
+					id: ctx.id,
+					operation: op,
+					state
+				});
+			};
+			for (const op of [
+				"update",
+				"delete",
+				"claimVersion",
+				"restore"
+			]) repo.on(`before:${op}`, guardById(op));
+			repo.on("before:findOneAndUpdate", async (ctx) => {
+				if (ctx[internalFlag]) return;
+				const filter = ctx.query ?? {};
+				const doc = await Model.findOne(filter).select({
+					[field]: 1,
+					_id: 1
+				}).lean();
+				if (!doc) return;
+				const state = getState(doc);
+				if (state !== void 0 && frozen.has(state)) throwViolation({
+					id: doc._id,
+					operation: "findOneAndUpdate",
+					state
+				});
+			});
+			const guardMany = (op) => async (ctx) => {
+				if (ctx[internalFlag]) return;
+				const filter = ctx.query ?? {};
+				const hit = await Model.exists({ $and: [filter, { [field]: { $in: [...frozen] } }] });
+				if (hit) throwViolation({
+					id: hit._id,
+					operation: op,
+					state: void 0
+				});
+			};
+			repo.on("before:updateMany", guardMany("updateMany"));
+			repo.on("before:deleteMany", guardMany("deleteMany"));
+			repo.on("before:bulkWrite", (ctx) => {
+				if (ctx[internalFlag]) return;
+				throwViolation({
+					id: void 0,
+					operation: "bulkWrite",
+					state: void 0
+				});
+			});
+			repo.on("before:claim", async (rawCtx) => {
+				const ctx = rawCtx;
+				if (ctx[internalFlag]) return;
+				const t = ctx.transition;
+				if (!t) return;
+				if ((t.field ?? "status") === field) {
+					const fromSpec = t.from;
+					if (!(Array.isArray(fromSpec) ? fromSpec.some((f) => frozen.has(String(f))) : frozen.has(String(fromSpec)))) return;
+					if (options.allowClaim?.({
+						id: ctx.id,
+						transition: t,
+						data: ctx.data
+					})) return;
+					throwViolation({
+						id: ctx.id,
+						operation: "claim",
+						state: void 0
+					});
+				}
+				const state = await readStateById(ctx);
+				if (state !== void 0 && frozen.has(state)) {
+					if (options.allowClaim?.({
+						id: ctx.id,
+						transition: t,
+						data: ctx.data
+					})) return;
+					throwViolation({
+						id: ctx.id,
+						operation: "claim",
+						state
+					});
+				}
+			});
+		}
+	};
+}
+//#endregion
 //#region src/plugins/lease.plugin.ts
 function leasePlugin(options = {}) {
 	const statusField = options.statusField ?? "status";
@@ -1053,4 +1272,4 @@ function uniqueField(field, errorMessage) {
 	};
 }
 //#endregion
-export { uniqueField as a, subdocumentPlugin as c, leasePlugin as d, fieldFilterPlugin as f, aggregateHelpersPlugin as h, requireField as i, observabilityPlugin as l, cascadePlugin as m, blockIf as n, validationChainPlugin as o, elasticSearchPlugin as p, immutableField as r, createTenantContext as s, autoInject as t, mongoOperationsPlugin as u };
+export { aggregateHelpersPlugin as _, uniqueField as a, subdocumentPlugin as c, leasePlugin as d, immutableStatesPlugin as f, appendOnlyPlugin as g, cascadePlugin as h, requireField as i, observabilityPlugin as l, elasticSearchPlugin as m, blockIf as n, validationChainPlugin as o, fieldFilterPlugin as p, immutableField as r, createTenantContext as s, autoInject as t, mongoOperationsPlugin as u };