@cosmicdrift/kumiko-framework 0.1.0

package/src/engine/__tests__/factories-time.test.ts

@@ -0,0 +1,158 @@
+// Unit-Tests für die neuen Time-Field-Factories
+// (createTimestampField, createTzField, locatedTimestamp).
+//
+// Test-Fokus: korrektes Field-Shape + locatedBy-Marker-Verdrahtung. Die
+// echte TZ-Konvertierung (Wall-Clock ↔ UTC) testen wir später beim
+// DB-Wrapper-Schritt.
+
+import { describe, expect, test } from "vitest";
+import {
+  createLocatedTimestampField,
+  createTimestampField,
+  createTzField,
+  locatedTimestamp,
+} from "../factories";
+
+describe("createTimestampField", () => {
+  test("default-Form ist nicht-required UTC-Instant ohne locatedBy", () => {
+    expect(createTimestampField()).toEqual({
+      type: "timestamp",
+      required: false,
+    });
+  });
+
+  test("kann required gesetzt werden", () => {
+    expect(createTimestampField({ required: true })).toEqual({
+      type: "timestamp",
+      required: true,
+    });
+  });
+
+  test("kann mit locatedBy markiert werden (für ad-hoc Cases)", () => {
+    expect(createTimestampField({ locatedBy: "myTz" })).toEqual({
+      type: "timestamp",
+      required: false,
+      locatedBy: "myTz",
+    });
+  });
+
+  test("kann sensitive markiert sein (PII / Audit-Schutz)", () => {
+    const f = createTimestampField({ sensitive: true });
+    expect(f.sensitive).toBe(true);
+  });
+});
+
+describe("createTzField", () => {
+  test("default-Form ist nicht-required IANA-Zone-Slot", () => {
+    expect(createTzField()).toEqual({ type: "tz", required: false });
+  });
+
+  test("required + access-rules übernimmt Overrides", () => {
+    const f = createTzField({
+      required: true,
+      access: { read: ["Admin"] },
+    });
+    expect(f.required).toBe(true);
+    expect(f.access).toEqual({ read: ["Admin"] });
+  });
+});
+
+describe("locatedTimestamp(name) Helper", () => {
+  test("erzeugt korrektes Pair aus <name>At + <name>Tz mit locatedBy-Verdrahtung", () => {
+    const fields = locatedTimestamp("pickup");
+    expect(fields).toEqual({
+      pickupAt: { type: "timestamp", locatedBy: "pickupTz" },
+      pickupTz: { type: "tz" },
+    });
+  });
+
+  test("required-Override propagiert auf BEIDE Felder", () => {
+    const fields = locatedTimestamp("delivery", { required: true });
+    expect(fields).toEqual({
+      deliveryAt: { type: "timestamp", locatedBy: "deliveryTz", required: true },
+      deliveryTz: { type: "tz", required: true },
+    });
+  });
+
+  test("access-Override propagiert auf BEIDE Felder (Field-Level Read-Access)", () => {
+    const fields = locatedTimestamp("internal", {
+      access: { read: ["Dispatcher"] },
+    });
+    expect(fields).toEqual({
+      internalAt: {
+        type: "timestamp",
+        locatedBy: "internalTz",
+        access: { read: ["Dispatcher"] },
+      },
+      internalTz: { type: "tz", access: { read: ["Dispatcher"] } },
+    });
+  });
+
+  test("locatedBy-Marker zeigt immer auf das EIGENE Tz-Feld (nicht auf einen anderen Namen)", () => {
+    // Das ist der Kern des Patterns — wenn die zwei Felder nicht
+    // konsistent verdrahtet sind, fliegt der Boot-Validator (kommt in
+    // späterer Iteration). Hier prüfen wir die Helper-Garantie.
+    for (const name of ["a", "x_y", "long_field_name"]) {
+      const fields = locatedTimestamp(name);
+      const at = fields[`${name}At`];
+      if (!at || at.type !== "timestamp") throw new Error("at field missing");
+      expect(at.locatedBy).toBe(`${name}Tz`);
+    }
+  });
+
+  test("Spread in createEntity-fields Kompositions-tauglich", () => {
+    // Realer Use-Case: pickup + delivery in einer Entity, plus normale Felder.
+    const entityFields = {
+      ...locatedTimestamp("pickup"),
+      ...locatedTimestamp("delivery"),
+      // Kein Konflikt zwischen den beiden Pairs.
+    };
+    expect(Object.keys(entityFields).sort()).toEqual([
+      "deliveryAt",
+      "deliveryTz",
+      "pickupAt",
+      "pickupTz",
+    ]);
+  });
+});
+
+describe("createLocatedTimestampField (Phase A — atomarer Field-Type)", () => {
+  test("default-Form ist nicht-required mit type 'locatedTimestamp'", () => {
+    expect(createLocatedTimestampField()).toEqual({
+      type: "locatedTimestamp",
+      required: false,
+    });
+  });
+
+  test("required-Override propagiert", () => {
+    expect(createLocatedTimestampField({ required: true })).toEqual({
+      type: "locatedTimestamp",
+      required: true,
+    });
+  });
+
+  test("access-Override propagiert (Field-Level Read-Access)", () => {
+    const f = createLocatedTimestampField({ access: { read: ["Dispatcher"] } });
+    expect(f).toEqual({
+      type: "locatedTimestamp",
+      required: false,
+      access: { read: ["Dispatcher"] },
+    });
+  });
+
+  test("sensitive-Override propagiert (PII-Schutz)", () => {
+    const f = createLocatedTimestampField({ sensitive: true });
+    expect(f.sensitive).toBe(true);
+  });
+
+  test("ein einziges Field-Objekt — kein Pair wie der alte locatedTimestamp helper", () => {
+    // Die neue Form: r.entity({ pickup: createLocatedTimestampField() })
+    // erzeugt EIN Schema-Feld (nicht zwei). Die zwei DB-Spalten + drei
+    // API-Felder kommen aus dem Framework-Auto-Convert (Phase B–D).
+    const field = createLocatedTimestampField();
+    expect(field.type).toBe("locatedTimestamp");
+    // Keine `at`/`tz`/`utc` Sub-Felder im Schema-Object selbst.
+    expect("at" in field).toBe(false);
+    expect("tz" in field).toBe(false);
+  });
+});

