@reventlessdev/reventless-core 3.0.0-alpha.134

package/tests/commandtopic/CommandTopicCallbackFixtures.res

@@ -0,0 +1,87 @@
+S.enableJson()
+
+// ─────────────────────────────────────────────────────────────
+// Command spec for CommandTopic_Callback tests
+// ─────────────────────────────────────────────────────────────
+
+// Not annotated with `: ReventlessInfra.CommandTopic.T` — keeps Id.t transparent (= string)
+// so string literals can be used as IDs and as `reference` field without coercion.
+module TestSpec = {
+  module Id = Reventless.Id.StringPure
+  let name = "TestCommandTopic"
+
+  @schema
+  type command =
+    | CreateItem({itemId: string})
+    | DeleteItem({itemId: string})
+}
+
+// ─────────────────────────────────────────────────────────────
+// Captures
+// ─────────────────────────────────────────────────────────────
+
+type capturedItem = {
+  reference: string,
+  command: TestSpec.command,
+}
+
+let capturedItems: ref<array<capturedItem>> = ref([])
+let commandHandlerResults: ref<array<result<string, string>>> = ref([Ok("ref-1")])
+let commandHandlerShouldThrow: ref<bool> = ref(false)
+
+// ─────────────────────────────────────────────────────────────
+// Ops module
+// ─────────────────────────────────────────────────────────────
+
+module TestOps: CommandTopic_Callback.Ops with module Spec = TestSpec = {
+  module Spec = TestSpec
+  let commandsHandler = stream =>
+    stream
+    ->Stream.runCollect
+    ->Effect.map(items => {
+      if commandHandlerShouldThrow.contents {
+        JsError.throwWithMessage("commandsHandler failed")
+      }
+      capturedItems :=
+        capturedItems.contents->Array.concat(
+          items->Array.map((item: ReventlessInfra.CommandTopic.topicItem<
+            Message.command'<TestSpec.Id.t, TestSpec.command>,
+          >) => {
+            reference: item.reference,
+            command: item.command.command,
+          }),
+        )
+      commandHandlerResults.contents
+    })
+}
+
+module TestHandler = CommandTopic_Callback.Make(TestSpec, TestOps)
+
+// ─────────────────────────────────────────────────────────────
+// Test helpers
+// ─────────────────────────────────────────────────────────────
+
+let testMeta: Message.meta = {
+  service: "TestService",
+  time: "2024-01-01T00:00:00Z",
+  ip: "127.0.0.1",
+  user: "test-user",
+  msgId: "cmd-msg-1",
+  correlationId: "cmd-corr-1",
+}
+
+let makeCommandJson = (id, command): JSON.t => {
+  let cmd': Message.command'<TestSpec.Id.t, TestSpec.command> = {id, meta: testMeta, command}
+  cmd'->Message.encodeCommand'(TestSpec.Id.schema, TestSpec.commandSchema)
+}
+
+let makeTopicItem = (id, command): CommandTopic.topicItem<JSON.t> => {
+  reference: id,
+  command: makeCommandJson(id, command),
+}
+
+let reset = () => {
+  capturedItems := []
+  commandHandlerResults := [Ok("ref-1")]
+  commandHandlerShouldThrow := false
+}

package/tests/commandtopic/CommandTopicCallbackFixtures.res.mjs

