@cosmicdrift/kumiko-framework 0.1.0

package/src/redis/__tests__/redis-options.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "vitest";
+import { redisClientOptionsFromEnv } from "../index";
+
+describe("redisClientOptionsFromEnv", () => {
+  test("empty env → empty options", () => {
+    expect(redisClientOptionsFromEnv({})).toEqual({});
+  });
+
+  test("reads all three supported keys", () => {
+    const opts = redisClientOptionsFromEnv({
+      REDIS_CONNECT_TIMEOUT_MS: "3000",
+      REDIS_COMMAND_TIMEOUT_MS: "5000",
+      REDIS_MAX_RETRIES_PER_REQUEST: "2",
+    });
+    expect(opts).toEqual({
+      connectTimeoutMs: 3000,
+      commandTimeoutMs: 5000,
+      maxRetriesPerRequest: 2,
+    });
+  });
+
+  test("empty string is treated as unset", () => {
+    const opts = redisClientOptionsFromEnv({
+      REDIS_CONNECT_TIMEOUT_MS: "",
+      REDIS_COMMAND_TIMEOUT_MS: "7500",
+    });
+    expect(opts).toEqual({ commandTimeoutMs: 7500 });
+  });
+
+  test("zero is allowed (e.g. 0 retries = fail-fast)", () => {
+    const opts = redisClientOptionsFromEnv({
+      REDIS_MAX_RETRIES_PER_REQUEST: "0",
+    });
+    expect(opts).toEqual({ maxRetriesPerRequest: 0 });
+  });
+
+  test("negative number → throws", () => {
+    expect(() => redisClientOptionsFromEnv({ REDIS_CONNECT_TIMEOUT_MS: "-1" })).toThrow(
+      /REDIS_CONNECT_TIMEOUT_MS="-1".*non-negative/i,
+    );
+  });
+
+  test("non-numeric → throws", () => {
+    expect(() => redisClientOptionsFromEnv({ REDIS_COMMAND_TIMEOUT_MS: "ten" })).toThrow(
+      /REDIS_COMMAND_TIMEOUT_MS="ten"/,
+    );
+  });
+
+  test("decimal → throws (ioredis expects integer ms)", () => {
+    expect(() => redisClientOptionsFromEnv({ REDIS_CONNECT_TIMEOUT_MS: "250.5" })).toThrow(
+      /REDIS_CONNECT_TIMEOUT_MS="250.5".*integer/i,
+    );
+  });
+});

package/src/redis/index.ts

@@ -0,0 +1,74 @@
+// Thin factory for ioredis clients with Prod-sensible defaults.
+// ioredis itself doesn't enforce a command-timeout — an unreachable Redis
+// will silently hang a request forever unless the caller sets
+// `commandTimeout`. Same story for connectTimeout: the default is 10s,
+// which is too long for a /health/ready probe with a 2s budget.
+//
+// Apps are expected to build their Redis clients via this helper so
+// production defaults stay consistent and env-var wiring lives in one
+// place. Tests / one-off scripts can still `new Redis()` directly.
+
+import IoRedis, { type Redis, type RedisOptions } from "ioredis";
+import { readPositiveIntEnv } from "../utils/env-parse";
+
+// Connection-tuning options. The fields mirror the most consequential
+// ioredis settings; anything else can be passed through via `extra` to
+// keep the helper from re-declaring the full ioredis surface.
+export type RedisClientOptions = {
+  // Milliseconds to wait when opening the TCP connection. Default 5s —
+  // long enough for a cold cache/standby to handshake, short enough that
+  // /health/ready can surface "Redis is gone" inside its 2s-ish probe
+  // window (probe runs in parallel, so 5s here + 2s timeout on the probe
+  // side gives the probe a real answer instead of a hang).
+  readonly connectTimeoutMs?: number;
+  // Milliseconds to wait for a single command to round-trip. Default 10s.
+  // Without this, ioredis waits forever on a stalled connection — a
+  // single bad network partition quietly exhausts the whole command queue.
+  readonly commandTimeoutMs?: number;
+  // Retries per request before bubbling up as an error. Default 3 — enough
+  // to ride out a transient blip but not so many that a dead Redis keeps
+  // requests stuck waiting for retries.
+  readonly maxRetriesPerRequest?: number;
+  // Escape hatch for any ioredis option the helper doesn't expose
+  // explicitly (TLS config, Sentinel, ReadyCheck toggles, …).
+  readonly extra?: Readonly<
+    Omit<RedisOptions, "connectTimeout" | "commandTimeout" | "maxRetriesPerRequest">
+  >;
+};
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 5_000;
+const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_RETRIES_PER_REQUEST = 3;
+
+export function createRedisClient(url: string, options: RedisClientOptions = {}): Redis {
+  const connectTimeout = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+  const commandTimeout = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+  const maxRetriesPerRequest = options.maxRetriesPerRequest ?? DEFAULT_MAX_RETRIES_PER_REQUEST;
+
+  return new IoRedis(url, {
+    ...options.extra,
+    connectTimeout,
+    commandTimeout,
+    maxRetriesPerRequest,
+  });
+}
+
+// Env-var reader — mirrors dbConnectionOptionsFromEnv's contract. Strict:
+// malformed values throw at boot rather than silently falling back to
+// defaults.
+export function redisClientOptionsFromEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): RedisClientOptions {
+  const opts: RedisClientOptions & {
+    connectTimeoutMs?: number;
+    commandTimeoutMs?: number;
+    maxRetriesPerRequest?: number;
+  } = {};
+  const connect = readPositiveIntEnv(env, "REDIS_CONNECT_TIMEOUT_MS");
+  const command = readPositiveIntEnv(env, "REDIS_COMMAND_TIMEOUT_MS");
+  const retries = readPositiveIntEnv(env, "REDIS_MAX_RETRIES_PER_REQUEST");
+  if (connect !== undefined) opts.connectTimeoutMs = connect;
+  if (command !== undefined) opts.commandTimeoutMs = command;
+  if (retries !== undefined) opts.maxRetriesPerRequest = retries;
+  return opts;
+}

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

