@web-ts-toolkit/moo 0.55.0 → 0.57.0

package/index.mjs

@@ -480,6 +480,341 @@ function cascadeDeletePlugin(schema, options) {
   });
 }
 
+// src/plugins/derived-fields/definitions.ts
+function defineDerivedField(definition) {
+  return definition;
+}
+var DerivedFieldsDependencyError = class extends Error {
+  constructor(issues) {
+    const snapshot = Object.freeze(
+      issues.map(
+        ({ targetPath, missingPaths }) => Object.freeze({ targetPath, missingPaths: Object.freeze([...missingPaths]) })
+      )
+    );
+    const details = snapshot.map(
+      ({ targetPath, missingPaths }) => `${JSON.stringify(targetPath)} requires ${missingPaths.map((path) => JSON.stringify(path)).join(", ")}`
+    ).join("; ");
+    super(`derivedFieldsPlugin missing dependencies: ${details}`);
+    /** Stable discriminator, including across separately bundled entrypoints. */
+    this.code = "MOO_DERIVED_FIELDS_MISSING_DEPENDENCIES";
+    this.name = "DerivedFieldsDependencyError";
+    this.issues = snapshot;
+  }
+};
+
+// src/plugins/derived-fields/lifecycle.ts
+import { isDeepStrictEqual } from "util";
+import { Document } from "mongoose";
+
+// src/plugins/derived-fields/planner.ts
+var hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+var isFullySelected = (document, path) => {
+  const projection = document.$__?.selected;
+  if (projection) {
+    if (hasOwn(projection, path) && projection[path] !== 1 && projection[path] !== true) return false;
+    const keys = Object.keys(projection);
+    if (keys.some((key) => key.startsWith(`${path}.`))) return false;
+    if (path !== "_id" && keys.length === 1 && projection._id === false) return true;
+  }
+  return document.isDirectSelected(path);
+};
+function planDerivedFields(registration, document, options = {}) {
+  const replacedPaths = registration.inputPaths.filter(
+    (path) => options.knownReplacedPaths?.has(path) || document.isDirectModified(path) && !document.$__?.primitiveAtomics?.[path]
+  );
+  const replacements = new Set(replacedPaths);
+  const availablePaths = registration.inputPaths.filter(
+    (path) => document.isNew || replacements.has(path) || isFullySelected(document, path)
+  );
+  const available = new Set(availablePaths);
+  const fields = registration.fields.filter(
+    (field) => document.isNew || field.mode === "always" || document.isDirectModified(field.targetPath) || options.pendingWritePaths?.has(field.targetPath) || field.dependsOn.some((path) => document.isModified(path) || options.pendingWritePaths?.has(path))
+  );
+  const issues = [];
+  for (const field of fields) {
+    const dependencies = field.mode === "always" ? registration.inputPaths : field.dependsOn;
+    const missingPaths = dependencies.filter((path) => !available.has(path));
+    if (missingPaths.length) issues.push({ targetPath: field.targetPath, missingPaths });
+  }
+  if (issues.length) throw new DerivedFieldsDependencyError(issues);
+  return Object.freeze({
+    fields: Object.freeze(fields),
+    availablePaths: Object.freeze(availablePaths),
+    replacedPaths: Object.freeze(replacedPaths)
+  });
+}
+
+// src/plugins/derived-fields/registration.ts
+var supportedDerivedFieldTypes = Object.freeze([
+  "String",
+  "Number",
+  "Boolean",
+  "Date",
+  "ObjectId",
+  "Decimal128",
+  "BigInt"
+]);
+var registrationKey = /* @__PURE__ */ Symbol.for("@web-ts-toolkit/moo/derived-fields/registration");
+var hasOwn2 = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+var isRootPath = (path) => path.length > 0 && !/[.\s$\0]/.test(path);
+var isSupportedPath = (path, type) => isRootPath(path) && supportedDerivedFieldTypes.includes(type.instance);
+var configurationError = (targetPath, reason) => {
+  throw new TypeError(`derivedFieldsPlugin target ${JSON.stringify(targetPath)}: ${reason}`);
+};
+var parseDefinition = (targetPath, value) => {
+  if (typeof value === "function") {
+    return Object.freeze({
+      targetPath,
+      mode: "always",
+      dependsOn: Object.freeze([]),
+      get: value
+    });
+  }
+  if (value === null || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    return configurationError(targetPath, "derived must be a getter function or a plain { dependsOn, get } descriptor");
+  }
+  if (Reflect.ownKeys(value).some((key) => key !== "dependsOn" && key !== "get") || !hasOwn2(value, "dependsOn") || !hasOwn2(value, "get")) {
+    return configurationError(targetPath, "derived descriptors require exactly dependsOn and get");
+  }
+  const descriptor = value;
+  if (!Array.isArray(descriptor.dependsOn) || typeof descriptor.get !== "function") {
+    return configurationError(targetPath, "dependsOn must be an array of root path names and get must be a function");
+  }
+  const dependencies = [];
+  for (const dependency of descriptor.dependsOn) {
+    if (typeof dependency !== "string" || !isRootPath(dependency)) {
+      return configurationError(
+        targetPath,
+        "dependsOn must contain only non-empty root path names (no dots, whitespace, or $)"
+      );
+    }
+    if (dependencies.includes(dependency)) {
+      return configurationError(targetPath, `duplicate dependency path ${JSON.stringify(dependency)}`);
+    }
+    dependencies.push(dependency);
+  }
+  return Object.freeze({
+    targetPath,
+    mode: "dependencies",
+    dependsOn: Object.freeze(dependencies),
+    get: descriptor.get
+  });
+};
+function registerDerivedFields(schema) {
+  const markedSchema = schema;
+  if (hasOwn2(markedSchema, registrationKey)) {
+    throw new TypeError("derivedFieldsPlugin is already registered on this schema");
+  }
+  const fields = [];
+  const versionKey = schema.options.versionKey;
+  const visitSchema = (current, prefix, ancestors) => {
+    current.eachPath((path, type) => {
+      const fullPath = `${prefix}${path}`;
+      if (!hasOwn2(type.options, "derived")) return;
+      if (prefix || !isSupportedPath(path, type)) {
+        configurationError(
+          fullPath,
+          `only root scalar persisted paths are supported (${supportedDerivedFieldTypes.join(", ")})`
+        );
+      }
+      if (path === versionKey) {
+        configurationError(
+          fullPath,
+          `Mongoose-managed version key ${JSON.stringify(versionKey)} cannot be a derived target`
+        );
+      }
+      if (path === "_id" || (type.$immutable ?? type.options.immutable)) {
+        configurationError(fullPath, "immutable targets are not supported");
+      }
+      fields.push(parseDefinition(fullPath, type.options.derived));
+    });
+    const virtuals = current.virtuals;
+    for (const [path, virtual] of Object.entries(virtuals)) {
+      if (hasOwn2(virtual.options, "derived")) {
+        configurationError(`${prefix}${path}`, "derived targets must be persisted schema paths, not virtuals");
+      }
+    }
+    if (ancestors.has(current)) return;
+    const nextAncestors = /* @__PURE__ */ new Set([...ancestors, current]);
+    const visitEmbedded = (type, path) => {
+      if (type.schema) {
+        visitSchema(type.schema, `${path}.`, nextAncestors);
+        return;
+      }
+      for (const member of type.schemaTypes ?? []) {
+        if (hasOwn2(member.options, "derived")) {
+          configurationError(path, "derived targets inside union containers are not supported");
+        }
+        visitEmbedded(member, path);
+      }
+      const embedded = type.getEmbeddedSchemaType?.() ?? type.caster ?? type.$embeddedSchemaType ?? type.$__schemaType;
+      if (!embedded || embedded === type) return;
+      const embeddedPath = `${path}.${type.instance === "Map" ? "$*" : "$"}`;
+      if (hasOwn2(embedded.options, "derived")) {
+        configurationError(embeddedPath, "derived targets inside containers are not supported");
+      }
+      visitEmbedded(embedded, embeddedPath);
+    };
+    current.eachPath((path, type) => visitEmbedded(type, `${prefix}${path}`));
+  };
+  visitSchema(schema, "", /* @__PURE__ */ new Set());
+  const targets = new Set(fields.map((field) => field.targetPath));
+  for (const field of fields) {
+    for (const dependency of field.dependsOn) {
+      if (dependency === versionKey) {
+        configurationError(
+          field.targetPath,
+          `Mongoose-managed version key ${JSON.stringify(versionKey)} cannot be a dependency`
+        );
+      }
+      if (targets.has(dependency)) {
+        configurationError(
+          field.targetPath,
+          `dependency path ${JSON.stringify(dependency)} is itself a derived target`
+        );
+      }
+      const type = schema.path(dependency);
+      if (!type) {
+        configurationError(field.targetPath, `unknown or non-persisted dependency path ${JSON.stringify(dependency)}`);
+      }
+      if (!isSupportedPath(dependency, type)) {
+        configurationError(
+          field.targetPath,
+          `dependency path ${JSON.stringify(dependency)} must be a supported root scalar persisted path`
+        );
+      }
+    }
+  }
+  const inputPaths = [];
+  schema.eachPath((path, type) => {
+    if (path !== versionKey && !targets.has(path) && isSupportedPath(path, type)) inputPaths.push(path);
+  });
+  const registration = Object.freeze({ fields: Object.freeze(fields), inputPaths: Object.freeze(inputPaths) });
+  Object.defineProperty(markedSchema, registrationKey, { value: registration });
+  return registration;
+}
+
+// src/plugins/derived-fields/snapshot.ts
+import { Types } from "mongoose";
+function cloneDerivedScalar(value) {
+  if (value instanceof Date) return new Date(value.getTime());
+  if (value !== null && typeof value === "object") {
+    const bson = value;
+    if (bson._bsontype === "ObjectId") return new Types.ObjectId(Buffer.from(bson.id));
+    if (bson._bsontype === "Decimal128") return new Types.Decimal128(Buffer.from(bson.bytes));
+  }
+  return value;
+}
+function readDerivedScalar(document, path) {
+  const id = document.populated(path);
+  return id === void 0 ? document.get(path, void 0, { getters: false }) : id;
+}
+function snapshotDerivedInputs(document, paths) {
+  return copyDerivedSnapshot(Object.fromEntries(paths.map((path) => [path, readDerivedScalar(document, path)])));
+}
+function copyDerivedSnapshot(snapshot, paths = Object.keys(snapshot)) {
+  return Object.freeze(Object.fromEntries(paths.map((path) => [path, cloneDerivedScalar(snapshot[path])])));
+}
+
+// src/plugins/derived-fields/lifecycle.ts
+var watchedPaths = (plan) => [
+  ...new Set(plan.fields.flatMap((field) => field.mode === "always" ? plan.availablePaths : field.dependsOn))
+];
+function derivedFieldsPlugin(schema) {
+  const registration = registerDerivedFields(schema);
+  const trackedPaths = [...registration.inputPaths, ...registration.fields.map((field) => field.targetPath)];
+  const states = /* @__PURE__ */ new WeakMap();
+  const stateFor = (document) => {
+    let state = states.get(document);
+    if (!state) {
+      state = { replacedPaths: /* @__PURE__ */ new Set(), assignedPaths: /* @__PURE__ */ new Set(), applyingResults: false };
+      states.set(document, state);
+    }
+    return state;
+  };
+  for (const path of trackedPaths) {
+    schema.path(path).set(function derivedFieldsObserveAssignment(value, _priorValue, _schemaType, options) {
+      if (this instanceof Document && !this.isNew && !options?._skipMarkModified && !isFullySelected(this, path)) {
+        const state = stateFor(this);
+        if (!state.applyingResults) state.assignedPaths.add(path);
+      }
+      return value;
+    });
+  }
+  const planFor = (document, state) => {
+    for (const path of state.assignedPaths) {
+      if (!document.$__.validationError?.errors[path] && !document.$__.primitiveAtomics?.[path]) {
+        document.markModified(path);
+      }
+    }
+    state.assignedPaths.clear();
+    const pendingWritePaths = new Set(
+      document.isNew ? [] : trackedPaths.filter(
+        (path) => path !== "_id" && document.$isDefault(path) && document.$__.selected?.[path] !== 0 && document.get(path, void 0, { getters: false }) != null
+      )
+    );
+    const plan = planDerivedFields(registration, document, {
+      knownReplacedPaths: state.replacedPaths,
+      pendingWritePaths
+    });
+    state.replacedPaths = new Set(document.isNew ? plan.availablePaths : plan.replacedPaths);
+    return plan;
+  };
+  const matches = (document, plan, checkpoint) => checkpoint !== void 0 && checkpoint.saveOptions === document.$__.saveOptions && checkpoint.isNew === document.isNew && // Restoring a target to its original persisted value can clear its dirty
+  // flag. It was still computed; only newly scheduled fields invalidate reuse.
+  plan.fields.every((field) => checkpoint.targets.includes(field.targetPath)) && isDeepStrictEqual(checkpoint.inputs, snapshotDerivedInputs(document, Object.keys(checkpoint.inputs))) && isDeepStrictEqual(checkpoint.results, snapshotDerivedInputs(document, checkpoint.targets));
+  const compute = async (document) => {
+    const state = stateFor(document);
+    state.checkpoint = void 0;
+    const plan = planFor(document, state);
+    const inputs = snapshotDerivedInputs(document, plan.availablePaths);
+    const staged = [];
+    for (const { targetPath, get } of plan.fields) {
+      const result = await get(copyDerivedSnapshot(inputs));
+      staged.push({ path: targetPath, value: cloneDerivedScalar(result) });
+    }
+    state.applyingResults = true;
+    try {
+      for (const { path, value } of staged) document.set(path, value);
+    } finally {
+      state.applyingResults = false;
+    }
+    const validationError = document.$__.validationError;
+    if (staged.some(({ path }) => validationError?.errors[path]?.name === "CastError")) throw validationError;
+    const targets = plan.fields.map((field) => field.targetPath);
+    state.checkpoint = {
+      saveOptions: document.$__.saveOptions,
+      isNew: document.isNew,
+      targets,
+      inputs: copyDerivedSnapshot(inputs, watchedPaths(plan)),
+      results: snapshotDerivedInputs(document, targets)
+    };
+  };
+  schema.pre("validate", async function derivedFieldsPreValidate() {
+    await compute(this);
+  });
+  schema.pre("save", async function derivedFieldsPreSave() {
+    const state = stateFor(this);
+    const plan = planFor(this, state);
+    if (this.$__.saveOptions && matches(this, plan, state.checkpoint)) return;
+    const options = this.$__.saveOptions;
+    const validate = options && "validateBeforeSave" in options ? !!options.validateBeforeSave : schema.options.validateBeforeSave;
+    if (validate) {
+      await this.validate(
+        void 0,
+        options && "validateModifiedOnly" in options ? { validateModifiedOnly: options.validateModifiedOnly } : void 0
+      );
+    } else {
+      await compute(this);
+    }
+    if (!matches(this, planFor(this, state), state.checkpoint)) {
+      throw new Error(
+        "derivedFieldsPlugin inputs or targets changed after computation; register source-mutating validation hooks before the plugin and keep getters/validators free of document mutations"
+      );
+    }
+  });
+}
+
 // src/plugins/new-document.ts
 var stateKey = "newDocumentPlugin";
 function newDocumentPlugin(schema, options) {
@@ -520,8 +855,8 @@ var uniqueEmptiableString = (field, options) => (
 );
 
 // src/is.ts
-import { Types } from "mongoose";
-var { ObjectId } = Types;
+import { Types as Types2 } from "mongoose";
+var { ObjectId } = Types2;
 var CANONICAL_OBJECT_ID_STRING = /^[0-9a-f]{24}$/;
 function isObjectId(value) {
   try {
@@ -537,7 +872,10 @@ function isObjectId(value) {
   }
 }
 export {
+  DerivedFieldsDependencyError,
   cascadeDeletePlugin,
+  defineDerivedField,
+  derivedFieldsPlugin,
   isObjectId,
   modelFunctionPlugin,
   newDocumentPlugin,

package/llms.txt

@@ -49,6 +49,44 @@ userSchema.plugin(modelFunctionPlugin, {
 // static + instance methods `fullName` and `fullNameById` are now available on the model
 ```
 
+Persisted derived fields (see README "Persisted Derived Fields" for full contract):
+
+```ts
+import { Schema } from 'mongoose';
+import { defineDerivedField, derivedFieldsPlugin } from '@web-ts-toolkit/moo';
+
+type User = { firstName: string; lastName: string; fullName: string };
+const userSchema = new Schema<User>({
+  firstName: String,
+  lastName: String,
+  fullName: {
+    type: String,
+    index: true,
+    derived: defineDerivedField<User, 'fullName'>({
+      dependsOn: ['firstName', 'lastName'],
+      get: (doc) => `${doc.firstName ?? ''} ${doc.lastName ?? ''}`.trim(),
+    }),
+  },
+}, { optimisticConcurrency: true });
+// Register source mutators first, then this plugin, then compile the model.
+userSchema.plugin(derivedFieldsPlugin);
+```
+
+- Stored results are searchable/filterable/sortable/indexable with ordinary MongoDB queries; reads/property access never compute or persist.
+- Existing explicit dependencies: no dependency modification/target assignment/pending default write => skip regardless of selection; work requested + all available => recompute; work requested + missing => reject before any getter. An omitted/missing target alone does not request repair.
+- Actual pending non-null source/target defaults count as writes without modification flags (including '', 0, false); null/undefined defaults alone do not write. Pending target fallback defaults recompute. Applying defaults to excluded dependencies can queue writes and require rejection even on an otherwise unrelated save; defaults never prove an excluded input available.
+- Available = selected (defaults usable, genuine absence without a default is known `undefined`, stored `null` is known) or explicitly fully replaced, including excluded null/undefined/default assignments retained on the same document. Unselected defaults/getters and relative `$inc()`/child modifications are not replacements. No automatic fetch.
+- New documents retain their supplied/defaulted/absent input availability on later saves, including with constructor projection metadata.
+- Bare getter shorthand recomputes each async validation/save and requires every supported non-derived input, including hidden fields and `_id`.
+- Sync/async getters receive isolated readonly partial plain inputs, depopulated ids and copied Date/ObjectId/Decimal128 scalars, no virtuals/derived targets/managed version key/containers. Return `undefined` to clear; staged results use Mongoose setters/casting. Getters/validators must not mutate captured hydrated inputs.
+- Root String/Number/Boolean/Date/ObjectId/Decimal128/BigInt only; reject nested/container/Mixed/Union/Binary/UUID/custom kinds, derived chains, immutable/virtual targets, unknown names, malformed options, and duplicate registration. Other ordinary fields coexist but are not getter inputs.
+- Reject Mongoose-managed versionKey (default __v or custom) as a target/explicit dependency and omit it from every input view: Mongoose initializes/increments it after pre-save middleware. With versionKey:false, explicitly declared version-like scalar fields are ordinary supported targets/inputs.
+- `DerivedFieldsDependencyError`: code `MOO_DERIVED_FIELDS_MISSING_DEPENDENCIES`, frozen path-only `issues: [{ targetPath, missingPaths }]`. Getter failures propagate; casting/validation use Mongoose errors. Rejection preserves application assignments in memory.
+- Register source-mutating validation/save middleware before plugin. Normal validation sees results; earlier pre-save changes recompute/revalidate. Later pre-save mutations are outside guarantee; unstable validation-time mutations reject on save. `validateBeforeSave:false` computes/casts but skips required/custom validators.
+- Guaranteed writes: hydrated save/Model.create; async document validation computes without persisting. Query updates/replacements/raw writes bypass. insertMany/bulk inserts may incidentally validate, not all-writer support; validateSync/middleware bypass/pathsToSave excluded.
+- Backfill old rows/formula changes explicitly (load dependencies, mark target modified, save). Ordinary multi-writer Mongoose concurrency applies; optimisticConcurrency recommended for source/result invariants.
+- All helper/error/types also available from `@web-ts-toolkit/moo/plugins` and `@web-ts-toolkit/moo/plugins/derived-fields`.
+
 New-document plugin:
 
 ```ts
@@ -146,8 +184,9 @@ userSchema.plugin(keycloakUserSyncPlugin, {
 - `@web-ts-toolkit/moo/is` — `isObjectId`
 - `@web-ts-toolkit/moo/schema` — `uniqueNullableString`, `uniqueEmptiableString`
 - `@web-ts-toolkit/moo/utils` — `isSchema`, `isObjectIdType`, `isReference`
-- `@web-ts-toolkit/moo/plugins` — non-Keycloak plugins (`modelFunctionPlugin`, `cascadeDeletePlugin`, `newDocumentPlugin`)
+- `@web-ts-toolkit/moo/plugins` — non-Keycloak plugins (`modelFunctionPlugin`, `cascadeDeletePlugin`, `derivedFieldsPlugin`, `newDocumentPlugin`)
 - `@web-ts-toolkit/moo/plugins/cascade-delete` — `cascadeDeletePlugin`
+- `@web-ts-toolkit/moo/plugins/derived-fields` — `derivedFieldsPlugin`, `defineDerivedField`, `DerivedFieldsDependencyError`, authoring types
 - `@web-ts-toolkit/moo/plugins/model-function` — `modelFunctionPlugin`
 - `@web-ts-toolkit/moo/plugins/new-document` — `newDocumentPlugin`
 - `@web-ts-toolkit/moo/plugins/keycloak-user-sync` — `createManagedKeycloakClient`, `keycloakUserSyncPlugin`

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/moo",
   "description": "Mongoose helpers for schema fields, ObjectId checks, and document plugins",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/moo",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "sideEffects": false,
   "keywords": [
     "mongoose",
@@ -51,6 +51,12 @@
       "require": "./plugins/cascade-delete.js",
       "default": "./plugins/cascade-delete.js"
     },
+    "./plugins/derived-fields": {
+      "types": "./plugins/derived-fields.d.ts",
+      "import": "./plugins/derived-fields.mjs",
+      "require": "./plugins/derived-fields.js",
+      "default": "./plugins/derived-fields.js"
+    },
     "./plugins/model-function": {
       "types": "./plugins/model-function.d.ts",
       "import": "./plugins/model-function.mjs",
@@ -83,7 +89,7 @@
     }
   },
   "dependencies": {
-    "@web-ts-toolkit/utils": "0.55.0"
+    "@web-ts-toolkit/utils": "0.57.0"
   },
   "files": [
     "**/*",

package/plugins/derived-fields.d.mts

@@ -0,0 +1,108 @@
+import { Schema } from 'mongoose';
+
+/**
+ * A partial plain persisted-model view, not a hydrated document. Only available,
+ * supported root scalar inputs are supplied; virtuals, populated documents,
+ * containers, derived targets, and Mongoose's managed version key are not inputs.
+ * Use the raw model type for `TModel`. Selected defaults are available; genuine
+ * selected absence is `undefined` and stored `null` is known. Defaults applied to
+ * unselected fields never prove availability, even when pending a write.
+ * Dates/ObjectIds/Decimal128s are copied per invocation; property getters/
+ * transforms are bypassed.
+ * Never mutate the hydrated document through a captured reference.
+ */
+type DerivedFieldInput<TModel> = Readonly<Partial<TModel>>;
+/** Sync/async computation with no document `this`; `undefined` clears the target. */
+type DerivedFieldGetter<TModel, TValue> = (this: void, doc: DerivedFieldInput<TModel>) => TValue | undefined | Promise<TValue | undefined>;
+/**
+ * Declare every source read by `get`. Existing documents skip when no dependency
+ * modification/default write or target assignment/default write requests work.
+ * Pending non-null defaults count even without Mongoose modification flags;
+ * null/undefined defaults alone do not write. Every requested computation requires
+ * all dependencies selected or fully replaced; excluded defaults are not replacements.
+ * The Mongoose-managed version key is not a supported dependency or target.
+ */
+interface DerivedFieldDescriptor<TModel, TValue> {
+    readonly dependsOn: readonly Extract<keyof TModel, string>[];
+    readonly get: DerivedFieldGetter<TModel, TValue>;
+}
+/**
+ * The `derived` schema-path option. A bare getter recomputes on every operation
+ * and requires every supported non-derived schema input to be available.
+ */
+type DerivedFieldDefinition<TModel, TValue> = DerivedFieldDescriptor<TModel, TValue> | DerivedFieldGetter<TModel, TValue>;
+/**
+ * Contextually types a `derived` option without augmenting Mongoose globally.
+ * The second type argument is the target's key in the raw persisted model, so
+ * dependency names, getter input, and the target's result type are checked.
+ * Schema registration separately checks runtime path eligibility.
+ *
+ * @example
+ * type User = { firstName: string; lastName: string; fullName: string };
+ * const derived = defineDerivedField<User, 'fullName'>({
+ *   dependsOn: ['firstName', 'lastName'],
+ *   get: (doc) => `${doc.firstName ?? ''} ${doc.lastName ?? ''}`.trim(),
+ * });
+ */
+declare function defineDerivedField<TModel, TTargetKey extends Extract<keyof TModel, string>>(definition: DerivedFieldDescriptor<TModel, TModel[TTargetKey]>): DerivedFieldDescriptor<TModel, TModel[TTargetKey]>;
+declare function defineDerivedField<TModel, TTargetKey extends Extract<keyof TModel, string>>(definition: DerivedFieldGetter<TModel, TModel[TTargetKey]>): DerivedFieldGetter<TModel, TModel[TTargetKey]>;
+declare function defineDerivedField<TModel, TTargetKey extends Extract<keyof TModel, string>>(definition: DerivedFieldDefinition<TModel, TModel[TTargetKey]>): DerivedFieldDefinition<TModel, TModel[TTargetKey]>;
+/** One target's unavailable dependency paths; never includes source values. */
+interface DerivedFieldDependencyIssue {
+    readonly targetPath: string;
+    readonly missingPaths: readonly string[];
+}
+/**
+ * Raised by dependency preflight before any getter runs. `issues` lists every
+ * scheduled target with missing inputs. No implicit database fetch is attempted.
+ */
+declare class DerivedFieldsDependencyError extends Error {
+    /** Stable discriminator, including across separately bundled entrypoints. */
+    readonly code: "MOO_DERIVED_FIELDS_MISSING_DEPENDENCIES";
+    /** Frozen path-only issues; no source values or hydrated document are attached. */
+    readonly issues: readonly DerivedFieldDependencyIssue[];
+    constructor(issues: readonly DerivedFieldDependencyIssue[]);
+}
+
+/**
+ * Computes opt-in root scalar `derived` fields before asynchronous document
+ * validation and hydrated `save()` (including `Model.create()`). Results are
+ * staged, then assigned through Mongoose setters/casting; `undefined` clears a
+ * target. Getters receive separate frozen plain views with copied scalar values.
+ * Supported targets/dependencies: root String, Number, Boolean, Date, ObjectId,
+ * Decimal128, BigInt; containers, nested paths, and derived chains are rejected.
+ * Mongoose's managed version key (default `__v` or custom) is rejected as a
+ * target/dependency and omitted from inputs; with versionKey:false it is ordinary.
+ *
+ * Register after defining paths and source-mutating middleware, before compiling
+ * the model. Source-changing pre-validation hooks must precede this plugin for
+ * standalone validation to see their final values. Earlier pre-save changes are
+ * recomputed and, unless validation is disabled, revalidated. Changes made by
+ * later pre-save hooks are outside this guarantee. Validation hooks/validators
+ * must not change inputs after this plugin computes them: a save that still has
+ * such changes after revalidation rejects with an ordering error.
+ *
+ * No inputs are fetched. Explicit descriptors skip unless a dependency modification
+ * or target assignment requests work, including actual pending default writes.
+ * Mongoose writes non-null defaults (including '', 0, false) without modification
+ * flags; null/undefined defaults alone do not write. Pending defaults schedule work
+ * but do not prove excluded inputs available: all dependencies must be selected or
+ * fully replaced. Missing/projected-out targets without a write request still skip.
+ * Bare getters run on every validation/save and require every supported input.
+ * New documents retain their supplied/defaulted/absent input availability on
+ * later saves, including when constructed with projection metadata.
+ * A normal save reuses its own validation computation when inputs/results are
+ * unchanged. Separate validations/saves do not share that computation cache.
+ * Validation-disabled saves still compute and reject getter/casting failures,
+ * but intentionally skip required/custom validation.
+ *
+ * Query writes, replacements, insertMany/bulkWrite fast paths, raw-driver writes,
+ * validateSync(), middleware bypass, and restricted pathsToSave are outside the
+ * document-save contract. Some bulk insert paths invoke async document validation
+ * and therefore compute incidentally; that is not all-writer consistency.
+ * Backfill old rows/formula changes explicitly; ordinary Mongoose concurrent-write
+ * semantics apply (consider optimisticConcurrency for source/result invariants).
+ */
+declare function derivedFieldsPlugin<TRawDocType>(schema: Schema<TRawDocType>): void;
+
+export { type DerivedFieldDefinition, type DerivedFieldDependencyIssue, type DerivedFieldDescriptor, type DerivedFieldGetter, type DerivedFieldInput, DerivedFieldsDependencyError, defineDerivedField, derivedFieldsPlugin };

package/plugins/derived-fields.d.ts

@@ -0,0 +1,108 @@
+import { Schema } from 'mongoose';
+
+/**
+ * A partial plain persisted-model view, not a hydrated document. Only available,
+ * supported root scalar inputs are supplied; virtuals, populated documents,
+ * containers, derived targets, and Mongoose's managed version key are not inputs.
+ * Use the raw model type for `TModel`. Selected defaults are available; genuine
+ * selected absence is `undefined` and stored `null` is known. Defaults applied to
+ * unselected fields never prove availability, even when pending a write.
+ * Dates/ObjectIds/Decimal128s are copied per invocation; property getters/
+ * transforms are bypassed.
+ * Never mutate the hydrated document through a captured reference.
+ */
+type DerivedFieldInput<TModel> = Readonly<Partial<TModel>>;
+/** Sync/async computation with no document `this`; `undefined` clears the target. */
+type DerivedFieldGetter<TModel, TValue> = (this: void, doc: DerivedFieldInput<TModel>) => TValue | undefined | Promise<TValue | undefined>;
+/**
+ * Declare every source read by `get`. Existing documents skip when no dependency
+ * modification/default write or target assignment/default write requests work.
+ * Pending non-null defaults count even without Mongoose modification flags;
+ * null/undefined defaults alone do not write. Every requested computation requires
+ * all dependencies selected or fully replaced; excluded defaults are not replacements.
+ * The Mongoose-managed version key is not a supported dependency or target.
+ */
+interface DerivedFieldDescriptor<TModel, TValue> {
+    readonly dependsOn: readonly Extract<keyof TModel, string>[];
+    readonly get: DerivedFieldGetter<TModel, TValue>;
+}
+/**
+ * The `derived` schema-path option. A bare getter recomputes on every operation
+ * and requires every supported non-derived schema input to be available.
+ */
+type DerivedFieldDefinition<TModel, TValue> = DerivedFieldDescriptor<TModel, TValue> | DerivedFieldGetter<TModel, TValue>;
+/**
+ * Contextually types a `derived` option without augmenting Mongoose globally.
+ * The second type argument is the target's key in the raw persisted model, so
+ * dependency names, getter input, and the target's result type are checked.
+ * Schema registration separately checks runtime path eligibility.
+ *
+ * @example
+ * type User = { firstName: string; lastName: string; fullName: string };
+ * const derived = defineDerivedField<User, 'fullName'>({
+ *   dependsOn: ['firstName', 'lastName'],
+ *   get: (doc) => `${doc.firstName ?? ''} ${doc.lastName ?? ''}`.trim(),
+ * });
+ */
+declare function defineDerivedField<TModel, TTargetKey extends Extract<keyof TModel, string>>(definition: DerivedFieldDescriptor<TModel, TModel[TTargetKey]>): DerivedFieldDescriptor<TModel, TModel[TTargetKey]>;
+declare function defineDerivedField<TModel, TTargetKey extends Extract<keyof TModel, string>>(definition: DerivedFieldGetter<TModel, TModel[TTargetKey]>): DerivedFieldGetter<TModel, TModel[TTargetKey]>;
+declare function defineDerivedField<TModel, TTargetKey extends Extract<keyof TModel, string>>(definition: DerivedFieldDefinition<TModel, TModel[TTargetKey]>): DerivedFieldDefinition<TModel, TModel[TTargetKey]>;
+/** One target's unavailable dependency paths; never includes source values. */
+interface DerivedFieldDependencyIssue {
+    readonly targetPath: string;
+    readonly missingPaths: readonly string[];
+}
+/**
+ * Raised by dependency preflight before any getter runs. `issues` lists every
+ * scheduled target with missing inputs. No implicit database fetch is attempted.
+ */
+declare class DerivedFieldsDependencyError extends Error {
+    /** Stable discriminator, including across separately bundled entrypoints. */
+    readonly code: "MOO_DERIVED_FIELDS_MISSING_DEPENDENCIES";
+    /** Frozen path-only issues; no source values or hydrated document are attached. */
+    readonly issues: readonly DerivedFieldDependencyIssue[];
+    constructor(issues: readonly DerivedFieldDependencyIssue[]);
+}
+
+/**
+ * Computes opt-in root scalar `derived` fields before asynchronous document
+ * validation and hydrated `save()` (including `Model.create()`). Results are
+ * staged, then assigned through Mongoose setters/casting; `undefined` clears a
+ * target. Getters receive separate frozen plain views with copied scalar values.
+ * Supported targets/dependencies: root String, Number, Boolean, Date, ObjectId,
+ * Decimal128, BigInt; containers, nested paths, and derived chains are rejected.
+ * Mongoose's managed version key (default `__v` or custom) is rejected as a
+ * target/dependency and omitted from inputs; with versionKey:false it is ordinary.
+ *
+ * Register after defining paths and source-mutating middleware, before compiling
+ * the model. Source-changing pre-validation hooks must precede this plugin for
+ * standalone validation to see their final values. Earlier pre-save changes are
+ * recomputed and, unless validation is disabled, revalidated. Changes made by
+ * later pre-save hooks are outside this guarantee. Validation hooks/validators
+ * must not change inputs after this plugin computes them: a save that still has
+ * such changes after revalidation rejects with an ordering error.
+ *
+ * No inputs are fetched. Explicit descriptors skip unless a dependency modification
+ * or target assignment requests work, including actual pending default writes.
+ * Mongoose writes non-null defaults (including '', 0, false) without modification
+ * flags; null/undefined defaults alone do not write. Pending defaults schedule work
+ * but do not prove excluded inputs available: all dependencies must be selected or
+ * fully replaced. Missing/projected-out targets without a write request still skip.
+ * Bare getters run on every validation/save and require every supported input.
+ * New documents retain their supplied/defaulted/absent input availability on
+ * later saves, including when constructed with projection metadata.
+ * A normal save reuses its own validation computation when inputs/results are
+ * unchanged. Separate validations/saves do not share that computation cache.
+ * Validation-disabled saves still compute and reject getter/casting failures,
+ * but intentionally skip required/custom validation.
+ *
+ * Query writes, replacements, insertMany/bulkWrite fast paths, raw-driver writes,
+ * validateSync(), middleware bypass, and restricted pathsToSave are outside the
+ * document-save contract. Some bulk insert paths invoke async document validation
+ * and therefore compute incidentally; that is not all-writer consistency.
+ * Backfill old rows/formula changes explicitly; ordinary Mongoose concurrent-write
+ * semantics apply (consider optimisticConcurrency for source/result invariants).
+ */
+declare function derivedFieldsPlugin<TRawDocType>(schema: Schema<TRawDocType>): void;
+
+export { type DerivedFieldDefinition, type DerivedFieldDependencyIssue, type DerivedFieldDescriptor, type DerivedFieldGetter, type DerivedFieldInput, DerivedFieldsDependencyError, defineDerivedField, derivedFieldsPlugin };