@@ -0,0 +1,152 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Stream from "@reventlessdev/rescript-effect/src/Stream.res.mjs";
+import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
+import * as Effect from "effect/Effect";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Message$ReventlessCore from "../../src/Message.res.mjs";
+import * as CommandTopic_Callback$ReventlessCore from "../../src/components/CommandTopic/CommandTopic_Callback.res.mjs";
+
+S.enableJson();
+
+let name = "TestCommandTopic";
+
+let commandSchema = S.union([
+  S.schema(s => ({
+    TAG: "CreateItem",
+    itemId: s.m(S.string)
+  })),
+  S.schema(s => ({
+    TAG: "DeleteItem",
+    itemId: s.m(S.string)
+  }))
+]);
+
+function commandAuthorization(param) {
+  return "AllowAuthenticated";
+}
+
+let TestSpec = {
+  Id: undefined,
+  name: name,
+  commandSchema: commandSchema,
+  commandAuthorization: commandAuthorization
+};
+
+let capturedItems = {
+  contents: []
+};
+
+let commandHandlerResults = {
+  contents: [{
+      TAG: "Ok",
+      _0: "ref-1"
+    }]
+};
+
+let commandHandlerShouldThrow = {
+  contents: false
+};
+
+function commandsHandler(stream) {
+  return Effect.map(Stream.runCollect(stream), items => {
+    if (commandHandlerShouldThrow.contents) {
+      Stdlib_JsError.throwWithMessage("commandsHandler failed");
+    }
+    capturedItems.contents = capturedItems.contents.concat(items.map(item => ({
+      reference: item.reference,
+      command: item.command.command
+    })));
+    return commandHandlerResults.contents;
+  });
+}
+
+let TestOps_Spec = {
+  Id: Id$Reventless.StringPure,
+  name: name,
+  commandSchema: commandSchema,
+  commandAuthorization: commandAuthorization
+};
+
+let TestOps = {
+  Spec: TestOps_Spec,
+  commandsHandler: commandsHandler
+};
+
+let $$let = TestOps_Spec;
+
+let $$let$1 = $$let.Id;
+
+let TestHandler = CommandTopic_Callback$ReventlessCore.Make({
+  Id: {
+    schema: Id$Reventless.StringPure.schema,
+    make: prim => prim,
+    makeFromString: prim => prim,
+    toString: prim => prim,
+    cmp: Id$Reventless.StringPure.cmp
+  },
+  name: name,
+  commandSchema: commandSchema
+})({
+  Spec: {
+    Id: {
+      schema: $$let$1.schema,
+      make: prim => prim,
+      makeFromString: prim => prim,
+      toString: prim => prim,
+      cmp: $$let$1.cmp
+    },
+    name: $$let.name,
+    commandSchema: $$let.commandSchema
+  },
+  commandsHandler: commandsHandler
+});
+
+let testMeta = {
+  service: "TestService",
+  time: "2024-01-01T00:00:00Z",
+  ip: "127.0.0.1",
+  user: "test-user",
+  msgId: "cmd-msg-1",
+  correlationId: "cmd-corr-1"
+};
+
+function makeCommandJson(id, command) {
+  let cmd$p = {
+    id: id,
+    meta: testMeta,
+    command: command
+  };
+  return Message$ReventlessCore.encodeCommand$p(cmd$p, Id$Reventless.StringPure.schema, commandSchema);
+}
+
+function makeTopicItem(id, command) {
+  return {
+    command: makeCommandJson(id, command),
+    reference: id
+  };
+}
+
+function reset() {
+  capturedItems.contents = [];
+  commandHandlerResults.contents = [{
+      TAG: "Ok",
+      _0: "ref-1"
+    }];
+  commandHandlerShouldThrow.contents = false;
+}
+
+export {
+  TestSpec,
+  capturedItems,
+  commandHandlerResults,
+  commandHandlerShouldThrow,
+  TestOps,
+  TestHandler,
+  testMeta,
+  makeCommandJson,
+  makeTopicItem,
+  reset,
+}
+/*  Not a pure module */

package/tests/commandtopic/CommandTopicCallbackTest.res

