@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/agents/examples/custom-handlers.md

@@ -0,0 +1,444 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/custom-handlers. Do not edit. -->
+
+# custom-handlers
+
+Beyond CRUD — when your domain refuses to fit a table.
+
+## README
+
+# Custom handlers
+
+Replace the default CRUD with handler bodies that carry business rules.
+This recipe ships a `counter` entity with three custom write handlers
+(create, increment with read-modify-write, reset with last-writer-wins)
+plus a custom query that filters the projection.
+
+The point is to show the **boundary**: where the entity executor stops
+doing work for you and where your code has to take over. The framework
+gives you `createEntityExecutor` so the executor's `create` / `update` /
+`detail` / `list` are still one-liners — only the surrounding business
+logic is yours.
+
+## What it shows
+
+- **`r.writeHandler(name, schema, handler, options)`** — the positional
+  inline form, useful when the handler body is short and stays close to
+  its registration.
+- **Read-modify-write with optimistic locking** — `increment` reads the
+  current count, computes the new one, and updates with the version it
+  read. Two concurrent increments cannot both succeed.
+- **`skipOptimisticLock` for last-writer-wins** — `reset` deliberately
+  bypasses the version check because the operation is admin-driven and
+  resetting twice is semantically the same as resetting once.
+- **Custom queries** — `counter:active` passes a server-side `filter`
+  (`eq`/`ne`/`lt`/`gt`/`lte`/`gte`/`in`) and `totalCount` to the executor's
+  list. Never filter a page in TypeScript: list is paginated, so rows after
+  the first page would be missed.
+- **`failNotFound` helper** — typed error response for the 404 case
+  without a hand-built `KumikoError` subclass.
+
+## When to reach for it
+
+You have an entity but the default CRUD doesn't capture what your
+business rule actually does. The default `update` blindly writes the
+payload; your `increment` needs to read first, decide, and write. That's
+the line.
+
+## Source
+
+The whole feature lives in `src/feature.ts` (~100 lines). Integration
+tests cover the optimistic-lock case, the skip-lock case, and the
+custom-filter query.
+
+```bash
+bun kumiko test integration samples/custom-handlers
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Custom Handlers Sample — Integration Test
+// Proves: custom business logic in handlers, payload transformation, custom queries
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { counterEntity, counterFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+const user = createTestUser({ id: 2, roles: ["User"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [counterFeature] });
+  await unsafeCreateEntityTable(stack.db, counterEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  stack.events.reset();
+});
+
+describe("custom write handler: increment", () => {
+  test("increment adds to existing count", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "page-views",
+      },
+      admin,
+    );
+    expect(created.data["count"]).toBe(0);
+
+    const incremented = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 5,
+      },
+      user,
+    );
+
+    expect(incremented.data["count"]).toBe(5);
+    expect(incremented.data["lastIncrementedBy"]).toBe(`user:${user.id}`);
+  });
+
+  test("multiple increments accumulate", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "clicks",
+      },
+      admin,
+    );
+
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 3,
+      },
+      user,
+    );
+    const result = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 7,
+      },
+      user,
+    );
+
+    expect(result.data["count"]).toBe(10);
+  });
+
+  test("increment validates max amount", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "guarded",
+      },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 101,
+      },
+      user,
+    );
+    expectErrorIncludes(error, "validation");
+  });
+
+  test("increment on non-existent returns error", async () => {
+    const error = await stack.http.writeErr(
+      "counters:write:counter:increment",
+      {
+        id: "00000000-0000-4000-8000-000000000999",
+        amount: 1,
+      },
+      user,
+    );
+    expect(error.code).toBe("not_found");
+  });
+});
+
+describe("custom write handler: reset", () => {
+  test("reset sets count back to zero", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "resettable",
+      },
+      admin,
+    );
+
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 42,
+      },
+      user,
+    );
+
+    const reset = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:reset",
+      {
+        id: created.id,
+      },
+      admin,
+    );
+
+    expect(reset.data["count"]).toBe(0);
+    expect(reset.data["lastIncrementedBy"]).toBe("");
+  });
+
+  test("only Admin can reset", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "admin-only-reset",
+      },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(
+      "counters:write:counter:reset",
+      {
+        id: created.id,
+      },
+      user,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+});
+
+describe("custom query handler: active counters", () => {
+  // Own tenants: the total assertions would otherwise count counters created by other tests.
+  const activeAdmin = createTestUser({ roles: ["Admin"], tenantId: testTenantId(11) });
+  const activeUser = createTestUser({ id: 2, roles: ["User"], tenantId: testTenantId(11) });
+  const otherAdmin = createTestUser({ roles: ["Admin"], tenantId: testTenantId(12) });
+
+  test("filters counters by minimum count", async () => {
+    const c1 = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      { name: "active-a" },
+      activeAdmin,
+    );
+    const c2 = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      { name: "active-b" },
+      activeAdmin,
+    );
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      { name: "inactive" },
+      activeAdmin,
+    );
+
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      { id: c1.id, amount: 10 },
+      activeUser,
+    );
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      { id: c2.id, amount: 5 },
+      activeUser,
+    );
+
+    const result = await stack.http.queryOk<{
+      rows: Record<string, unknown>[];
+      nextCursor: string | null;
+      total?: number;
+    }>("counters:query:counter:active", { minCount: 5 }, activeAdmin);
+
+    const names = result.rows.map((r) => r["name"]);
+    expect(names).toContain("active-a");
+    expect(names).toContain("active-b");
+    expect(names).not.toContain("inactive");
+    expect(result.total).toBe(2);
+  });
+
+  test("total and nextCursor describe the full filtered set", async () => {
+    for (const name of ["total-a", "total-b", "total-c"]) {
+      const created = await stack.http.writeOk<SaveContext>(
+        "counters:write:counter:create",
+        { name },
+        otherAdmin,
+      );
+      await stack.http.writeOk<SaveContext>(
+        "counters:write:counter:increment",
+        { id: created.id, amount: 1 },
+        otherAdmin,
+      );
+    }
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      { name: "total-untouched" },
+      otherAdmin,
+    );
+
+    const result = await stack.http.queryOk<{
+      rows: Record<string, unknown>[];
+      nextCursor: string | null;
+      total?: number;
+    }>("counters:query:counter:active", { minCount: 1 }, otherAdmin);
+
+    expect(result.rows).toHaveLength(3);
+    expect(result.total).toBe(3);
+    expect(result.nextCursor).toBeNull();
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Custom Handlers Sample
+// Shows: writeHandler with business logic, queryHandler with a server-side filter,
+// handler that modifies payload before DB write.
+
+import {
+  createEntity,
+  createEntityExecutor,
+  createNumberField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+// detail() returns an untyped row; parse the two fields the increment needs once.
+const counterVersionRowSchema = z.object({ count: z.number(), version: z.number() });
+
+export const counterEntity = createEntity({
+  table: "read_sample_counters",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    count: createNumberField({ default: 0 }),
+    lastIncrementedBy: createTextField({ personal: "ref" }),
+  },
+});
+
+export const counterFeature = defineFeature("counters", (r) => {
+  r.entity("counter", counterEntity);
+
+  // createEntityExecutor bundles buildEntityTable + createEventStoreExecutor —
+  // the same pair every custom write-handler opens with. Collapses 3 lines
+  // + the { entityName } bookkeeping into one destructure.
+  const { executor: counterExecutor } = createEntityExecutor("counter", counterEntity);
+
+  // Standard create
+  r.writeHandler(
+    "counter:create",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) =>
+      counterExecutor.create({ ...event.payload, count: 0 }, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Custom handler: increment with business logic
+  r.writeHandler(
+    "counter:increment",
+    z.object({ id: z.uuid(), amount: z.number().min(1).max(100) }),
+    async (event, ctx) => {
+      const current = await counterExecutor.detail({ id: event.payload.id }, event.user, ctx.db);
+      if (!current) {
+        return failNotFound("counter", event.payload.id);
+      }
+
+      const { count, version } = counterVersionRowSchema.parse(current);
+      const newCount = count + event.payload.amount;
+      // Read-modify-write on counter: use the version we just read so two
+      // concurrent increments don't clobber each other's changes.
+      return counterExecutor.update(
+        {
+          id: event.payload.id,
+          version,
+          changes: { count: newCount, lastIncrementedBy: `user:${event.user.id}` },
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+    { access: { roles: ["Admin", "User"] } },
+  );
+
+  // Custom handler: reset to zero
+  r.writeHandler(
+    "counter:reset",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) =>
+      // Admin reset: last-writer-wins is intentional — there's no useful
+      // concurrent-reset race to guard against.
+      counterExecutor.update(
+        { id: event.payload.id, changes: { count: 0, lastIncrementedBy: "" } },
+        event.user,
+        ctx.db,
+        { skipOptimisticLock: true },
+      ),
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Custom query: only counters above a threshold. list() returns one page
+  // (default 50, max 200, MAX_LIST_LIMIT), so a JS filter would miss rows after
+  // page 1; filter in the query instead. totalCount counts over the whole WHERE.
+  r.queryHandler(
+    "counter:active",
+    z.object({ minCount: z.number().int().default(1), cursor: z.string().optional() }),
+    async (query, ctx) =>
+      counterExecutor.list(
+        {
+          filter: { field: "count", op: "gte", value: query.payload.minCount },
+          totalCount: true,
+          cursor: query.payload.cursor,
+        },
+        query.user,
+        ctx.db,
+      ),
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in user may list active counters; the sample has no per-user counter ownership",
+        },
+      },
+    },
+  );
+
+  // Standard detail
+  r.queryHandler(
+    "counter:detail",
+    z.object({ id: z.uuid() }),
+    async (query, ctx) => counterExecutor.detail(query.payload, query.user, ctx.db),
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in user may read a counter by id; the sample has no per-user counter ownership",
+        },
+      },
+    },
+  );
+});
+```

