@cosmicdrift/kumiko-framework 0.15.0 → 0.18.0

package/src/pipeline/__tests__/dispatcher-utils.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import { createSystemUser } from "../../engine/system-user";
+import { InternalError } from "../../errors";
+import {
+  describeShape,
+  dispatcherSpanAttributes,
+  extractNestedSpecs,
+  isFailedWriteResult,
+  isLifecycleResult,
+  isWriteResultShape,
+  prefixValidationPath,
+  resolveType,
+  wrapToKumiko,
+} from "../dispatcher-utils";
+
+describe("isFailedWriteResult", () => {
+  test("narrows failed write results", () => {
+    const result = { isSuccess: false as const, error: { code: "validation_error" } };
+    expect(isFailedWriteResult(result)).toBe(true);
+    expect(isFailedWriteResult({ isSuccess: true, data: {} })).toBe(false);
+  });
+});
+
+describe("isWriteResultShape / isLifecycleResult", () => {
+  test("detects write-result envelope", () => {
+    expect(isWriteResultShape({ isSuccess: true, data: 1 })).toBe(true);
+    expect(isWriteResultShape({ kind: "created" })).toBe(false);
+  });
+
+  test("detects lifecycle results", () => {
+    expect(isLifecycleResult({ kind: "deleted" })).toBe(true);
+    expect(isLifecycleResult(null)).toBe(false);
+  });
+});
+
+describe("describeShape", () => {
+  test("summarizes unknown values", () => {
+    expect(describeShape(null)).toBe("null");
+    expect(describeShape("x")).toBe("string");
+    expect(describeShape({ a: 1, b: 2 })).toContain("object with keys");
+  });
+});
+
+describe("dispatcherSpanAttributes", () => {
+  test("includes handler, operation, user, tenant, optional feature", () => {
+    const user = createSystemUser("tenant-1");
+    const attrs = dispatcherSpanAttributes("feat:query:task:list", "query", user, "feat");
+    expect(attrs).toMatchObject({
+      "kumiko.handler": "feat:query:task:list",
+      "kumiko.operation": "query",
+      "kumiko.feature": "feat",
+    });
+  });
+});
+
+describe("prefixValidationPath", () => {
+  test("prefixes validation field paths", () => {
+    const info = {
+      code: "validation_error",
+      httpStatus: 400,
+      i18nKey: "errors.validation.failed",
+      message: "Validation failed",
+      details: {
+        fields: [{ path: "title", code: "too_small", i18nKey: "errors.validation.too_small" }],
+      },
+    };
+    const prefixed = prefixValidationPath(info, "tasks.0");
+    const fields = (prefixed.details as { fields: { path: string }[] }).fields;
+    expect(fields[0]?.path).toBe("tasks.0.title");
+  });
+
+  test("leaves non-validation errors unchanged", () => {
+    const info = {
+      code: "not_found",
+      httpStatus: 404,
+      i18nKey: "errors.notFound",
+      message: "missing",
+    };
+    expect(prefixValidationPath(info, "x")).toBe(info);
+  });
+});
+
+describe("resolveType", () => {
+  test("unwraps HandlerRef objects", () => {
+    expect(resolveType({ name: "feat:write:task:create" })).toBe("feat:write:task:create");
+    expect(resolveType("feat:query:task:list")).toBe("feat:query:task:list");
+  });
+});
+
+describe("wrapToKumiko", () => {
+  test("passes through KumikoError instances", () => {
+    const err = new InternalError();
+    expect(wrapToKumiko(err)).toBe(err);
+  });
+
+  test("wraps generic Error as InternalError", () => {
+    const wrapped = wrapToKumiko(new TypeError("boom"));
+    expect(wrapped.code).toBe("internal_error");
+    expect(wrapped.cause).toBeInstanceOf(TypeError);
+  });
+});
+
+describe("extractNestedSpecs", () => {
+  test("returns null for non-create handlers", () => {
+    expect(extractNestedSpecs("feat:write:task:update", { tasks: [] }, {} as never)).toBeNull();
+  });
+});

package/src/pipeline/__tests__/redis-keys.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test";
+import { RedisKeys } from "../redis-keys";
+
+describe("RedisKeys", () => {
+  test("uses unique kumiko-prefixed namespaces", () => {
+    const values = Object.values(RedisKeys);
+    expect(new Set(values).size).toBe(values.length);
+    for (const key of values) {
+      expect(key.startsWith("kumiko:")).toBe(true);
+    }
+  });
+});

package/src/pipeline/dispatcher-utils.ts

@@ -6,7 +6,13 @@ import type {
   SessionUser,
   WriteResult,
 } from "../engine/types";
-import { InternalError, isKumikoError, type KumikoError, type WriteErrorInfo } from "../errors";
+import {
+  type FieldIssue,
+  InternalError,
+  isKumikoError,
+  type KumikoError,
+  type WriteErrorInfo,
+} from "../errors";
 
 export type FailedWriteResult = Extract<WriteResult, { isSuccess: false }>;
 