@@ -0,0 +1,66 @@
+open JestGlobals
+open CommandTopicCallbackFixtures
+
+let _ = beforeEach(() => reset())
+
+describe("CommandTopic_Callback.handleJsonCommands:", () => {
+  describe("valid command JSON", () => {
+    testPromise("decoded command passed to commandsHandler", async () => {
+      let item = makeTopicItem("agg-1", TestSpec.CreateItem({itemId: "item-1"}))
+      let _ = await TestHandler.handleJsonCommands(Stream.fromIterable([item]))->Effect.runPromise
+      expect(capturedItems.contents->Array.length)->toBe(1)
+      let captured = capturedItems.contents->Array.getUnsafe(0)
+      expect(captured.reference)->toBe("agg-1")
+      expect(captured.command)->toEqual(TestSpec.CreateItem({itemId: "item-1"}))
+    })
+  })
+
+  describe("results returned from commandsHandler", () => {
+    testPromise("handler results propagated as return value", async () => {
+      commandHandlerResults := [Ok("agg-1"), Error("agg-2")]
+      let item = makeTopicItem("agg-1", TestSpec.CreateItem({itemId: "item-1"}))
+      let results = await TestHandler.handleJsonCommands(Stream.fromIterable([item]))->Effect.runPromise
+      expect(results)->toEqual([Ok("agg-1"), Error("agg-2")])
+    })
+  })
+
+  describe("malformed command JSON", () => {
+    testPromise("skipped gracefully — commandsHandler called with empty array", async () => {
+      let invalidItem: CommandTopic.topicItem<JSON.t> = {
+        reference: "ref-1",
+        command: JSON.Encode.string("not-a-command-object"),
+      }
+      let _ = await TestHandler.handleJsonCommands(Stream.fromIterable([invalidItem]))->Effect.runPromise
+      // Decode fails — commandsHandler called with empty list, returns default [Ok("ref-1")]
+      expect(capturedItems.contents->Array.length)->toBe(0)
+    })
+  })
+
+  describe("multiple commands in batch", () => {
+    testPromise("all decodable commands reach commandsHandler", async () => {
+      let items = [
+        makeTopicItem("agg-1", TestSpec.CreateItem({itemId: "item-1"})),
+        makeTopicItem("agg-2", TestSpec.DeleteItem({itemId: "item-2"})),
+        makeTopicItem("agg-3", TestSpec.CreateItem({itemId: "item-3"})),
+      ]
+      let _ = await TestHandler.handleJsonCommands(Stream.fromIterable(items))->Effect.runPromise
+      expect(capturedItems.contents->Array.length)->toBe(3)
+    })
+  })
+
+  describe("mixed valid and invalid commands", () => {
+    testPromise("only valid commands reach commandsHandler", async () => {
+      let validItem = makeTopicItem("agg-1", TestSpec.CreateItem({itemId: "item-1"}))
+      let invalidItem: CommandTopic.topicItem<JSON.t> = {
+        reference: "ref-bad",
+        command: JSON.Encode.null,
+      }
+      let _ =
+        await TestHandler.handleJsonCommands(
+          Stream.fromIterable([validItem, invalidItem]),
+        )->Effect.runPromise
+      expect(capturedItems.contents->Array.length)->toBe(1)
+      expect((capturedItems.contents->Array.getUnsafe(0)).reference)->toBe("agg-1")
+    })
+  })
+})

package/tests/commandtopic/CommandTopicCallbackTest.res.mjs

