@cosmicdrift/kumiko-samples 0.387.0 → 0.389.0

package/samples/recipes/lifecycle-hooks/README.md

@@ -27,6 +27,10 @@ back.
 - **`r.hook({ type: "postDelete", target: { allOf: entityRef }, handler })`** — fires after commit.
   External side effects (logs, notifications) belong here because
   failures cannot roll the delete back.
+- **`ctx.scheduleAfterRollback(fn)`** — the counterpart of `scheduleAfterCommit`: runs `fn` when
+  the handler transaction (or the enclosing savepoint of a nested `ctx.write`) does not commit.
+  Use it to give back something reserved outside the transaction, like the slot in
+  `article:reserve-slot`. A failed COMMIT triggers it too, so write the callback idempotent.
 
 ## When to reach for it
 

package/samples/recipes/lifecycle-hooks/src/feature.ts

@@ -13,7 +13,12 @@ import {
   defineFeature,
   type SaveContext,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  ConflictError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
 
 export const articleEntity = createEntity({
   table: "read_sample_articles",
@@ -35,6 +40,9 @@ export const articleEntity = createEntity({
 // Collect hook events for testing
 export const hookLog: { type: string; data: Record<string, unknown> }[] = [];
 
+// Stands in for a quota held in an external system, outside the handler transaction.
+export const reservedSlots = new Set<string>();
+
 const editorWrite = { access: { roles: ["Admin", "Editor"] } } as const;
 
 export const articlesFeature = defineFeature("blog", (r) => {
@@ -48,6 +56,23 @@ export const articlesFeature = defineFeature("blog", (r) => {
   );
   r.writeHandler(defineEntityDeleteHandler("article", articleEntity, editorWrite));
 
+  // --- scheduleAfterRollback: give back a reservation made outside the transaction when it does
+  // not commit. The callback must be idempotent: a failed COMMIT also triggers it.
+  r.writeHandler({
+    name: "article:reserve-slot",
+    schema: z.object({ slot: z.string(), reject: z.boolean() }),
+    access: editorWrite.access,
+    handler: async (event, ctx) => {
+      const { slot, reject } = event.payload;
+      reservedSlots.add(slot);
+      ctx.scheduleAfterRollback?.(async () => {
+        reservedSlots.delete(slot);
+      });
+      if (reject) return writeFailure(new UnprocessableError("slot_rejected"));
+      return { isSuccess: true as const, data: {} };
+    },
+  });
+
   // --- Validation hook on create: reject banned words + length ---
   r.hook({
     type: "validation",

package/samples/recipes/list-table-options/README.md

@@ -0,0 +1,50 @@
+# List table options
+
+Opt-in table behaviour for entity, projection and related lists. A list without
+the `table` block renders and behaves as before.
+
+## What it shows
+
+- `table.rememberState`: search, sort, page size, facets and date range survive
+  leaving and re-entering the list within the browser session.
+- `table.resetAll`: one button resets everything that differs from the defaults.
+- `table.columnPicker`: the view menu lets the user hide and reorder columns;
+  `hidden: true` on a column starts it hidden.
+- `table.density`: row density default and an optional user choice.
+- `table.pinning`: the user pins columns left or right in the view menu;
+  `pinned: "left"` on a column starts it pinned.
+- `table.resizing`: columns can be resized (table-layout fixed); `width` and
+  `minWidth` on a column are start values in px.
+- `table.keyboardNavigation`: rows are one tab stop, arrow keys move between rows,
+  Space selects the focused row.
+- `table.export`: an Export button downloads the whole filtered list as an XLSX
+  file; `maxRows` lowers the default limit of 10000 rows.
+  Reference columns export their label and timestamps use the browser time zone.
+- `bulkActions`: row checkboxes and a selection bar. "Delete" runs the delete
+  row action once per selected row; done tasks are skipped.
+- `table.grouping`: the server groups the list by status; each header shows the
+  group's count and estimate sum, "done" starts collapsed and the view menu
+  offers grouping by priority or none.
+- `table.totals`: a footer row with the estimate sum over the filtered list.
+- `facets.estimateHours: { display: "range" }`: from/to inputs for a number field.
+- The same block on a `projectionList`, and `task:workload`, a hand-written list
+  query that keeps grouping and totals by accepting `aggregate`
+  (`entityListSchema`) and answering it with `answerListAggregate`.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/list-table-options
+bun test
+```
+
+The test boots the feature through the boot validator and checks that a
+misspelled key, a hidden column without the picker, an unknown density, a pinned column
+without `pinning`, a width without `resizing` and a bulk action on a navigate
+row action are rejected.
+`workload.integration.test.ts` runs the hand-written query over HTTP and checks
+the grouped sums and the filtered total.

package/samples/recipes/list-table-options/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-list-table-options",
+  "description": "Opt-in table behaviour of a list: remembered search/sort/filters, one reset button, column picker with hidden columns, row density, server-side groups with sums, a totals row and a number range facet.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
+  }
+}

package/samples/recipes/list-table-options/src/feature.ts

@@ -0,0 +1,221 @@
+import {
+  answerListAggregate,
+  buildEntityTable,
+  createEventStoreExecutor,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createDateField,
+  createEntity,
+  createNumberField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+  entityListSchema,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { ListTableOptions } from "@cosmicdrift/kumiko-framework/ui-types";
+import { z } from "zod";
+
+export const taskEntity = createEntity({
+  table: "read_list_table_tasks",
+  fields: {
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      searchable: true,
+      sortable: true,
+    }),
+    status: createSelectField({
+      options: ["open", "inProgress", "blocked", "done"] as const,
+      default: "open",
+      sortable: true,
+      filterable: true,
+    }),
+    priority: createSelectField({
+      options: ["low", "medium", "high"] as const,
+      default: "medium",
+      sortable: true,
+      filterable: true,
+    }),
+    dueDate: createDateField({ sortable: true }),
+    assignee: createTextField({ personal: false, reason: "is_business_data", sortable: true }),
+    estimateHours: createNumberField({ sortable: true, filterable: true }),
+  },
+});
+
+export const openAccess = {
+  access: {
+    openToAll: { reason: "recipe: any signed-in user manages the tasks; no per-user ownership" },
+  },
+} as const;
+
+// Overridable so a test can feed the boot validator a block that must be rejected.
+export function createTaskBoardFeature(
+  taskTable: ListTableOptions = {
+    rememberState: true,
+    resetAll: true,
+    columnPicker: true,
+    density: { default: "comfortable", userChoice: true },
+    pinning: true,
+    resizing: true,
+    keyboardNavigation: true,
+    export: { xlsx: true, maxRows: 5000 },
+    grouping: { field: "status", collapsedWhen: "done", userChoice: true, fields: ["priority"] },
+    totals: [{ field: "estimateHours", kind: "sum" }],
+  },
+): FeatureDefinition {
+  return defineFeature("task-board", (r) => {
+    r.crud("task", taskEntity, { write: openAccess, read: openAccess });
+
+    r.screen({
+      id: "task-list",
+      type: "entityList",
+      entity: "task",
+      columns: [
+        // Starts pinned left; width and minWidth are start values for resizing.
+        { field: "title", pinned: "left", width: 280, minWidth: 160 },
+        "status",
+        "priority",
+        { field: "dueDate", hideOnNarrow: true },
+        { field: "assignee", hideOnNarrow: true },
+        // Starts hidden; the user can add it back in the view menu.
+        { field: "estimateHours", hidden: true, hideOnNarrow: true },
+      ],
+      facets: { status: { display: "chips" }, priority: {}, estimateHours: { display: "range" } },
+      defaultSort: { field: "dueDate", dir: "asc" },
+      searchable: true,
+      table: taskTable,
+      rowActions: [
+        { kind: "navigate", id: "open", label: "Open", screen: "task-edit", rowClick: true },
+        {
+          kind: "writeHandler",
+          id: "delete",
+          label: "Delete",
+          handler: "task-board:write:task:delete",
+          style: "danger",
+          // Done tasks are skipped by the bulk run and counted as skipped.
+          visible: { field: "status", ne: "done" },
+        },
+      ],
+      // Row checkboxes and a selection bar; each selected row gets its own delete write.
+      bulkActions: [{ id: "delete", rowAction: "delete" }],
+      access: openAccess.access,
+    });
+
+    r.screen({
+      id: "task-edit",
+      type: "entityEdit",
+      entity: "task",
+      dormant: true,
+      listScreenId: "task-list",
+      layout: {
+        sections: [
+          {
+            columns: 2,
+            fields: ["title", "assignee", "status", "priority", "dueDate", "estimateHours"],
+          },
+        ],
+      },
+    });
+
+    // The same block works on a list over any query.
+    r.queryHandler({
+      name: "task:overdue",
+      schema: z.object({}),
+      handler: async () => ({
+        rows: [{ id: "t1", title: "Quarterly VAT filing", assignee: "Ines", daysLate: 3 }],
+        nextCursor: null,
+      }),
+      access: openAccess.access,
+      outputSchema: z.object({
+        rows: z.array(
+          z.object({
+            id: z.string(),
+            title: z.string(),
+            assignee: z.string(),
+            daysLate: z.number(),
+          }),
+        ),
+        nextCursor: z.string().nullable(),
+      }),
+    });
+
+    r.screen({
+      id: "task-overdue",
+      type: "projectionList",
+      query: "task-board:query:task:overdue",
+      columns: ["title", "assignee", "daysLate"],
+      table: { rememberState: true, density: { userChoice: true } },
+    });
+
+    // A hand-written list query keeps grouping and totals when it accepts
+    // `aggregate` (entityListSchema carries it) and answers it on the server.
+    const taskExecutor = createEventStoreExecutor(
+      buildEntityTable("task", taskEntity),
+      taskEntity,
+      {
+        entityName: "task",
+      },
+    );
+    r.queryHandler({
+      name: "task:workload",
+      schema: entityListSchema,
+      handler: async (query, ctx) => {
+        const parentVisibility = { entities: ctx.registry.getAllEntities() };
+        const listPayload = query.payload;
+        if (listPayload.aggregate !== undefined) {
+          return answerListAggregate(
+            taskExecutor,
+            { ...listPayload, aggregate: listPayload.aggregate },
+            query.user,
+            ctx.db,
+            { parentVisibility },
+            {
+              entity: taskEntity,
+              resolveEntity: (name) => ctx.registry.getEntity(name),
+              viewer: { user: query.user, parentVisibility },
+            },
+          );
+        }
+        return taskExecutor.list(listPayload, query.user, ctx.db, { parentVisibility });
+      },
+      access: openAccess.access,
+    });
+
+    r.screen({
+      id: "task-workload",
+      type: "projectionList",
+      query: "task-board:query:task:workload",
+      columns: ["title", "assignee", "status", "estimateHours"],
+      defaultSort: { field: "title", dir: "asc" },
+      table: {
+        grouping: { field: "assignee" },
+        totals: [{ field: "estimateHours", kind: "sum" }],
+      },
+    });
+
+    r.nav({ id: "tasks", label: "task-board:nav.tasks", icon: "list", order: 10 });
+    r.nav({
+      id: "task-list",
+      label: "task-board:nav.list",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-list",
+      order: 10,
+    });
+    r.nav({
+      id: "task-overdue",
+      label: "task-board:nav.overdue",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-overdue",
+      order: 20,
+    });
+    r.nav({
+      id: "task-workload",
+      label: "task-board:nav.workload",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-workload",
+      order: 30,
+    });
+  });
+}

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

@@ -15,6 +15,7 @@ import {
   createTextField,
   defineFeature,
   defineWriteHandler,
+  MAX_LIST_LIMIT,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import {
@@ -51,7 +52,7 @@ function toFileNameSegment(text: string): string {
 }
 
 // One row above the limit tells "exactly full" from "cut off"; entity lists cap at 200 rows.
-const AUDIT_ROW_LIMIT = 100;
+const AUDIT_ROW_LIMIT = MAX_LIST_LIMIT - 1;
 
 const access = { access: { roles: ["Admin", "User"] } } as const;
 

package/samples/recipes/rate-limiting/README.md

@@ -28,6 +28,24 @@ exhausted) and no bucket is charged. Each `per` may appear once; an empty list f
 An anonymous handler needs every bucket to be ip-keyed, and `{ disabled: true, reason }`
 stays a single declaration.
 
+## Cost per payload element
+
+A bulk handler books one token per item instead of one per request. Declare `rateLimitCost`
+next to `rateLimit`:
+
+```ts illustration
+r.writeHandler({
+  // ...
+  rateLimit: { per: "tenant+handler", limit: 20, windowSeconds: 600 },
+  rateLimitCost: (payload) => payload.files.length,
+});
+```
+
+The cost is computed from the validated payload and booked on every declared bucket, so an
+invalid payload costs nothing and a rejected request consumes nothing. Results below 1 count
+as 1. Because it books after the parse, boot rejects `rateLimitCost` on anonymous or ip-limited
+handlers.
+
 ## Per-payload limits
 
 A public write handler that mails an address typed by the caller is also limited per

package/samples/recipes/rate-limiting/src/feature.ts

@@ -33,5 +33,17 @@ export function createRateLimitShowcaseFeature(): FeatureDefinition {
         { per: "tenant+handler", limit: 3, windowSeconds: 3600 },
       ],
     });
+
+    // Bulk upload: a request books one token per item instead of one per request. The cost
+    // comes from the validated payload, so a schema-invalid request costs nothing; a request
+    // that would exceed the remaining budget is rejected and consumes nothing.
+    r.writeHandler({
+      name: "bulk-upload",
+      schema: z.object({ files: z.array(z.string()).min(1).max(20) }),
+      handler: async () => ({ isSuccess: true as const, data: {} }),
+      access: { roles: ["Admin", "User"] },
+      rateLimit: { per: "tenant+handler", limit: 20, windowSeconds: 600 },
+      rateLimitCost: (payload) => payload.files.length,
+    });
   });
 }

package/samples/recipes/state-machine/src/events.ts

@@ -5,6 +5,7 @@
 
 import type { EventDef } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { INVOICE_STATES } from "./entities/invoice.ts";
 
 export const FEATURE_NAME = "billing";
 export const ENTITY_NAME = "invoice";
@@ -36,8 +37,8 @@ export const INVOICE_CREATED_EVENT = `${ENTITY_NAME}.created` as const;
 
 export const emptyEventPayload = z.object({});
 export const statusForcedPayload = z.object({
-  newStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
-  fromStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
+  newStatus: z.enum(INVOICE_STATES),
+  fromStatus: z.enum(INVOICE_STATES),
 });
 
 // The EventDefs r.defineEvent returns inside the feature setup. Handlers receive them so that

package/samples/recipes/tenant-isolation/README.md

@@ -5,6 +5,7 @@ Multi-tenant data isolation by default.
 ## What it shows
 
 - Tenant filter on ordinary handlers
+- `ctx.db.upsert`: insert-or-update on a tenant-scoped, non-event-sourced table. `conflictTarget` must contain `tenantId` and match a declared unique index (here `tenant_id, key`); event-fed tables are rejected
 - What breaks if you forget tenancy (and how the framework prevents it)
 
 ## Source

package/samples/recipes/tenant-isolation/src/feature.ts

@@ -1,4 +1,6 @@
+import { defineUnmanagedTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
 
 export const noteEntity = createEntity({
   table: "read_sample_notes",
@@ -8,6 +10,26 @@ export const noteEntity = createEntity({
   },
 });
 
+// Not event-sourced: ctx.db.upsert rejects executor-managed tables.
+export const preferenceTable = defineUnmanagedTable({
+  tableName: "sample_tenant_preferences",
+  columns: [
+    {
+      name: "id",
+      pgType: "uuid",
+      notNull: true,
+      primaryKey: true,
+      defaultSql: "gen_random_uuid()",
+    },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "key", pgType: "text", notNull: true },
+    { name: "value", pgType: "text", notNull: true },
+  ],
+  indexes: [
+    { name: "sample_tenant_preferences_tenant_key", columns: ["tenant_id", "key"], unique: true },
+  ],
+});
+
 const adminWrite = { access: { roles: ["Admin"] } } as const;
 const openRead = {
   access: {
@@ -25,4 +47,18 @@ export const noteFeature = defineFeature("notes", (r) => {
     read: openRead,
     verbs: { update: false, delete: false, restore: false },
   });
+
+  r.storeTable(preferenceTable, { reason: "settings.tenant_preferences" });
+
+  r.writeHandler({
+    name: "preference:set",
+    schema: z.object({ key: z.string().min(1), value: z.string() }),
+    handler: async (event, ctx) => {
+      const row = await ctx.db.upsert<{ value: string }>(preferenceTable, event.payload, {
+        conflictTarget: ["tenantId", "key"],
+      });
+      return { isSuccess: true, data: { value: row?.value } };
+    },
+    ...adminWrite,
+  });
 });

package/packages/bundled-features/src/billing-foundation/consumer-protection/stored-user-email.ts

@@ -1,12 +0,0 @@
-import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
-import { decryptStoredPii } from "../../shared/index.ts";
-
-// findForAuth returns the stored column, which is ciphertext under an active KMS;
-// channel-email refuses to mail a ciphertext address. Null for an erased subject.
-export async function openStoredUserEmail(
-  stored: string,
-  fallbackRequestId: string,
-): Promise<string | null> {
-  const email = await decryptStoredPii(stored, "email", fallbackRequestId);
-  return email === PII_ERASED_SENTINEL ? null : email;
-}