@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

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>[];
 }