@@ -0,0 +1,236 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { generateId as uuid } from "@cosmicdrift/kumiko-framework/utils";
+import { Meilisearch } from "meilisearch";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createMeilisearchAdapter } 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";
+
+// Use a fake tenantId to get a unique index name
+const TENANT = uuid();
+
+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,
+  });
+
+  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" },
+  });
+});
+
+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 ---
+
+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([]);
+  });
+});
+
+// --- 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);
+  });
+});
+
+// --- 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);
+  });
+});
+
+// --- 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);
+  });
+
+  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 ---
+
+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 ---
+
+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 ---
+
+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);
+  });
+});
+
+// --- 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]);
+  });
+
+  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(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);
+  });
+});

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

@@ -0,0 +1,256 @@
+import { beforeEach, describe, expect, test } from "vitest";
+import { createInMemorySearchAdapter } from "../in-memory-adapter";
+import type { SearchAdapter } from "../types";
+
+const TENANT = "00000000-0000-4000-8000-000000000001";
+let adapter: SearchAdapter;
+
+beforeEach(async () => {
+  adapter = createInMemorySearchAdapter();
+  await adapter.configure(TENANT, {
+    searchableFields: ["email", "firstName", "lastName", "_roles", "_department"],
+    rankingFields: ["email", "firstName", "lastName", "_roles", "_department"],
+  });
+});
+
+// --- Basic search ---
+
+describe("basic search", () => {
+  test("finds by field value", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 10,
+      fields: { email: "marc@test.de", firstName: "Marc" },
+    });
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 2,
+      weight: 10,
+      fields: { email: "anna@test.de", firstName: "Anna" },
+    });
+
+    const results = await adapter.search(TENANT, "marc");
+    expect(results).toHaveLength(1);
+    expect(results[0]?.entityId).toBe(1);
+  });
+
+  test("search is case-insensitive", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Marc" },
+    });
+
+    expect(await adapter.search(TENANT, "MARC")).toHaveLength(1);
+    expect(await adapter.search(TENANT, "marc")).toHaveLength(1);
+  });
+
+  test("returns empty for no matches", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Marc" },
+    });
+    expect(await adapter.search(TENANT, "nonexistent")).toEqual([]);
+  });
+});
+
+// --- Partial matching ---
+
+describe("partial matching", () => {
+  test("finds by prefix", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Alexander" },
+    });
+    expect(await adapter.search(TENANT, "alex")).toHaveLength(1);
+  });
+
+  test("finds by substring in email", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 1,
+      fields: { email: "marc.weber@company.de" },
+    });
+    expect(await adapter.search(TENANT, "weber")).toHaveLength(1);
+  });
+});
+
+// --- Tenant isolation ---
+
+describe("tenant isolation", () => {
+  test("tenant 1 cannot see tenant 2 data", async () => {
+    await adapter.configure("00000000-0000-4000-8000-000000000002", {
+      searchableFields: ["firstName"],
+    });
+    await adapter.index("00000000-0000-4000-8000-000000000001", {
+      entityType: "user",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Marc" },
+    });
+    await adapter.index("00000000-0000-4000-8000-000000000002", {
+      entityType: "user",
+      entityId: 2,
+      weight: 1,
+      fields: { firstName: "Marc" },
+    });
+
+    const t1 = await adapter.search("00000000-0000-4000-8000-000000000001", "marc");
+    const t2 = await adapter.search("00000000-0000-4000-8000-000000000002", "marc");
+
+    expect(t1).toHaveLength(1);
+    expect(t1[0]?.entityId).toBe(1);
+    expect(t2).toHaveLength(1);
+    expect(t2[0]?.entityId).toBe(2);
+  });
+});
+
+// --- Entity type filtering (list search) ---
+
+describe("list search (filterType)", () => {
+  test("filters by entity type", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 10,
+      fields: { firstName: "Marc" },
+    });
+    await adapter.index(TENANT, {
+      entityType: "role",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Marc Admin" },
+    });
+
+    const users = await adapter.search(TENANT, "marc", { filterType: "user" });
+    const roles = await adapter.search(TENANT, "marc", { filterType: "role" });
+
+    expect(users).toHaveLength(1);
+    expect(users[0]?.entityType).toBe("user");
+    expect(roles).toHaveLength(1);
+    expect(roles[0]?.entityType).toBe("role");
+  });
+});
+
+// --- Global search (no filter) ---
+
+describe("global search (no filterType)", () => {
+  test("returns all entity types sorted by weight", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 10,
+      fields: { firstName: "Admin" },
+    });
+    await adapter.index(TENANT, {
+      entityType: "role",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Admin Role" },
+    });
+
+    const results = await adapter.search(TENANT, "admin");
+    expect(results).toHaveLength(2);
+    // User (weight 10) should rank before Role (weight 1)
+    expect(results[0]?.entityType).toBe("user");
+    expect(results[1]?.entityType).toBe("role");
+  });
+});
+
+// --- searchWeight scoring ---
+
+describe("searchWeight scoring", () => {
+  test("higher weight entity ranks first", async () => {
+    await adapter.index(TENANT, {
+      entityType: "vehicle",
+      entityId: 1,
+      weight: 10,
+      fields: { firstName: "BMW 320i" },
+    });
+    await adapter.index(TENANT, {
+      entityType: "workshop",
+      entityId: 1,
+      weight: 5,
+      fields: { firstName: "BMW Werkstatt" },
+    });
+    await adapter.index(TENANT, {
+      entityType: "role",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "BMW Fleet Manager" },
+    });
+
+    const results = await adapter.search(TENANT, "bmw");
+    expect(results[0]?.entityType).toBe("vehicle");
+    expect(results[1]?.entityType).toBe("workshop");
+    expect(results[2]?.entityType).toBe("role");
+  });
+});
+
+// --- Relation data in search ---
+
+describe("resolved relation data", () => {
+  test("finds user by role name via _roles field", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 10,
+      fields: { email: "marc@test.de", firstName: "Marc", _roles: "Admin, Developer" },
+    });
+
+    const results = await adapter.search(TENANT, "developer");
+    expect(results).toHaveLength(1);
+    expect(results[0]?.entityId).toBe(1);
+  });
+
+  test("finds user by department name via _department field", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 10,
+      fields: { email: "marc@test.de", _department: "Marketing" },
+    });
+
+    const results = await adapter.search(TENANT, "marketing");
+    expect(results).toHaveLength(1);
+  });
+});
+
+// --- Remove ---
+
+describe("remove", () => {
+  test("removes document from search", async () => {
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Marc" },
+    });
+    await adapter.remove(TENANT, "user", 1);
+    expect(await adapter.search(TENANT, "marc")).toEqual([]);
+  });
+});
+
+// --- Limit ---
+
+describe("limit", () => {
+  test("respects limit", async () => {
+    for (let i = 1; i <= 10; i++) {
+      await adapter.index(TENANT, {
+        entityType: "user",
+        entityId: i,
+        weight: 1,
+        fields: { firstName: `User${i}`, lastName: "Same" },
+      });
+    }
+    const results = await adapter.search(TENANT, "same", { limit: 3 });
+    expect(results).toHaveLength(3);
+  });
+});