@web-ts-toolkit/moo 0.54.0 → 0.56.0

package/README.md

@@ -20,6 +20,7 @@ Peer dependencies:
 - model-function plugin
 - new-document plugin
 - cascade-delete plugin
+- persisted derived fields for ordinary MongoDB queries and indexes
 - optional Keycloak user-sync plugin through a dedicated subpath
 
 ## Quick Start
@@ -49,6 +50,7 @@ Subpath entrypoints:
 - `@web-ts-toolkit/moo/utils` — `isSchema`, `isObjectIdType`, `isReference`, and the `ReferenceShape` type
 - `@web-ts-toolkit/moo/plugins` — plugin entrypoint
 - `@web-ts-toolkit/moo/plugins/cascade-delete` — cascade-delete plugin
+- `@web-ts-toolkit/moo/plugins/derived-fields` — `derivedFieldsPlugin`, `defineDerivedField`, dependency error and authoring types
 - `@web-ts-toolkit/moo/plugins/model-function` — model-function plugin
 - `@web-ts-toolkit/moo/plugins/new-document` — new-document plugin
 - `@web-ts-toolkit/moo/plugins/keycloak-user-sync` — Keycloak user-sync plugin
@@ -73,6 +75,174 @@ userSchema.plugin(cascadeDeletePlugin, {
 });
 ```
 
+## Persisted Derived Fields
+
+Use `derived` on a stored schema path to compute a value during async document
+validation and persist it with hydrated `save()` / `Model.create()`. The stored
+value supports ordinary MongoDB filtering, searching, sorting, and indexes; reads
+and property access do not compute or write anything.
+
+Named root imports are canonical. `defineDerivedField<User, 'fullName'>` checks
+dependency names, a readonly partial raw-model input, and the target's result type
+without globally augmenting Mongoose:
+
+```ts
+import mongoose, { 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: { type: String, required: true },
+    lastName: { type: String, required: true },
+    fullName: {
+      type: String,
+      required: true,
+      index: true,
+      derived: defineDerivedField<User, 'fullName'>({
+        dependsOn: ['firstName', 'lastName'],
+        get: (doc) => `${doc.firstName ?? ''} ${doc.lastName ?? ''}`.trim(),
+      }),
+    },
+  },
+  { optimisticConcurrency: true },
+);
+
+// Define all paths and source-mutating middleware before registering the plugin.
+userSchema.plugin(derivedFieldsPlugin);
+const User = mongoose.model<User>('User', userSchema);
+
+await mongoose.connect('mongodb://127.0.0.1:27017/app');
+await User.create({ firstName: 'Ada', lastName: 'Lovelace' });
+const matches = await User.find({ fullName: /^Ada/ }).sort({ fullName: 1 });
+```
+
+The same API (including types) is available from the grouped plugins entrypoint
+and the direct entrypoint:
+
+```ts
+import {
+  defineDerivedField,
+  derivedFieldsPlugin,
+  DerivedFieldsDependencyError,
+  type DerivedFieldDescriptor,
+  type DerivedFieldGetter,
+  type DerivedFieldInput,
+} from '@web-ts-toolkit/moo/plugins/derived-fields';
+```
+
+### Dependencies and projections
+
+Declare every source read by `get` in `dependsOn`. Existing documents request
+recomputation for a dependency modification or explicit target change, including
+actual pending default writes to either:
+
+| Recompute requested? | All dependencies available? | Result                                                            |
+| -------------------- | --------------------------- | ----------------------------------------------------------------- |
+| No                   | Either                      | Skip and preserve the persisted derived value.                    |
+| Yes                  | Yes                         | Recompute and save with the source changes.                       |
+| Yes                  | No                          | Reject before persistence, without invoking any scheduled getter. |
+
+Mongoose can queue a non-null default for persistence on an existing document
+without marking the path modified. These pending writes count as changes, including
+`''`, `0`, and `false`. Defaults of `null`/`undefined` alone do not queue writes and
+do not request computation. A target's pending fallback default is recomputed rather
+than accepted as an arbitrary override. Mere target absence/projection omission,
+without a pending write, does not request repair.
+
+New documents compute using supplied/defaulted inputs before ordinary validation.
+`dependsOn: []` is valid for creation and target-change/default-write constants.
+
+**Available** means selected by the query or fully replaced on the hydrated
+document. Selected defaults are available; selected genuine absence without a
+default is `undefined`, and stored `null` is also a known value. An unselected field
+is unavailable even if a default or property getter could manufacture a value. Assigning an
+excluded dependency explicitly (including `null`, `undefined`, or its default
+value) supplies a replacement; that availability is retained on the same document
+across saves. Child-only modifications and relative `$inc()` operations do not
+prove an excluded input fully available. Fetch the needed fields yourself or
+explicitly replace them; the plugin never fetches omitted inputs. Applying defaults
+to excluded dependencies may queue writes, but does not supply replacements: an
+otherwise unrelated save then rejects before getters or persistence rather than
+writing manufactured sources with stale results.
+
+A newly inserted document retains availability of its supplied, defaulted, and
+absent inputs across later saves, including when constructed with projection
+metadata.
+
+A bare function (`derived: defineDerivedField<User, 'fullName'>(get)`) is supported
+as conservative shorthand. It recomputes on every async validation/save operation
+and requires **every supported non-derived input** to be available, including
+hidden paths and `_id`, even if the function only reads one field. Prefer explicit
+descriptors for projection-friendly updates.
+
+### Getter inputs, results, and errors
+
+Getters may be sync or async; return `undefined` to clear a stored target. Each
+receives an isolated frozen plain input view with available supported scalars
+only, no document methods/`this`, virtuals, derived targets, managed version key, or
+containers. References are persisted ids rather than populated documents;
+Date/ObjectId/Decimal128 values
+are copied per invocation. Property getters, transforms, and automatic database
+fetches are bypassed. Results are staged before assignment through normal Mongoose
+setters/casting. Getters and validators must not mutate the hydrated document via
+captured references; keep computations deterministic and declare their real inputs.
+
+Missing-input preflight aggregates every affected target before any getter runs.
+`DerivedFieldsDependencyError.code` is
+`MOO_DERIVED_FIELDS_MISSING_DEPENDENCIES`, with frozen path-only
+`issues: [{ targetPath, missingPaths }]` (no source values). The code is a stable
+discriminator across separately bundled entrypoints. Getter failures propagate;
+target casting and ordinary validation failures use Mongoose errors. Rejected saves
+do not persist that save, but retain application assignments in memory; no
+in-memory rollback is promised.
+
+### Lifecycle and write boundaries
+
+- Register source-mutating pre-validation and pre-save hooks **before** this
+  plugin, then compile the model. Normal async validation sees the computed/cast
+  derived results. Earlier pre-save source/target changes after initial validation
+  trigger recomputation and revalidation (preserving `validateModifiedOnly`). A
+  normal save reuses its validation computation when inputs/results are unchanged;
+  separate `validate()` calls/saves are separate operations.
+- Later pre-save mutations are outside the guarantee. Later validation-hook or
+  validator mutations are not a standalone-validation guarantee; save attempts one
+  revalidation and rejects an ordering error if inputs/results remain unstable.
+  Timestamp sources assigned in earlier pre-save hooks are covered, but a new
+  document's first validation can see an unset timestamp. Ordinary Mongoose change
+  tracking still applies (for example, mark in-place Date mutations modified).
+- With schema-level or per-save `validateBeforeSave: false`, the plugin still
+  preflights, computes, and casts, but skips ordinary required/custom validators.
+  Dependency, getter, and target casting errors still reject before writing.
+- Query updates/replacements and raw-driver writes bypass computation.
+  `insertMany()` and bulk insert paths may incidentally invoke async document
+  validation, but are not guaranteed all-writer support; lean/skip-validation paths
+  and bulk updates can bypass it. `validateSync()`, middleware bypass, and restricted
+  `pathsToSave` are outside this contract.
+- Changing a formula or adopting the plugin for old rows requires an explicit
+  backfill/repair. Load all dependencies, `doc.markModified('fullName')`, then
+  `await doc.save()` to request recomputation even if sources are unchanged. This
+  is not an automatic read-time repair. Multiple writers retain ordinary Mongoose
+  concurrency semantics: use `optimisticConcurrency` where the source/result
+  invariant matters and retry version conflicts by reloading complete inputs.
+
+### Initial scope
+
+Targets and dependencies must be root persisted **String, Number, Boolean, Date,
+ObjectId, Decimal128, or BigInt** paths. Nested paths, subdocuments, arrays, maps,
+Mixed, Union, Buffer/Binary/UUID, BSON Double/Int32, and unknown custom scalar kinds
+are unsupported as targets/dependencies. Unsupported ordinary fields may coexist
+but are absent from getter views. Self/derived-to-derived dependencies, unknown or
+duplicate dependency names, malformed options, virtual/immutable targets, and
+duplicate plugin registration throw at `schema.plugin(...)` time. Paths and
+definitions are snapshotted at registration; later schema/option edits are not
+discovered. Mongoose's managed `versionKey` (default `__v` or a custom name) is
+rejected as a target or explicit dependency and excluded from all getter views,
+including shorthand: Mongoose initializes/increments it after pre-save middleware.
+With `versionKey: false`, explicitly declared version-like fields are ordinary
+supported scalar targets/inputs.
+
 ## Model Function Plugin
 
 ```ts

