@cosmicdrift/kumiko-framework 0.2.3 → 0.4.0

package/src/engine/__tests__/steps-aggregate-append-event.test.ts

@@ -0,0 +1,115 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getStep } from "../define-step";
+import { buildAggregateAppendEventStep } from "../steps/aggregate-append-event";
+import type { PipelineCtx } from "../types/step";
+
+const mockUnsafeAppendEvent = vi.fn();
+
+const mockCtx = {
+  unsafeAppendEvent: mockUnsafeAppendEvent,
+  event: { type: "test", payload: {} },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
+describe("buildAggregateAppendEventStep", () => {
+  it("returns a StepInstance with kind aggregate.appendEvent", () => {
+    const step = buildAggregateAppendEventStep({
+      aggregateId: "abc-123",
+      aggregateType: "widget",
+      type: "widget:event:custom",
+      payload: { note: "test" },
+    });
+    expect(step.kind).toBe("aggregate.appendEvent");
+  });
+
+  it("accepts optional headers", () => {
+    const step = buildAggregateAppendEventStep({
+      aggregateId: "abc",
+      aggregateType: "widget",
+      type: "widget:event:custom",
+      payload: {},
+      headers: { correlationId: "corr-1" },
+    });
+    expect((step.args as { headers: Record<string, string> }).headers).toEqual({
+      correlationId: "corr-1",
+    });
+  });
+});
+
+describe("aggregate.appendEvent run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("calls ctx.unsafeAppendEvent with resolved aggregateId and payload", async () => {
+    const stepDef = getStep("aggregate.appendEvent");
+    expect(stepDef).toBeDefined();
+
+    await stepDef!.run(
+      {
+        aggregateId: "abc-123",
+        aggregateType: "widget",
+        type: "widget:event:custom",
+        payload: { note: "hello" },
+      },
+      mockCtx,
+    );
+
+    expect(mockUnsafeAppendEvent).toHaveBeenCalledOnce();
+    const call = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect(call).toMatchObject({
+      aggregateId: "abc-123",
+      aggregateType: "widget",
+      type: "widget:event:custom",
+      payload: { note: "hello" },
+    });
+  });
+
+  it("resolves function resolvers before calling unsafeAppendEvent", async () => {
+    const stepDef = getStep("aggregate.appendEvent");
+    const idFn = vi.fn(() => "dynamic-id");
+    const payloadFn = vi.fn(() => ({ note: "dynamic" }));
+    const headersFn = vi.fn(() => ({ key: "val" }));
+
+    await stepDef!.run(
+      {
+        aggregateId: idFn,
+        aggregateType: "widget",
+        type: "widget:event:custom",
+        payload: payloadFn,
+        headers: headersFn,
+      },
+      mockCtx,
+    );
+
+    expect(idFn).toHaveBeenCalledWith(mockCtx);
+    expect(payloadFn).toHaveBeenCalledWith(mockCtx);
+    expect(headersFn).toHaveBeenCalledWith(mockCtx);
+
+    expect(mockUnsafeAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        aggregateId: "dynamic-id",
+        payload: { note: "dynamic" },
+        headers: { key: "val" },
+      }),
+    );
+  });
+
+  it("omits headers from the event when headers resolver is undefined", async () => {
+    const stepDef = getStep("aggregate.appendEvent");
+
+    await stepDef!.run(
+      {
+        aggregateId: "abc",
+        aggregateType: "widget",
+        type: "widget:event:plain",
+        payload: { x: 1 },
+      },
+      mockCtx,
+    );
+
+    const call = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect(call.headers).toBeUndefined();
+  });
+});

package/src/engine/__tests__/steps-aggregate-create.test.ts

