liwi-mongo 13.3.3 → 14.0.0

package/src/MongoStore.test.ts

@@ -1,6 +1,11 @@
 import assert from "node:assert/strict";
 import { beforeEach, describe, it, mock } from "node:test";
+import { NotFoundError, ProtectedFieldUpdateError } from "liwi-store";
+import mongodb from "mongodb";
 import type { MongoBaseModel } from "./MongoBaseModel.ts";
+import MongoConnection from "./MongoConnection.ts";
+import MongoStore from "./MongoStore.ts";
+import { createReplacePipeline } from "./writes/createReplacePipeline.ts";
 
 interface TestModel extends MongoBaseModel {
   label: string;
@@ -8,33 +13,34 @@ interface TestModel extends MongoBaseModel {
 }
 
 let findOneAndUpdateCalls: unknown[][];
+let findOneAndDeleteCalls: unknown[][];
+let updateManyCalls: unknown[][];
 let existingDocument: TestModel | null;
+let documentAfterWrite: TestModel | null;
 
 const collection = {
   findOneAndUpdate: (...args: unknown[]) => {
     findOneAndUpdateCalls.push(args);
     return Promise.resolve(existingDocument);
   },
-};
-
-// eslint-disable-next-line n/no-unsupported-features/node-builtins
-mock.module("mongodb", {
-  // @ts-expect-error: not yet typed
-  exports: {
-    default: {
-      MongoClient: {
-        connect: () =>
-          Promise.resolve({
-            on: () => undefined,
-            db: () => ({ collection: () => collection }),
-          }),
-      },
-    },
+  findOneAndDelete: (...args: unknown[]) => {
+    findOneAndDeleteCalls.push(args);
+    return Promise.resolve(existingDocument);
   },
-});
+  findOne: () => Promise.resolve(documentAfterWrite),
+  updateMany: (...args: unknown[]) => {
+    updateManyCalls.push(args);
+    return Promise.resolve({ matchedCount: 1 });
+  },
+  deleteOne: () => Promise.resolve({ deletedCount: existingDocument ? 1 : 0 }),
+};
 
-const { default: MongoConnection } = await import("./MongoConnection.ts");
-const { default: MongoStore } = await import("./MongoStore.ts");
+mock.method(mongodb.MongoClient, "connect", () =>
+  Promise.resolve({
+    on: () => undefined,
+    db: () => ({ collection: () => collection }),
+  } as unknown as mongodb.MongoClient),
+);
 
 const createStore = (): InstanceType<typeof MongoStore<TestModel>> =>
   new MongoStore<TestModel>(new MongoConnection({ database: "test" }), "tasks");
@@ -106,4 +112,239 @@ describe("MongoStore upsertOneWithInfo", () => {
       prev: existingDocument,
     });
   });
