@cosmicdrift/kumiko-framework 0.2.3 → 0.4.0

package/src/engine/__tests__/steps-read.test.ts

@@ -0,0 +1,142 @@
+import type { SQL } from "drizzle-orm";
+import { pgTable, text, uuid } from "drizzle-orm/pg-core";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getStep } from "../define-step";
+import { buildReadFindManyStep } from "../steps/read-find-many";
+import { buildReadFindOneStep } from "../steps/read-find-one";
+import type { PipelineCtx } from "../types/step";
+
+const testTable = pgTable("test_read", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenantId: uuid("tenant_id").notNull(),
+  label: text("label"),
+});
+
+class MockQuery {
+  rows: Record<string, unknown>[] = [];
+  where = vi.fn(() => this);
+  limit = vi.fn(() => this);
+  // biome-ignore lint/suspicious/noThenProperty: mock query builder is intentionally thenable so await resolves rows
+  then: Promise<Record<string, unknown>[]>["then"];
+
+  constructor(rows?: Record<string, unknown>[]) {
+    if (rows) this.rows = rows;
+    const promise = Promise.resolve(this.rows);
+    // biome-ignore lint/suspicious/noThenProperty: see above
+    this.then = promise.then.bind(promise);
+  }
+}
+
+const mockDb = { select: vi.fn(() => ({ from: vi.fn(() => new MockQuery([])) })) };
+
+const mockCtx = {
+  db: mockDb,
+  event: { type: "test", payload: {} },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
+describe("buildReadFindOneStep", () => {
+  it("returns a StepInstance with kind read.findOne", () => {
+    const step = buildReadFindOneStep("myLookup", {
+      table: testTable,
+      where: undefined as unknown as SQL,
+    });
+    expect(step.kind).toBe("read.findOne");
+    expect((step.args as { name: string }).name).toBe("myLookup");
+  });
+
+  it("stores the result key from the name arg", () => {
+    const step = buildReadFindOneStep("lookupResult", {
+      table: testTable,
+      where: undefined as unknown as SQL,
+    });
+    const def = getStep("read.findOne");
+    expect(def?.resultKey?.(step.args as { name: string })).toBe("lookupResult");
+  });
+});
+
+describe("read.findOne run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns null when no row is found", async () => {
+    const stepDef = getStep("read.findOne");
+    const query = new MockQuery([]);
+    mockDb.select.mockReturnValue({ from: vi.fn().mockReturnValue(query) });
+
+    const result = await stepDef!.run(
+      { name: "lookup", table: testTable, where: undefined as unknown as SQL },
+      mockCtx,
+    );
+
+    expect(result).toBeNull();
+  });
+
+  it("returns the first row when found", async () => {
+    const stepDef = getStep("read.findOne");
+    const row = { id: "abc", tenantId: "t1", label: "hello" };
+    const query = new MockQuery([row]);
+    mockDb.select.mockReturnValue({ from: vi.fn().mockReturnValue(query) });
+
+    const result = await stepDef!.run(
+      { name: "lookup", table: testTable, where: undefined as unknown as SQL },
+      mockCtx,
+    );
+
+    expect(result).toEqual(row);
+  });
+
+  it("resolves a function where-clause before querying", async () => {
+    const stepDef = getStep("read.findOne");
+    const whereFn = vi.fn(() => "dynamic where" as unknown as SQL);
+    const query = new MockQuery([]);
+    mockDb.select.mockReturnValue({ from: vi.fn().mockReturnValue(query) });
+
+    await stepDef!.run({ name: "lookup", table: testTable, where: whereFn }, mockCtx);
+
+    expect(whereFn).toHaveBeenCalledWith(mockCtx);
+    expect(query.where).toHaveBeenCalledWith("dynamic where");
+  });
+});
+
+describe("buildReadFindManyStep", () => {
+  it("returns a StepInstance with kind read.findMany", () => {
+    const step = buildReadFindManyStep("myList", { table: testTable });
+    expect(step.kind).toBe("read.findMany");
+    expect((step.args as { name: string }).name).toBe("myList");
+  });
+
+  it("accepts an optional limit", () => {
+    const step = buildReadFindManyStep("myList", { table: testTable, limit: 10 });
+    expect((step.args as { limit: number }).limit).toBe(10);
+  });
+});
+
+describe("read.findMany run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns an empty array when no rows exist", async () => {
+    const stepDef = getStep("read.findMany");
+    const query = new MockQuery([]);
+    mockDb.select.mockReturnValue({ from: vi.fn().mockReturnValue(query) });
+
+    const result = await stepDef!.run({ name: "list", table: testTable }, mockCtx);
+
+    expect(result).toEqual([]);
+  });
+
+  it("applies the limit when specified", async () => {
+    const stepDef = getStep("read.findMany");
+    const rows = [{ id: "a" }, { id: "b" }];
+    const query = new MockQuery(rows);
+    mockDb.select.mockReturnValue({ from: vi.fn().mockReturnValue(query) });
+
+    await stepDef!.run({ name: "list", table: testTable, limit: 2 }, mockCtx);
+
+    expect(query.limit).toHaveBeenCalledWith(2);
+  });
+});

