@cosmicdrift/kumiko-framework 0.154.1 → 0.155.0

package/src/search/__tests__/meilisearch-adapter.integration.test.ts

@@ -1,13 +1,30 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { generateId as uuid } from "@cosmicdrift/kumiko-framework/utils";
 import { Meilisearch } from "meilisearch";
-import { createMeilisearchAdapter } from "../meilisearch-adapter";
+import { createMeilisearchAdapter, meilisearchTenantIndex } from "../meilisearch-adapter";
 import type { SearchAdapter } from "../types";
 
 const MEILI_URL = process.env["MEILI_URL"] ?? "http://localhost:17700";
 const MEILI_KEY = process.env["MEILI_MASTER_KEY"] ?? "kumiko-dev-key";
 
+async function meiliAvailable(): Promise<boolean> {
+  try {
+    const health = await fetch(`${MEILI_URL}/health`);
+    return health.ok;
+  } catch {
+    return false;
+  }
+}
+
+// skipIf when compose Meili is down — unit tests still cover index/doc id shaping.
+const MEILI_UP = await meiliAvailable();
+if (!MEILI_UP) {
+  console.warn(
+    `Meilisearch not reachable at ${MEILI_URL} — skipping live adapter tests ` +
+      `(docker compose up -d meilisearch, default port 17700)`,
+  );
+}
+
 // Use a fake tenantId to get a unique index name
 const TENANT = uuid();
 
@@ -15,222 +32,220 @@ let adapter: SearchAdapter;
 let client: Meilisearch;
 let indexPrefix: string;
 
-// Mirrors meilisearch-adapter.ts's tenantIndex() — used by tests that need
-// to talk to Meilisearch directly (e.g. stats before/after a no-op).
-const tenantIndex = (prefix: string, tenantId: TenantId): string => `${prefix}t${tenantId}`;
-
-beforeAll(async () => {
-  client = new Meilisearch({ host: MEILI_URL, apiKey: MEILI_KEY });
-  indexPrefix = `test_${uuid().slice(-6)}_`;
-  adapter = createMeilisearchAdapter({
-    url: MEILI_URL,
-    apiKey: MEILI_KEY,
-    indexPrefix,
-  });
+describe.skipIf(!MEILI_UP)("meilisearch adapter (live)", () => {
+  beforeAll(async () => {
+    client = new Meilisearch({ host: MEILI_URL, apiKey: MEILI_KEY });
+    indexPrefix = `test_${uuid().slice(-6)}_`;
+    adapter = createMeilisearchAdapter({
+      url: MEILI_URL,
+      apiKey: MEILI_KEY,
+      indexPrefix,
+    });
 
-  await adapter.configure(TENANT, {
-    searchableFields: ["email", "firstName", "lastName", "notes", "_roles"],
-    rankingFields: ["email", "firstName", "lastName", "notes", "_roles"],
-  });
+    await adapter.configure(TENANT, {
+      searchableFields: ["email", "firstName", "lastName", "notes", "_roles"],
+      rankingFields: ["email", "firstName", "lastName", "notes", "_roles"],
+    });
 
-  // Seed data with different entity types and weights
-  await adapter.index(TENANT, {
-    entityType: "user",
-    entityId: 1,
-    weight: 10,
-    fields: {
-      email: "marc.weber@company.de",
-      firstName: "Marc",
-      lastName: "Weber",
-      notes: "Senior developer",
-      _roles: "Admin, Developer",
-    },
-  });
-  await adapter.index(TENANT, {
-    entityType: "user",
-    entityId: 2,
-    weight: 10,
-    fields: {
-      email: "anna.schmidt@company.de",
-      firstName: "Anna",
-      lastName: "Schmidt",
-      notes: "Project manager",
-    },
-  });
-  await adapter.index(TENANT, {
-    entityType: "user",
-    entityId: 3,
-    weight: 10,
-    fields: {
-      email: "admin@company.de",
-      firstName: "Admin",
-      lastName: "User",
-      notes: "System administrator",
-    },
-  });
-  await adapter.index(TENANT, {
-    entityType: "role",
-    entityId: 1,
-    weight: 1,
-    fields: { firstName: "Admin" },
-  });
-  await adapter.index(TENANT, {
-    entityType: "role",
-    entityId: 2,
-    weight: 1,
-    fields: { firstName: "Developer" },
-  });
-  await adapter.index(TENANT, {
-    entityType: "department",
-    entityId: 1,
-    weight: 5,
-    fields: { firstName: "Engineering" },
+    // Seed data with different entity types and weights
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 10,
+      fields: {
+        email: "marc.weber@company.de",
+        firstName: "Marc",
+        lastName: "Weber",
+        notes: "Senior developer",
+        _roles: "Admin, Developer",
+      },
+    });
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 2,
+      weight: 10,
+      fields: {
+        email: "anna.schmidt@company.de",
+        firstName: "Anna",
+        lastName: "Schmidt",
+        notes: "Project manager",
+      },
+    });
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 3,
+      weight: 10,
+      fields: {
+        email: "admin@company.de",
+        firstName: "Admin",
+        lastName: "User",
+        notes: "System administrator",
+      },
+    });
+    await adapter.index(TENANT, {
+      entityType: "role",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Admin" },
+    });
+    await adapter.index(TENANT, {
+      entityType: "role",
+      entityId: 2,
+      weight: 1,
+      fields: { firstName: "Developer" },
+    });
+    await adapter.index(TENANT, {
+      entityType: "department",
+      entityId: 1,
+      weight: 5,
+      fields: { firstName: "Engineering" },
+    });
   });