package/src/engine/__tests__/field-predicates.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "vitest";
+import type { AnyFileFieldDef, FieldDefinition } from "../types";
+import { isFileField } from "../types";
+
+describe("isFileField()", () => {
+  test("accepts all four file variants", () => {
+    const variants: FieldDefinition[] = [
+      { type: "file" },
+      { type: "image" },
+      { type: "files" },
+      { type: "images" },
+    ];
+    for (const f of variants) expect(isFileField(f)).toBe(true);
+  });
+
+  test("rejects non-file variants", () => {
+    const variants: FieldDefinition[] = [
+      { type: "text" },
+      { type: "number" },
+      { type: "boolean" },
+      { type: "select", options: ["a", "b"] },
+      { type: "money" },
+      { type: "date" },
+      { type: "embedded", schema: {} },
+    ];
+    for (const f of variants) expect(isFileField(f)).toBe(false);
+  });
+
+  test("rejects undefined", () => {
+    expect(isFileField(undefined)).toBe(false);
+  });
+
+  test("narrows the type so readers can access file-specific props", () => {
+    const field: FieldDefinition | undefined = {
+      type: "file",
+      maxSize: "5mb",
+      accept: ["image/*"],
+    };
+    if (isFileField(field)) {
+      // If the TypeGuard didn't narrow, this would not compile.
+      const narrowed: AnyFileFieldDef = field;
+      expect(narrowed.maxSize).toBe("5mb");
+      expect(narrowed.accept).toEqual(["image/*"]);
+    } else {
+      throw new Error("isFileField should have narrowed to AnyFileFieldDef");
+    }
+  });
+});