@@ -0,0 +1,106 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as CommandTopicCallbackFixtures$ReventlessCore from "./CommandTopicCallbackFixtures.res.mjs";
+
+globalThis.beforeEach(() => CommandTopicCallbackFixtures$ReventlessCore.reset());
+
+globalThis.describe("CommandTopic_Callback.handleJsonCommands:", () => {
+  globalThis.describe("valid command JSON", () => {
+    globalThis.test("decoded command passed to commandsHandler", async () => {
+      let item = CommandTopicCallbackFixtures$ReventlessCore.makeTopicItem("agg-1", {
+        TAG: "CreateItem",
+        itemId: "item-1"
+      });
+      await Effect.runPromise(CommandTopicCallbackFixtures$ReventlessCore.TestHandler.handleJsonCommands(Stream.fromIterable([item])));
+      globalThis.expect(CommandTopicCallbackFixtures$ReventlessCore.capturedItems.contents.length).toBe(1);
+      let captured = CommandTopicCallbackFixtures$ReventlessCore.capturedItems.contents[0];
+      globalThis.expect(captured.reference).toBe("agg-1");
+      globalThis.expect(captured.command).toEqual({
+        TAG: "CreateItem",
+        itemId: "item-1"
+      });
+    });
+  });
+  globalThis.describe("results returned from commandsHandler", () => {
+    globalThis.test("handler results propagated as return value", async () => {
+      CommandTopicCallbackFixtures$ReventlessCore.commandHandlerResults.contents = [
+        {
+          TAG: "Ok",
+          _0: "agg-1"
+        },
+        {
+          TAG: "Error",
+          _0: "agg-2"
+        }
+      ];
+      let item = CommandTopicCallbackFixtures$ReventlessCore.makeTopicItem("agg-1", {
+        TAG: "CreateItem",
+        itemId: "item-1"
+      });
+      let results = await Effect.runPromise(CommandTopicCallbackFixtures$ReventlessCore.TestHandler.handleJsonCommands(Stream.fromIterable([item])));
+      globalThis.expect(results).toEqual([
+        {
+          TAG: "Ok",
+          _0: "agg-1"
+        },
+        {
+          TAG: "Error",
+          _0: "agg-2"
+        }
+      ]);
+    });
+  });
+  globalThis.describe("malformed command JSON", () => {
+    globalThis.test("skipped gracefully — commandsHandler called with empty array", async () => {
+      let invalidItem = {
+        command: "not-a-command-object",
+        reference: "ref-1"
+      };
+      await Effect.runPromise(CommandTopicCallbackFixtures$ReventlessCore.TestHandler.handleJsonCommands(Stream.fromIterable([invalidItem])));
+      globalThis.expect(CommandTopicCallbackFixtures$ReventlessCore.capturedItems.contents.length).toBe(0);
+    });
+  });
+  globalThis.describe("multiple commands in batch", () => {
+    globalThis.test("all decodable commands reach commandsHandler", async () => {
+      let items = [
+        CommandTopicCallbackFixtures$ReventlessCore.makeTopicItem("agg-1", {
+          TAG: "CreateItem",
+          itemId: "item-1"
+        }),
+        CommandTopicCallbackFixtures$ReventlessCore.makeTopicItem("agg-2", {
+          TAG: "DeleteItem",
+          itemId: "item-2"
+        }),
+        CommandTopicCallbackFixtures$ReventlessCore.makeTopicItem("agg-3", {
+          TAG: "CreateItem",
+          itemId: "item-3"
+        })
+      ];
+      await Effect.runPromise(CommandTopicCallbackFixtures$ReventlessCore.TestHandler.handleJsonCommands(Stream.fromIterable(items)));
+      globalThis.expect(CommandTopicCallbackFixtures$ReventlessCore.capturedItems.contents.length).toBe(3);
+    });
+  });
+  globalThis.describe("mixed valid and invalid commands", () => {
+    globalThis.test("only valid commands reach commandsHandler", async () => {
+      let validItem = CommandTopicCallbackFixtures$ReventlessCore.makeTopicItem("agg-1", {
+        TAG: "CreateItem",
+        itemId: "item-1"
+      });
+      let invalidItem_command = null;
+      let invalidItem = {
+        command: invalidItem_command,
+        reference: "ref-bad"
+      };
+      await Effect.runPromise(CommandTopicCallbackFixtures$ReventlessCore.TestHandler.handleJsonCommands(Stream.fromIterable([
+        validItem,
+        invalidItem
+      ])));
+      globalThis.expect(CommandTopicCallbackFixtures$ReventlessCore.capturedItems.contents.length).toBe(1);
+      globalThis.expect(CommandTopicCallbackFixtures$ReventlessCore.capturedItems.contents[0].reference).toBe("agg-1");
+    });
+  });
+});
+
+/*  Not a pure module */

package/tests/commandtopic/CommandTopicHelpersRejectionTest.res