+
+  it("computes next with undefined values as the driver stores them", async () => {
+    existingDocument = {
+      _id: "1",
+      label: "old",
+      status: "x",
+      created,
+      updated,
+    };
+
+    const result = await createStore().upsertOneWithInfo({
+      _id: "1",
+      label: "a",
+      status: undefined,
+      updated,
+    });
+
+    assert.equal(result.object.status, null);
+  });
+
+  it("rejects updated in setOnInsert, which would conflict with $set", async () => {
+    await assert.rejects(
+      createStore().upsertOneWithInfo(
+        { _id: "1", label: "a" },
+        { updated: new Date() },
+      ),
+      ProtectedFieldUpdateError,
+    );
+    assert.deepEqual(findOneAndUpdateCalls, []);
+  });
+});
+
+describe("MongoStore writes with info", () => {
+  const stored: TestModel = { _id: "1", label: "stored", created, updated };
+  const next: TestModel = { _id: "1", label: "next", created, updated };
+  let writeStart: number;
+
+  const assertWriteTime = (value: unknown): Date => {
+    assert.ok(value instanceof Date);
+    assert.ok(value.getTime() >= writeStart && value.getTime() <= Date.now());
+    return value;
+  };
+
+  const stampOf = (update: unknown): unknown =>
+    (update as { $set: { updated: unknown } }).$set.updated;
+
+  const replacementStampOf = (pipeline: unknown): unknown =>
+    (
+      pipeline as [
+        {
+          $replaceWith: {
+            $mergeObjects: [{ $literal: { updated: unknown } }];
+          };
+        },
+      ]
+    )[0].$replaceWith.$mergeObjects[0].$literal.updated;
+
+  beforeEach(() => {
+    writeStart = Date.now();
+    findOneAndUpdateCalls = [];
+    findOneAndDeleteCalls = [];
+    updateManyCalls = [];
+    existingDocument = stored;
+    documentAfterWrite = next;
+  });
+
+  it("partially updates atomically with the criteria and the write time, then reads next", async () => {
+    const result = await createStore().partialUpdateByKeyWithInfo(
+      "1",
+      { $set: { label: "next" } },
+      { status: "open" },
+    );
+
+    const writeTime = assertWriteTime(stampOf(findOneAndUpdateCalls[0]?.[1]));
+    assert.deepEqual(findOneAndUpdateCalls, [
+      [
+        { _id: "1", status: "open" },
+        { $set: { label: "next", updated: writeTime } },
+        { returnDocument: "before" },
+      ],
+    ]);
+    assert.deepEqual(result, { prev: stored, next });
+  });
+
+  it("does not stamp updated with touchUpdated: false", async () => {
+    await createStore().partialUpdateByKey(
+      "1",
+      { $set: { label: "next" } },
+      undefined,
+      { touchUpdated: false },
+    );
+
+    assert.deepEqual(findOneAndUpdateCalls, [
+      [{ _id: "1" }, { $set: { label: "next" } }, { returnDocument: "after" }],
+    ]);
+  });
+
+  it("rejects a protected field update before writing", async () => {
+    await assert.rejects(
+      createStore().partialUpdateByKey("1", { $set: { created: new Date() } }),
+      ProtectedFieldUpdateError,
+    );
+    assert.deepEqual(findOneAndUpdateCalls, []);
+  });
+
+  it("partially updates many documents in one command with one write time", async () => {
+    await createStore().partialUpdateMany(
+      { status: "open" },
+      { $set: { label: "next" } },
+    );
+
+    const writeTime = assertWriteTime(stampOf(updateManyCalls[0]?.[1]));
+    assert.deepEqual(updateManyCalls, [
+      [{ status: "open" }, { $set: { label: "next", updated: writeTime } }],
+    ]);
+  });
+
+  it("resolves next undefined when the document is deleted before the read-back", async () => {
+    documentAfterWrite = null;
+
+    const result = await createStore().partialUpdateByKeyWithInfo("1", {
+      $set: { label: "next" },
+    });
+
+    assert.deepEqual(result, { prev: stored, next: undefined });
+  });
+
+  it("resolves undefined when the partial update matches nothing", async () => {
+    existingDocument = null;
+
+    const store = createStore();
+
+    assert.equal(
+      await store.partialUpdateByKeyWithInfo("1", { $set: { label: "x" } }),
+      undefined,
+    );
+    await assert.rejects(
+      store.partialUpdateByKey("1", { $set: { label: "x" } }),
+      NotFoundError,
+    );
+  });
+
+  it("replaces atomically, keeping the stored created and stamping updated", async () => {
+    const callerCreated = new Date("2025-01-01");
+    const object: TestModel = {
+      _id: "1",
+      label: "next",
+      created: callerCreated,
+      updated,
+    };
+
+    const result = await createStore().replaceOneWithInfo(object);
+
+    const writeTime = assertWriteTime(
+      replacementStampOf(findOneAndUpdateCalls[0]?.[1]),
+    );
+    const replacement = { ...object, updated: writeTime };
+    assert.deepEqual(findOneAndUpdateCalls, [
+      [
+        { _id: "1" },
+        createReplacePipeline(replacement),
+        { returnDocument: "before" },
+      ],
+    ]);
+    assert.deepEqual(result, {
+      prev: stored,
+      next: { ...replacement, created },
+    });
+    assert.equal(object.updated, updated);
+  });
+
+  it("partially updates in one call returning the document after the write", async () => {
+    existingDocument = next;
+
+    const result = await createStore().partialUpdateByKey("1", {
+      $set: { label: "next" },
+    });
+
+    const writeTime = assertWriteTime(stampOf(findOneAndUpdateCalls[0]?.[1]));
+    assert.deepEqual(findOneAndUpdateCalls, [
+      [
+        { _id: "1" },
+        { $set: { label: "next", updated: writeTime } },
+        { returnDocument: "after" },
+      ],
+    ]);
+    assert.deepEqual(result, next);
+  });
+
+  it("replaceOne returns the stored document and leaves the caller's object untouched", async () => {
+    existingDocument = next;
+    const object: TestModel = { _id: "1", label: "next", created, updated };
+
+    const result = await createStore().replaceOne(object);
+
+    const writeTime = assertWriteTime(
+      replacementStampOf(findOneAndUpdateCalls[0]?.[1]),
+    );
+    assert.deepEqual(findOneAndUpdateCalls, [
+      [
+        { _id: "1" },
+        createReplacePipeline({ ...object, updated: writeTime }),
+        { returnDocument: "after" },
+      ],
+    ]);
+    assert.equal(result, next);
+    assert.equal(object.updated, updated);
+  });
+
+  it("throws NotFoundError when replacing a missing document", async () => {
+    existingDocument = null;
+
+    await assert.rejects(
+      createStore().replaceOne({ _id: "1", label: "x", created, updated }),
+      NotFoundError,
+    );
+  });
+
+  it("deletes atomically with the criteria and returns prev", async () => {
+    const result = await createStore().deleteByKeyWithInfo("1", {
+      status: "open",
+    });
+
+    assert.deepEqual(findOneAndDeleteCalls, [[{ _id: "1", status: "open" }]]);
+    assert.deepEqual(result, { prev: stored });
+  });
+
+  it("resolves when deleting a missing document", async () => {
+    existingDocument = null;
+
+    const store = createStore();
+
+    assert.equal(await store.deleteByKeyWithInfo("1"), undefined);
+    await store.deleteByKey("1");
+  });
 });

