@web-ts-toolkit/moo 0.55.0 → 0.57.0

package/plugins/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) {
@@ -493,7 +828,10 @@ function newDocumentPlugin(schema, options) {
   });
 }
 export {
+  DerivedFieldsDependencyError,
   cascadeDeletePlugin,
+  defineDerivedField,
+  derivedFieldsPlugin,
   modelFunctionPlugin,
   newDocumentPlugin
 };