@cosmicdrift/kumiko-samples 0.364.0 → 0.365.1

package/samples/recipes/dashboard-stats/README.md

@@ -0,0 +1,38 @@
+# 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
+```

package/samples/recipes/dashboard-stats/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-dashboard-stats",
+  "description": "Key figures on a dashboard: stat panels backed by one counting query.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/dashboard-stats/src/feature.ts

@@ -0,0 +1,104 @@
+// 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,
+  });
+});

package/samples/recipes/legal-pages/README.md

@@ -87,8 +87,8 @@ imprint" decision.
 
 ```bash
 # In the app workspace:
-bun kumiko-schema generate <name>    # detects text-block entity → SQL migration
-bun kumiko-schema apply       # one-time (pre-deploy step in prod)
+bunx kumiko-schema generate <name>    # detects text-block entity → SQL migration
+bunx kumiko-schema apply       # one-time (pre-deploy step in prod)
 ```
 
 ### 3. Initial seed of the required blocks

package/samples/recipes/managed-pages/README.md

@@ -81,8 +81,8 @@ the recipe lists `createConfigFeature()` explicitly (see `src/feature.ts`).
 ### 2. Create the table
 
 ```bash
-bun kumiko-schema generate <name>    # detects the `page` entity → SQL migration
-bun kumiko-schema apply
+bunx kumiko-schema generate <name>    # detects the `page` entity → SQL migration
+bunx kumiko-schema apply
 ```
 
 ### 3. Authoring + branding

package/samples/recipes/pdf-audit-export/README.md

@@ -5,7 +5,8 @@ A write handler exports tenant data as a PDF and keeps it as a FileRef.
 ## What it shows
 
 - `renderTablePdf` (`@cosmicdrift/kumiko-bundled-features/renderer-pdf`) draws a table document in pure JavaScript: repeating header, weighted columns, page footer. The handler passes ready-formatted strings.
-- `createFileRefFromBytes` (`@cosmicdrift/kumiko-framework/files`) stores the bytes like an upload (validation, tenant-prefixed storage key, `fileRef.created` event); the tenant comes from the caller.
+- The export is a `beforeTransaction` handler: it reads the rows (reads work in that phase), renders the PDF and calls `uploadFileBytesBeforeTransaction` (`@cosmicdrift/kumiko-framework/files`), which validates the bytes and writes them to the tenant-prefixed storage key. The upload runs before the transaction because storage I/O inside it would hold a pool connection for as long as the upload takes.
+- The handler itself calls `createFileRefFromUploadedBytes(ctx, event.prepared)` and creates the `file_refs` row and the `fileRef.created` event in the transaction. If the transaction does not commit, the phase's `release` deletes the uploaded bytes again (only when no row exists for the storage key). A crash between upload and commit leaves the bytes in storage; nothing sweeps them.
 - The result is a normal FileRef: `GET /api/files/:id` serves it with `Content-Type: application/pdf`, other tenants get 404.
 
 ## Source

package/samples/recipes/pdf-audit-export/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-sample-pdf-audit-export",
-  "description": "Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and stores the bytes as a FileRef via createFileRefFromBytes.",
+  "description": "Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and uploads the bytes before the transaction (uploadFileBytesBeforeTransaction) and stores them as a FileRef (createFileRefFromUploadedBytes).",
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",

package/samples/recipes/pdf-audit-export/src/feature.ts

@@ -1,9 +1,10 @@
 // PDF Audit Export Sample
 //
 // A write handler turns tenant data into a PDF and keeps it as a regular
-// FileRef: renderTablePdf draws the table (pure JS, no browser), then
-// createFileRefFromBytes stores the bytes through the same validation,
-// storage layout and fileRef.created event as an upload.
+// FileRef: renderTablePdf draws the table (pure JS, no browser). The storage
+// write runs in the beforeTransaction phase, so the transaction holds no pool
+// connection while the bytes upload; the handler then only creates the
+// fileRef row from event.prepared.
 
 import { renderTablePdf } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
 import {
@@ -13,8 +14,13 @@ import {
   createSelectField,
   createTextField,
   defineFeature,
+  defineWriteHandler,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { createFileRefFromBytes } from "@cosmicdrift/kumiko-framework/files";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  createFileRefFromUploadedBytes,
+  uploadFileBytesBeforeTransaction,
+} from "@cosmicdrift/kumiko-framework/files";
 import * as z from "zod";
 
 export const INSPECTION_RESULTS = ["ok", "defect"] as const;
@@ -44,7 +50,8 @@ function toFileNameSegment(text: string): string {
   return text.replaceAll(/[^A-Za-z0-9_-]+/g, "-");
 }
 
-const AUDIT_ROW_LIMIT = 200;
+// One row above the limit tells "exactly full" from "cut off"; entity lists cap at 200 rows.
+const AUDIT_ROW_LIMIT = 100;
 
 const access = { access: { roles: ["Admin", "User"] } } as const;
 
@@ -65,50 +72,63 @@ export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
   );
 
   r.writeHandler(
-    "export-audit",
-    z.object({ assetName: z.string().min(1), from: z.iso.date(), to: z.iso.date() }),
-    async (event, ctx) => {
-      const { assetName, from, to } = event.payload;
-      const inspections = await inspectionExecutor.list(
-        {
-          filters: [
-            { field: "assetName", op: "eq", value: assetName },
-            { field: "inspectedOn", op: "gte", value: from },
-            { field: "inspectedOn", op: "lte", value: to },
-          ],
-          sort: "inspectedOn",
-          sortDirection: "asc",
-          limit: AUDIT_ROW_LIMIT,
-        },
-        event.user,
-        ctx.db,
-      );
+    defineWriteHandler({
+      name: "export-audit",
+      schema: z.object({ assetName: z.string().min(1), from: z.iso.date(), to: z.iso.date() }),
+      access: access.access,
+      beforeTransaction: async (event, ctx) => {
+        const { assetName, from, to } = event.payload;
+        const inspections = await inspectionExecutor.list(
+          {
+            filters: [
+              { field: "assetName", op: "eq", value: assetName },
+              { field: "inspectedOn", op: "gte", value: from },
+              { field: "inspectedOn", op: "lte", value: to },
+            ],
+            sort: "inspectedOn",
+            sortDirection: "asc",
+            limit: AUDIT_ROW_LIMIT + 1,
+          },
+          event.user,
+          ctx.db,
+        );
+        // A protocol that silently drops inspections would look complete.
+        if (inspections.rows.length > AUDIT_ROW_LIMIT) {
+          return writeFailure(
+            new UnprocessableError("audit_period_too_large", {
+              details: { limit: AUDIT_ROW_LIMIT },
+            }),
+          );
+        }
 
-      const { pdfBytes } = await renderTablePdf({
-        title: `Prüfprotokoll ${assetName}`,
-        meta: [
-          { label: "Zeitraum", value: `${formatGermanDate(from)} bis ${formatGermanDate(to)}` },
-          { label: "Prüfungen", value: String(inspections.rows.length) },
-        ],
-        columns: [{ header: "Datum" }, { header: "Ergebnis" }, { header: "Prüfer", weight: 2 }],
-        rows: inspections.rows.map((row) => [
-          formatGermanDate(String(row["inspectedOn"])),
-          RESULT_LABELS[z.enum(INSPECTION_RESULTS).parse(row["result"])],
-          String(row["inspector"] ?? ""),
-        ]),
-        emptyText: "Keine Prüfungen im Zeitraum",
-        footerText: `Prüfbericht ${assetName}`,
-        pageLabel: "Seite {page} von {pages}",
-      });
+        const { pdfBytes } = await renderTablePdf({
+          title: `Prüfprotokoll ${assetName}`,
+          meta: [
+            { label: "Zeitraum", value: `${formatGermanDate(from)} bis ${formatGermanDate(to)}` },
+            { label: "Prüfungen", value: String(inspections.rows.length) },
+          ],
+          columns: [{ header: "Datum" }, { header: "Ergebnis" }, { header: "Prüfer", weight: 2 }],
+          rows: inspections.rows.map((row) => [
+            formatGermanDate(String(row["inspectedOn"])),
+            RESULT_LABELS[z.enum(INSPECTION_RESULTS).parse(row["result"])],
+            String(row["inspector"] ?? ""),
+          ]),
+          emptyText: "Keine Prüfungen im Zeitraum",
+          footerText: `Prüfbericht ${assetName}`,
+          pageLabel: "Seite {page} von {pages}",
+        });
 
-      const created = await createFileRefFromBytes(ctx, {
-        fileName: `audit-${toFileNameSegment(assetName)}.pdf`,
-        mimeType: "application/pdf",
-        data: pdfBytes,
-      });
-      if (!created.isSuccess) return created;
-      return { isSuccess: true as const, data: { fileRefId: created.data.id } };
-    },
-    access,
+        return uploadFileBytesBeforeTransaction(ctx, {
+          fileName: `audit-${toFileNameSegment(assetName)}.pdf`,
+          mimeType: "application/pdf",
+          data: pdfBytes,
+        });
+      },
+      handler: async (event, ctx) => {
+        const created = await createFileRefFromUploadedBytes(ctx, event.prepared);
+        if (!created.isSuccess) return created;
+        return { isSuccess: true as const, data: { fileRefId: created.data.id } };
+      },
+    }),
   );
 });

package/samples/recipes/workflow-engine/src/db/queries/suspended-runs.ts

@@ -1,5 +1,5 @@
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { type DbRunner, toPostgresArrayLiteral } from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectExpiredSuspensionEvents(
   db: DbRunner,
@@ -9,6 +9,6 @@ export async function selectExpiredSuspensionEvents(
     `SELECT * FROM "kumiko_events"
        WHERE "type" = ANY($1::text[])
        AND (("payload"->>'wakeAt')::timestamptz < now() OR ("payload"->>'timeoutAt')::timestamptz < now())`,
-    [eventTypes as unknown as string[]],
+    [toPostgresArrayLiteral(eventTypes)],
   )) as Record<string, unknown>[];
 }