@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

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";
@@ -22,7 +23,7 @@ export const INVOICE_EVENTS = {
 // Qualifier used by the reducer to match events from the stream.
 // `<const TShort>` preserves the literal-string at the call-site, so
 // `eventName(INVOICE_EVENTS.sent)` carries `"billing:event:invoice-sent"`
-// as a literal type. That literal is what `ctx.appendEvent({ type, ... })`
+// as a literal type. That literal is what `ctx.events.append({ type, ... })`
 // strict-checks against the augmented `KumikoEventTypeMap`.
 export function eventName<const TShort extends string>(
   short: TShort,
@@ -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/state-machine/src/reducer.ts

@@ -41,7 +41,7 @@ export async function loadInvoiceState(
   ctx: HandlerContext,
   id: string,
 ): Promise<InvoiceState | null> {
-  const events = await ctx.loadAggregate(id);
+  const events = await ctx.events.load(id);
   if (events.length === 0) return null;
   const state: InvoiceState = { ...initialInvoiceState };
   for (const evt of events) reduceInvoice(state, evt);

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/samples/recipes/workflow-engine/src/resume-loop.ts

@@ -96,7 +96,7 @@ export async function runResumeLoop(
     if (run.definitionFingerprint !== undefined) {
       const currentFingerprint = computeDefinitionFingerprint(run.workflow);
       if (currentFingerprint !== run.definitionFingerprint) {
-        await handlerCtx.unsafeAppendEvent({
+        await handlerCtx.events.unsafeAppend({
           aggregateId: run.runId,
           aggregateType: WORKFLOW_AGGREGATE_TYPE,
           type: WORKFLOW_RUN_FAILED_TYPE,
@@ -124,7 +124,7 @@ export async function runResumeLoop(
     // no FAILED-event. Stale WAITING-rows in the fetcher result also
     // hit this branch on the second poll-tick.
     try {
-      await handlerCtx.unsafeAppendEvent({
+      await handlerCtx.events.unsafeAppend({
         aggregateId: run.runId,
         aggregateType: WORKFLOW_AGGREGATE_TYPE,
         type: WORKFLOW_RESUMED_TYPE,
@@ -176,7 +176,7 @@ export async function runResumeLoop(
       // returned. A second suspension (e.g. `wait` further down the
       // pipeline) leaves the run pending for the next resume-loop tick.
       if (outcome.kind !== "suspended") {
-        await handlerCtx.unsafeAppendEvent({
+        await handlerCtx.events.unsafeAppend({
           aggregateId: run.runId,
           aggregateType: WORKFLOW_AGGREGATE_TYPE,
           type: WORKFLOW_RUN_COMPLETED_TYPE,
@@ -193,7 +193,7 @@ export async function runResumeLoop(
         stepIndex: run.stepIndex,
         error: String(error),
       });
-      await handlerCtx.unsafeAppendEvent({
+      await handlerCtx.events.unsafeAppend({
         aggregateId: run.runId,
         aggregateType: WORKFLOW_AGGREGATE_TYPE,
         type: WORKFLOW_RUN_FAILED_TYPE,

package/samples/recipes/workflow-engine/src/workflow-runner.ts

@@ -70,7 +70,7 @@ export async function startAndRunWorkflow(args: {
     ...(args.idempotencyKey && { idempotencyKey: args.idempotencyKey }),
   };
 
-  await args.handlerCtx.unsafeAppendEvent({
+  await args.handlerCtx.events.unsafeAppend({
     aggregateId: args.runId,
     aggregateType: WORKFLOW_AGGREGATE_TYPE,
     type: WORKFLOW_RUN_STARTED_TYPE,
@@ -97,7 +97,7 @@ export async function startAndRunWorkflow(args: {
     return { outcome: "suspended" };
   }
 
-  await args.handlerCtx.unsafeAppendEvent({
+  await args.handlerCtx.events.unsafeAppend({
     aggregateId: args.runId,
     aggregateType: WORKFLOW_AGGREGATE_TYPE,
     type: WORKFLOW_RUN_COMPLETED_TYPE,