@cosmicdrift/kumiko-framework

Framework core for Kumiko — engine, pipeline, API, DB, event-store, and every other bit that makes Kumiko go.

Multi-tenant, command-based, event-sourced app framework for Bun + Hono + Postgres. Define features, register entities, write commands — the framework wires dispatch, persistence, projections, async subscribers, and realtime delivery.

See the monorepo root README for the broader pitch, the docs/plans directory for architecture, and samples/ for runnable examples of every feature.

Install

bun add @cosmicdrift/kumiko-framework
# peers you probably already have:
bun add hono ioredis zod

Bun is the intended runtime and test runner.

At-a-glance

import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";

export const taskEntity = createEntity({
  table: "read_tasks",
  fields: {
    title: createTextField({ required: true, searchable: true }),
    done: createTextField(),
  },
  softDelete: true,
});

export const taskFeature = defineFeature("tasks", (r) => {
  // r.crud wires create/update/delete/restore + list/detail queries in one
  // call — events + projection in the same TX, optimistic locking, access
  // control, all explicit via the options below.
  r.crud("task", taskEntity, {
    write: { access: { roles: ["User"] } },
    read: {
      access: {
        openToAll: {
          reason: "any signed-in user may list and view tasks; only writes are role-gated",
        },
      },
    },
  });

  // Read-model fed from task events, rebuildable via the CLI
  r.projection({
    name: "tasks-per-day",
    source: "task",
    table: tasksPerDayTable,
    apply: {
      "task.created": async (event, tx) => {
        /* count++ */
      },
    },
  });

  // Async consumer — runs after commit via the event-dispatcher,
  // cursor-based, at-least-once, per-consumer dead-letter semantics.
  // Omit `table` for pure side-effect handlers (mail, webhooks, ...).
  r.multiStreamProjection({
    name: "notify-new-task",
    apply: {
      "task.created": async (event) => {
        // e.g. push to an external notification service
      },
    },
  });
});

Package exports

Core concepts

• Feature as unit of deployment. defineFeature registers entities, write/query handlers, projections, post-event subscribers, lifecycle hooks, access rules, and translations.
• Commands in, state out. Writes are commands dispatched through HTTP; the dispatcher validates, enforces access, runs lifecycle hooks, persists events, and triggers projections in a single TX.
• Event-sourced by default. Every write goes through createEventStoreExecutor and appends a domain event to the aggregate stream. Auto-generated CRUD events (<entity>.created/updated/deleted/restored) for record writes, explicit ctx.events.append for domain events with intent. Projections feed off the stream for same-TX read-after-write consistency.
• Async side-effects via cursor. SSE broadcast, search indexing, and feature-registered r.multiStreamProjection consumers run on a single cursor-based dispatcher (AsyncDaemon pattern). Per-consumer checkpoints, halt-on-poison, dead-letter after N retries.
• Multi-tenant scoping. Every event, entity, projection, and search index carries tenantId. TenantDb is a TX-scoped wrapper that refuses writes outside the current tenant.
• Optimistic concurrency. UNIQUE(aggregate_id, version) on events gives atomic append + conflict detection; VersionConflictError surfaces races as a first-class value.
• Idempotency + dedup. Request-id backed unique index on the events table turns retries into replays. IdempotencyGuard caches write outcomes per tenant.

Status

This framework is pre-1.0 and evolves fast. Every feature has a runnable sample under samples/; the roadmap lives in docs/plans/uebersicht.md.

License

MIT, see LICENSE.