@cosmicdrift/kumiko-framework 0.14.0 → 0.16.0

package/src/db/__tests__/db-helpers.test.ts

@@ -1,369 +0,0 @@
-import { getTableName } from "drizzle-orm";
-import { getTableConfig } from "drizzle-orm/pg-core";
-import { describe, expect, test } from "vitest";
-import {
-  createBooleanField,
-  createEntity,
-  createImageField,
-  createMultiSelectField,
-  createSelectField,
-  createTextField,
-} from "../../engine";
-import type { EntityRelations } from "../../engine/types";
-import { decodeCursor, encodeCursor } from "../cursor";
-import { buildBaseColumns, buildDrizzleTable, toTableName } from "../table-builder";
-
-// --- Cursor encoding ---
-
-describe("cursor encoding", () => {
-  // String-Roundtrip seit Sprint F: encodeCursor akzeptiert string|number,
-  // decodeCursor returnt immer einen String — UUID-IDs (Default) brauchen
-  // keine Number-Kapsel, Integer-IDs werden via PG-Cast in der WHERE-Clause
-  // korrekt verglichen. Detail-Tests in cursor.test.ts.
-  test.each([1, 42, 999, 100000])("encodes and decodes integer id %i", (id) => {
-    const cursor = encodeCursor(id);
-    expect(decodeCursor(cursor)).toBe(String(id));
-  });
-
-  test("cursor is url-safe base64", () => {
-    const cursor = encodeCursor(12345);
-    expect(cursor).toMatch(/^[A-Za-z0-9_-]+$/);
-  });
-
-  test("throws on empty/corrupted cursor", () => {
-    expect(() => decodeCursor("")).toThrow(/invalid cursor/i);
-  });
-});
-
-// --- Base columns ---
-
-describe("buildBaseColumns", () => {
-  test("includes standard columns", () => {
-    const cols = buildBaseColumns(false);
-    expect(cols).toHaveProperty("id");
-    expect(cols).toHaveProperty("tenantId");
-    expect(cols).toHaveProperty("insertedAt");
-    expect(cols).toHaveProperty("modifiedAt");
-    expect(cols).toHaveProperty("insertedById");
-    expect(cols).toHaveProperty("modifiedById");
-  });
-
-  test("without softDelete has no isDeleted", () => {
-    const cols = buildBaseColumns(false);
-    expect(cols).not.toHaveProperty("isDeleted");
-  });
-
-  test("with softDelete includes isDeleted", () => {
-    const cols = buildBaseColumns(true);
-    expect(cols).toHaveProperty("isDeleted");
-  });
-});
-
-// --- Table builder ---
-
-describe("buildDrizzleTable", () => {
-  test("creates table with base columns + entity fields", () => {
-    const entity = createEntity({
-      table: "users",
-      fields: {
-        email: createTextField({ required: true }),
-        firstName: createTextField(),
-        isEnabled: createBooleanField({ default: true }),
-      },
-    });
-
-    const table = buildDrizzleTable("user", entity);
-
-    // Has base columns
-    expect(table["id"]).toBeDefined();
-    expect(table["tenantId"]).toBeDefined();
-    expect(table["insertedAt"]).toBeDefined();
-
-    // Has entity fields
-    expect(table["email"]).toBeDefined();
-    expect(table["firstName"]).toBeDefined();
-    expect(table["isEnabled"]).toBeDefined();
-  });
-
-  test("soft delete entity includes isDeleted column", () => {
-    const entity = createEntity({
-      table: "users",
-      fields: { email: createTextField() },
-      softDelete: true,
-    });
-
-    const table = buildDrizzleTable("user", entity);
-    expect(table["isDeleted"]).toBeDefined();
-  });
-
-  test("select field becomes text column", () => {
-    const entity = createEntity({
-      table: "users",
-      fields: {
-        locale: createSelectField({ options: ["de", "en"] as const }),
-      },
-    });
-
-    const table = buildDrizzleTable("user", entity);
-    expect(table["locale"]).toBeDefined();
-  });
-
-  test("multiSelect field becomes jsonb column with default []", () => {
-    const entity = createEntity({
-      table: "drivers",
-      fields: {
-        licenceClasses: createMultiSelectField({ options: ["B", "BE", "C"] as const }),
-      },
-    });
-
-    const table = buildDrizzleTable("driver", entity);
-    const config = getTableConfig(table);
-    const column = config.columns.find((c) => c.name === "licence_classes");
-    expect(column).toBeDefined();
-    // jsonb-customType: column-data-type ist string ("jsonb"); column-type
-    // hier reicht als Smoke — die Default-`[]`-Garantie testen wir indirekt
-    // über die Migration-Rebuild-Integration-Tests, die echte Inserts
-    // gegen Postgres machen.
-    expect(column?.dataType).toBe("json");
-    expect(column?.default).toEqual([]);
-  });
-
-  test("converts camelCase to snake_case", () => {
-    const entity = createEntity({
-      table: "users",
-      fields: {
-        firstName: createTextField(),
-        employmentType: createSelectField({ options: ["FullTime", "PartTime"] as const }),
-      },
-    });
-
-    const table = buildDrizzleTable("user", entity);
-    // Column objects exist under camelCase keys
-    expect(table["firstName"]).toBeDefined();
-    expect(table["employmentType"]).toBeDefined();
-  });
-
-  test("featureName option prefixes table name", () => {
-    const entity = createEntity({
-      table: "orders",
-      fields: { name: createTextField() },
-    });
-
-    const table = buildDrizzleTable("order", entity, { featureName: "shop" });
-    expect(getTableName(table)).toBe("shop_orders");
-  });
-
-  test("without featureName, table name is unchanged", () => {
-    const entity = createEntity({
-      table: "orders",
-      fields: { name: createTextField() },
-    });
-
-    const table = buildDrizzleTable("order", entity);
-    expect(getTableName(table)).toBe("orders");
-  });
-
-  test("derives table name from entityName when table is omitted", () => {
-    const entity = createEntity({ fields: { name: createTextField() } });
-    const table = buildDrizzleTable("task", entity);
-    expect(getTableName(table)).toBe("read_tasks");
-  });
-
-  test("derives table name with featureName prefix when table is omitted", () => {
-    const entity = createEntity({ fields: { name: createTextField() } });
-    const table = buildDrizzleTable("order", entity, { featureName: "shop" });
-    // featureName-Prefix landet zwischen `read_` und dem Plural — alle
-    // Read-Models starten konsistent mit `read_`, egal ob ein Feature-
-    // Prefix gesetzt ist oder nicht.
-    expect(getTableName(table)).toBe("read_shop_orders");
-  });
-});
-
-// --- Auto-Indices ---
-
-describe("buildDrizzleTable auto-indices", () => {
-  test("every table gets a tenant_id index", () => {
-    const entity = createEntity({
-      table: "users",
-      fields: { email: createTextField() },
-    });
-    const table = buildDrizzleTable("user", entity);
-    const { indexes } = getTableConfig(table);
-
-    const tenantIndex = indexes.find((idx) => idx.config.name === "users_tenant_id_idx");
-    expect(tenantIndex).toBeDefined();
-    expect(tenantIndex?.config.columns.map((c) => (c as { name: string }).name)).toEqual([
-      "tenant_id",
-    ]);
-  });
-
-  test("file field produces an index on its column", () => {
-    const entity = createEntity({
-      table: "documents",
-      fields: {
-        title: createTextField(),
-        avatar: createImageField(),
-      },
-    });
-    const table = buildDrizzleTable("document", entity);
-    const { indexes } = getTableConfig(table);
-
-    const avatarIndex = indexes.find((idx) => idx.config.name === "documents_avatar_idx");
-    expect(avatarIndex).toBeDefined();
-  });
-
-  test("index names include feature prefix when featureName is set", () => {
-    const entity = createEntity({
-      table: "items",
-      fields: { name: createTextField() },
-    });
-    const table = buildDrizzleTable("item", entity, { featureName: "shop" });
-    const { indexes } = getTableConfig(table);
-
-    expect(indexes.some((idx) => idx.config.name === "shop_items_tenant_id_idx")).toBe(true);
-  });
-
-  test("table without file fields or relations has only the tenant index", () => {
-    const entity = createEntity({
-      table: "notes",
-      fields: { body: createTextField() },
-    });
-    const table = buildDrizzleTable("note", entity);
-    const { indexes } = getTableConfig(table);
-
-    expect(indexes).toHaveLength(1);
-    expect(indexes[0]?.config.name).toBe("notes_tenant_id_idx");
-  });
-
-  test("belongsTo relations produce an index on their foreign key column", () => {
-    const entity = createEntity({
-      table: "tasks",
-      fields: {
-        title: createTextField({ required: true }),
-        assigneeId: createTextField(),
-        projectId: createTextField(),
-      },
-    });
-    const relations: EntityRelations = {
-      assignee: { type: "belongsTo", target: "user", foreignKey: "assigneeId" },
-      project: { type: "belongsTo", target: "project", foreignKey: "projectId" },
-    };
-    const table = buildDrizzleTable("task", entity, { relations });
-    const { indexes } = getTableConfig(table);
-
-    const names = indexes.map((i) => i.config.name);
-    expect(names).toContain("tasks_tenant_id_idx");
-    expect(names).toContain("tasks_assignee_id_idx");
-    expect(names).toContain("tasks_project_id_idx");
-  });
-
-  test("hasMany / manyToMany relations do NOT produce indexes on this table (their FK lives on the other side)", () => {
-    const entity = createEntity({
-      table: "teams",
-      fields: { name: createTextField() },
-    });
-    const relations: EntityRelations = {
-      members: { type: "hasMany", target: "user", foreignKey: "teamId" },
-      tags: {
-        type: "manyToMany",
-        target: "tag",
-        through: { table: "team_tags", sourceKey: "teamId", targetKey: "tagId" },
-      },
-    };
-    const table = buildDrizzleTable("team", entity, { relations });
-    const { indexes } = getTableConfig(table);
-
-    // Only the tenant index — hasMany FK lives on the "user" table; the join
-    // table for manyToMany isn't owned by this entity either.
-    expect(indexes).toHaveLength(1);
-    expect(indexes[0]?.config.name).toBe("teams_tenant_id_idx");
-  });
-
-  test("relation and file field on the same column deduplicate to one index", () => {
-    const entity = createEntity({
-      table: "photos",
-      fields: {
-        title: createTextField(),
-        ownerId: createImageField(), // contrived: name collides with an FK relation below
-      },
-    });
-    const relations: EntityRelations = {
-      owner: { type: "belongsTo", target: "user", foreignKey: "ownerId" },
-    };
-    const table = buildDrizzleTable("photo", entity, { relations });
-    const { indexes } = getTableConfig(table);
-
-    const names = indexes.map((i) => i.config.name);
-    // Exactly one owner_id index, not two
-    expect(names.filter((n) => n === "photos_owner_id_idx")).toHaveLength(1);
-  });
-});
-
-// --- toTableName ---
-
-describe("toTableName", () => {
-  test.each([
-    ["task", "read_tasks"],
-    ["user", "read_users"],
-    ["tenant", "read_tenants"],
-  ])("simple plural: %s → %s", (input, expected) => {
-    expect(toTableName(input)).toBe(expected);
-  });
-
-  test.each([
-    ["category", "read_categories"],
-    ["entity", "read_entities"],
-    ["policy", "read_policies"],
-  ])("y → ies: %s → %s", (input, expected) => {
-    expect(toTableName(input)).toBe(expected);
-  });
-
-  test.each([
-    ["key", "read_keys"],
-    ["survey", "read_surveys"],
-    ["day", "read_days"],
-  ])("vowel+y stays: %s → %s", (input, expected) => {
-    expect(toTableName(input)).toBe(expected);
-  });
-
-  test.each([
-    ["status", "read_statuses"],
-    ["address", "read_addresses"],
-    ["match", "read_matches"],
-    ["tax", "read_taxes"],
-    ["wish", "read_wishes"],
-  ])("sibilant → es: %s → %s", (input, expected) => {
-    expect(toTableName(input)).toBe(expected);
-  });
-
-  test.each([
-    ["memberTask", "read_member_tasks"],
-    ["userProfile", "read_user_profiles"],
-    ["orderItem", "read_order_items"],
-  ])("camelCase → snake_case + plural: %s → %s", (input, expected) => {
-    expect(toTableName(input)).toBe(expected);
-  });
-
-  test.each([
-    ["tenant-membership", "read_tenant_memberships"],
-    ["user-profile-address", "read_user_profile_addresses"],
-    ["invoice-issuer", "read_invoice_issuers"],
-  ])("kebab-case → snake_case + plural: %s → %s", (input, expected) => {
-    expect(toTableName(input)).toBe(expected);
-  });
-});
-
-// --- Sorting in CursorQueryOptions ---
-
-describe("sorting", () => {
-  test("CursorQueryOptions accepts sort and sortDirection", () => {
-    // Type-level test: this should compile
-    const opts: import("../cursor").CursorQueryOptions = {
-      tenantId: "00000000-0000-4000-8000-000000000001",
-      sort: "lastName",
-      sortDirection: "asc",
-    };
-    expect(opts.sort).toBe("lastName");
-    expect(opts.sortDirection).toBe("asc");
-  });
-});

