@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/agents/examples/custom-fields-basic.md

@@ -0,0 +1,315 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/custom-fields-basic. Do not edit. -->
+
+# custom-fields-basic
+
+Tenant-defined extra fields on an entity without writing migrations.
+
+## README
+
+# Custom fields
+
+Let a tenant add their own fields to your entity at runtime — without
+writing a migration, without rebuilding your handler, without a code
+change. The recipe wires a `property` entity into the `custom-fields`
+bundle and drives a full *define → set → read* roundtrip.
+
+The result: the tenant defines `internalNumber: text`, sets it on a
+property, and reads it back flattened onto the row — looking exactly
+like a first-class column.
+
+## What it shows
+
+- **`customFieldsField()`** — a jsonb column factory that holds the
+  per-row custom field values. Add it to any entity you want
+  custom-field-capable.
+- **`wireCustomFieldsFor(r, entityName, table)`** — wires the
+  bundle's projection: a multi-stream projection consumes
+  `customField.set` / `.cleared` events and writes them into the
+  jsonb column, and an entity-postQuery hook flattens the jsonb onto
+  the row at read-time.
+- **No migrations at runtime** — the schema for custom fields lives
+  in two bundled tables (`field-definition` for the spec, jsonb on
+  the host row for the values). Defining a field is a write, not a
+  DDL.
+- **Stammfeld-look on the response** — reads return `{ id, name,
+  internalNumber: "X-2042" }`. The consumer can't tell which fields
+  are first-class and which are custom.
+
+## Feature composition
+
+```
+custom-fields          → core bundle: events + write-handlers + MSP +
+                         field-definition entity
+property-management    → our feature: opts the `property` entity into
+                         custom-fields via wireCustomFieldsFor
+```
+
+The `property-management` feature `r.requires("custom-fields")` — the
+bundle is non-optional for this recipe because the wired entity would
+otherwise have an empty jsonb column and no way to write into it.
+
+## Flow
+
+1. Tenant admin calls `custom-fields:write:define-tenant-field` to
+   declare `internalNumber: text` on `property`.
+2. App code creates a `property` row via
+   `property-management:write:property:create`.
+3. Tenant admin calls `custom-fields:write:set-custom-field` with the
+   `entityId`, `fieldKey: "internalNumber"`, `value: "X-2042"`.
+4. The bundle's MSP consumes the `customField.set` event and writes
+   the value into the property row's `customFields` jsonb column.
+5. The next `property-management:query:property:list` returns the row
+   with `internalNumber: "X-2042"` flattened onto the response — the
+   entity-postQuery hook merges the jsonb keys onto the row root.
+
+## When to reach for it
+
+You ship a SaaS where every tenant wants one or two of their own
+columns — internal IDs, vendor names, custom flags — and you don't
+want to either ship them all as `extraFields1..extraFields5` or push
+the tenant to a request-a-feature queue. Custom fields cover the
+single-or-handful-of-extra-fields case without engineering
+involvement.
+
+If you need the field to drive business logic (`if vipFlag then ...`),
+make it a first-class field instead — see [`basic-entity`](../basic-entity/).
+
+## Tests
+
+The integration test under `src/__tests__/` walks two scenarios:
+
+- Tenant defines a text field, sets a value, reads it back flat.
+- Tenant defines a number field, sets it, reads it back with the
+  number type preserved.
+
+```bash
+bun kumiko test integration samples/custom-fields-basic
+```
+
+## Source
+
+The feature is ~80 lines (`src/feature.ts`). The integration test is
+~110 lines (`src/__tests__/feature.integration.test.ts`).
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Custom-Fields Basic — integration test.
+//
+// Proves the full define → set → read roundtrip via the real dispatcher,
+// MSP-pipeline and DB:
+//   1. tenant defines `internalNumber` on `property`
+//   2. property is created
+//   3. customField is set → MSP writes into jsonb
+//   4. list-query returns the value flattened onto the row
+//
+// This is the smallest evidence that wireCustomFieldsFor + the bundle's
+// projection-hook + entity-postQuery flattening all line up.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  createCustomFieldsFeature,
+  fieldDefinitionEntity,
+} from "@cosmicdrift/kumiko-bundled-features/custom-fields";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { propertyEntity, propertyFeature } from "../feature";
+
+// Each test runs in its own tenant, so rows from other tests never show up.
+let admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(1) });
+let nextTenant = 1;
+const customFields = createCustomFieldsFeature();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [customFields, propertyFeature] });
+  await unsafeCreateEntityTable(stack.db, fieldDefinitionEntity);
+  await unsafeCreateEntityTable(stack.db, propertyEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  nextTenant += 1;
+  admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(nextTenant) });
+});
+
+async function defineField(fieldKey: string, type = "text") {
+  return stack.http.writeOk(
+    "custom-fields:write:define-tenant-field",
+    {
+      entityName: "property",
+      fieldKey,
+      serializedField: { type },
+      required: false,
+      searchable: false,
+      displayOrder: 0,
+    },
+    admin,
+  );
+}
+
+async function setField(entityId: string, fieldKey: string, value: unknown) {
+  return stack.http.writeOk(
+    "custom-fields:write:set-custom-field",
+    { entityName: "property", entityId, fieldKey, value },
+    admin,
+  );
+}
+
+async function listProperties() {
+  return (await stack.http.queryOk("property-management:query:property:list", {}, admin)) as {
+    rows: Array<Record<string, unknown>>;
+  };
+}
+
+describe("custom-fields-basic recipe — define + set + read", () => {
+  test("tenant-defined field lands flat on the entity response", async () => {
+    const id = "11111111-1111-4000-8000-000000000001";
+
+    await defineField("internalNumber");
+    await stack.http.writeOk(
+      "property-management:write:property:create",
+      { id, name: "Hofgarten 12" },
+      admin,
+    );
+    await setField(id, "internalNumber", "X-2042");
+    await stack.eventDispatcher?.runOnce();
+
+    const { rows } = await listProperties();
+    const property = rows.find((row) => row["id"] === id);
+    expect(property?.["internalNumber"]).toBe("X-2042");
+  });
+
+  test("typed field: number value preserves its type", async () => {
+    const id = "22222222-2222-4000-8000-000000000002";
+
+    await defineField("tier", "number");
+    await stack.http.writeOk(
+      "property-management:write:property:create",
+      { id, name: "MultiField" },
+      admin,
+    );
+    await setField(id, "tier", 2);
+    await stack.eventDispatcher?.runOnce();
+
+    const property = (await listProperties()).rows.find((row) => row["id"] === id);
+    expect(property?.["tier"]).toBe(2);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// kumiko-feature-version: 1
+// Custom-Fields Basic Sample
+//
+// Shows how a feature opts a tenant-owned entity into the custom-fields
+// extension: tenants can define their own fields at runtime, set values
+// per row, and read them back flattened onto the entity — without writing
+// a single migration or extra handler.
+//
+// Flow:
+//   1. App-author defines a `property` entity and wires it via
+//      `wireCustomFieldsFor(r, "property", propertyTable)`.
+//   2. A tenant admin defines a field at runtime
+//      (e.g. `internalNumber: text`) via the bundle's CRUD.
+//   3. Values are written via `custom-fields:write:set-custom-field`,
+//      not through the host entity's own write handler.
+//   4. Reads return the field flattened onto the row — looks like a
+//      first-class column. The flattening is an entity-level postQuery
+//      hook (registered by wireCustomFieldsFor), so it fires for ANY
+//      query whose name maps to this entity — including the hand-written
+//      `property:list` below.
+
+import {
+  customFieldsField,
+  wireCustomFieldsFor,
+} from "@cosmicdrift/kumiko-bundled-features/custom-fields";
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// --- Entity ---
+//
+// The field shape is declared as a plain object literal so the feature is
+// self-describing Object-Form (what the AI/Designer should emit). The same
+// literal is passed inline to `r.entity` below. `{ type: "jsonb" }` is
+// exactly what `customFieldsField()` produces — the jsonb column the
+// bundle's projection writes into; without it `wireCustomFieldsFor` has
+// nowhere to land the values.
+
+export const propertyEntity = createEntity({
+  table: "read_sample_cf_properties",
+  fields: {
+    name: { type: "text", required: true, maxLength: 200 },
+    customFields: customFieldsField(),
+  },
+});
+
+export const propertyTable = buildEntityTable("property", propertyEntity);
+
+function propertyExecutor() {
+  return createEventStoreExecutor(propertyTable, propertyEntity, { entityName: "property" });
+}
+
+// --- Feature ---
+
+export const propertyFeature = defineFeature("property-management", (r) => {
+  r.requires("custom-fields");
+
+  r.entity("property", {
+    table: "read_sample_cf_properties",
+    fields: {
+      name: { type: "text", required: true, maxLength: 200 },
+      customFields: { type: "jsonb" },
+    },
+  });
+
+  // Opt this entity into the custom-fields extension. This registers the
+  // multi-stream projection (MSP) that consumes customField.set / .cleared
+  // events and writes them into the `customFields` jsonb column, plus the
+  // entity postQuery hook that flattens the jsonb onto the row at read-time.
+  wireCustomFieldsFor(r, "property", propertyTable);
+
+  r.writeHandler({
+    name: "property:create",
+    schema: z.object({ id: z.string(), name: z.string() }),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (event, ctx) =>
+      propertyExecutor().create(
+        { id: event.payload.id, name: event.payload.name, customFields: {} },
+        event.user,
+        ctx.db,
+      ),
+  });
+
+  // List query. Named `property:list` so it maps to the `property` entity
+  // (colon convention) — that mapping is what lets the entity postQuery
+  // hook from wireCustomFieldsFor flatten customFields onto each row. The
+  // handler itself just reads the tenant-scoped read table; ctx.db is
+  // already tenant-scoped.
+  r.queryHandler({
+    name: "property:list",
+    schema: z.object({}),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (_query, ctx) => {
+      const rows = await ctx.db.selectMany(propertyTable);
+      return { rows };
+    },
+  });
+});
+```