@cosmicdrift/kumiko-framework 0.19.0 → 0.19.1

package/README.md

@@ -7,7 +7,7 @@ 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 +
-> Drizzle. Define features, register entities, write commands — the framework
+> Postgres. Define features, register entities, write commands — the framework
 > wires dispatch, persistence, projections, async subscribers, and realtime
 > delivery.
 
@@ -18,12 +18,12 @@ for runnable examples of every feature.
 ## Install
 
 ```bash
-yarn add @cosmicdrift/kumiko-framework
+bun add @cosmicdrift/kumiko-framework
 # peers you probably already have:
-yarn add drizzle-orm hono ioredis zod
+bun add hono ioredis zod
 ```
 
-Bun is the intended runtime. Node 20+ works for the CLI and tests.
+Bun is the intended runtime and test runner.
 
 ## At-a-glance
 
@@ -108,7 +108,7 @@ export const taskFeature = defineFeature("tasks", (r) => {
 | Entry | What's in it |
 |---|---|
 | `@cosmicdrift/kumiko-framework/engine` | `defineFeature`, `createEntity`, field helpers, access rules, registry |
-| `@cosmicdrift/kumiko-framework/db` | Drizzle re-exports, `createEventStoreExecutor`, table builders, tenant-db |
+| `@cosmicdrift/kumiko-framework/db` | `buildEntityTableMeta`, `createEventStoreExecutor`, migrations, tenant-db |
 | `@cosmicdrift/kumiko-framework/event-store` | `events` table, `append`, `loadAggregate`, `loadAggregateAsOf` |
 | `@cosmicdrift/kumiko-framework/pipeline` | Dispatcher, event-dispatcher (AsyncDaemon), projection-rebuild, SSE + search consumers |
 | `@cosmicdrift/kumiko-framework/api` | `buildServer`, auth middleware, SSE route, error contract |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -123,6 +123,10 @@
       "types": "./src/search/meilisearch-adapter.ts",
       "default": "./src/search/meilisearch-adapter.ts"
     },
+    "./seeding": {
+      "types": "./src/seeding/index.ts",
+      "default": "./src/seeding/index.ts"
+    },
     "./secrets": {
       "types": "./src/secrets/index.ts",
       "default": "./src/secrets/index.ts"

package/src/seeding/__tests__/entity-seed.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { runEventStoreSeed } from "../entity-seed";
+
+describe("runEventStoreSeed", () => {
+  test('default ifExists="skip" returns existing id without update', async () => {
+    let updateCalls = 0;
+    let createCalls = 0;
+
+    const result = await runEventStoreSeed({
+      existing: { id: "agg-1", version: 3 },
+      create: async () => {
+        createCalls++;
+        return { id: "new" };
+      },
+      update: async () => {
+        updateCalls++;
+        return { id: "agg-1" };
+      },
+    });
+
+    expect(result.id).toBe("agg-1");
+    expect(updateCalls).toBe(0);
+    expect(createCalls).toBe(0);
+  });
+
+  test('ifExists="update" calls update when row exists', async () => {
+    let updateCalls = 0;
+
+    const result = await runEventStoreSeed({
+      existing: { id: "agg-2", version: 1 },
+      ifExists: "update",
+      create: async () => ({ id: "new" }),
+      update: async (existing) => {
+        updateCalls++;
+        expect(existing.version).toBe(1);
+        return { id: existing.id };
+      },
+    });
+
+    expect(result.id).toBe("agg-2");
+    expect(updateCalls).toBe(1);
+  });
+
+  test("missing row calls create", async () => {
+    let createCalls = 0;
+
+    const result = await runEventStoreSeed({
+      existing: null,
+      create: async () => {
+        createCalls++;
+        return { id: "created" };
+      },
+      update: async () => ({ id: "never" }),
+    });
+
+    expect(result.id).toBe("created");
+    expect(createCalls).toBe(1);
+  });
+});

package/src/seeding/entity-seed.ts

@@ -0,0 +1,27 @@
+import { DEFAULT_SEED_IF_EXISTS, type SeedIfExists } from "./types";
+
+export type EventStoreSeedExisting = {
+  readonly id: string | number;
+  readonly version: number;
+};
+
+export type RunEventStoreSeedOptions<TExisting extends EventStoreSeedExisting> = {
+  readonly existing: TExisting | null | undefined;
+  readonly ifExists?: SeedIfExists;
+  readonly create: () => Promise<{ id: string | number }>;
+  readonly update: (existing: TExisting) => Promise<{ id: string | number }>;
+};
+
+/** Shared create-or-skip/update path for event-store boot-seed helpers. */
+export async function runEventStoreSeed<TExisting extends EventStoreSeedExisting>(
+  opts: RunEventStoreSeedOptions<TExisting>,
+): Promise<{ id: string | number }> {
+  const ifExists = opts.ifExists ?? DEFAULT_SEED_IF_EXISTS;
+  if (opts.existing != null) {
+    if (ifExists === "skip") {
+      return { id: opts.existing.id };
+    }
+    return opts.update(opts.existing);
+  }
+  return opts.create();
+}

package/src/seeding/index.ts

@@ -0,0 +1,6 @@
+export {
+  type EventStoreSeedExisting,
+  type RunEventStoreSeedOptions,
+  runEventStoreSeed,
+} from "./entity-seed";
+export { DEFAULT_SEED_IF_EXISTS, type SeedIfExists } from "./types";

package/src/seeding/types.ts

@@ -0,0 +1,8 @@
+/** Boot-seed semantics for event-sourced entity helpers.
+ *
+ *  - `skip` (default): row exists → return without write (no event).
+ *  - `update`: row exists → overwrite via executor.update (opt-in, e.g.
+ *    demo-fixtures where code is source-of-truth). */
+export type SeedIfExists = "skip" | "update";
+
+export const DEFAULT_SEED_IF_EXISTS: SeedIfExists = "skip";