@@ -0,0 +1,92 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { EventStoreExecutor } from "../../db/event-store-executor";
+import { getStep } from "../define-step";
+import { buildAggregateCreateStep } from "../steps/aggregate-create";
+import type { PipelineCtx } from "../types/step";
+
+const mockCreate = vi.fn();
+const mockExecutor = { create: mockCreate } as unknown as EventStoreExecutor & {
+  create: typeof mockCreate;
+};
+const mockDb = {};
+
+const mockCtx = {
+  db: mockDb,
+  event: { type: "test", payload: { label: "test" }, user: { id: "u1" } },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
+describe("buildAggregateCreateStep", () => {
+  it("returns a StepInstance with kind aggregate.create", () => {
+    const step = buildAggregateCreateStep("widget", {
+      executor: mockExecutor,
+      data: { label: "hello" },
+    });
+    expect(step.kind).toBe("aggregate.create");
+    expect((step.args as { name: string }).name).toBe("widget");
+  });
+
+  it("stores the result key from the name arg", () => {
+    const step = buildAggregateCreateStep("myResult", {
+      executor: mockExecutor,
+      data: { label: "hello" },
+    });
+    const def = getStep("aggregate.create");
+    expect(def?.resultKey?.(step.args as { name: string })).toBe("myResult");
+  });
+});
+
+describe("aggregate.create run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("resolves data and calls executor.create with user and db", async () => {
+    const stepDef = getStep("aggregate.create");
+    mockExecutor.create.mockResolvedValue({
+      isSuccess: true,
+      data: { id: "abc-123", label: "hello" },
+    });
+
+    const result = await stepDef!.run(
+      { name: "widget", executor: mockExecutor, data: { label: "hello" } },
+      mockCtx,
+    );
+
+    expect(mockExecutor.create).toHaveBeenCalledWith(
+      { label: "hello" },
+      mockCtx.event.user,
+      mockDb,
+    );
+    expect(result).toEqual({ id: "abc-123", label: "hello" });
+  });
+
+  it("resolves a function data resolver before calling executor.create", async () => {
+    const stepDef = getStep("aggregate.create");
+    const dataFn = vi.fn((ctx: PipelineCtx) => ({
+      label: (ctx.event.payload as { label: string }).label,
+    }));
+    mockExecutor.create.mockResolvedValue({
+      isSuccess: true,
+      data: { id: "abc", label: "test" },
+    });
+
+    await stepDef!.run({ name: "widget", executor: mockExecutor, data: dataFn }, mockCtx);
+
+    expect(dataFn).toHaveBeenCalledWith(mockCtx);
+    expect(mockExecutor.create).toHaveBeenCalledWith({ label: "test" }, mockCtx.event.user, mockDb);
+  });
+
+  it("re-throws executor WriteFailure as a KumikoError", async () => {
+    const stepDef = getStep("aggregate.create");
+    mockExecutor.create.mockResolvedValue({
+      isSuccess: false,
+      error: { code: "validation_error", message: "label is required" },
+    });
+
+    await expect(
+      stepDef!.run({ name: "widget", executor: mockExecutor, data: {} }, mockCtx),
+    ).rejects.toThrow(/label is required/);
+  });
+});

package/src/engine/__tests__/steps-aggregate-update.test.ts

@@ -0,0 +1,127 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { EventStoreExecutor } from "../../db/event-store-executor";
+import { getStep } from "../define-step";
+import { buildAggregateUpdateStep } from "../steps/aggregate-update";
+import type { PipelineCtx } from "../types/step";
+
+const mockUpdate = vi.fn();
+const mockExecutor = { update: mockUpdate } as unknown as EventStoreExecutor & {
+  update: typeof mockUpdate;
+};
+const mockDb = {};
+
+const mockCtx = {
+  db: mockDb,
+  event: { type: "test", payload: {}, user: { id: "u1" } },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
+describe("buildAggregateUpdateStep", () => {
+  it("returns a StepInstance with kind aggregate.update", () => {
+    const step = buildAggregateUpdateStep("widget", {
+      executor: mockExecutor,
+      id: "abc-123",
+      changes: { label: "updated" },
+    });
+    expect(step.kind).toBe("aggregate.update");
+    expect((step.args as { name: string }).name).toBe("widget");
+  });
+
+  it("stores the result key from the name arg", () => {
+    const step = buildAggregateUpdateStep("myUpdate", {
+      executor: mockExecutor,
+      id: "abc",
+      changes: {},
+    });
+    const def = getStep("aggregate.update");
+    expect(def?.resultKey?.(step.args as { name: string })).toBe("myUpdate");
+  });
+
+  it("accepts an optional version resolver", () => {
+    const step = buildAggregateUpdateStep("widget", {
+      executor: mockExecutor,
+      id: "abc",
+      changes: {},
+      version: () => 1,
+    });
+    expect(typeof (step.args as { version: unknown }).version).toBe("function");
+  });
+
+  it("accepts skipOptimisticLock flag", () => {
+    const step = buildAggregateUpdateStep("widget", {
+      executor: mockExecutor,
+      id: "abc",
+      changes: {},
+      skipOptimisticLock: true,
+    });
+    expect((step.args as { skipOptimisticLock: boolean }).skipOptimisticLock).toBe(true);
+  });
+});
+
+describe("aggregate.update run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("resolves id, changes, version and calls executor.update", async () => {
+    const stepDef = getStep("aggregate.update");
+    mockUpdate.mockResolvedValue({
+      isSuccess: true,
+      data: { id: "abc", changes: { label: "updated" }, previous: { label: "old" } },
+    });
+
+    await stepDef!.run(
+      {
+        name: "widget",
+        executor: mockExecutor,
+        id: "abc-123",
+        changes: { label: "updated" },
+      },
+      mockCtx,
+    );
+
+    expect(mockExecutor.update).toHaveBeenCalled();
+    const [input, user, db] = mockUpdate.mock.calls[0]!;
+    expect(input).toMatchObject({ id: "abc-123", changes: { label: "updated" } });
+    expect(user).toBe(mockCtx.event.user);
+    expect(db).toBe(mockDb);
+  });
+
+  it("passes skipOptimisticLock when set", async () => {
+    const stepDef = getStep("aggregate.update");
+    mockUpdate.mockResolvedValue({
+      isSuccess: true,
+      data: { id: "abc", changes: {} },
+    });
+
+    await stepDef!.run(
+      {
+        name: "widget",
+        executor: mockExecutor,
+        id: "abc",
+        changes: {},
+        skipOptimisticLock: true,
+      },
+      mockCtx,
+    );
+
+    const [, , , opts] = mockUpdate.mock.calls[0]!;
+    expect(opts).toEqual({ skipOptimisticLock: true });
+  });
+
+  it("re-throws executor WriteFailure as a KumikoError", async () => {
+    const stepDef = getStep("aggregate.update");
+    mockUpdate.mockResolvedValue({
+      isSuccess: false,
+      error: { code: "not_found", message: "aggregate not found" },
+    });
+
+    await expect(
+      stepDef!.run(
+        { name: "widget", executor: mockExecutor, id: "nonexistent", changes: {} },
+        mockCtx,
+      ),
+    ).rejects.toThrow(/aggregate not found/);
+  });
+});

