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.

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.

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 code

The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):

// 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 };
    },
  });
});

📄 On GitHub: samples/recipes/custom-fields-basic/src/feature.ts