package/index.d.mts

@@ -1,5 +1,6 @@
 export { ModelDocument, ModelFunctionInstanceMethods, ModelFunctionPluginOptions, ModelFunctionStaticMethods, modelFunctionPlugin } from './plugins/model-function.mjs';
 export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, QueryOperators, cascadeDeletePlugin } from './plugins/cascade-delete.mjs';
+export { DerivedFieldDefinition, DerivedFieldDependencyIssue, DerivedFieldDescriptor, DerivedFieldGetter, DerivedFieldInput, DerivedFieldsDependencyError, defineDerivedField, derivedFieldsPlugin } from './plugins/derived-fields.mjs';
 export { NewDocumentPluginOptions, newDocumentPlugin } from './plugins/new-document.mjs';
 export { SchemaOptionOverrides, uniqueEmptiableString, uniqueNullableString } from './schema.mjs';
 export { isObjectId } from './is.mjs';

package/index.d.ts

@@ -1,5 +1,6 @@
 export { ModelDocument, ModelFunctionInstanceMethods, ModelFunctionPluginOptions, ModelFunctionStaticMethods, modelFunctionPlugin } from './plugins/model-function.js';
 export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, QueryOperators, cascadeDeletePlugin } from './plugins/cascade-delete.js';
+export { DerivedFieldDefinition, DerivedFieldDependencyIssue, DerivedFieldDescriptor, DerivedFieldGetter, DerivedFieldInput, DerivedFieldsDependencyError, defineDerivedField, derivedFieldsPlugin } from './plugins/derived-fields.js';
 export { NewDocumentPluginOptions, newDocumentPlugin } from './plugins/new-document.js';
 export { SchemaOptionOverrides, uniqueEmptiableString, uniqueNullableString } from './schema.js';
 export { isObjectId } from './is.js';

