Idempotency
Same request, same result — dedupe on request ID.
What it shows
Section titled “What it shows”requestIdprevents duplicate inserts and returns the cached result- Custom write handler that owns business defaults
Source
Section titled “Source”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.
cd samples/recipes/idempotencybun testSource code
Section titled “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):
// 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