package/src/engine/__tests__/hook-phases.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEntity, createRegistry, defineFeature, HookPhases } from "../index";
+import type { PostSaveHookFn } from "../types";
+
+// These tests lock in the phase defaults + filtering so the invariants survive
+// refactors. Behavior under test:
+//   - r.hook("postSave", ...) defaults to afterCommit
+//   - r.hook("postSave", ..., { phase: inTransaction }) routes to the inTx bucket
+//   - r.hook("preDelete", ...) always lands in inTransaction (no option)
+//   - Registry getters filter by phase when asked, return all otherwise
+
+const noopSave: PostSaveHookFn = async () => undefined;
+
+describe("HookPhases defaults", () => {
+  test("postSave hook without options defaults to afterCommit phase", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.writeHandler("thing:create", z.object({}), async () => ({ isSuccess: true, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("postSave", "thing:create", noopSave);
+    });
+
+    const entry = feature.hooks.postSave["thing:create"];
+    expect(entry).toHaveLength(1);
+    expect(entry?.[0]?.phase).toBe(HookPhases.afterCommit);
+  });
+
+  test("postSave hook respects explicit phase option", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.writeHandler("thing:create", z.object({}), async () => ({ isSuccess: true, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("postSave", "thing:create", noopSave, { phase: HookPhases.inTransaction });
+    });
+
+    const entry = feature.hooks.postSave["thing:create"];
+    expect(entry?.[0]?.phase).toBe(HookPhases.inTransaction);
+  });
+
+  test("preDelete hook is always inTransaction (no option)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.writeHandler(
+        "thing:delete",
+        z.object({ id: z.uuid() }),
+        async () => ({
+          isSuccess: true,
+          data: null,
+        }),
+        { access: { openToAll: true } },
+      );
+      r.hook("preDelete", "thing:delete", async () => undefined);
+    });
+
+    const entry = feature.hooks.preDelete["thing:delete"];
+    expect(entry?.[0]?.phase).toBe(HookPhases.inTransaction);
+  });
+
+  test("entityHook postSave defaults to afterCommit, preDelete is forced inTransaction", () => {
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.entityHook("postSave", thing, noopSave);
+      r.entityHook("preDelete", thing, async () => undefined);
+    });
+
+    expect(feature.entityHooks.postSave["thing"]?.[0]?.phase).toBe(HookPhases.afterCommit);
+    expect(feature.entityHooks.preDelete["thing"]?.[0]?.phase).toBe(HookPhases.inTransaction);
+  });
+});
+
+describe("Registry phase filtering", () => {
+  test("getPostSaveHooks filters by phase when given", () => {
+    const inTxFn: PostSaveHookFn = async () => undefined;
+    const afterFn: PostSaveHookFn = async () => undefined;
+
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.writeHandler("thing:create", z.object({}), async () => ({ isSuccess: true, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("postSave", "thing:create", inTxFn, { phase: HookPhases.inTransaction });
+      r.hook("postSave", "thing:create", afterFn); // default afterCommit
+    });
+
+    const registry = createRegistry([feature]);
+    const handlerQn = "test:write:thing:create";
+
+    const inTxOnly = registry.getPostSaveHooks(handlerQn, HookPhases.inTransaction);
+    const afterOnly = registry.getPostSaveHooks(handlerQn, HookPhases.afterCommit);
+    const all = registry.getPostSaveHooks(handlerQn);
+
+    expect(inTxOnly).toHaveLength(1);
+    expect(inTxOnly[0]).toBe(inTxFn);
+    expect(afterOnly).toHaveLength(1);
+    expect(afterOnly[0]).toBe(afterFn);
+    expect(all).toHaveLength(2);
+  });
+
+  test("getPostSaveHooks returns empty array when no hooks for handler", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.writeHandler("thing:create", z.object({}), async () => ({ isSuccess: true, data: null }), {
+        access: { openToAll: true },
+      });
+    });
+
+    const registry = createRegistry([feature]);
+    expect(registry.getPostSaveHooks("test:write:thing:create")).toEqual([]);
+    expect(registry.getPostSaveHooks("test:write:thing:create", HookPhases.inTransaction)).toEqual(
+      [],
+    );
+  });
+
+  test("getEntityPostSaveHooks filters by phase", () => {
+    const inTxFn: PostSaveHookFn = async () => undefined;
+    const afterFn: PostSaveHookFn = async () => undefined;
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.entityHook("postSave", thing, inTxFn, { phase: HookPhases.inTransaction });
+      r.entityHook("postSave", thing, afterFn);
+    });
+
+    const registry = createRegistry([feature]);
+    expect(registry.getEntityPostSaveHooks("thing", HookPhases.inTransaction)).toEqual([inTxFn]);
+    expect(registry.getEntityPostSaveHooks("thing", HookPhases.afterCommit)).toEqual([afterFn]);
+    expect(registry.getEntityPostSaveHooks("thing")).toHaveLength(2);
+  });
+});