@@ -0,0 +1,83 @@
+// Tests for CommandTopic_Helpers.runInlineAndCollect — verifies the precedence rules
+// for the rejected/accepted side-channels and the synthesized "Conflict" Error result.
+
+open JestGlobals
+
+let metaWithMsgId = (msgId): Reventless.Message.meta => {
+  service: "TestService",
+  time: "2024-01-01T00:00:00Z",
+  ip: "127.0.0.1",
+  user: "test-user",
+  msgId,
+  correlationId: "corr-1",
+}
+
+let cmdJson = (msgId): Reventless.Message.commandJson => {
+  id: "agg-1",
+  meta: metaWithMsgId(msgId),
+  commandJson: JSON.Encode.object(Dict.fromArray([("TAG", JSON.Encode.string("Noop"))])),
+}
+
+describe("CommandTopic_Helpers.runInlineAndCollect:", () => {
+  testPromise("Rejected from rejectedResultChannel beats Accepted from acceptedResultChannel", async () => {
+    let handler: CommandTopic_Helpers.jsonCommandsHandler = stream =>
+      stream
+      ->Stream.runCollect
+      ->Effect.map(items => {
+        items->Array.forEach(item => {
+          // Both channels report for the same reference; rejected wins.
+          CommandTopic_Helpers.reportAccepted(item.reference, {entityId: "agg-1", eventCount: 0})
+          CommandTopic_Helpers.reportRejected(
+            item.reference,
+            {errorCode: "AlreadyExists", errorDetail: ""},
+          )
+        })
+        items->Array.map(item => Ok(item.reference))
+      })
+
+    let outcomes = await CommandTopic_Helpers.runInlineAndCollect([cmdJson("msg-1")], handler)
+    expect(outcomes->Array.length)->toBe(1)
+    switch outcomes->Array.getUnsafe(0) {
+    | Rejected({msgId, errorCode, errorDetail}) =>
+      expect(msgId)->toEqual("msg-1")
+      expect(errorCode)->toEqual("AlreadyExists")
+      expect(errorDetail)->toEqual(None)
+    | Accepted(_) | Pending(_) => expect("expected Rejected")->toEqual("got other")
+    }
+  })
+
+  testPromise("Rejected from rejectedResultChannel beats Error result (synthesized Conflict)", async () => {
+    let handler: CommandTopic_Helpers.jsonCommandsHandler = stream =>
+      stream
+      ->Stream.runCollect
+      ->Effect.map(items => {
+        items->Array.forEach(item =>
+          CommandTopic_Helpers.reportRejected(
+            item.reference,
+            {errorCode: "BusinessRuleViolated", errorDetail: "{\"reason\":\"x\"}"},
+          )
+        )
+        // Handler still returns Error — rejectedChannel takes precedence.
+        items->Array.map(item => Error(item.reference))
+      })
+
+    let outcomes = await CommandTopic_Helpers.runInlineAndCollect([cmdJson("msg-1")], handler)
+    switch outcomes->Array.getUnsafe(0) {
+    | Rejected({errorCode, errorDetail}) =>
+      expect(errorCode)->toEqual("BusinessRuleViolated")
+      expect(errorDetail)->toEqual(Some("{\"reason\":\"x\"}"))
+    | Accepted(_) | Pending(_) => expect("expected Rejected")->toEqual("got other")
+    }
+  })
+
+  testPromise("Error result without rejectedChannel still synthesizes Conflict", async () => {
+    let handler: CommandTopic_Helpers.jsonCommandsHandler = stream =>
+      stream->Stream.runCollect->Effect.map(items => items->Array.map(item => Error(item.reference)))
+
+    let outcomes = await CommandTopic_Helpers.runInlineAndCollect([cmdJson("msg-1")], handler)
+    switch outcomes->Array.getUnsafe(0) {
+    | Rejected({errorCode}) => expect(errorCode)->toEqual("Conflict")
+    | _ => expect("expected Rejected(Conflict)")->toEqual("got other")
+    }
+  })
+})

package/tests/commandtopic/CommandTopicHelpersRejectionTest.res.mjs