package/src/engine/__tests__/steps-call-feature.test.ts

@@ -0,0 +1,123 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getStep } from "../define-step";
+import { buildCallFeatureStep } from "../steps/call-feature";
+import type { PipelineCtx } from "../types/step";
+
+const mockWrite = vi.fn();
+const mockWriteAs = vi.fn();
+
+const mockCtx = {
+  write: mockWrite,
+  writeAs: mockWriteAs,
+  event: { type: "test", payload: { title: "test" } },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
+describe("buildCallFeatureStep", () => {
+  it("returns a StepInstance with kind callFeature", () => {
+    const step = buildCallFeatureStep("inner", {
+      handler: "other-feature:write:handler",
+      payload: { key: "val" },
+    });
+    expect(step.kind).toBe("callFeature");
+    expect((step.args as { name: string }).name).toBe("inner");
+    expect((step.args as { handler: string }).handler).toBe("other-feature:write:handler");
+  });
+
+  it("stores the result key from the name arg", () => {
+    const step = buildCallFeatureStep("myCall", {
+      handler: "feat:write:h",
+      payload: {},
+    });
+    const def = getStep("callFeature");
+    expect(def?.resultKey?.(step.args as { name: string })).toBe("myCall");
+  });
+});
+
+describe("callFeature run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("calls ctx.write with the resolved payload and handler name", async () => {
+    const stepDef = getStep("callFeature");
+    mockWrite.mockResolvedValue({
+      isSuccess: true,
+      data: { id: "abc-123" },
+    });
+
+    const result = await stepDef!.run(
+      {
+        name: "inner",
+        handler: "other-feature:write:handler",
+        payload: { title: "hello" },
+      },
+      mockCtx,
+    );
+
+    expect(mockWrite).toHaveBeenCalledWith("other-feature:write:handler", {
+      title: "hello",
+    });
+    expect(result).toEqual({ id: "abc-123" });
+  });
+
+  it("resolves a function payload resolver before calling ctx.write", async () => {
+    const stepDef = getStep("callFeature");
+    const payloadFn = vi.fn((ctx: PipelineCtx) => ({
+      title: (ctx.event.payload as { title: string }).title,
+    }));
+    mockWrite.mockResolvedValue({
+      isSuccess: true,
+      data: { id: "abc" },
+    });
+
+    await stepDef!.run({ name: "inner", handler: "feat:write:h", payload: payloadFn }, mockCtx);
+
+    expect(payloadFn).toHaveBeenCalledWith(mockCtx);
+    expect(mockWrite).toHaveBeenCalledWith("feat:write:h", { title: "test" });
+  });
+
+  it("calls ctx.writeAs when opts.as is provided", async () => {
+    const stepDef = getStep("callFeature");
+    const adminUser = { id: "admin-id", tenantId: "t1", roles: ["Admin"] };
+    mockWriteAs.mockResolvedValue({
+      isSuccess: true,
+      data: { id: "abc" },
+    });
+
+    await stepDef!.run(
+      {
+        name: "inner",
+        handler: "feat:write:h",
+        payload: {},
+        as: adminUser,
+      },
+      mockCtx,
+    );
+
+    expect(mockWriteAs).toHaveBeenCalledWith(adminUser, "feat:write:h", {});
+    expect(mockWrite).not.toHaveBeenCalled();
+  });
+
+  it("preserves WriteFailure as error cause when the sub-handler returns failure", async () => {
+    const stepDef = getStep("callFeature");
+    const writeError = {
+      code: "validation_error",
+      message: "title is required",
+      details: [{ path: ["title"], message: "required" }],
+    };
+    mockWrite.mockResolvedValue({
+      isSuccess: false,
+      error: writeError,
+    });
+
+    try {
+      await stepDef!.run({ name: "inner", handler: "feat:write:h", payload: {} }, mockCtx);
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect((err as Error).message).toMatch(/returned failure/);
+      expect((err as Error & { cause?: unknown }).cause).toEqual(writeError);
+    }
+  });
+});