package/src/engine/__tests__/steps-resolver-utils.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveOptional, resolveRequired } from "../steps/_resolver-utils";
+import type { PipelineCtx } from "../types/step";
+
+const dummyCtx = {} as unknown as PipelineCtx;
+
+describe("resolveRequired", () => {
+  it("returns a static value as-is", () => {
+    expect(resolveRequired("hello", dummyCtx)).toBe("hello");
+    expect(resolveRequired(42, dummyCtx)).toBe(42);
+    expect(resolveRequired(null, dummyCtx)).toBeNull();
+    expect(resolveRequired({ key: "val" }, dummyCtx)).toEqual({ key: "val" });
+  });
+
+  it("calls a function resolver with the ctx and returns its result", () => {
+    const fn = vi.fn((_ctx: PipelineCtx) => "from-fn");
+    expect(resolveRequired(fn, dummyCtx)).toBe("from-fn");
+    expect(fn).toHaveBeenCalledOnce();
+    expect(fn).toHaveBeenCalledWith(dummyCtx);
+  });
+
+  it("passes the full ctx to the resolver function", () => {
+    const ctx = { event: { type: "test" }, steps: { x: 1 }, scope: {} } as unknown as PipelineCtx;
+    const fn = vi.fn((c: PipelineCtx) => c.event.type);
+    expect(resolveRequired(fn, ctx)).toBe("test");
+  });
+});
+
+describe("resolveOptional", () => {
+  it("returns the static value when defined", () => {
+    expect(resolveOptional("hello", dummyCtx)).toBe("hello");
+    expect(resolveOptional(0, dummyCtx)).toBe(0);
+    expect(resolveOptional(false, dummyCtx)).toBe(false);
+    expect(resolveOptional("", dummyCtx)).toBe("");
+  });
+
+  it("returns undefined when arg is undefined", () => {
+    expect(resolveOptional(undefined, dummyCtx)).toBeUndefined();
+  });
+
+  it("calls a function resolver when defined", () => {
+    const fn = vi.fn(() => "resolved");
+    expect(resolveOptional(fn, dummyCtx)).toBe("resolved");
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it("returns undefined for undefined function resolver", () => {
+    expect(resolveOptional(undefined, dummyCtx)).toBeUndefined();
+  });
+});

package/src/engine/__tests__/steps-unsafe-projection-delete.test.ts

@@ -0,0 +1,69 @@
+import type { SQL } from "drizzle-orm";
+import { pgTable, text, uuid } from "drizzle-orm/pg-core";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getStep } from "../define-step";
+import { buildUnsafeProjectionDeleteStep } from "../steps/unsafe-projection-delete";
+import type { PipelineCtx } from "../types/step";
+
+const testTable = pgTable("test_projection", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenantId: uuid("tenant_id").notNull(),
+  label: text("label"),
+});
+
+const mockDb = { delete: vi.fn() };
+const mockDeleteBuilder = { where: vi.fn() };
+
+const mockCtx = {
+  db: mockDb,
+  event: { type: "test", payload: {} },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
+describe("buildUnsafeProjectionDeleteStep", () => {
+  it("returns a StepInstance with kind unsafeProjectionDelete", () => {
+    const step = buildUnsafeProjectionDeleteStep({
+      table: testTable,
+      where: () => undefined as unknown as SQL,
+    });
+    expect(step.kind).toBe("unsafeProjectionDelete");
+    expect(step.args).toMatchObject({ table: testTable });
+  });
+
+  it("accepts a static SQL where clause", () => {
+    const step = buildUnsafeProjectionDeleteStep({
+      table: testTable,
+      where: undefined as unknown as SQL,
+    });
+    expect(step.args).toHaveProperty("table");
+  });
+});
+
+describe("unsafeProjectionDelete run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb.delete.mockReturnValue(mockDeleteBuilder);
+  });
+
+  it("calls db.delete().where() with the resolved where clause", async () => {
+    const stepDef = getStep("unsafeProjectionDelete");
+    expect(stepDef).toBeDefined();
+
+    const whereClause = "fake sql" as unknown as SQL;
+    await stepDef!.run({ table: testTable, where: whereClause }, mockCtx);
+
+    expect(mockDb.delete).toHaveBeenCalledOnce();
+    expect(mockDeleteBuilder.where).toHaveBeenCalledWith(whereClause);
+  });
+
+  it("resolves a function where-clause before calling delete", async () => {
+    const stepDef = getStep("unsafeProjectionDelete");
+
+    const whereFn = vi.fn(() => "dynamic where" as unknown as SQL);
+    await stepDef!.run({ table: testTable, where: whereFn }, mockCtx);
+
+    expect(whereFn).toHaveBeenCalledWith(mockCtx);
+    expect(mockDeleteBuilder.where).toHaveBeenCalledWith("dynamic where");
+  });
+});