package/src/db/__tests__/drizzle-helpers.integration.ts

@@ -1,186 +0,0 @@
-import { drizzle } from "drizzle-orm/postgres-js";
-import postgres from "postgres";
-import { afterAll, beforeAll, describe, expect, test } from "vitest";
-import { createBooleanField, createEntity, createTextField } from "../../engine";
-import { testTenantId, unsafeCreateEntityTable } from "../../stack";
-import { applyCursorQuery, encodeCursor } from "../cursor";
-import { buildDrizzleTable } from "../table-builder";
-
-function requireEnv(name: string): string {
-  const value = process.env[name];
-  if (!value) throw new Error(`Missing required env var: ${name}`);
-  return value;
-}
-
-const TEST_DB_URL = requireEnv("TEST_DATABASE_URL");
-
-type Row = Record<string, unknown>;
-
-const entity = createEntity({
-  table: "test_users",
-  // cursor-pagination uses gt(id, cursor) which relies on ordered integer ids.
-  // This test exercises that classic serial-PK path deliberately.
-  idType: "serial",
-  fields: {
-    email: createTextField({ required: true, searchable: true }),
-    firstName: createTextField({ searchable: true }),
-    isEnabled: createBooleanField({ default: true }),
-  },
-  softDelete: true,
-});
-
-const table = buildDrizzleTable("testUser", entity);
-
-let client: ReturnType<typeof postgres>;
-let db: ReturnType<typeof drizzle>;
-
-beforeAll(async () => {
-  const adminClient = postgres(TEST_DB_URL.replace(/\/[^/]+$/, "/postgres"), {
-    onnotice: () => {},
-  });
-  try {
-    await adminClient`DROP DATABASE IF EXISTS kumiko_test_step7`;
-    await adminClient`CREATE DATABASE kumiko_test_step7`;
-  } finally {
-    await adminClient.end();
-  }
-
-  const testUrl = TEST_DB_URL.replace(/\/[^/]+$/, "/kumiko_test_step7");
-  client = postgres(testUrl);
-  db = drizzle(client);
-
-  await unsafeCreateEntityTable(db, entity);
-
-  const rows = [
-    {
-      tenantId: "00000000-0000-4000-8000-000000000001",
-      email: "admin@test.de",
-      firstName: "Admin",
-    },
-    { tenantId: "00000000-0000-4000-8000-000000000001", email: "marc@test.de", firstName: "Marc" },
-    { tenantId: "00000000-0000-4000-8000-000000000001", email: "anna@test.de", firstName: "Anna" },
-    {
-      tenantId: "00000000-0000-4000-8000-000000000001",
-      email: "deleted@test.de",
-      firstName: "Deleted",
-      isDeleted: true,
-    },
-    {
-      tenantId: "00000000-0000-4000-8000-000000000002",
-      email: "other@test.de",
-      firstName: "Other",
-    },
-  ];
-
-  for (const row of rows) {
-    await db.insert(table).values({
-      tenantId: row.tenantId,
-      email: row.email,
-      firstName: row.firstName,
-      isEnabled: true,
-      isDeleted: row.isDeleted ?? false,
-    });
-  }
-});
-
-afterAll(async () => {
-  await client.end();
-  const adminClient = postgres(TEST_DB_URL.replace(/\/[^/]+$/, "/postgres"), {
-    onnotice: () => {},
-  });
-  try {
-    await adminClient`DROP DATABASE IF EXISTS kumiko_test_step7`;
-  } finally {
-    await adminClient.end();
-  }
-});
-
-async function query(options: Parameters<typeof applyCursorQuery>[2]): Promise<Row[]> {
-  return applyCursorQuery(db.select().from(table).$dynamic(), table, options);
-}
-
-// --- Tests ---
-
-describe("tenant isolation", () => {
-  test("only returns rows for specified tenant", async () => {
-    const rows = await query({ tenantId: testTenantId(1) });
-    expect(rows.every((r) => r["tenantId"] === testTenantId(1))).toBe(true);
-  });
-
-  test("tenant 2 only sees own data", async () => {
-    const rows = await query({ tenantId: "00000000-0000-4000-8000-000000000002" });
-    expect(rows).toHaveLength(1);
-    expect(rows[0]?.["email"]).toBe("other@test.de");
-  });
-});
-
-describe("soft delete filtering", () => {
-  test("excludes soft-deleted rows", async () => {
-    const rows = await query({ tenantId: "00000000-0000-4000-8000-000000000001" });
-    expect(rows.find((r) => r["email"] === "deleted@test.de")).toBeUndefined();
-  });
-});
-
-describe("cursor pagination", () => {
-  test("limits results", async () => {
-    const rows = await query({ tenantId: "00000000-0000-4000-8000-000000000001", limit: 2 });
-    expect(rows).toHaveLength(2);
-  });
-
-  test("cursor skips past previous results", async () => {
-    const page1 = await query({ tenantId: "00000000-0000-4000-8000-000000000001", limit: 2 });
-    expect(page1).toHaveLength(2);
-
-    const lastId = page1[page1.length - 1]?.["id"] as number;
-    const page2 = await query({
-      tenantId: "00000000-0000-4000-8000-000000000001",
-      limit: 2,
-      cursor: encodeCursor(lastId),
-    });
-
-    const page1Ids = page1.map((r) => r["id"]);
-    const page2Ids = page2.map((r) => r["id"]);
-    expect(page1Ids.some((id) => page2Ids.includes(id))).toBe(false);
-  });
-});
-
-describe("filterIds (search results from SearchAdapter)", () => {
-  test("filters by ID list from search adapter", async () => {
-    // SearchAdapter returns IDs, cursor query filters by them
-    const rows = await query({
-      tenantId: "00000000-0000-4000-8000-000000000001",
-      filterIds: [1, 2],
-    });
-    expect(rows).toHaveLength(2);
-    expect(rows.every((r) => [1, 2].includes(r["id"] as number))).toBe(true);
-  });
-
-  test("empty filterIds returns nothing", async () => {
-    const rows = await query({ tenantId: "00000000-0000-4000-8000-000000000001", filterIds: [] });
-    expect(rows).toHaveLength(0);
-  });
-});
-
-describe("sorting", () => {
-  test("sorts by column ASC", async () => {
-    const rows = await query({
-      tenantId: "00000000-0000-4000-8000-000000000001",
-      sort: "firstName",
-      sortDirection: "asc",
-    });
-    const names = rows.map((r) => r["firstName"]);
-    const sorted = [...names].sort();
-    expect(names).toEqual(sorted);
-  });
-
-  test("sorts by column DESC", async () => {
-    const rows = await query({
-      tenantId: "00000000-0000-4000-8000-000000000001",
-      sort: "firstName",
-      sortDirection: "desc",
-    });
-    const names = rows.map((r) => r["firstName"]);
-    const sorted = [...names].sort().reverse();
-    expect(names).toEqual(sorted);
-  });
-});