package/src/engine/__tests__/identifiers.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "vitest";
+import { parseTenantId } from "../types/identifiers";
+
+describe("parseTenantId", () => {
+  test("accepts canonical lowercase UUIDs", () => {
+    expect(parseTenantId("00000000-0000-4000-8000-000000000001")).toBe(
+      "00000000-0000-4000-8000-000000000001",
+    );
+  });
+
+  test("rejects non-UUID strings", () => {
+    expect(parseTenantId("not-a-uuid")).toBeNull();
+    expect(parseTenantId("acme")).toBeNull();
+    expect(parseTenantId("")).toBeNull();
+  });
+
+  test("rejects SQL-injection-shaped probes", () => {
+    expect(parseTenantId("'; DROP TABLE tenants; --")).toBeNull();
+    expect(parseTenantId("../../../etc/passwd")).toBeNull();
+  });
+
+  test("rejects uppercase UUIDs (canonical form is lowercase)", () => {
+    // The framework writes lowercase everywhere — accepting uppercase here
+    // would let two different strings produce the same logical tenant and
+    // diverge on string-equality checks downstream.
+    expect(parseTenantId("00000000-0000-4000-8000-00000000000A")).toBeNull();
+  });
+
+  test("rejects non-string inputs", () => {
+    expect(parseTenantId(undefined)).toBeNull();
+    expect(parseTenantId(null)).toBeNull();
+    expect(parseTenantId(123)).toBeNull();
+    expect(parseTenantId({})).toBeNull();
+  });
+});