@@ -0,0 +1,109 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stream from "@reventlessdev/rescript-effect/src/Stream.res.mjs";
+import * as Effect from "effect/Effect";
+import * as CommandTopic_Helpers$ReventlessCore from "../../src/components/CommandTopic/CommandTopic_Helpers.res.mjs";
+
+function metaWithMsgId(msgId) {
+  return {
+    service: "TestService",
+    time: "2024-01-01T00:00:00Z",
+    ip: "127.0.0.1",
+    user: "test-user",
+    msgId: msgId,
+    correlationId: "corr-1"
+  };
+}
+
+function cmdJson(msgId) {
+  return {
+    id: "agg-1",
+    meta: metaWithMsgId(msgId),
+    commandJson: Object.fromEntries([[
+        "TAG",
+        "Noop"
+      ]])
+  };
+}
+
+globalThis.describe("CommandTopic_Helpers.runInlineAndCollect:", () => {
+  globalThis.test("Rejected from rejectedResultChannel beats Accepted from acceptedResultChannel", async () => {
+    let handler = stream => Effect.map(Stream.runCollect(stream), items => {
+      items.forEach(item => {
+        CommandTopic_Helpers$ReventlessCore.reportAccepted(item.reference, {
+          entityId: "agg-1",
+          eventCount: 0
+        });
+        CommandTopic_Helpers$ReventlessCore.reportRejected(item.reference, {
+          errorCode: "AlreadyExists",
+          errorDetail: ""
+        });
+      });
+      return items.map(item => ({
+        TAG: "Ok",
+        _0: item.reference
+      }));
+    });
+    let outcomes = await CommandTopic_Helpers$ReventlessCore.runInlineAndCollect([cmdJson("msg-1")], handler);
+    globalThis.expect(outcomes.length).toBe(1);
+    let match = outcomes[0];
+    switch (match.TAG) {
+      case "Rejected" :
+        globalThis.expect(match.msgId).toEqual("msg-1");
+        globalThis.expect(match.errorCode).toEqual("AlreadyExists");
+        globalThis.expect(match.errorDetail).toEqual(undefined);
+        return;
+      case "Accepted" :
+      case "Pending" :
+        globalThis.expect("expected Rejected").toEqual("got other");
+        return;
+    }
+  });
+  globalThis.test("Rejected from rejectedResultChannel beats Error result (synthesized Conflict)", async () => {
+    let handler = stream => Effect.map(Stream.runCollect(stream), items => {
+      items.forEach(item => CommandTopic_Helpers$ReventlessCore.reportRejected(item.reference, {
+        errorCode: "BusinessRuleViolated",
+        errorDetail: "{\"reason\":\"x\"}"
+      }));
+      return items.map(item => ({
+        TAG: "Error",
+        _0: item.reference
+      }));
+    });
+    let outcomes = await CommandTopic_Helpers$ReventlessCore.runInlineAndCollect([cmdJson("msg-1")], handler);
+    let match = outcomes[0];
+    switch (match.TAG) {
+      case "Rejected" :
+        globalThis.expect(match.errorCode).toEqual("BusinessRuleViolated");
+        globalThis.expect(match.errorDetail).toEqual("{\"reason\":\"x\"}");
+        return;
+      case "Accepted" :
+      case "Pending" :
+        globalThis.expect("expected Rejected").toEqual("got other");
+        return;
+    }
+  });
+  globalThis.test("Error result without rejectedChannel still synthesizes Conflict", async () => {
+    let handler = stream => Effect.map(Stream.runCollect(stream), items => items.map(item => ({
+      TAG: "Error",
+      _0: item.reference
+    })));
+    let outcomes = await CommandTopic_Helpers$ReventlessCore.runInlineAndCollect([cmdJson("msg-1")], handler);
+    let match = outcomes[0];
+    switch (match.TAG) {
+      case "Rejected" :
+        globalThis.expect(match.errorCode).toEqual("Conflict");
+        return;
+      case "Accepted" :
+      case "Pending" :
+        globalThis.expect("expected Rejected(Conflict)").toEqual("got other");
+        return;
+    }
+  });
+});
+
+export {
+  metaWithMsgId,
+  cmdJson,
+}
+/*  Not a pure module */