package/src/engine/__tests__/steps-unsafe-projection-upsert.test.ts

@@ -0,0 +1,117 @@
+import { pgTable, text, uuid } from "drizzle-orm/pg-core";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getStep } from "../define-step";
+import { buildUnsafeProjectionUpsertStep } from "../steps/unsafe-projection-upsert";
+import type { PipelineCtx } from "../types/step";
+
+const testTable = pgTable("test_projection", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenantId: uuid("tenant_id").notNull(),
+  externalId: text("external_id").notNull().unique(),
+  label: text("label"),
+});
+
+const mockConflictBuilder = { onConflictDoUpdate: vi.fn() };
+const mockValuesBuilder = { values: vi.fn(() => mockConflictBuilder) };
+const mockDb = { insert: vi.fn(() => mockValuesBuilder) };
+
+const mockCtx = {
+  db: mockDb,
+  event: { type: "test", payload: {} },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
+describe("buildUnsafeProjectionUpsertStep", () => {
+  it("returns a StepInstance with kind unsafeProjectionUpsert", () => {
+    const step = buildUnsafeProjectionUpsertStep({
+      table: testTable,
+      on: ["externalId"],
+      row: { tenantId: "t1", externalId: "e1", label: "hello" },
+    });
+    expect(step.kind).toBe("unsafeProjectionUpsert");
+    expect(step.args).toMatchObject({
+      table: testTable,
+      on: ["externalId"],
+    });
+  });
+
+  it("accepts a static row resolver", () => {
+    const step = buildUnsafeProjectionUpsertStep({
+      table: testTable,
+      on: ["externalId"],
+      row: { tenantId: "t1", externalId: "e1" },
+    });
+    expect((step.args as { row: unknown }).row).toEqual({ tenantId: "t1", externalId: "e1" });
+  });
+
+  it("accepts a function row resolver", () => {
+    const resolver = vi.fn(() => ({ tenantId: "t1", externalId: "e1" }));
+    const step = buildUnsafeProjectionUpsertStep({
+      table: testTable,
+      on: ["externalId"],
+      row: resolver,
+    });
+    expect(typeof (step.args as { row: unknown }).row).toBe("function");
+  });
+
+  it("accepts multiple conflict key columns", () => {
+    const step = buildUnsafeProjectionUpsertStep({
+      table: testTable,
+      on: ["tenantId", "externalId"],
+      row: { tenantId: "t1", externalId: "e1" },
+    });
+    expect((step.args as { on: string[] }).on).toEqual(["tenantId", "externalId"]);
+  });
+});
+
+describe("unsafeProjectionUpsert run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("throws when a conflict-key column does not exist on the table", async () => {
+    const stepDef = getStep("unsafeProjectionUpsert");
+    expect(stepDef).toBeDefined();
+
+    await expect(
+      stepDef!.run(
+        {
+          table: testTable,
+          on: ["nonExistentColumn"],
+          row: { tenantId: "t1" },
+        },
+        mockCtx,
+      ),
+    ).rejects.toThrow(/column "nonExistentColumn" not found/);
+  });
+
+  it("builds conflict targets from the `on` keys and excludes them from updateSet", async () => {
+    const stepDef = getStep("unsafeProjectionUpsert");
+    const row = { tenantId: "t1", externalId: "e1", label: "hello" };
+
+    await stepDef!.run({ table: testTable, on: ["externalId"], row }, mockCtx);
+
+    expect(mockDb.insert).toHaveBeenCalledOnce();
+    expect(mockConflictBuilder.onConflictDoUpdate).toHaveBeenCalledOnce();
+
+    const conflictArgs = mockConflictBuilder.onConflictDoUpdate.mock.calls[0]![0]!;
+    expect(conflictArgs.set).toEqual({ tenantId: "t1", label: "hello" });
+  });
+
+  it("calls insert().onConflictDoUpdate with the resolved row and conflict targets", async () => {
+    const stepDef = getStep("unsafeProjectionUpsert");
+
+    await stepDef!.run(
+      {
+        table: testTable,
+        on: ["externalId"],
+        row: { tenantId: "t1", externalId: "e1", label: "hi" },
+      },
+      mockCtx,
+    );
+
+    expect(mockDb.insert).toHaveBeenCalled();
+    expect(mockConflictBuilder.onConflictDoUpdate).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,135 @@
+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 { buildWebhookSendStep } from "../steps/webhook-send";
+import type { PipelineCtx } from "../types/step";
+
+const mockUnsafeAppendEvent = vi.fn();
+
+const mockCtx = {
+  unsafeAppendEvent: mockUnsafeAppendEvent,
+  event: { type: "test", payload: { url: "https://hooks.example/test" } },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
+describe("buildWebhookSendStep", () => {
+  it("returns a StepInstance with kind webhook.send", () => {
+    const step = buildWebhookSendStep({
+      url: "https://hooks.example/test",
+      mode: "deferred",
+    });
+    expect(step.kind).toBe("webhook.send");
+  });
+
+  it("requires mode to be deferred", () => {
+    const step = buildWebhookSendStep({
+      url: "https://hooks.example/test",
+      mode: "deferred",
+    });
+    expect((step.args as { mode: string }).mode).toBe("deferred");
+  });
+
+  it("accepts optional method, headers, body, auth, retry", () => {
+    const step = buildWebhookSendStep({
+      url: "https://hooks.example/test",
+      method: "PUT",
+      headers: { "X-Custom": "val" },
+      body: { event: "test" },
+      auth: { kind: "bearer", secretRef: "MY_SECRET" },
+      retry: { times: 5, backoff: "linear" },
+      mode: "deferred",
+    });
+    expect((step.args as { method: string }).method).toBe("PUT");
+    expect((step.args as { retry: { times: number } }).retry.times).toBe(5);
+  });
+});
+
+describe("webhook.send run", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("appends a step.dispatch-requested system event with the webhook spec", async () => {
+    const stepDef = getStep("webhook.send");
+    expect(stepDef).toBeDefined();
+
+    await stepDef!.run(
+      {
+        url: "https://hooks.example/test",
+        mode: "deferred",
+        method: "POST",
+        body: { event: "incident-opened", id: "abc" },
+      },
+      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("webhook.send");
+    expect(eventArg.payload.spec.url).toBe("https://hooks.example/test");
+    expect(eventArg.payload.spec.body).toEqual({ event: "incident-opened", id: "abc" });
+  });
+
+  it("resolves function-based url and body resolvers", async () => {
+    const stepDef = getStep("webhook.send");
+    const urlFn = vi.fn(() => "https://hooks.example/dynamic");
+    const bodyFn = vi.fn(() => ({ key: "value" }));
+
+    await stepDef!.run(
+      {
+        url: urlFn,
+        mode: "deferred",
+        body: bodyFn,
+      },
+      mockCtx,
+    );
+
+    expect(urlFn).toHaveBeenCalledWith(mockCtx);
+    expect(bodyFn).toHaveBeenCalledWith(mockCtx);
+    expect(mockUnsafeAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        payload: expect.objectContaining({
+          spec: expect.objectContaining({
+            url: "https://hooks.example/dynamic",
+            body: { key: "value" },
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("defaults method to POST when not specified", async () => {
+    const stepDef = getStep("webhook.send");
+
+    await stepDef!.run({ url: "https://hooks.example/test", mode: "deferred" }, mockCtx);
+
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect(eventArg.payload.spec.method).toBe("POST");
+  });
+
+  it("defaults retry to 3x exponential when not specified", async () => {
+    const stepDef = getStep("webhook.send");
+
+    await stepDef!.run({ url: "https://hooks.example/test", mode: "deferred" }, mockCtx);
+
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect(eventArg.payload.retry).toEqual({ times: 3, backoff: "exponential" });
+  });
+
+  it("passes auth config through when provided", async () => {
+    const stepDef = getStep("webhook.send");
+    const auth = { kind: "bearer" as const, secretRef: "WEBHOOK_TOKEN" };
+
+    await stepDef!.run({ url: "https://hooks.example/secured", mode: "deferred", auth }, mockCtx);
+
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect(eventArg.payload.spec.auth).toEqual(auth);
+  });
+});