-});
 
-afterAll(async () => {
-  // Clean up all test indices
-  const indices = await client.getIndexes();
-  for (const idx of indices.results) {
-    if (idx.uid.startsWith("test_")) {
-      try {
-        await client.index(idx.uid).delete().waitTask();
-      } catch {
-        /* ok */
+  afterAll(async () => {
+    // Clean up all test indices
+    const indices = await client.getIndexes();
+    for (const idx of indices.results) {
+      if (idx.uid.startsWith("test_")) {
+        try {
+          await client.index(idx.uid).delete().waitTask();
+        } catch {
+          /* ok */
+        }
       }
     }
-  }
-});
+  });
 
-// --- Basic search ---
+  // --- Basic search ---
 
-describe("basic search", () => {
-  test("finds user by name", async () => {
-    const results = await adapter.search(TENANT, "anna");
-    expect(results.some((r) => r.entityId === 2 && r.entityType === "user")).toBe(true);
-  });
+  describe("basic search", () => {
+    test("finds user by name", async () => {
+      const results = await adapter.search(TENANT, "anna");
+      expect(results.some((r) => r.entityId === 2 && r.entityType === "user")).toBe(true);
+    });
 
-  test("returns empty for no match", async () => {
-    const results = await adapter.search(TENANT, "zzzznonexistent99999");
-    expect(results).toEqual([]);
+    test("returns empty for no match", async () => {
+      const results = await adapter.search(TENANT, "zzzznonexistent99999");
+      expect(results).toEqual([]);
+    });
   });
-});
 
-// --- Partial matching ---
+  // --- Partial matching ---
 
-describe("partial matching", () => {
-  test("finds by prefix", async () => {
-    const results = await adapter.search(TENANT, "mar");
-    expect(results.some((r) => r.entityId === 1 && r.entityType === "user")).toBe(true);
+  describe("partial matching", () => {
+    test("finds by prefix", async () => {
+      const results = await adapter.search(TENANT, "mar");
+      expect(results.some((r) => r.entityId === 1 && r.entityType === "user")).toBe(true);
+    });
   });
-});
 
-// --- Typo tolerance ---
+  // --- Typo tolerance ---
 
-describe("typo tolerance", () => {
-  test("finds despite typos", async () => {
-    const results = await adapter.search(TENANT, "schmit");
-    expect(results.some((r) => r.entityId === 2)).toBe(true);
+  describe("typo tolerance", () => {
+    test("finds despite typos", async () => {
+      const results = await adapter.search(TENANT, "schmit");
+      expect(results.some((r) => r.entityId === 2)).toBe(true);
+    });
   });
-});
 
-// --- Filter by entity type (list search) ---
+  // --- Filter by entity type (list search) ---
 
-describe("list search (filterType)", () => {
-  test("only returns specified entity type", async () => {
-    const results = await adapter.search(TENANT, "admin", { filterType: "user" });
-    expect(results.every((r) => r.entityType === "user")).toBe(true);
-    expect(results.length).toBeGreaterThan(0);
-  });
+  describe("list search (filterType)", () => {
+    test("only returns specified entity type", async () => {
+      const results = await adapter.search(TENANT, "admin", { filterType: "user" });
+      expect(results.every((r) => r.entityType === "user")).toBe(true);
+      expect(results.length).toBeGreaterThan(0);
+    });
 
-  test("role filter returns only roles", async () => {
-    const results = await adapter.search(TENANT, "admin", { filterType: "role" });
-    expect(results.every((r) => r.entityType === "role")).toBe(true);
+    test("role filter returns only roles", async () => {
+      const results = await adapter.search(TENANT, "admin", { filterType: "role" });
+      expect(results.every((r) => r.entityType === "role")).toBe(true);
+    });
   });
-});
 
-// --- Global search with weight ---
+  // --- Global search with weight ---
 
-describe("global search with searchWeight", () => {
-  test("user (weight 10) ranks before role (weight 1) for same query", async () => {
-    const results = await adapter.search(TENANT, "admin");
-    const userIdx = results.findIndex((r) => r.entityType === "user");
-    const roleIdx = results.findIndex((r) => r.entityType === "role");
-    // User should appear before Role due to _weight:desc sort
-    if (userIdx >= 0 && roleIdx >= 0) {
-      expect(userIdx).toBeLessThan(roleIdx);
-    }
+  describe("global search with searchWeight", () => {
+    test("user (weight 10) ranks before role (weight 1) for same query", async () => {
+      const results = await adapter.search(TENANT, "admin");
+      const userIdx = results.findIndex((r) => r.entityType === "user");
+      const roleIdx = results.findIndex((r) => r.entityType === "role");
+      // User should appear before Role due to _weight:desc sort
+      if (userIdx >= 0 && roleIdx >= 0) {
+        expect(userIdx).toBeLessThan(roleIdx);
+      }
+    });
   });
-});
 
-// --- Resolved relation data ---
+  // --- Resolved relation data ---
 
-describe("relation data in search", () => {
-  test("finds user by role name in _roles field", async () => {
-    const results = await adapter.search(TENANT, "developer", { filterType: "user" });
-    expect(results.some((r) => r.entityId === 1)).toBe(true);
+  describe("relation data in search", () => {
+    test("finds user by role name in _roles field", async () => {
+      const results = await adapter.search(TENANT, "developer", { filterType: "user" });
+      expect(results.some((r) => r.entityId === 1)).toBe(true);
+    });
   });
-});
 
-// --- Remove ---
+  // --- Remove ---
 
-describe("remove", () => {
-  test("removed document not found", async () => {
-    // Create temp doc
-    await adapter.index(TENANT, {
-      entityType: "temp",
-      entityId: 999,
-      weight: 1,
-      fields: { firstName: "DeleteMe" },
-    });
-    let results = await adapter.search(TENANT, "deleteme");
-    expect(results.some((r) => r.entityId === 999)).toBe(true);
+  describe("remove", () => {
+    test("removed document not found", async () => {
+      // Create temp doc
+      await adapter.index(TENANT, {
+        entityType: "temp",
+        entityId: 999,
+        weight: 1,
+        fields: { firstName: "DeleteMe" },
+      });
+      let results = await adapter.search(TENANT, "deleteme");
+      expect(results.some((r) => r.entityId === 999)).toBe(true);
 
-    await adapter.remove(TENANT, "temp", 999);
-    results = await adapter.search(TENANT, "deleteme");
-    expect(results.some((r) => r.entityId === 999)).toBe(false);
+      await adapter.remove(TENANT, "temp", 999);
+      results = await adapter.search(TENANT, "deleteme");
+      expect(results.some((r) => r.entityId === 999)).toBe(false);
+    });
   });
-});
 
-// --- Batch variants ---
+  // --- Batch variants ---
 
-describe("indexBatch / removeBatch", () => {
-  test("indexBatch indexes multiple docs in a single task", async () => {
-    const docs = Array.from({ length: 5 }, (_, i) => ({
-      entityType: "batch" as const,
-      entityId: 1000 + i,
-      weight: 1,
-      fields: { firstName: `Bulk${i}`, notes: "batchtoken" },
-    }));
-    await adapter.indexBatch?.(TENANT, docs);
-
-    const hits = await adapter.search(TENANT, "batchtoken", { limit: 20, filterType: "batch" });
-    expect(hits.length).toBe(5);
-    const ids = hits.map((h) => h.entityId).sort();
-    expect(ids).toEqual([1000, 1001, 1002, 1003, 1004]);
-  });
+  describe("indexBatch / removeBatch", () => {
+    test("indexBatch indexes multiple docs in a single task", async () => {
+      const docs = Array.from({ length: 5 }, (_, i) => ({
+        entityType: "batch" as const,
+        entityId: 1000 + i,
+        weight: 1,
+        fields: { firstName: `Bulk${i}`, notes: "batchtoken" },
+      }));
+      await adapter.indexBatch?.(TENANT, docs);
 
-  test("removeBatch removes multiple docs in a single task", async () => {
-    await adapter.removeBatch?.(
-      TENANT,
-      [1000, 1001, 1002, 1003, 1004].map((id) => ({ entityType: "batch", entityId: id })),
-    );
-    const hits = await adapter.search(TENANT, "batchtoken", { limit: 20, filterType: "batch" });
-    expect(hits.length).toBe(0);
-  });
+      const hits = await adapter.search(TENANT, "batchtoken", { limit: 20, filterType: "batch" });
+      expect(hits.length).toBe(5);
+      const ids = hits.map((h) => h.entityId).sort();
+      expect(ids).toEqual([1000, 1001, 1002, 1003, 1004]);
+    });
 
-  test("indexBatch no-ops on empty array — no Meilisearch task created", async () => {
-    // We verify the "no-op" contract by peeking at Meilisearch's own
-    // IndexStats.numberOfDocuments + isIndexing directly. If the adapter had
-    // accidentally sent an addDocuments request (even with an empty body),
-    // isIndexing would flip to true or a task would land in the queue.
-    // numberOfDocuments must also stay unchanged — the empty batch must not
-    // replace, delete, or otherwise touch existing docs.
-    const index = client.index(tenantIndex(indexPrefix, TENANT));
-    const before = await index.getStats();
-    await expect(adapter.indexBatch?.(TENANT, [])).resolves.toBeUndefined();
-    const after = await index.getStats();
-    expect(after.numberOfDocuments).toBe(before.numberOfDocuments);
-    expect(after.isIndexing).toBe(false);
+    test("removeBatch removes multiple docs in a single task", async () => {
+      await adapter.removeBatch?.(
+        TENANT,
+        [1000, 1001, 1002, 1003, 1004].map((id) => ({ entityType: "batch", entityId: id })),
+      );
+      const hits = await adapter.search(TENANT, "batchtoken", { limit: 20, filterType: "batch" });
+      expect(hits.length).toBe(0);
+    });
+
+    test("indexBatch no-ops on empty array — no Meilisearch task created", async () => {
+      // We verify the "no-op" contract by peeking at Meilisearch's own
+      // IndexStats.numberOfDocuments + isIndexing directly. If the adapter had
+      // accidentally sent an addDocuments request (even with an empty body),
+      // isIndexing would flip to true or a task would land in the queue.
+      // numberOfDocuments must also stay unchanged — the empty batch must not
+      // replace, delete, or otherwise touch existing docs.
+      const index = client.index(meilisearchTenantIndex(indexPrefix, TENANT));
+      const before = await index.getStats();
+      await expect(adapter.indexBatch?.(TENANT, [])).resolves.toBeUndefined();
+      const after = await index.getStats();
+      expect(after.numberOfDocuments).toBe(before.numberOfDocuments);
+      expect(after.isIndexing).toBe(false);
+    });
   });
 });

package/src/search/__tests__/meilisearch-ids.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { meilisearchDocId, meilisearchTenantIndex } from "../meilisearch-adapter";
+
+describe("meilisearchTenantIndex", () => {
+  test("prefixes tenant id with t after the index prefix", () => {
+    expect(meilisearchTenantIndex("kumiko_", "00000000-0000-4000-8000-000000000001")).toBe(
+      "kumiko_t00000000-0000-4000-8000-000000000001",
+    );
+  });
+
+  test("keeps custom prefixes intact", () => {
+    expect(meilisearchTenantIndex("test_abc_", 42 as never)).toBe("test_abc_t42");
+  });
+});
+
+describe("meilisearchDocId", () => {
+  test("joins entity type and id with underscore", () => {
+    expect(meilisearchDocId("user", 7)).toBe("user_7");
+  });
+
+  test("preserves UUID dashes (legal Meilisearch primary-key chars)", () => {
+    expect(meilisearchDocId("order", "a1b2c3d4-e5f6-7890-abcd-ef1234567890" as never)).toBe(
+      "order_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    );
+  });
+
+  test("sanitizes illegal primary-key characters to underscore", () => {
+    expect(meilisearchDocId("note", "a:b/c.d" as never)).toBe("note_a_b_c_d");
+  });
+});

package/src/search/meilisearch-adapter.ts

@@ -8,13 +8,14 @@ export type MeilisearchAdapterOptions = {
   indexPrefix?: string;
 };
 
-function tenantIndex(prefix: string, tenantId: TenantId): string {
+// Exported for unit tests (index-name / primary-key shape) without a live Meili.
+export function meilisearchTenantIndex(prefix: string, tenantId: TenantId): string {
   return `${prefix}t${tenantId}`;
 }
 
 // Meilisearch primary-key-ids: alphanumerics, `-`, `_`. UUIDs contain `-` —
 // legal. Replace anything else just in case callers pass unexpected shapes.
-function docId(entityType: string, entityId: EntityId): string {
+export function meilisearchDocId(entityType: string, entityId: EntityId): string {
   return `${entityType}_${String(entityId).replace(/[^0-9A-Za-z_-]/g, "_")}`;
 }
 
@@ -24,7 +25,7 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
 
   return {
     async configure(tenantId, config) {
-      const index = client.index(tenantIndex(prefix, tenantId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
       const fields = config.rankingFields ?? config.searchableFields;
       await index.updateSearchableAttributes([...fields]).waitTask();
       await index.updateFilterableAttributes(["_type", "_weight"]).waitTask();
@@ -32,12 +33,12 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
     },
 
     async index(tenantId, doc) {
-      const index = client.index(tenantIndex(prefix, tenantId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
       await index
         .addDocuments(
           [
             {
-              _id: docId(doc.entityType, doc.entityId),
+              _id: meilisearchDocId(doc.entityType, doc.entityId),
               _type: doc.entityType,
               _weight: doc.weight,
               _entityId: doc.entityId,
@@ -52,9 +53,9 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
     async indexBatch(tenantId, docs) {
       // skip: empty batch — avoid an unnecessary Meilisearch round-trip
       if (docs.length === 0) return;
-      const index = client.index(tenantIndex(prefix, tenantId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
       const payload = docs.map((doc) => ({
-        _id: docId(doc.entityType, doc.entityId),
+        _id: meilisearchDocId(doc.entityType, doc.entityId),
         _type: doc.entityType,
         _weight: doc.weight,
         _entityId: doc.entityId,
@@ -69,13 +70,13 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
     async removeBatch(tenantId, items) {
       // skip: empty batch — avoid an unnecessary Meilisearch round-trip
       if (items.length === 0) return;
-      const index = client.index(tenantIndex(prefix, tenantId));
-      const ids = items.map((i) => docId(i.entityType, i.entityId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
+      const ids = items.map((i) => meilisearchDocId(i.entityType, i.entityId));
       await index.deleteDocuments(ids).waitTask();
     },
 
     async search(tenantId, query, options) {
-      const index = client.index(tenantIndex(prefix, tenantId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
 
       const filter: string[] = [];
       if (options?.filterType) {
@@ -99,8 +100,8 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
     },
 
     async remove(tenantId, entityType, entityId) {
-      const index = client.index(tenantIndex(prefix, tenantId));
-      await index.deleteDocument(docId(entityType, entityId)).waitTask();
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
+      await index.deleteDocument(meilisearchDocId(entityType, entityId)).waitTask();
     },
   };
 }

package/src/engine/__tests__/define-feature-crud.test.ts

@@ -1,55 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { defineFeature } from "../define-feature";
-import { registerEntityCrud } from "../entity-handlers";
-import { createEntity, createTextField } from "../factories";
-
-const taskEntity = createEntity({
-  table: "crud_sugar_tasks",
-  fields: {
-    title: createTextField({ required: true }),
-  },
-  softDelete: true,
-});
-
-const access = {
-  write: { access: { roles: ["Admin"] } },
-  read: { access: { openToAll: true } },
-} as const;
-
-describe("r.crud", () => {
-  test("registers the same entity + handlers as registerEntityCrud", () => {
-    const viaCrud = defineFeature("crud-sugar", (r) => {
-      r.crud("task", taskEntity, access);
-    });
-    const viaHelper = defineFeature("crud-sugar", (r) => {
-      registerEntityCrud(r, "task", taskEntity, access);
-    });
-
-    expect(viaCrud.entities).toEqual(viaHelper.entities);
-    expect(Object.keys(viaCrud.writeHandlers)).toEqual(Object.keys(viaHelper.writeHandlers));
-    expect(Object.keys(viaCrud.queryHandlers)).toEqual(Object.keys(viaHelper.queryHandlers));
-    expect(Object.keys(viaCrud.writeHandlers)).toEqual([
-      "task:create",
-      "task:update",
-      "task:delete",
-      "task:restore",
-    ]);
-    expect(Object.keys(viaCrud.queryHandlers)).toEqual(["task:list", "task:detail"]);
-    expect(viaCrud.writeHandlers["task:create"]?.access).toEqual({ roles: ["Admin"] });
-    expect(viaCrud.queryHandlers["task:list"]?.access).toEqual({ openToAll: true });
-  });
-
-  test("returns an EntityRef like r.entity", () => {
-    defineFeature("crud-sugar", (r) => {
-      const ref = r.crud("task", taskEntity, access);
-      expect(ref).toEqual({ name: "task", table: "crud_sugar_tasks" });
-    });
-  });
-
-  test("verbs opt-out skips handlers", () => {
-    const feature = defineFeature("crud-sugar", (r) => {
-      r.crud("task", taskEntity, { ...access, verbs: { delete: false, restore: false } });
-    });
-    expect(Object.keys(feature.writeHandlers)).toEqual(["task:create", "task:update"]);
-  });
-});