liwi-mongo 13.4.0 → 14.0.0

package/src/writes/stampPartialUpdate.test.ts

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { ProtectedFieldUpdateError } from "liwi-store";
+import type { Update } from "liwi-store";
+import type { MongoBaseModel } from "../MongoBaseModel.ts";
+import { stampPartialUpdate } from "./stampPartialUpdate.ts";
+
+interface TestModel extends MongoBaseModel {
+  label: string;
+  count: number;
+}
+
+const now = new Date("2026-10-11T10:00:00Z");
+const callerTime = new Date("2026-01-01");
+
+const stamp = (update: Record<string, unknown>): Update<TestModel> =>
+  stampPartialUpdate(update as Update<TestModel>, now);
+
+describe("stampPartialUpdate", () => {
+  it("adds updated to $set", () => {
+    assert.deepEqual(stamp({ $set: { label: "a" }, $inc: { count: 1 } }), {
+      $set: { label: "a", updated: now },
+      $inc: { count: 1 },
+    });
+  });
+
+  it("adds a $set when the update has none", () => {
+    assert.deepEqual(stamp({ $inc: { count: 1 } }), {
+      $inc: { count: 1 },
+      $set: { updated: now },
+    });
+  });
+
+  it("does not stamp without a write time", () => {
+    const update: Update<TestModel> = { $set: { label: "a" } };
+
+    assert.equal(stampPartialUpdate(update, undefined), update);
+  });
+
+  it("does not mutate the caller's update", () => {
+    const update = { $set: { label: "a" } };
+
+    stamp(update);
+
+    assert.deepEqual(update, { $set: { label: "a" } });
+  });
+
+  for (const update of [
+    { $set: { updated: callerTime } },
+    { $currentDate: { updated: true } },
+    { $max: { updated: callerTime } },
+  ]) {
+    it(`lets the caller set updated with ${Object.keys(update)[0]!}`, () => {
+      assert.equal(stamp(update), update);
+    });
+  }
+
+  for (const update of [
+    { $unset: { updated: true } },
+    { $inc: { updated: 1 } },
+    { $mul: { updated: 2 } },
+    { $min: { updated: callerTime } },
+    { $setOnInsert: { updated: callerTime } },
+    { $rename: { updated: "lastUpdate" } },
+    { $rename: { lastUpdate: "updated" } },
+    { $push: { updated: callerTime } },
+    { $set: { "updated.day": 1 } },
+  ]) {
+    it(`rejects ${JSON.stringify(update)}`, () => {
+      assert.throws(() => stamp(update), ProtectedFieldUpdateError);
+    });
+  }
+
+  for (const update of [
+    { $set: { created: callerTime } },
+    { $currentDate: { created: true } },
+    { $max: { created: callerTime } },
+    { $unset: { created: true } },
+    { $rename: { created: "creation" } },
+    { $rename: { creation: "created" } },
+    { $set: { "created.day": 1 } },
+  ]) {
+    it(`rejects ${JSON.stringify(update)}`, () => {
+      assert.throws(() => stamp(update), ProtectedFieldUpdateError);
+    });
+  }
+
+  it("ignores fields that only start like a protected field", () => {
+    assert.deepEqual(stamp({ $set: { updatedBy: "bot", createdBy: "bot" } }), {
+      $set: { updatedBy: "bot", createdBy: "bot", updated: now },
+    });
+  });
+});

package/src/writes/stampPartialUpdate.ts

@@ -0,0 +1,84 @@
+import { ProtectedFieldUpdateError } from "liwi-store";
+import type { BaseModel, Update } from "liwi-store";
+
+type ProtectedField = "created" | "updated";
+
+const protectedFields: readonly ProtectedField[] = ["created", "updated"];
+
+const updatedOverrideOperators: ReadonlySet<string> = new Set([
+  "$set",
+  "$currentDate",
+  "$max",
+]);
+
+const findProtectedField = (path: string): ProtectedField | undefined =>
+  protectedFields.find(
+    (field) => path === field || path.startsWith(`${field}.`),
+  );
+
+const listTouchedPaths = (
+  operator: string,
+  fields: Record<string, unknown>,
+): string[] => {
+  const keys = Object.keys(fields);
+  if (operator !== "$rename") return keys;
+  const renameTargets = Object.values(fields).filter(
+    (target): target is string => typeof target === "string",
+  );
+  return [...keys, ...renameTargets];
+};
+
+const describeRejection = (
+  field: ProtectedField,
+  operator: string,
+  path: string,
+): string =>
+  field === "created"
+    ? `Cannot use ${operator} on "${path}": created is set on insert and never updated`
+    : `Cannot use ${operator} on "${path}": updated can only be set with $set, $currentDate or $max`;
+
+const validateProtectedFields = <Model extends BaseModel>(
+  update: Update<Model>,
+): { isUpdatedSetByCaller: boolean } => {
+  let isUpdatedSetByCaller = false;
+  const operations = Object.entries(
+    update as Record<string, Record<string, unknown> | undefined>,
+  );
+
+  for (const [operator, fields] of operations) {
+    if (!fields) continue;
+    for (const path of listTouchedPaths(operator, fields)) {
+      const field = findProtectedField(path);
+      if (!field) continue;
+      if (
+        field === "updated" &&
+        path === "updated" &&
+        updatedOverrideOperators.has(operator)
+      ) {
+        isUpdatedSetByCaller = true;
+        continue;
+      }
+      throw new ProtectedFieldUpdateError(
+        describeRejection(field, operator, path),
+      );
+    }
+  }
+
+  return { isUpdatedSetByCaller };
+};
+
+/**
+ * Throws `ProtectedFieldUpdateError` when the update touches `created`, or touches
+ * `updated` with an operator other than `$set`, `$currentDate` or `$max`.
+ * Otherwise returns the update with `updated` set to `now`, unless the caller sets
+ * `updated` itself or `now` is `undefined`. The caller's update is never mutated.
+ */
+export const stampPartialUpdate = <Model extends BaseModel>(
+  update: Update<Model>,
+  now: Date | undefined,
+): Update<Model> => {
+  const { isUpdatedSetByCaller } = validateProtectedFields(update);
+  if (isUpdatedSetByCaller || !now) return update;
+  const $set: Record<string, unknown> = { ...update.$set, updated: now };
+  return { ...update, $set: $set as Update<Model>["$set"] };
+};