package/src/db/__tests__/row-helpers.test.ts

@@ -1,59 +0,0 @@
-import type { SQL } from "drizzle-orm";
-import { describe, expect, test, vi } from "vitest";
-import { fetchOne } from "../row-helpers";
-
-// Drizzle builder chain mocked structurally — fetchOne only calls
-// db.select().from(table).where(where).limit(1) and reads the first row.
-function makeFakeDb(rows: unknown[]) {
-  const limit = vi.fn().mockResolvedValue(rows);
-  const where = vi.fn(() => ({ limit }));
-  const from = vi.fn(() => ({ where }));
-  const select = vi.fn(() => ({ from }));
-  // biome-ignore lint/suspicious/noExplicitAny: test shim — we never feed this to a real DbRunner type check.
-  return { db: { select } as any, select, from, where, limit };
-}
-
-const fakeTable = {} as never;
-const fakeCond1 = { __c: 1 } as unknown as SQL;
-const fakeCond2 = { __c: 2 } as unknown as SQL;
-
-describe("fetchOne", () => {
-  test("returns the first row when the query yields at least one match", async () => {
-    const { db } = makeFakeDb([
-      { id: 1, name: "alice" },
-      { id: 2, name: "bob" },
-    ]);
-    const row = await fetchOne<{ id: number; name: string }>(db, fakeTable, fakeCond1);
-    expect(row).toEqual({ id: 1, name: "alice" });
-  });
-
-  test("returns undefined on an empty result", async () => {
-    const { db } = makeFakeDb([]);
-    const row = await fetchOne(db, fakeTable, fakeCond1);
-    expect(row).toBeUndefined();
-  });
-
-  test("applies limit(1) — no need to pull the whole table", async () => {
-    const { db, limit } = makeFakeDb([]);
-    await fetchOne(db, fakeTable, fakeCond1);
-    expect(limit).toHaveBeenCalledWith(1);
-  });
-
-  test("passes the single condition directly to .where (no AND wrapping)", async () => {
-    const { db, where } = makeFakeDb([]);
-    await fetchOne(db, fakeTable, fakeCond1);
-    expect(where).toHaveBeenCalledWith(fakeCond1);
-  });
-
-  test("combines multiple conditions with AND", async () => {
-    const { db, where } = makeFakeDb([]);
-    await fetchOne(db, fakeTable, fakeCond1, fakeCond2);
-    const calls = where.mock.calls as unknown as readonly (readonly unknown[])[];
-    const arg = calls[0]?.[0];
-    // drizzle's and() returns an SQL expression — we can't cheaply inspect
-    // its innards, but it must not be the raw first condition and must be
-    // defined (i.e. the helper actually composed something).
-    expect(arg).toBeDefined();
-    expect(arg).not.toBe(fakeCond1);
-  });
-});

package/src/engine/steps/_drizzle-boundary.ts

@@ -1,19 +0,0 @@
-// Drizzle-boundary cast helper — drizzle's `db.insert()/select()/delete()`
-// expect a PgTable<...> shape with `enableRLS` (driver-added). The
-// abstract `Table` we accept on step args is missing that method, so
-// TS rejects direct assignment. Runtime is identical — drizzle's
-// builder methods only read the table-name + column-defs, both of
-// which `Table` carries. Cast at the boundary, document it once.
-//
-// Used by read-find-one, read-find-many, unsafe-projection-upsert,
-// unsafe-projection-delete. Followup #13 (closed at the M.1.6
-// cleanup-pass).
-
-import type { Table } from "drizzle-orm";
-
-// biome-ignore lint/suspicious/noExplicitAny: drizzle type-boundary
-type DrizzleQueryTarget = any;
-
-export function asQueryTarget(t: Table): DrizzleQueryTarget {
-  return t;
-}