@cosmicdrift/kumiko-framework 0.174.1 → 0.176.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.174.1",
+  "version": "0.176.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>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.174.1",
+    "@cosmicdrift/kumiko-types": "0.176.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.27",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.174.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.176.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/entity-table-from-registry.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../../engine/define-feature";
+import { createEntity, createTextField } from "../../engine/factories";
+import { createRegistry } from "../../engine/registry";
+import { extractTableName, type SchemaTable } from "../dialect";
+import { entityTableFromRegistry } from "../entity-table-from-registry";
+import { buildEntityTable } from "../table-builder";
+
+function unitEntity() {
+  return createEntity({ table: "read_units", fields: { name: createTextField() } });
+}
+
+describe("entityTableFromRegistry", () => {
+  test("returns the table the registry booted, not one derived from the definition", () => {
+    const registry = createRegistry([
+      defineFeature("housing", (r) => {
+        r.entity("unit", unitEntity());
+      }),
+    ]);
+
+    const fromRegistry = entityTableFromRegistry(registry, "unit", unitEntity());
+    const projection = [...registry.getAllProjections().values()].find(
+      (p) => p.isImplicit && p.source === "unit",
+    );
+
+    expect(projection).toBeDefined();
+    expect(fromRegistry).toBe(projection?.table as SchemaTable);
+  });
+
+  // An entity nobody registered has no projection to read — the caller still
+  // gets a usable table instead of undefined, which is what made the helper
+  // worth having over a raw lookup.
+  test("falls back to deriving the table when no implicit projection exists", () => {
+    const registry = createRegistry([]);
+
+    const derived = entityTableFromRegistry(registry, "unit", unitEntity());
+
+    expect(extractTableName(derived)).toBe(
+      extractTableName(buildEntityTable("unit", unitEntity())),
+    );
+  });
+
+  // A projection for a different entity must not be handed back: both are
+  // implicit, and picking the first one would silently write into the wrong
+  // table.
+  test("ignores implicit projections of other entities", () => {
+    const registry = createRegistry([
+      defineFeature("housing", (r) => {
+        r.entity("unit", unitEntity());
+      }),
+    ]);
+
+    const other = createEntity({ table: "read_tenants", fields: { name: createTextField() } });
+    const derived = entityTableFromRegistry(registry, "tenant", other);
+
+    expect(extractTableName(derived)).toBe("read_tenants");
+  });
+});
+
+// Guards the cast in entity-table-from-registry.ts: the helper hands the
+// projection's table straight to callers that pass it to selectMany/executors,
+// so it has to carry the physical name those consumers read off it.
+test("the registry table carries a physical name", () => {
+  const registry = createRegistry([
+    defineFeature("housing", (r) => {
+      r.entity("unit", unitEntity());
+    }),
+  ]);
+
+  expect(extractTableName(entityTableFromRegistry(registry, "unit", unitEntity()))).toBe(
+    "read_units",
+  );
+});

package/src/db/entity-table-from-registry.ts

@@ -0,0 +1,31 @@
+// The table an entity actually lives in, as the booted registry sees it.
+//
+// `buildEntityTable` derives a table from the entity definition alone, which is
+// right until something changed the projection after registration — an
+// extendEntityProjection, a featureName prefix, a table override. The registry
+// carries the result of all of that, so a caller that needs to read or write
+// the same rows the pipeline writes has to ask the registry first and may only
+// fall back to deriving.
+//
+// Callers are the ones holding a registry and an entity definition but no
+// executor: seeds, jobs and consumers that talk to a feature's read model
+// directly.
+
+import type { Registry } from "../engine";
+import type { SchemaTable } from "./dialect";
+import { buildEntityTable } from "./table-builder";
+
+export function entityTableFromRegistry(
+  registry: Registry,
+  entityName: string,
+  entity: Parameters<typeof buildEntityTable>[1],
+): SchemaTable {
+  for (const projection of registry.getAllProjections().values()) {
+    if (!projection.isImplicit) continue;
+    if (projection.source !== entityName) continue;
+    // @cast-boundary registry-projection — ProjectionDefinition.table is the
+    // untyped table object every projection registrar accepts.
+    return projection.table as SchemaTable;
+  }
+  return buildEntityTable(entityName, entity);
+}

package/src/db/index.ts

@@ -49,6 +49,7 @@ export {
   decryptEntityFieldValues,
   encryptEntityFieldValues,
 } from "./entity-field-encryption";
+export { entityTableFromRegistry } from "./entity-table-from-registry";
 export type {
   BuildEntityTableMetaOptions,
   ColumnMeta,