package/tests/counter/CounterCallbackTest.res

@@ -0,0 +1,83 @@
+open JestGlobals
+open CounterFixtures
+
+let _ = beforeEach(() => reset())
+
+// ─────────────────────────────────────────────────────────────
+// groupByCounterId (sync, wrapped as async for open compatibility)
+// ─────────────────────────────────────────────────────────────
+
+describe("Counter_Callback.groupByCounterId:", () => {
+  testPromise("groups references by counter ID and sums increments", async () => {
+    // Counter.makeId((counterId, ref)) = counterId ++ "#" ++ ref
+    let result = Counter_Callback.groupByCounterId([
+      (Counter.makeId(("counter-a", "ref-1")), 1),
+      (Counter.makeId(("counter-a", "ref-2")), 2),
+    ])
+    let sorted = result->Array.toSorted(((a, _), (b, _)) => String.compare(a, b))
+    expect(sorted)->toEqual([("counter-a", 3)])
+  })
+
+  testPromise("groups different counter IDs independently", async () => {
+    let result = Counter_Callback.groupByCounterId([
+      (Counter.makeId(("counter-a", "ref-1")), 1),
+      (Counter.makeId(("counter-b", "ref-2")), 1),
+    ])
+    let sorted = result->Array.toSorted(((a, _), (b, _)) => String.compare(a, b))
+    expect(sorted)->toEqual([("counter-a", 1), ("counter-b", 1)])
+  })
+
+  testPromise("returns empty array for empty input", async () => {
+    let result = Counter_Callback.groupByCounterId([])
+    expect(result)->toEqual([])
+  })
+})
+
+// ─────────────────────────────────────────────────────────────
+// counterHandler (async)
+// ─────────────────────────────────────────────────────────────
+
+describe("Counter_Callback.counterHandler:", () => {
+  describe("count reaches zero", () => {
+    testPromise("CountFinished event dispatched via jsonEventsHandler", async () => {
+      let ref1 = Counter.makeId(("counter-1", "ref-a"))
+      let counts = [makeCountsJson(ref1, 0)]
+      await TestCounterHandler.counterHandler(~references=[(ref1, 1)], ~counts)
+      // jsonEventsHandler should have been called with 1 event batch containing 1 event
+      let batches = capturedEventBatches.contents
+      expect((batches->Array.length, batches->Array.getUnsafe(0)->Array.length))->toEqual((1, 1))
+    })
+  })
+
+  describe("count above zero", () => {
+    testPromise("no CountFinished event, countsDbCount still called", async () => {
+      let ref1 = Counter.makeId(("counter-1", "ref-a"))
+      let counts = [makeCountsJson(ref1, 3)]
+      await TestCounterHandler.counterHandler(~references=[(ref1, 1)], ~counts)
+      // jsonEventsHandler called with empty array (no finished counters)
+      let batches = capturedEventBatches.contents
+      let events = batches->Array.getUnsafe(0)
+      expect(events->Array.length)->toBe(0)
+      // countsDbCount was called once
+      expect(capturedCountCalls.contents->Array.length)->toBe(1)
+    })
+  })
+
+  describe("multiple counters in batch", () => {
+    testPromise("each decremented independently", async () => {
+      let refA = Counter.makeId(("counter-a", "ref-1"))
+      let refB = Counter.makeId(("counter-b", "ref-2"))
+      let counts = [makeCountsJson(refA, 2), makeCountsJson(refB, 0)]
+      await TestCounterHandler.counterHandler(
+        ~references=[(refA, 1), (refB, 1)],
+        ~counts,
+      )
+      // countsDbCount called twice (once per counter ID)
+      expect(capturedCountCalls.contents->Array.length)->toBe(2)
+      // One CountFinished event (counter-b reached 0)
+      let batches = capturedEventBatches.contents
+      let events = batches->Array.getUnsafe(0)
+      expect(events->Array.length)->toBe(1)
+    })
+  })
+})