@cosmicdrift/kumiko-framework 0.398.0 → 0.400.0

package/agents/api.md

@@ -0,0 +1,20 @@
+<!-- Generated by `bun run gen:agent-docs` from package.json exports of the listed entry points. Do not edit. -->
+
+# API reference
+
+Public signatures of the entry points an app imports, generated from their sources. Read these instead of `dist/*.d.ts`.
+
+Format: one line per function or constant, object and options types as property lists (`name?: Type;`), and the first sentence of the doc comment after `//`. Bodies and `@internal` declarations are left out. A type that an entry point uses but does not export is listed in `api/types.md`.
+
+| Import path | File | Exports |
+| --- | --- | --- |
+| `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 411 |
+| `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 25 |
+| `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 154 |
+| `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 150 |
+| `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 38 |
+| `@cosmicdrift/kumiko-framework/seeding` | `api/framework-seeding.md` | 6 |
+| `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 298 |
+| `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 21 |
+| `@cosmicdrift/kumiko-testing/helpers` | `api/testing-helpers.md` | 71 |
+| `@cosmicdrift/kumiko-dev-server/testing` | `api/dev-server-testing.md` | 5 |

package/agents/examples/derived-fields-sql.md

@@ -0,0 +1,251 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/derived-fields-sql. Do not edit. -->
+
+# derived-fields-sql
+
+SQL derived fields on a list: coalesce, related count with a where, related first (text and money), sortable columns and a defaultSort on a derived value.
+
+## README
+
+# Derived fields (SQL)
+
+A derived field is read-time only: no column, never in a write schema. A `sql` derived field is
+computed inside the list SELECT as the viewer, so it can be sorted on the server and never
+enters the entity cache. A viewer who cannot read a field the value depends on gets NULL.
+
+## What it shows
+
+- `coalesce`: the nickname when set, else the name.
+- `related` + `count` with a `where`: open tickets per building.
+- `related` + `first`: the title of the newest ticket.
+- `related` + `first` on a money field with `valueType: "money"`: amount and currency come
+  back in the shape of a stored money field (no key when the value is unset).
+- `sortable: true` on a derived field and an `entityList` `defaultSort` on it.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/derived-fields-sql
+bun test
+```
+
+`src/__tests__/feature.integration.test.ts` runs the list query over HTTP.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
+import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
+import { buildingListSort, derivedFieldsSqlFeature } from "../feature";
+
+type Row = Record<string, unknown>;
+type Page = { readonly rows: readonly Row[] };
+
+const LIST = "derived-fields-sql:query:building:list";
+const user = createTestUser({ roles: ["User"], tenantId: testTenantId(1) });
+
+let stack: TestStack;
+const names = (page: Page): unknown[] => page.rows.map((row) => row["name"]);
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [derivedFieldsSqlFeature], systemHooks: [] });
+  const create = async (name: string, nickname?: string): Promise<string> => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "derived-fields-sql:write:building:create",
+      { name, ...(nickname !== undefined && { nickname }) },
+      user,
+    );
+    return created.id;
+  };
+  const ticket = (
+    buildingId: string,
+    title: string,
+    status: string,
+    openedOn: string,
+    cost?: { amount: number; currency: string },
+  ) =>
+    stack.http.writeOk(
+      "derived-fields-sql:write:ticket:create",
+      { buildingId, title, status, openedOn, ...(cost !== undefined && { cost }) },
+      user,
+    );
+
+  const harbor = await create("Harbor House", "The Harbor");
+  const mill = await create("Old Mill");
+  await create("Quiet Court");
+  await ticket(harbor, "Roof leak", "open", "2026-01-10", { amount: 800, currency: "EUR" });
+  await ticket(harbor, "Boiler", "inProgress", "2026-03-05", { amount: 1250.5, currency: "EUR" });
+  await ticket(harbor, "Paint hall", "done", "2026-05-01");
+  await ticket(mill, "Broken window", "open", "2026-02-02", { amount: 90, currency: "CHF" });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("derived-fields-sql recipe", () => {
+  test("coalesce falls back to the name when there is no nickname", async () => {
+    const page = await stack.http.queryOk<Page>(LIST, { limit: 10 }, user);
+    const shown = new Map(page.rows.map((row) => [row["name"], row["shownName"]]));
+
+    expect(shown.get("Harbor House")).toBe("The Harbor");
+    expect(shown.get("Old Mill")).toBe("Old Mill");
+  });
+
+  test("related count follows the where, first picks the newest ticket", async () => {
+    const page = await stack.http.queryOk<Page>(LIST, { limit: 10 }, user);
+    const harbor = page.rows.find((row) => row["name"] === "Harbor House");
+    const quiet = page.rows.find((row) => row["name"] === "Quiet Court");
+
+    expect(harbor?.["openTickets"]).toBe(2);
+    // `first` ignores the where: it is the newest ticket by openedOn, done or not.
+    expect(harbor?.["latestTicket"]).toBe("Paint hall");
+    expect(quiet?.["openTickets"]).toBe(0);
+    expect(quiet?.["latestTicket"]).toBeNull();
+  });
+
+  test("first on a money field arrives as amount and currency, absent when unset", async () => {
+    const page = await stack.http.queryOk<Page>(LIST, { limit: 10 }, user);
+    const byName = new Map(page.rows.map((row) => [row["name"], row]));
+
+    expect(byName.get("Old Mill")?.["latestCost"]).toMatchObject({ amount: 90, currency: "CHF" });
+    // Harbor's newest ticket has no cost: no key, like an unset stored money field.
+    expect(Object.hasOwn(byName.get("Harbor House") ?? {}, "latestCost")).toBe(false);
+  });
+
+  test("a sortable derived column sorts on the server", async () => {
+    const asc = await stack.http.queryOk<Page>(
+      LIST,
+      { sort: "shownName", sortDirection: "asc", limit: 10 },
+      user,
+    );
+
+    expect(names(asc)).toEqual(["Old Mill", "Quiet Court", "Harbor House"]);
+  });
+
+  test("the screen's defaultSort on a derived value orders the list", async () => {
+    const screen = createRegistry([derivedFieldsSqlFeature]).getScreen(
+      "derived-fields-sql:screen:building-list",
+    );
+    const defaultSort = screen?.type === "entityList" ? screen.defaultSort : undefined;
+    expect(defaultSort).toEqual(buildingListSort);
+
+    const page = await stack.http.queryOk<Page>(
+      LIST,
+      { sort: defaultSort?.field, sortDirection: defaultSort?.dir, limit: 10 },
+      user,
+    );
+    expect(names(page)).toEqual(["Harbor House", "Old Mill", "Quiet Court"]);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import {
+  createDateField,
+  createDerivedField,
+  createEntity,
+  createMoneyField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const openAccess = {
+  access: {
+    openToAll: { reason: "recipe: any signed-in user reads and edits; no per-user ownership" },
+  },
+} as const;
+
+export const ticketEntity = createEntity({
+  table: "read_derived_sql_tickets",
+  fields: {
+    buildingId: { type: "reference", entity: "building" },
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    status: createSelectField({ options: ["open", "inProgress", "done"] as const }),
+    openedOn: createDateField({ required: true }),
+    cost: createMoneyField(),
+  },
+  // The sortable derived columns of the building run a subquery per row over this column.
+  indexes: [{ columns: ["buildingId"] }],
+});
+
+export const buildingEntity = createEntity({
+  table: "read_derived_sql_buildings",
+  fields: {
+    name: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      searchable: true,
+    }),
+    nickname: createTextField({ personal: false, reason: "is_business_data" }),
+  },
+  // Computed inside the list SELECT as the viewer; never stored, never cached.
+  derivedFields: {
+    // First non-null of the columns, so the list shows the nickname when there is one.
+    shownName: createDerivedField({
+      valueType: "text",
+      sortable: true,
+      sql: { kind: "coalesce", fields: ["nickname", "name"] },
+    }),
+    openTickets: createDerivedField({
+      valueType: "number",
+      sortable: true,
+      sql: {
+        kind: "related",
+        entity: "ticket",
+        on: { field: "buildingId" },
+        measure: { kind: "count" },
+        where: [{ field: "status", op: "in", value: ["open", "inProgress"] }],
+      },
+    }),
+    latestTicket: createDerivedField({
+      valueType: "text",
+      sql: {
+        kind: "related",
+        entity: "ticket",
+        on: { field: "buildingId" },
+        measure: { kind: "first", field: "title", orderBy: "openedOn", direction: "desc" },
+      },
+    }),
+    // Money reads amount and currency together and has the shape of a stored money field.
+    latestCost: createDerivedField({
+      valueType: "money",
+      sortable: true,
+      sql: {
+        kind: "related",
+        entity: "ticket",
+        on: { field: "buildingId" },
+        measure: { kind: "first", field: "cost", orderBy: "openedOn", direction: "desc" },
+      },
+    }),
+  },
+});
+
+export const buildingListSort = { field: "openTickets", dir: "desc" } as const;
+
+export const derivedFieldsSqlFeature = defineFeature("derived-fields-sql", (r) => {
+  r.crud("ticket", ticketEntity, { write: openAccess, read: openAccess });
+  r.crud("building", buildingEntity, { write: openAccess, read: openAccess });
+
+  r.screen({
+    id: "building-list",
+    type: "entityList",
+    entity: "building",
+    columns: ["shownName", "openTickets", "latestTicket", "latestCost"],
+    // A derived column sorts on the server only when it is `sortable: true`.
+    defaultSort: buildingListSort,
+    access: openAccess.access,
+  });
+});
+```

package/agents/examples/documents.md

@@ -0,0 +1,161 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/documents. Do not edit. -->
+
+# documents
+
+A document register on top of existing records: captured files, expiry dates and per-record visibility.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createFilesFeature,
+  createInMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
+import {
+  buildMultipartBody,
+  patchFileInstanceofForBunTest,
+} from "@cosmicdrift/kumiko-testing/helpers";
+import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
+import * as z from "zod";
+import { documents, propertyManagement } from "../feature.ts";
+
+const tenant = testTenantId(1);
+const admin = createTestUser({ id: 1, tenantId: tenant, roles: ["TenantAdmin"] });
+const propertyReader = createTestUser({ id: 2, tenantId: tenant, roles: ["PropertyReader"] });
+const contractReader = createTestUser({ id: 3, tenantId: tenant, roles: ["ContractReader"] });
+
+type Page = { rows: readonly { title: string }[] };
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  patchFileInstanceofForBunTest();
+  stack = await setupTestStack({
+    features: [createFilesFeature(), propertyManagement, documents],
+    files: { storageProvider: createInMemoryFileProvider() },
+  });
+});
+afterAll(() => stack.cleanup());
+
+async function uploadContractFile(): Promise<string> {
+  const form = new FormData();
+  form.append("entityType", "contract");
+  form.append("fieldName", "file");
+  form.append(
+    "file",
+    new File([Buffer.from("%PDF-1.4 lease")], "lease.pdf", { type: "application/pdf" }),
+  );
+  const { body, contentType } = await buildMultipartBody(form);
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${await stack.jwt.sign(admin)}`,
+      "Content-Type": contentType,
+    },
+    body,
+  });
+  return z.object({ id: z.string() }).parse(await res.json()).id;
+}
+
+describe("documents recipe", () => {
+  test("a contract file becomes a document that only contract readers see", async () => {
+    const property = await stack.http.writeOk<{ id: string }>(
+      "property-management:write:property:create",
+      { name: "Main street 1" },
+      admin,
+    );
+    const contract = await stack.http.writeOk<{ id: string }>(
+      "property-management:write:contract:create",
+      { name: "C-1", propertyId: property.id, file: await uploadContractFile() },
+      admin,
+    );
+
+    const forRecord = (as: typeof admin, entityType: string, entityId: string) =>
+      stack.http.queryOk<Page>("documents:query:for-record", { entityType, entityId }, as);
+
+    expect(
+      (await forRecord(contractReader, "contract", contract.id)).rows.map((r) => r.title),
+    ).toEqual(["Contract C-1"]);
+    expect((await forRecord(admin, "property", property.id)).rows.map((r) => r.title)).toEqual([
+      "Contract C-1",
+    ]);
+    // the property reader may open the property but not the contract that owns the file
+    expect((await forRecord(propertyReader, "property", property.id)).rows).toEqual([]);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// kumiko-feature-version: 1
+// Documents Sample
+//
+// A `contract` entity with a file field becomes a document source without knowing about the
+// documents feature: the capture rule below files every saved contract file as a document of
+// category "contract" and links it to the contract and to its property. Who sees the document
+// follows from who may read the linked records and the contract that owns the file.
+
+import { createDocumentsFeature } from "@cosmicdrift/kumiko-bundled-features/documents";
+import {
+  createEntity,
+  createFileField,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const text = () =>
+  createTextField({ personal: false, reason: "is_business_data", required: true, maxLength: 120 });
+
+export const propertyEntity = createEntity({
+  table: "read_sample_documents_properties",
+  fields: { name: text() },
+  access: { read: { PropertyReader: "all", TenantAdmin: "all" } },
+});
+
+export const contractEntity = createEntity({
+  table: "read_sample_documents_contracts",
+  fields: { name: text(), propertyId: text(), file: createFileField() },
+  access: { read: { ContractReader: "all", TenantAdmin: "all" } },
+});
+
+const access = { roles: ["PropertyReader", "ContractReader", "TenantAdmin"] };
+
+export const propertyManagement = defineFeature("property-management", (r) => {
+  r.requires({ features: ["files", "documents"] });
+  r.entity({ name: "property", ...propertyEntity });
+  r.entity({ name: "contract", ...contractEntity });
+  for (const [name, entity] of [
+    ["property", propertyEntity],
+    ["contract", contractEntity],
+  ] as const) {
+    r.writeHandler(defineEntityCreateHandler(name, entity, { access }));
+    r.writeHandler(defineEntityUpdateHandler(name, entity, { access: { roles: ["TenantAdmin"] } }));
+    r.queryHandler(defineEntityListHandler(name, entity, { access }));
+    r.queryHandler(defineEntityDetailHandler(name, entity, { access }));
+  }
+});
+
+export const documents = createDocumentsFeature({
+  categories: ["contract", "insurance"],
+  linkTargets: ["property", "contract"],
+  access,
+  capture: [
+    {
+      entity: "contract",
+      field: "file",
+      category: "contract",
+      title: (row) => `Contract ${String(row["name"])}`,
+      links: (row) => [{ entityType: "property", entityId: String(row["propertyId"]) }],
+    },
+  ],
+});
+```