package/src/engine/__tests__/lifecycle-hooks.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEntity, createRegistry, defineFeature } from "../index";
+import type { PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn, SaveContext } from "../types";
+
+const stubHandler = async () => ({ isSuccess: true as const, data: null });
+
+describe("lifecycle hook registration", () => {
+  test("preSave hooks are registered", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+      r.hook("preSave", "user", async (changes) => {
+        changes["email"] = (changes["email"] as string).toLowerCase();
+        return changes;
+      });
+    });
+
+    expect(Object.keys(feature.hooks.preSave)).toContain("user");
+  });
+
+  test("postSave hooks are registered", () => {
+    const feature = defineFeature("test", (r) => {
+      r.hook("postSave", "user", async () => {});
+    });
+
+    expect(Object.keys(feature.hooks.postSave)).toContain("user");
+  });
+
+  test("preDelete hooks are registered", () => {
+    const feature = defineFeature("test", (r) => {
+      r.hook("preDelete", "user", async () => {});
+    });
+
+    expect(Object.keys(feature.hooks.preDelete)).toContain("user");
+  });
+
+  test("postDelete hooks are registered", () => {
+    const feature = defineFeature("test", (r) => {
+      r.hook("postDelete", "user", async () => {});
+    });
+
+    expect(Object.keys(feature.hooks.postDelete)).toContain("user");
+  });
+
+  test("multiple hooks on same entity are collected in order", () => {
+    const feature = defineFeature("test", (r) => {
+      r.hook("preSave", "user", async (changes) => changes);
+      r.hook("preSave", "user", async (changes) => changes);
+    });
+
+    const hooks = feature.hooks.preSave["user"];
+    expect(hooks).toHaveLength(2);
+  });
+
+  test("validation hooks still work alongside lifecycle hooks", () => {
+    const feature = defineFeature("test", (r) => {
+      r.hook("validation", "userForm", () => null);
+      r.hook("preSave", "user", async (changes) => changes);
+      r.hook("postSave", "user", async () => {});
+    });
+
+    expect(feature.hooks.validation["userForm"]).toBeDefined();
+    expect(feature.hooks.preSave["user"]).toHaveLength(1);
+    expect(feature.hooks.postSave["user"]).toHaveLength(1);
+  });
+});
+
+describe("lifecycle hooks in registry", () => {
+  test("merges preSave hooks within same feature", () => {
+    const f1 = defineFeature("a", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+      r.writeHandler("user", z.object({}), stubHandler, { access: { openToAll: true } });
+      r.hook("preSave", "user", async (changes) => changes);
+      r.hook("preSave", "user", async (changes) => changes);
+    });
+
+    const registry = createRegistry([f1]);
+    expect(registry.getPreSaveHooks("a:write:user")).toHaveLength(2);
+  });
+
+  test("cross-feature hooks use full prefixed name", () => {
+    const f1 = defineFeature("a", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+      r.writeHandler("user", z.object({}), stubHandler, { access: { openToAll: true } });
+      r.hook("postSave", "user", async () => {});
+    });
+    // Feature b hooks into a.user by using the full prefixed name
+    const f2 = defineFeature("b", (r) => {
+      r.writeHandler("a.user", z.object({}), stubHandler, { access: { openToAll: true } });
+      r.hook("postSave", "a.user", async () => {});
+      r.hook("postSave", "a.user", async () => {});
+    });
+
+    const registry = createRegistry([f1, f2]);
+    // f1 registers as "a:write:user", f2 registers as "b:write:a-user" — different keys
+    expect(registry.getPostSaveHooks("a:write:user")).toHaveLength(1);
+    expect(registry.getPostSaveHooks("b:write:a-user")).toHaveLength(2);
+  });
+
+  test("returns empty array for entity without hooks", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+    });
+
+    const registry = createRegistry([feature]);
+    expect(registry.getPreSaveHooks("test:write:user")).toEqual([]);
+    expect(registry.getPostSaveHooks("test:write:user")).toEqual([]);
+    expect(registry.getPreDeleteHooks("test:write:user")).toEqual([]);
+    expect(registry.getPostDeleteHooks("test:write:user")).toEqual([]);
+    expect(registry.getPreQueryHooks("test:query:user")).toEqual([]);
+  });
+});
+
+describe("preSave hook behavior", () => {
+  test("preSave receives changes and can modify them", async () => {
+    const hook: PreSaveHookFn = async (changes, ctx) => {
+      expect(ctx.isNew).toBe(false);
+      expect(ctx.previous["email"]).toBe("old@test.de");
+      return { ...changes, email: (changes["email"] as string).toLowerCase() };
+    };
+
+    const result = await hook(
+      { email: "MARC@TEST.DE" },
+      { previous: { email: "old@test.de" }, isNew: false },
+    );
+    expect(result["email"]).toBe("marc@test.de");
+  });
+
+  test("preSave knows if it is a create (isNew=true)", async () => {
+    let wasNew: boolean | undefined;
+    const hook: PreSaveHookFn = async (changes, ctx) => {
+      wasNew = ctx.isNew;
+      return changes;
+    };
+
+    await hook({}, { previous: {}, isNew: true });
+    expect(wasNew).toBe(true);
+  });
+
+  test("preSave can abort by throwing", async () => {
+    const hook: PreSaveHookFn = async () => {
+      throw new Error("blocked_by_policy");
+    };
+
+    await expect(hook({}, { previous: {}, isNew: false })).rejects.toThrow("blocked_by_policy");
+  });
+});
+
+describe("postSave hook behavior", () => {
+  test("postSave receives full SaveContext with changes and previous", async () => {
+    let received: SaveContext | undefined;
+    const hook: PostSaveHookFn = async (result) => {
+      received = result;
+    };
+
+    await hook(
+      {
+        kind: "save",
+        id: 42,
+        data: { email: "new@test.de", status: "Started" },
+        changes: { status: "Started" },
+        previous: { email: "new@test.de", status: "Draft" },
+        isNew: false,
+      },
+      {},
+    );
+
+    expect(received?.id).toBe(42);
+    expect(received?.changes["status"]).toBe("Started");
+    expect(received?.previous["status"]).toBe("Draft");
+    expect(received?.isNew).toBe(false);
+  });
+
+  test("postSave: detect status transition for email trigger", async () => {
+    let shouldSendEmail = false;
+
+    const hook: PostSaveHookFn = async (result) => {
+      if (result.changes["status"] === "Started" && result.previous["status"] !== "Started") {
+        shouldSendEmail = true;
+      }
+    };
+
+    // First time: Draft → Started → send email
+    await hook(
+      {
+        kind: "save",
+        id: 1,
+        data: {},
+        changes: { status: "Started" },
+        previous: { status: "Draft" },
+        isNew: false,
+      },
+      {},
+    );
+    expect(shouldSendEmail).toBe(true);
+
+    // Second save: Started → Started (no change) → no email
+    shouldSendEmail = false;
+    await hook(
+      {
+        kind: "save",
+        id: 1,
+        data: {},
+        changes: { status: "Started" },
+        previous: { status: "Started" },
+        isNew: false,
+      },
+      {},
+    );
+    expect(shouldSendEmail).toBe(false);
+  });
+});
+
+describe("preDelete hook behavior", () => {
+  test("preDelete receives full entity data before deletion", async () => {
+    let receivedData: Record<string, unknown> | undefined;
+    const hook: PreDeleteHookFn = async (payload) => {
+      receivedData = payload.data;
+    };
+
+    await hook(
+      { kind: "delete", id: 1, data: { email: "delete-me@test.de", hasOrders: true } },
+      {},
+    );
+    expect(receivedData?.["email"]).toBe("delete-me@test.de");
+  });
+
+  test("preDelete can abort by throwing", async () => {
+    const hook: PreDeleteHookFn = async (payload) => {
+      if (payload.data["hasOrders"]) throw new Error("has_dependencies");
+    };
+
+    await expect(hook({ kind: "delete", id: 1, data: { hasOrders: true } }, {})).rejects.toThrow(
+      "has_dependencies",
+    );
+  });
+});