package/index.js

@@ -30,7 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DerivedFieldsDependencyError: () => DerivedFieldsDependencyError,
   cascadeDeletePlugin: () => cascadeDeletePlugin,
+  defineDerivedField: () => defineDerivedField,
+  derivedFieldsPlugin: () => derivedFieldsPlugin,
   isObjectId: () => isObjectId,
   modelFunctionPlugin: () => modelFunctionPlugin,
   newDocumentPlugin: () => newDocumentPlugin,
@@ -521,6 +524,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
+var import_node_util = require("util");
+var import_mongoose5 = require("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
+var import_mongoose4 = require("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 import_mongoose4.Types.ObjectId(Buffer.from(bson.id));
+    if (bson._bsontype === "Decimal128") return new import_mongoose4.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 import_mongoose5.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)) && (0, import_node_util.isDeepStrictEqual)(checkpoint.inputs, snapshotDerivedInputs(document, Object.keys(checkpoint.inputs))) && (0, import_node_util.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) {
@@ -561,8 +899,8 @@ var uniqueEmptiableString = (field, options) => (
 );
 
 // src/is.ts
-var import_mongoose4 = require("mongoose");
-var { ObjectId } = import_mongoose4.Types;
+var import_mongoose6 = require("mongoose");
+var { ObjectId } = import_mongoose6.Types;
 var CANONICAL_OBJECT_ID_STRING = /^[0-9a-f]{24}$/;
 function isObjectId(value) {
   try {
@@ -579,7 +917,10 @@ function isObjectId(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DerivedFieldsDependencyError,
   cascadeDeletePlugin,
+  defineDerivedField,
+  derivedFieldsPlugin,
   isObjectId,
   modelFunctionPlugin,
   newDocumentPlugin,