package/src/engine/__tests__/steps-mail-send.test.ts

@@ -0,0 +1,136 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getStep } from "../define-step";
+import {
+  STEP_DISPATCH_AGGREGATE_TYPE,
+  STEP_DISPATCH_REQUESTED_TYPE,
+} from "../steps/_step-dispatch-constants";
+import { buildMailSendStep } from "../steps/mail-send";
+import type { PipelineCtx } from "../types/step";
+
+const mockUnsafeAppendEvent = vi.fn();
+
+const mockCtx = {
+  unsafeAppendEvent: mockUnsafeAppendEvent,
+  event: { type: "test", payload: {} },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
+describe("buildMailSendStep", () => {
+  it("returns a StepInstance with kind mail.send", () => {
+    const step = buildMailSendStep({
+      to: "user@example.com",
+      subject: "Hello",
+      body: "World",
+      mode: "deferred",
+    });
+    expect(step.kind).toBe("mail.send");
+  });
+
+  it("requires mode to be deferred", () => {
+    const step = buildMailSendStep({
+      to: "user@example.com",
+      subject: "Hello",
+      body: "World",
+      mode: "deferred",
+    });
+    expect((step.args as { mode: string }).mode).toBe("deferred");
+  });
+
+  it("accepts an optional from address", () => {
+    const step = buildMailSendStep({
+      to: "user@example.com",
+      subject: "Hello",
+      body: "World",
+      from: "noreply@example.com",
+      mode: "deferred",
+    });
+    expect((step.args as { from: string }).from).toBe("noreply@example.com");
+  });
+
+  it("accepts string array for to", () => {
+    const step = buildMailSendStep({
+      to: ["a@example.com", "b@example.com"],
+      subject: "Hello",
+      body: "World",
+      mode: "deferred",
+    });
+    expect((step.args as { to: unknown }).to).toEqual(["a@example.com", "b@example.com"]);
+  });
+});
+
+describe("mail.send run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("appends a step.dispatch-requested system event with the mail spec", async () => {
+    const stepDef = getStep("mail.send");
+    expect(stepDef).toBeDefined();
+
+    await stepDef!.run(
+      {
+        to: "user@example.com",
+        subject: "Test",
+        body: "Body text",
+        mode: "deferred",
+      },
+      mockCtx,
+    );
+
+    expect(mockUnsafeAppendEvent).toHaveBeenCalledOnce();
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+
+    expect(eventArg.aggregateType).toBe(STEP_DISPATCH_AGGREGATE_TYPE);
+    expect(eventArg.type).toBe(STEP_DISPATCH_REQUESTED_TYPE);
+    expect(eventArg.payload.stepKind).toBe("mail.send");
+    expect(eventArg.payload.spec).toMatchObject({
+      to: "user@example.com",
+      subject: "Test",
+      body: "Body text",
+    });
+  });
+
+  it("resolves function-based resolvers", async () => {
+    const stepDef = getStep("mail.send");
+    const toFn = vi.fn(() => "resolved@example.com");
+    const subjectFn = vi.fn(() => "Resolved Subject");
+    const bodyFn = vi.fn(() => "Resolved Body");
+
+    await stepDef!.run({ to: toFn, subject: subjectFn, body: bodyFn, mode: "deferred" }, mockCtx);
+
+    expect(toFn).toHaveBeenCalledWith(mockCtx);
+    expect(subjectFn).toHaveBeenCalledWith(mockCtx);
+    expect(bodyFn).toHaveBeenCalledWith(mockCtx);
+  });
+
+  it("includes from when provided", async () => {
+    const stepDef = getStep("mail.send");
+
+    await stepDef!.run(
+      {
+        to: "user@example.com",
+        subject: "Hi",
+        body: "Message",
+        from: "system@example.com",
+        mode: "deferred",
+      },
+      mockCtx,
+    );
+
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect(eventArg.payload.spec.from).toBe("system@example.com");
+  });
+
+  it("omits from from the spec when not provided", async () => {
+    const stepDef = getStep("mail.send");
+
+    await stepDef!.run(
+      { to: "user@example.com", subject: "Hi", body: "Message", mode: "deferred" },
+      mockCtx,
+    );
+
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect(eventArg.payload.spec.from).toBeUndefined();
+  });
+});