@@ -146,12 +152,7 @@ export function prefixValidationPath(info: WriteErrorInfo, prefix: string): Writ
   if (info.code !== "validation_error") return info;
   const details = info.details as // @cast-boundary error-details
     | {
-        fields?: readonly {
-          path: string;
-          code: string;
-          i18nKey: string;
-          params?: Readonly<Record<string, unknown>>;
-        }[];
+        fields?: readonly FieldIssue[];
       }
     | undefined;
   const fields = details?.fields;

package/src/stack/request-helper.ts

@@ -4,6 +4,44 @@ import type { SessionUser } from "../engine/types";
 
 export type BatchCommand = { type: string; payload: unknown };
 
+type WireErrorBody = {
+  readonly code?: string;
+  readonly details?: {
+    readonly causeName?: string;
+    readonly causeMessage?: string;
+    readonly causeStack?: string;
+  };
+};
+
+function formatWriteFailure(type: string, body: unknown): string {
+  const parsed = body as {
+    isSuccess?: boolean;
+    error?: WireErrorBody | string;
+  };
+  const code =
+    (typeof parsed.error === "object" ? parsed.error?.code : undefined) ??
+    (typeof parsed.error === "string" ? parsed.error : "unknown");
+  const details =
+    typeof parsed.error === "object" && parsed.error?.details !== undefined
+      ? parsed.error.details
+      : undefined;
+  const causeMessage =
+    details && typeof details === "object" && "causeMessage" in details
+      ? String((details as { causeMessage?: unknown }).causeMessage ?? "")
+      : "";
+  const causeName =
+    details && typeof details === "object" && "causeName" in details
+      ? String((details as { causeName?: unknown }).causeName ?? "")
+      : "";
+  if (code === "internal_error" && (causeMessage || causeName)) {
+    return `Expected write "${type}" to succeed but got error: ${code} (${causeName}: ${causeMessage})`;
+  }
+  if (details !== undefined) {
+    return `Expected write "${type}" to succeed but got error: ${code} — ${JSON.stringify(details)}`;
+  }
+  return `Expected write "${type}" to succeed but got error: ${code}`;
+}
+
 export type RequestHelper = {
   write: (
     type: string,
@@ -123,10 +161,7 @@ export function createRequestHelper(app: Hono, jwt: JwtHelper): RequestHelper {
       // follow the error-contract shape { error: { code, i18nKey, ... } } with
       // a 4xx/5xx status — no isSuccess flag. Detect either.
       if (body.isSuccess !== true) {
-        const code =
-          (typeof body.error === "object" ? body.error?.code : undefined) ??
-          (typeof body.error === "string" ? body.error : "unknown");
-        throw new Error(`Expected write "${type}" to succeed but got error: ${code}`);
+        throw new Error(formatWriteFailure(type, body));
       }
       return body.data as T; // @cast-boundary engine-bridge
     },

package/src/stack/table-helpers.ts

@@ -107,7 +107,7 @@ export async function unsafePushTables(
         if (!prevIdxNames.has(idx.name)) {
           const kind = idx.unique ? "UNIQUE INDEX" : "INDEX";
           const colList = idx.columns.map((c) => `"${c}"`).join(", ");
-          await createIndexIfNotExists(db, kind, idx.name, meta.tableName, colList);
+          await createIndexIfNotExists(db, kind, idx.name, meta.tableName, colList, idx.whereSql);
         }
       }
     } else {

package/src/stack/test-stack.ts

@@ -4,6 +4,7 @@ import type { JwtHelper } from "../api/jwt";
 import { buildServer } from "../api/server";
 import { createSseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
+import { extractTableInfo } from "../db/query";
 import { createRegistry } from "../engine/registry";
 import type { FeatureDefinition, Registry, TenantId } from "../engine/types";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store";
@@ -207,10 +208,9 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     // exist; drizzle-kit's diff machinery would otherwise emit CREATE for
     // them again.
     const { tableExists } = await import("../db/schema-inspection");
-    const { getTableName } = await import("drizzle-orm");
     const missing: Record<string, unknown> = {};
     for (const [key, tbl] of Object.entries(projectionTables)) {
-      const physical = getTableName(tbl as Parameters<typeof getTableName>[0]); // @cast-boundary drizzle-bridge
+      const physical = extractTableInfo(tbl).name;
       if (await tableExists(testDb.db, `public.${physical}`)) continue;
       missing[key] = tbl;
     }

package/src/utils/__tests__/case.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { toSnakeCase } from "../case";
+
+describe("toSnakeCase", () => {
+  test("camelCase → snake_case", () => {
+    expect(toSnakeCase("tenantMembership")).toBe("tenant_membership");
+  });
+
+  test("kebab-case → snake_case", () => {
+    expect(toSnakeCase("billing-period")).toBe("billing_period");
+  });
+
+  test("single segment unchanged", () => {
+    expect(toSnakeCase("users")).toBe("users");
+  });
+});

package/src/utils/__tests__/is-plain-object.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { isPlainObject } from "../is-plain-object";
+
+describe("isPlainObject", () => {
+  test("accepts plain objects", () => {
+    expect(isPlainObject({})).toBe(true);
+    expect(isPlainObject({ a: 1 })).toBe(true);
+  });
+
+  test("rejects null, arrays, and primitives", () => {
+    expect(isPlainObject(null)).toBe(false);
+    expect(isPlainObject([])).toBe(false);
+    expect(isPlainObject("x")).toBe(false);
+    expect(isPlainObject(42)).toBe(false);
+  });
+});

package/src/utils/__tests__/parse-string-array-json.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { parseStringArrayJson } from "../parse-string-array-json";
+
+describe("parseStringArrayJson", () => {
+  test("parses string array", () => {
+    expect(parseStringArrayJson('["admin","editor"]')).toEqual(["admin", "editor"]);
+  });
+
+  test("returns fallback on invalid JSON", () => {
+    expect(parseStringArrayJson("{bad", ["guest"])).toEqual(["guest"]);
+  });
+
+  test("returns fallback when JSON is not a string array", () => {
+    expect(parseStringArrayJson("[1,2]", [])).toEqual([]);
+  });
+});

package/src/utils/__tests__/safe-json.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { parseJsonOrThrow, parseJsonSafe } from "../safe-json";
+
+describe("parseJsonSafe", () => {
+  test("parses valid JSON", () => {
+    expect(parseJsonSafe<{ a: number } | null>('{"a":1}', null)).toEqual({ a: 1 });
+  });
+
+  test("returns fallback on invalid JSON", () => {
+    expect(parseJsonSafe("{bad", { ok: false })).toEqual({ ok: false });
+  });
+});
+
+describe("parseJsonOrThrow", () => {
+  test("parses valid JSON", () => {
+    expect(parseJsonOrThrow<number[]>("[1,2]", "test")).toEqual([1, 2]);
+  });
+
+  test("throws with context on invalid JSON", () => {
+    expect(() => parseJsonOrThrow("{", "roles column")).toThrow(/Invalid JSON in roles column/);
+  });
+});

package/src/utils/case.ts

@@ -0,0 +1,6 @@
+// Accepts both camelCase (`tenantMembership`) and kebab-case (`tenant-membership`)
+// names. Kebab is canonical for new multi-word identifiers; camelCase remains
+// supported for shipped code.
+export function toSnakeCase(str: string): string {
+  return str.replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}

package/src/utils/index.ts

@@ -1,5 +1,8 @@
 export { assertUnreachable } from "./assert";
+export { toSnakeCase } from "./case";
 export { readPositiveIntEnv } from "./env-parse";
 export { generateId } from "./ids";
-export { parseJsonOrThrow, parseJsonSafe } from "./safe-json";
+export { isPlainObject } from "./is-plain-object";
+export { parseStringArrayJson } from "./parse-string-array-json";
+export { parseJsonOrThrow, parseJsonSafe, stringifyJson } from "./safe-json";
 export { parseRoles } from "./serialization";

package/src/utils/is-plain-object.ts

@@ -0,0 +1,4 @@
+/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/utils/parse-string-array-json.ts

@@ -0,0 +1,14 @@
+import { parseJsonSafe } from "./safe-json";
+
+/** Parses a JSON-encoded string array from DB/cache columns; returns fallback on invalid input. */
+export function parseStringArrayJson(
+  raw: string,
+  fallback: readonly string[] = [],
+): readonly string[] {
+  const parsed = parseJsonSafe<unknown>(raw, null);
+  if (parsed === null) return fallback;
+  if (Array.isArray(parsed) && parsed.every((x) => typeof x === "string")) {
+    return parsed;
+  }
+  return fallback;
+}

package/src/utils/safe-json.ts

@@ -28,3 +28,22 @@ export function parseJsonOrThrow<T>(raw: string, context: string): T {
     throw new Error(`Invalid JSON in ${context}: ${msg}`);
   }
 }
+
+/** JSON.stringify that survives BigInt / Temporal values from DB rows. */
+export function stringifyJson(value: unknown): string {
+  return JSON.stringify(value, (_key, v) => {
+    if (typeof v === "bigint") {
+      const asNumber = Number(v);
+      if (
+        asNumber <= Number.MAX_SAFE_INTEGER &&
+        asNumber >= Number.MIN_SAFE_INTEGER &&
+        BigInt(asNumber) === v
+      ) {
+        return asNumber;
+      }
+      return v.toString();
+    }
+    if (v instanceof Temporal.Instant) return v.toString();
+    return v;
+  });
+}