package/src/MongoStore.ts

@@ -1,15 +1,20 @@
+import { NotFoundError, ProtectedFieldUpdateError } from "liwi-store";
 import type {
   AllowedKeyValue,
   CreateQueryOptions,
   Criteria,
+  DeleteResult,
   Fields,
   OptionalBaseModelKeysForInsert,
+  PartialUpdateOptions,
+  PartialUpdateResult,
   QueryParams,
   Sort,
   SubscribableStore,
   Update,
   UpsertPartialObject,
   UpsertResult,
+  WriteResult,
 } from "liwi-store";
 import type {
   Collection,
@@ -38,6 +43,20 @@ import type {
   MongoIndexSyncResult,
   SyncIndexesOptions,
 } from "./indexes/types.ts";
+import { createReplacePipeline } from "./writes/createReplacePipeline.ts";
+import { stampPartialUpdate } from "./writes/stampPartialUpdate.ts";
+
+const resolveWriteTime = (options?: PartialUpdateOptions): Date | undefined =>
+  options?.touchUpdated === false ? undefined : new Date();
+
+// the driver stores `undefined` as `null` (`ignoreUndefined` is off)
+const toStoredValues = <T extends object>(values: T): T =>
+  Object.fromEntries(
+    Object.entries(values).map(([field, value]: [string, unknown]) => [
+      field,
+      value === undefined ? null : value,
+    ]),
+  ) as T;
 
 export type MongoUpsertResult<
   KeyValue extends AllowedKeyValue,
@@ -197,12 +216,42 @@ export default class MongoStore<
     return object as Model;
   }
 
