@cosmicdrift/kumiko-framework 0.127.0 → 0.129.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.127.0",
+  "version": "0.129.0",
   "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>",
@@ -189,7 +189,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.127.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.129.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/entity-handlers.test.ts

@@ -10,8 +10,11 @@ import {
   defineEntityUpdateHandler,
   defineEntityWriteHandler,
   defineProjectionQueryHandler,
+  type EntityCrudRegistrar,
+  registerEntityCrud,
 } from "../entity-handlers";
 import { createEntity, createTextField } from "../factories";
+import type { QueryHandlerDef, WriteHandlerDef } from "../types";
 
 const VALID_UUID = "00000000-0000-4000-8000-000000000001";
 
@@ -272,3 +275,80 @@ describe("Verb-specific entity-handler factories", () => {
     expect(typeof legacyApi.handler).toBe("function");
   });
 });
+
+function createCrudRegistrarMock(): {
+  readonly r: EntityCrudRegistrar;
+  readonly entities: Record<string, unknown>;
+  readonly writes: WriteHandlerDef[];
+  readonly queries: QueryHandlerDef[];
+} {
+  const entities: Record<string, unknown> = {};
+  const writes: WriteHandlerDef[] = [];
+  const queries: QueryHandlerDef[] = [];
+  const r: EntityCrudRegistrar = {
+    entity(name, definition) {
+      entities[name] = definition;
+    },
+    writeHandler(def) {
+      writes.push(def);
+    },
+    queryHandler(def) {
+      queries.push(def);
+    },
+  };
+  return { r, entities, writes, queries };
+}
+
+describe("registerEntityCrud", () => {
+  test("registers entity + standard handlers (restore only when softDelete)", () => {
+    const { r, entities, writes, queries } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntitySoftDelete, {
+      write: { access: { roles: ["Admin"] } },
+      read: { access: { openToAll: true } },
+    });
+    expect(entities["note"]).toBe(noteEntitySoftDelete);
+    expect(writes.map((w) => w.name)).toEqual([
+      "note:create",
+      "note:update",
+      "note:delete",
+      "note:restore",
+    ]);
+    expect(queries.map((q) => q.name)).toEqual(["note:list", "note:detail"]);
+    expect(writes[0]?.access).toEqual({ roles: ["Admin"] });
+    expect(queries[0]?.access).toEqual({ openToAll: true });
+  });
+
+  test("verbs.delete: false skips delete handler", () => {
+    const { r, writes } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntity, {
+      verbs: { delete: false },
+    });
+    expect(writes.map((w) => w.name)).toEqual(["note:create", "note:update"]);
+  });
+
+  test("no options → handlers have no access (no implicit openToAll)", () => {
+    const { r, writes, queries } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntity);
+    for (const def of [...writes, ...queries]) {
+      expect(def.access).toBeUndefined();
+    }
+  });
+
+  test("restore verb on entity without softDelete throws", () => {
+    const { r } = createCrudRegistrarMock();
+    expect(() => registerEntityCrud(r, "note", noteEntity, { verbs: { restore: true } })).toThrow(
+      /softDelete/,
+    );
+  });
+
+  test("registerEntity: false skips r.entity when already registered", () => {
+    const { r, entities, writes } = createCrudRegistrarMock();
+    r.entity("note", noteEntity);
+    registerEntityCrud(r, "note", noteEntity, {
+      registerEntity: false,
+      verbs: { update: false, delete: false, restore: false, list: false, detail: false },
+    });
+    expect(Object.keys(entities)).toEqual(["note"]);
+    expect(writes.map((w) => w.name)).toEqual(["note:create"]);
+  });
+});

package/src/engine/entity-handlers.ts

@@ -27,6 +27,9 @@ import type {
 //
 // Two API shapes — pick one per project, don't mix:
 //
+//   PREFERRED — full standard CRUD set in one call:
+//     registerEntityCrud(r, "note", noteEntity, { write: { access }, read: { access } })
+//
 //   PREFERRED — one function per verb, type-safe, no magic strings:
 //     r.writeHandler(defineEntityCreateHandler("note", noteEntity, { access }))
 //     r.writeHandler(defineEntityUpdateHandler("note", noteEntity, { access }))
@@ -434,3 +437,71 @@ export function defineProjectionQueryHandler(
     ...(options?.access && { access: options.access }),
   };
 }
+
+type EntityCrudVerb = "create" | "update" | "delete" | "restore" | "list" | "detail";
+
+export type RegisterEntityCrudOptions = {
+  readonly write?: EntityHandlerOptions;
+  readonly read?: EntityQueryHandlerOptions;
+  readonly verbs?: Partial<Record<EntityCrudVerb, boolean>>;
+  /** Default true. Set false when the entity was already registered (e.g. before r.relation). */
+  readonly registerEntity?: boolean;
+};
+
+/** Minimal registrar surface — keeps entity-handlers free of define-feature imports. */
+export type EntityCrudRegistrar = {
+  entity(name: string, definition: EntityDefinition): unknown;
+  writeHandler(def: WriteHandlerDef): unknown;
+  queryHandler(def: QueryHandlerDef): unknown;
+};
+
+function defaultCrudVerbs(entity: EntityDefinition): Record<EntityCrudVerb, boolean> {
+  return {
+    create: true,
+    update: true,
+    delete: true,
+    restore: entity.softDelete === true,
+    list: true,
+    detail: true,
+  };
+}
+
+/** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */
+export function registerEntityCrud(
+  r: EntityCrudRegistrar,
+  entityName: string,
+  entity: EntityDefinition,
+  options?: RegisterEntityCrudOptions,
+): void {
+  const verbs = { ...defaultCrudVerbs(entity), ...options?.verbs };
+  if (verbs.restore && entity.softDelete !== true) {
+    throw new Error(
+      `registerEntityCrud("${entityName}"): restore requested but entity has no softDelete: true`,
+    );
+  }
+
+  if (options?.registerEntity !== false) {
+    r.entity(entityName, entity);
+  }
+  const writeOpts = options?.write;
+  const readOpts = options?.read;
+
+  if (verbs.create) {
+    r.writeHandler(defineEntityCreateHandler(entityName, entity, writeOpts));
+  }
+  if (verbs.update) {
+    r.writeHandler(defineEntityUpdateHandler(entityName, entity, writeOpts));
+  }
+  if (verbs.delete) {
+    r.writeHandler(defineEntityDeleteHandler(entityName, entity, writeOpts));
+  }
+  if (verbs.restore) {
+    r.writeHandler(defineEntityRestoreHandler(entityName, entity, writeOpts));
+  }
+  if (verbs.list) {
+    r.queryHandler(defineEntityListHandler(entityName, entity, readOpts));
+  }
+  if (verbs.detail) {
+    r.queryHandler(defineEntityDetailHandler(entityName, entity, readOpts));
+  }
+}

package/src/engine/index.ts

@@ -66,6 +66,9 @@ export {
   defineEntityUpdateHandler,
   defineEntityWriteHandler,
   defineProjectionQueryHandler,
+  type EntityCrudRegistrar,
+  type RegisterEntityCrudOptions,
+  registerEntityCrud,
 } from "./entity-handlers";
 export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";