package/agents/examples/dashboard-stats.md

@@ -0,0 +1,229 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/dashboard-stats. Do not edit. -->
+
+# dashboard-stats
+
+Key figures on a dashboard: stat panels backed by one counting query.
+
+## README
+
+# Dashboard stats
+
+Key figures on a dashboard. This recipe ships a `ticket` entity, one query
+handler that returns the figures as a flat object, and a `dashboard` screen
+with a stat group (open, closed) and a single stat (total).
+
+The point is to show how the three pieces connect: the screen only names a
+query and the fields to read, the query does the counting.
+
+## What it shows
+
+- **Panels reference a query by qualified name**: each `stat` carries
+  `query: "tickets:query:ticket:stats"`. The dashboard calls that handler and
+  renders the result.
+- **`valueField` picks a field from a flat result**: the handler returns
+  `{ open, closed, total }`, and each stat names one of those keys.
+- **`stat-group` and `stat`**: a group shows several stats side by side under
+  one title, a top-level `stat` stands alone.
+- **Counting happens in the database**: the handler calls the executor's
+  `list` with `filter`, `limit: 1` and `totalCount: true`. The total is counted
+  over the whole WHERE clause, so no rows are loaded just to be counted.
+- **Labels are translation keys**: declared with `r.translations`.
+
+## When to reach for it
+
+You want a landing screen with a few numbers: open items, overdue invoices,
+this month's revenue. Write one query per screen that returns every figure,
+and let the stats pick their field.
+
+## Source
+
+The whole feature lives in `src/feature.ts` (~100 lines). The integration test
+checks that every stat reads a field the query returns, and that the query
+counts open and closed tickets correctly.
+
+```bash
+bun kumiko test integration samples/dashboard-stats
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Dashboard Stats Sample, integration test.
+// Proves: the dashboard screen boots, its panels point at a registered query,
+// and that query counts per status in the database.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { TICKET_STATS_QUERY, ticketEntity, ticketFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = createTestUser({ roles: ["Admin"], tenantId: testTenantId(31) });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [ticketFeature] });
+  await unsafeCreateEntityTable(stack.db, ticketEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("dashboard screen", () => {
+  test("boots, and every stat reads a field the stats query returns", async () => {
+    const screen = ticketFeature.screens["ticket-dashboard"];
+    if (screen?.type !== "dashboard") throw new Error("ticket-dashboard is not a dashboard screen");
+
+    const stats = screen.panels.flatMap((panel) =>
+      panel.kind === "stat-group" ? panel.stats : panel.kind === "stat" ? [panel] : [],
+    );
+    expect(stats.map((s) => s.valueField)).toEqual(["open", "closed", "total"]);
+    for (const stat of stats) expect(stat.query).toBe(TICKET_STATS_QUERY);
+
+    const result = await stack.http.queryOk<Record<string, unknown>>(TICKET_STATS_QUERY, {}, admin);
+    for (const stat of stats) expect(result).toHaveProperty(stat.valueField);
+  });
+});
+
+describe("ticket:stats", () => {
+  test("counts open and closed tickets in the database", async () => {
+    for (const [title, status] of [
+      ["a", "open"],
+      ["b", "open"],
+      ["c", "open"],
+      ["d", "closed"],
+      ["e", "closed"],
+    ] as const) {
+      await stack.http.writeOk<SaveContext>(
+        "tickets:write:ticket:create",
+        { title, status },
+        admin,
+      );
+    }
+
+    const result = await stack.http.queryOk<Record<string, unknown>>(TICKET_STATS_QUERY, {}, admin);
+
+    expect(result).toEqual({ open: 3, closed: 2, total: 5 });
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Dashboard Stats Sample
+// Shows: a dashboard screen with a stat-group and a single stat, backed by one
+// query handler that counts in the database.
+
+import {
+  createEntity,
+  createEntityExecutor,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const TICKET_STATUSES = ["open", "closed"] as const;
+
+export const ticketEntity = createEntity({
+  table: "read_sample_tickets",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    status: createSelectField({ options: TICKET_STATUSES, default: "open", required: true }),
+  },
+});
+
+export const TICKET_STATS_QUERY = "tickets:query:ticket:stats";
+
+const readerRoles = { roles: ["Admin", "User"] } as const;
+
+export const ticketFeature = defineFeature("tickets", (r) => {
+  const { executor: ticketExecutor } = createEntityExecutor("ticket", ticketEntity);
+
+  r.crud("ticket", ticketEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: readerRoles },
+  });
+
+  // Flat result: each dashboard stat reads one field via its valueField.
+  // limit: 1 keeps the page tiny; totalCount counts over the whole WHERE in
+  // the database, so no rows are loaded just to be counted.
+  r.queryHandler(
+    "ticket:stats",
+    z.object({}),
+    async (query, ctx) => {
+      const countWithStatus = async (status: (typeof TICKET_STATUSES)[number]): Promise<number> => {
+        const page = await ticketExecutor.list(
+          { filter: { field: "status", op: "eq", value: status }, limit: 1, totalCount: true },
+          query.user,
+          ctx.db,
+        );
+        return page.total ?? 0;
+      };
+      const [open, closed] = await Promise.all([
+        countWithStatus("open"),
+        countWithStatus("closed"),
+      ]);
+      return { open, closed, total: open + closed };
+    },
+    { access: readerRoles },
+  );
+
+  r.translations({
+    keys: {
+      "tickets.dashboard.group": { en: "Tickets by status" },
+      "tickets.dashboard.open": { en: "Open" },
+      "tickets.dashboard.closed": { en: "Closed" },
+      "tickets.dashboard.total": { en: "All tickets" },
+    },
+  });
+
+  r.screen({
+    id: "ticket-dashboard",
+    type: "dashboard",
+    panels: [
+      {
+        kind: "stat-group",
+        id: "by-status",
+        label: "tickets.dashboard.group",
+        stats: [
+          {
+            kind: "stat",
+            id: "open",
+            label: "tickets.dashboard.open",
+            query: TICKET_STATS_QUERY,
+            valueField: "open",
+          },
+          {
+            kind: "stat",
+            id: "closed",
+            label: "tickets.dashboard.closed",
+            query: TICKET_STATS_QUERY,
+            valueField: "closed",
+          },
+        ],
+      },
+      {
+        kind: "stat",
+        id: "total",
+        label: "tickets.dashboard.total",
+        query: TICKET_STATS_QUERY,
+        valueField: "total",
+      },
+    ],
+    access: readerRoles,
+  });
+});
+```