+  /**
+   * Always sets `updated` to the write time and keeps the stored `created`: the
+   * object's own `created` and `updated` are ignored. The object is not mutated.
+   */
   async replaceOne(object: Model): Promise<Model> {
-    if (!object.updated) object.updated = new Date();
+    const collection = await this.collection;
+    const next = await collection.findOneAndUpdate(
+      { _id: object._id } as Filter<Model>,
+      createReplacePipeline({ ...object, updated: new Date() }),
+      { returnDocument: "after" },
+    );
+    if (!next) {
+      throw new NotFoundError(`Document not found: ${String(object._id)}`);
+    }
+    return next as Model;
+  }
+
+  /** Same rules as `replaceOne`; `next` is derived from the atomic `prev`, no read back. */
+  async replaceOneWithInfo(
+    object: Model,
+  ): Promise<WriteResult<Model> | undefined> {
+    const replacement: Model = { ...object, updated: new Date() };
 
     const collection = await this.collection;
-    await collection.replaceOne({ _id: object._id } as Filter<Model>, object);
-    return object;
+    const prev = await collection.findOneAndUpdate(
+      { _id: object._id } as Filter<Model>,
+      createReplacePipeline(replacement),
+      { returnDocument: "before" },
+    );
+    if (!prev) return undefined;
+
+    const storedCreated = prev.created as Date | null | undefined;
+    return {
+      prev: prev as Model,
+      next: { ...replacement, created: storedCreated ?? replacement.created },
+    };
   }
 
   async upsertOne<
@@ -230,6 +279,12 @@ export default class MongoStore<
     object: UpsertPartialObject<MongoKeyPath, KeyValue, Model, K>,
     setOnInsertPartialObject?: Update<Model>["$setOnInsert"],
   ): Promise<MongoUpsertResult<KeyValue, Model>> {
+    if (setOnInsertPartialObject && "updated" in setOnInsertPartialObject) {
+      throw new ProtectedFieldUpdateError(
+        'Cannot use $setOnInsert on "updated": upsert always sets it with $set, pass it in the object instead',
+      );
+    }
+
     const $setOnInsert: Update<Model>["$setOnInsert"] = {
       // @ts-expect-error -- created is Date as set in BaseModel
       created: object.created || new Date(),
@@ -260,7 +315,7 @@ export default class MongoStore<
       };
     }
 
