Skip to content

Idempotency

Same request, same result — dedupe on request ID.

  • requestId prevents duplicate inserts and returns the cached result
  • Custom write handler that owns business defaults

Feature entry point: src/feature.ts.

Needs the Postgres from the repo root’s docker-compose.yml (docker compose up -d); TEST_DATABASE_URL defaults to postgresql://kumiko:kumiko@localhost:15432/kumiko_test.

Terminal window
cd samples/recipes/idempotency
bun test

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):

// Idempotency Sample
// Shows: requestId prevents duplicate inserts, returns cached result.
// Custom `order:place` handler so we can inject a default status — a generic
// `order:create` would not know about the business rule "new orders start as
// pending".
import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
import { z } from "zod";
export const orderEntity = createEntity({
name: "order",
table: "read_sample_orders",
fields: {
customerName: createTextField({ personal: { of: "id" }, find: "none", required: true }),
product: createTextField({ personal: false, reason: "is_business_data", required: true }),
status: createTextField({ personal: false, reason: "is_business_data", default: "pending" }),
},
});
const orderTable = buildEntityTable(orderEntity);
export const orderFeature = defineFeature("orders", (r) => {
r.entity(orderEntity);
const orderExecutor = createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" });
r.writeHandler({
name: "order:place",
schema: z.object({
customerName: z.string().min(1),
product: z.string().min(1),
}),
handler: async (event, ctx) =>
orderExecutor.create({ ...event.payload, status: "pending" }, event.user, ctx.db),
access: { roles: ["Admin", "Customer"] },
});
r.queryHandler({
name: "order:list",
schema: z.object({ limit: z.number().optional() }),
handler: async (query, ctx) => orderExecutor.list(query.payload, query.user, ctx.db),
access: {
openToAll: {
reason:
"any signed-in user may list orders in this recipe; placing an order still requires a role above",
},
},
});
});

📄 On GitHub: samples/recipes/idempotency/src/feature.ts