-    const next = { ...prev, ...$set };
+    const next = { ...prev, ...toStoredValues($set) };
 
     return {
       resolvedAs: "updated",
@@ -278,45 +333,86 @@ export default class MongoStore<
     key: KeyValue,
     partialUpdate: Update<Model>,
     criteria?: Criteria<Model>,
+    options?: PartialUpdateOptions,
   ): Promise<Model> {
+    const update = stampPartialUpdate(partialUpdate, resolveWriteTime(options));
     const collection = await this.collection;
-    const commandResult = await collection.updateOne(
+    const next = await collection.findOneAndUpdate(
       { _id: key, ...criteria } as Filter<Model>,
-      partialUpdate as UpdateFilter<Model>,
+      update as UpdateFilter<Model>,
+      { returnDocument: "after" },
     );
-    if (!commandResult.acknowledged) {
-      console.error(commandResult);
-      throw new Error("Update failed");
-    }
-    const object = await this.findByKey(key);
-    return object!;
+    if (!next) throw new NotFoundError(`Document not found: ${String(key)}`);
+    return next as Model;
+  }
+
+  /**
+   * `prev` is read atomically with the write. `next` is read right after it,
+   * so it may already include a later concurrent write, which emits its own change.
+   * Resolves `undefined` when no document matches.
+   */
+  async partialUpdateByKeyWithInfo(
+    key: KeyValue,
+    partialUpdate: Update<Model>,
+    criteria?: Criteria<Model>,
+    options?: PartialUpdateOptions,
+  ): Promise<PartialUpdateResult<Model> | undefined> {
+    const update = stampPartialUpdate(partialUpdate, resolveWriteTime(options));
+    const collection = await this.collection;
+    const prev = await collection.findOneAndUpdate(
+      { _id: key, ...criteria } as Filter<Model>,
+      update as UpdateFilter<Model>,
+      { returnDocument: "before" },
+    );
+    if (!prev) return undefined;
+
+    return { prev: prev as Model, next: await this.findByKey(key) };
   }
 
   partialUpdateOne(
     object: Model,
     partialUpdate: Update<Model>,
+    options?: PartialUpdateOptions,
   ): Promise<Model> {
-    return this.partialUpdateByKey(object._id, partialUpdate);
+    return this.partialUpdateByKey(
+      object._id,
+      partialUpdate,
+      undefined,
+      options,
+    );
   }
 
-  partialUpdateMany(
+  /** One `updateMany` command; every document gets the same `updated`. */
+  async partialUpdateMany(
     criteria: Criteria<Model>,
     partialUpdate: Update<Model>,
+    options?: PartialUpdateOptions,
   ): Promise<void> {
-    return this.collection
-      .then((collection) =>
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-        collection.updateMany(criteria as Filter<Model>, partialUpdate as any),
-      )
-      .then((res) => undefined); // TODO return updated object
+    const update = stampPartialUpdate(partialUpdate, resolveWriteTime(options));
+    const collection = await this.collection;
+    await collection.updateMany(
+      criteria as Filter<Model>,
+      update as UpdateFilter<Model>,
+    );
   }
 
-  deleteByKey(key: KeyValue, criteria?: Criteria<Model>): Promise<void> {
-    return this.collection
-      .then((collection) =>
-        collection.deleteOne({ _id: key, ...criteria } as Filter<Model>),
-      )
-      .then(() => undefined);
+  async deleteByKey(key: KeyValue, criteria?: Criteria<Model>): Promise<void> {
+    const collection = await this.collection;
+    await collection.deleteOne({ _id: key, ...criteria } as Filter<Model>);
+  }
+
+  async deleteByKeyWithInfo(
+    key: KeyValue,
+    criteria?: Criteria<Model>,
+  ): Promise<DeleteResult<Model> | undefined> {
+    const collection = await this.collection;
+    const prev = await collection.findOneAndDelete({
+      _id: key,
+      ...criteria,
+    } as Filter<Model>);
+    if (!prev) return undefined;
+
+    return { prev: prev as Model };
   }
 
   deleteOne(object: Model): Promise<void> {

package/src/MongoStoreIndexes.test.ts

@@ -1,8 +1,12 @@
 import assert from "node:assert/strict";
 import { beforeEach, describe, it, mock } from "node:test";
+import mongodb from "mongodb";
 import type { IndexDescription, IndexDescriptionInfo } from "mongodb";
 import type { MongoBaseModel } from "./MongoBaseModel.ts";
+import MongoConnection from "./MongoConnection.ts";
+import MongoRegistry from "./MongoRegistry.ts";
 import type { MongoStoreOptions } from "./MongoStore.ts";
+import MongoStore from "./MongoStore.ts";
 
 interface TestModel extends MongoBaseModel {
   completed: boolean;
@@ -47,30 +51,12 @@ const db = {
   },
 };
 
-// eslint-disable-next-line n/no-unsupported-features/node-builtins
-mock.module("mongodb", {
-  // @ts-expect-error: not yet typed
-  exports: {
-    default: {
-      MongoClient: {
-        connect: () =>
-          Promise.resolve({
-            on: () => undefined,
-            db: () => db,
-          }),
-      },
-      ObjectId: class {
-        toString(): string {
-          return "generated-id";
-        }
-      },
-    },
-  },
-});
-
-const { default: MongoConnection } = await import("./MongoConnection.ts");
-const { default: MongoStore } = await import("./MongoStore.ts");
-const { default: MongoRegistry } = await import("./MongoRegistry.ts");
+mock.method(mongodb.MongoClient, "connect", () =>
+  Promise.resolve({
+    on: () => undefined,
+    db: () => db,
+  } as unknown as mongodb.MongoClient),
+);
 
 const createStore = (
   options?: MongoStoreOptions<TestModel>,