@veducio/keja 0.0.0-stage → 0.2.3

package/src/route/middleware.ts

@@ -0,0 +1,144 @@
+const middlewareBrand = "keja.middleware";
+const middlewareFields: unique symbol = Symbol("keja.middleware.fields");
+declare const passed: unique symbol;
+
+const reservedFields = ["params", "query", "body", "respond"] as const;
+
+type ReservedField = (typeof reservedFields)[number];
+
+type ForbidReserved<Fields> = Fields & {
+  [Key in ReservedField]?: never;
+};
+
+export type MiddlewareContext = {
+  request: Request;
+  version: string;
+  params: Record<string, string>;
+  next: (fields?: Record<string, unknown>) => Promise<Response>;
+};
+
+export type MiddlewareDefinition<Fields extends object = object> = {
+  readonly [middlewareBrand]: true;
+  readonly [middlewareFields]: Fields;
+  handle: (input: MiddlewareContext) => Response | Promise<Response>;
+};
+
+type MiddlewareStep = {
+  definition: MiddlewareDefinition<object>;
+  allowFields: boolean;
+};
+
+type Passed<Result> = Result extends {
+  readonly [passed]: infer Fields extends Record<string, unknown>;
+}
+  ? Fields
+  : never;
+
+type WithoutReserved<Fields> = {
+  [Key in keyof Fields as Key extends ReservedField ? never : Key]: Fields[Key];
+};
+
+type MiddlewareFields<Result> = [Passed<Result>] extends [never]
+  ? Record<never, never>
+  : WithoutReserved<Passed<Result>>;
+
+type MiddlewareNext = {
+  (): Promise<Response & { readonly [passed]: Record<never, never> }>;
+  <const Fields extends Record<string, unknown>>(
+    fields: ForbidReserved<Fields>,
+  ): Promise<Response & { readonly [passed]: Fields }>;
+};
+
+export function defineMiddleware<Result>(
+  handle: (input: {
+    request: Request;
+    version: string;
+    params: Record<string, string>;
+    next: MiddlewareNext;
+  }) => Promise<Result>,
+): MiddlewareDefinition<MiddlewareFields<Result>> {
+  return {
+    [middlewareBrand]: true,
+    [middlewareFields]: undefined as unknown as MiddlewareFields<Result>,
+    handle,
+  } as unknown as MiddlewareDefinition<MiddlewareFields<Result>>;
+}
+
+export function middlewareList(
+  value: unknown,
+): MiddlewareDefinition<object>[] | null {
+  const exported = Array.isArray(value) ? value : [value];
+  if (!exported.every(isMiddleware)) {
+    return null;
+  }
+  return exported;
+}
+
+export function isMiddleware(
+  value: unknown,
+): value is MiddlewareDefinition<object> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    middlewareBrand in value &&
+    (value as Record<string, unknown>)[middlewareBrand] === true &&
+    "handle" in value &&
+    typeof value.handle === "function"
+  );
+}
+
+export async function runMiddleware(
+  steps: readonly MiddlewareStep[],
+  context: {
+    request: Request;
+    version: string;
+    params: Record<string, string>;
+  },
+  done: (fields: Record<string, unknown>) => Response | Promise<Response>,
+) {
+  const fields: Record<string, unknown> = {};
+  let index = 0;
+  const dispatch = async (): Promise<Response> => {
+    const step = steps[index];
+    index += 1;
+    if (!step) {
+      return done(fields);
+    }
+    let called = false;
+    const response = await step.definition.handle({
+      request: context.request,
+      version: context.version,
+      params: context.params,
+      next: async (passed) => {
+        if (called) {
+          throw new Error("next() was already called");
+        }
+        called = true;
+        if (passed !== undefined) {
+          if (!isFieldBag(passed)) {
+            throw new Error("next() values must be an object");
+          }
+          if (!step.allowFields && Object.keys(passed).length > 0) {
+            throw new Error("Server middleware cannot pass values to next()");
+          }
+          for (const key of Object.keys(passed)) {
+            if (reservedFields.includes(key as ReservedField)) {
+              throw new Error(`Middleware cannot pass reserved field ${key}`);
+            }
+          }
+          Object.assign(fields, passed);
+        }
+        return dispatch();
+      },
+    });
+    if (!(response instanceof Response)) {
+      throw new Error("Middleware must return a Response");
+    }
+    return response;
+  };
+  return dispatch();
+}
+
+function isFieldBag(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/seed/apply.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { setDatabase } from "../db/client.ts";
+import { createTypeId } from "../typeid/id.ts";
+import { applySeeder } from "./apply.ts";
+import { defineSeeder } from "./define.ts";
+
+describe("applySeeder", () => {
+  it("inserts owned rows and skips an existing _id", async () => {
+    const calls: unknown[][] = [];
+    setDatabase(((...args: unknown[]) => {
+      calls.push(args);
+      const first = args[0];
+      if (typeof first === "string") {
+        return new Identifier(first);
+      }
+      if (isTemplate(first)) {
+        return [{ _id: "kept" }];
+      }
+      return new InsertHelper(Array.isArray(first) ? first : [first]);
+    }) as never);
+    try {
+      const at = new Date("2026-01-15T00:00:00.000Z");
+      const inserted = await applySeeder(
+        defineSeeder({
+          table: "users",
+          objects: [
+            {
+              _id: createTypeId("users"),
+              _object: "v1.users",
+              _tenant: "tenant_1",
+              _archived: false,
+              _createdAt: at,
+              _updatedAt: at,
+              name: "Ada",
+            },
+          ],
+        }),
+      );
+      expect(inserted).toBe(1);
+      const template = calls.find((args) => isTemplate(args[0]));
+      const statement = Array.from(template?.[0] as ArrayLike<string>).join(
+        " ",
+      );
+      expect(statement).toContain("on conflict (_id) do nothing");
+      expect(statement).toContain("returning _id");
+    } finally {
+      setDatabase(null);
+    }
+  });
+});
+
+class Identifier {
+  constructor(readonly name: string) {}
+}
+
+class InsertHelper {
+  constructor(readonly value: unknown[]) {}
+  columns = ["_id"];
+}
+
+function isTemplate(value: unknown) {
+  return (
+    Array.isArray(value) && value.every((part) => typeof part === "string")
+  );
+}

package/src/seed/apply.ts

@@ -0,0 +1,11 @@
+import { DBCall } from "../db/client.ts";
+import type { Seeder } from "./define.ts";
+
+export async function applySeeder(seeder: Seeder) {
+  const inserted = await DBCall`
+    insert into ${DBCall(seeder.table)} ${DBCall(seeder.objects)}
+    on conflict (_id) do nothing
+    returning _id
+  `;
+  return Array.isArray(inserted) ? inserted.length : 0;
+}

package/src/seed/define.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { createTypeId } from "../typeid/id.ts";
+import { defineSeeder, isSeeder } from "./define.ts";
+
+const at = new Date("2026-01-15T00:00:00.000Z");
+
+function row(name: string) {
+  return {
+    _id: createTypeId("users"),
+    _object: "v1.users",
+    _tenant: "tenant_1",
+    _archived: false,
+    _createdAt: at,
+    _updatedAt: at,
+    name,
+  };
+}
+
+describe("defineSeeder", () => {
+  it("keeps a table and its owned objects", () => {
+    const seeder = defineSeeder({
+      table: "users",
+      objects: [row("Ada Lovelace")],
+    });
+    expect(isSeeder(seeder)).toBe(true);
+    expect(seeder.table).toBe("users");
+    expect(seeder.objects[0]?.name).toBe("Ada Lovelace");
+  });
+
+  it("rejects a table name, an empty list, and a row that is not owned", () => {
+    expect(() =>
+      defineSeeder({ table: "Users", objects: [row("Ada")] }),
+    ).toThrow("Users is not a table name");
+    expect(() => defineSeeder({ table: "users", objects: [] })).toThrow(
+      "users has no objects",
+    );
+    expect(() =>
+      defineSeeder({
+        table: "users",
+        objects: [{ name: "Ada" }],
+      }),
+    ).toThrow("OwnedObjects _id must be a typeid");
+    const ada = row("Ada");
+    expect(() =>
+      defineSeeder({
+        table: "users",
+        objects: [ada, { ...ada, email: "ada@example.com" }],
+      }),
+    ).toThrow("users objects must use the same columns");
+  });
+});

package/src/seed/define.ts

@@ -0,0 +1,55 @@
+import { projectError } from "../errors/framework-errors.ts";
+import { processBrand } from "../process/slot.ts";
+import { assertOwnedObject, type OwnedObject } from "../typeid/owned.ts";
+
+const seederBrand = processBrand("seeder");
+const tableName = /^[a-z_][a-z0-9_]*$/;
+
+export type Seeder = {
+  table: string;
+  objects: OwnedObject[];
+};
+
+export function defineSeeder(input: {
+  table: string;
+  objects: readonly Record<string, unknown>[];
+}): Seeder {
+  if (!tableName.test(input.table)) {
+    throw projectError("invalidSeeder", `${input.table} is not a table name`);
+  }
+  if (input.objects.length === 0) {
+    throw projectError("invalidSeeder", `${input.table} has no objects`);
+  }
+  const objects = input.objects.map((object) => readObject(object));
+  const columns = Object.keys(objects[0] ?? {}).join("\0");
+  for (const object of objects) {
+    if (Object.keys(object).join("\0") !== columns) {
+      throw projectError(
+        "invalidSeeder",
+        `${input.table} objects must use the same columns`,
+      );
+    }
+  }
+  return Object.assign(
+    { table: input.table, objects },
+    { [seederBrand]: true },
+  );
+}
+
+export function isSeeder(value: unknown): value is Seeder {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    seederBrand in value &&
+    (value as Record<symbol, unknown>)[seederBrand] === true
+  );
+}
+
+function readObject(object: Record<string, unknown>) {
+  try {
+    return assertOwnedObject(object);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "Invalid object";
+    throw projectError("invalidSeeder", detail);
+  }
+}

package/src/seed/load.test.ts

@@ -0,0 +1,54 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { createTypeId } from "../typeid/id.ts";
+import { defineSeeder } from "./define.ts";
+import {
+  collectSeederFiles,
+  readSeederFile,
+  seedersFromModule,
+} from "./load.ts";
+
+describe("seed files", () => {
+  it("walks seed modules and skips tests", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "keja-seed-"));
+    mkdirSync(path.join(root, "billing"), { recursive: true });
+    writeFileSync(path.join(root, "users.ts"), "");
+    writeFileSync(path.join(root, "users.test.ts"), "");
+    writeFileSync(path.join(root, "billing", "notes.ts"), "");
+    const files = await collectSeederFiles(root);
+    expect(files.sort()).toEqual(["billing/notes.ts", "users.ts"]);
+  });
+
+  it("reads every seeder export and rejects a file with none", () => {
+    const users = defineSeeder({
+      table: "users",
+      objects: [owned("users")],
+    });
+    const notes = defineSeeder({
+      table: "notes",
+      objects: [owned("notes")],
+    });
+    expect(seedersFromModule({ default: users, notes })).toEqual([
+      users,
+      notes,
+    ]);
+    expect(() => readSeederFile("helpers.ts", { value: 1 })).toThrow(
+      "helpers.ts must export defineSeeder(...)",
+    );
+  });
+});
+
+function owned(prefix: string) {
+  const at = new Date("2026-01-15T00:00:00.000Z");
+  return {
+    _id: createTypeId(prefix),
+    _object: "v1.notes",
+    _tenant: "tenant_1",
+    _archived: false as const,
+    _createdAt: at,
+    _updatedAt: at,
+    name: prefix,
+  };
+}

package/src/seed/load.ts

@@ -0,0 +1,67 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { projectError } from "../errors/framework-errors.ts";
+import { isSeeder, type Seeder } from "./define.ts";
+
+export async function loadSeeders(directory: string) {
+  if (!existsSync(directory)) {
+    return [];
+  }
+  const files = (await collectSeederFiles(directory)).sort();
+  const seeders: Seeder[] = [];
+  for (const file of files) {
+    const loaded = await import(pathToFileURL(path.join(directory, file)).href);
+    seeders.push(...readSeederFile(file, loaded));
+  }
+  return seeders;
+}
+
+export function readSeederFile(file: string, module: object) {
+  const exported = seedersFromModule(module);
+  if (exported.length === 0) {
+    throw projectError(
+      "invalidSeederFile",
+      `${file} must export defineSeeder(...)`,
+    );
+  }
+  return exported;
+}
+
+export function seedersFromModule(module: object) {
+  const record = module as Record<string, unknown>;
+  const names = Object.keys(record).filter((name) => name !== "default");
+  const ordered = "default" in record ? ["default", ...names] : names;
+  const seeders: Seeder[] = [];
+  for (const name of ordered) {
+    const value = record[name];
+    if (isSeeder(value)) {
+      seeders.push(value);
+    }
+  }
+  return seeders;
+}
+
+export async function collectSeederFiles(directory: string) {
+  const files = await walk(directory, "");
+  return files.filter(
+    (file) => file.endsWith(".ts") && !file.endsWith(".test.ts"),
+  );
+}
+
+async function walk(directory: string, prefix: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...(await walk(path.join(directory, entry.name), relative)));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(relative);
+    }
+  }
+  return files;
+}

package/src/seed/report.test.ts

@@ -0,0 +1,16 @@
+import { Chalk } from "chalk";
+import { describe, expect, it } from "vitest";
+import { formatSeed } from "./report.ts";
+
+describe("formatSeed", () => {
+  it("lists inserted rows and an empty seed folder", () => {
+    expect(formatSeed([{ table: "users", inserted: 2 }])).toBe(
+      "\n  SEED\n\n  - users      2\n",
+    );
+    expect(formatSeed([])).toBe("\n  SEED\n\n  - Seeders    none\n");
+    const style = new Chalk({ level: 1 });
+    expect(formatSeed([{ table: "users", inserted: 2 }], true)).toContain(
+      style.dim("SEED"),
+    );
+  });
+});

package/src/seed/report.ts

@@ -0,0 +1,15 @@
+import { Chalk } from "chalk";
+
+export function formatSeed(
+  results: readonly { table: string; inserted: number }[],
+  color = false,
+) {
+  const style = new Chalk({ level: color ? 1 : 0 });
+  const row = (label: string, value: string) =>
+    `  ${style.dim(`- ${label.padEnd(10)}`)} ${value}`;
+  const lines =
+    results.length > 0
+      ? results.map((result) => row(result.table, String(result.inserted)))
+      : [row("Seeders", "none")];
+  return `\n  ${style.dim("SEED")}\n\n${lines.join("\n")}\n`;
+}

package/src/self-test/checks.ts

@@ -0,0 +1,88 @@
+import os from "node:os";
+import {
+  type EnvSource,
+  openApiServerEnv,
+  requiredEnv,
+  validateOpenApiServer,
+} from "../env/required-env.ts";
+
+const supportedPlatforms = new Set(["darwin", "linux", "win32"]);
+const supportedArchitectures = new Set(["arm64", "x64"]);
+
+export type BunRuntime = {
+  version?: string;
+  env?: EnvSource;
+};
+
+export type MachineInfo = {
+  platform: string;
+  arch: string;
+  hostname: string;
+};
+
+type Failure = {
+  ok: false;
+  error: string;
+};
+
+export type BunCheck =
+  | {
+      ok: true;
+      version: string;
+    }
+  | Failure;
+
+export type MachineCheck = ({ ok: true } & MachineInfo) | Failure;
+
+export type EnvCheck = { ok: true } | Failure;
+
+export function checkBun(runtime: BunRuntime | undefined): BunCheck {
+  if (
+    runtime == null ||
+    typeof runtime.version !== "string" ||
+    runtime.version === ""
+  ) {
+    return { ok: false, error: "Process is not running in Bun" };
+  }
+  return { ok: true, version: runtime.version };
+}
+
+export function checkMachine(
+  machine: MachineInfo = readMachine(),
+): MachineCheck {
+  if (!supportedPlatforms.has(machine.platform)) {
+    return { ok: false, error: `Unsupported platform ${machine.platform}` };
+  }
+  if (!supportedArchitectures.has(machine.arch)) {
+    return { ok: false, error: `Unsupported architecture ${machine.arch}` };
+  }
+  return { ok: true, ...machine };
+}
+
+export function checkEnv(env: EnvSource): EnvCheck {
+  const errors: string[] = [];
+  for (const requirement of requiredEnv) {
+    const error = requirement.validate(env[requirement.name]);
+    if (error) {
+      errors.push(error);
+    }
+  }
+  for (const server of openApiServerEnv) {
+    const error = validateOpenApiServer(server.name, env[server.name]);
+    if (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length > 0) {
+    return { ok: false, error: errors.join("\n") };
+  }
+  return { ok: true };
+}
+
+function readMachine(): MachineInfo {
+  return {
+    platform: os.platform(),
+    arch: os.arch(),
+    hostname: os.hostname(),
+  };
+}

package/src/self-test/run.test.ts

@@ -0,0 +1,128 @@
+import { Chalk } from "chalk";
+import { describe, expect, it } from "vitest";
+import { checkEnv, checkMachine } from "./checks.ts";
+import { formatSelfTest, runSelfTest } from "./run.ts";
+
+const validEnv = {
+  HOST: "127.0.0.1",
+  HTTP_PORT: "3000",
+  HTTP_SERVICE_PORT: "3001",
+};
+
+describe("runSelfTest", () => {
+  it("stops when the process is not Bun", () => {
+    const result = runSelfTest({
+      runtime: undefined,
+      env: {},
+    });
+    expect(result).toEqual({
+      ok: false,
+      step: "bun",
+      error: "Process is not running in Bun",
+    });
+  });
+
+  it("checks the machine after Bun and before env", () => {
+    const result = runSelfTest({
+      runtime: { version: "1.4.4", env: validEnv },
+      machine: { platform: "freebsd", arch: "x64", hostname: "test" },
+      env: {},
+    });
+    expect(result).toEqual({
+      ok: false,
+      step: "machine",
+      error: "Unsupported platform freebsd",
+    });
+  });
+
+  it("checks required env after the machine", () => {
+    const result = runSelfTest({
+      runtime: { version: "1.4.4" },
+      machine: { platform: "linux", arch: "x64", hostname: "test" },
+      env: { HOST: "127.0.0.1" },
+    });
+    if (result.ok) {
+      throw new Error("expected env check to fail");
+    }
+    expect(result.step).toBe("env");
+    const checked = checkEnv({
+      HOST: " ",
+      HTTP_PORT: "70000",
+      HTTP_SERVICE_PORT: "3001",
+    });
+    if (checked.ok) {
+      throw new Error("expected env check to fail");
+    }
+    expect(checked.error).toContain("HOST is required");
+    expect(checked.error).toContain(
+      "HTTP_PORT must be an integer from 1 to 65535",
+    );
+    const openApi = checkEnv({
+      ...validEnv,
+      OPENAPI_SERVER: "notaurl",
+    });
+    if (openApi.ok) {
+      throw new Error("expected openapi server check to fail");
+    }
+    expect(openApi.error).toContain(
+      "OPENAPI_SERVER must be an absolute http or https URL",
+    );
+  });
+
+  it("prints the checks in the same rows as the server addresses", () => {
+    expect(
+      formatSelfTest({
+        ok: true,
+        bun: { ok: true, version: "1.4.4" },
+        machine: {
+          ok: true,
+          platform: "win32",
+          arch: "x64",
+          hostname: "Plomyk",
+        },
+      }),
+    ).toBe(
+      "\n  SELF TEST\n\n  - Bun      1.4.4\n  - Machine  win32 x64 Plomyk\n  - Env      ready\n\n  successful\n",
+    );
+    expect(
+      formatSelfTest({
+        ok: false,
+        step: "env",
+        error: "HOST is required\nHTTP_PORT must be an integer from 1 to 65535",
+      }),
+    ).toBe(
+      "\n  SELF TEST\n\n  x Env\n    HOST is required\n    HTTP_PORT must be an integer from 1 to 65535\n\n  failed, exiting\n",
+    );
+    const style = new Chalk({ level: 1 });
+    const passed = formatSelfTest(
+      {
+        ok: true,
+        bun: { ok: true, version: "1.4.4" },
+        machine: {
+          ok: true,
+          platform: "win32",
+          arch: "x64",
+          hostname: "Plomyk",
+        },
+      },
+      true,
+    );
+    expect(passed).toContain(style.green("successful"));
+    const failed = formatSelfTest(
+      { ok: false, step: "env", error: "HOST is required" },
+      true,
+    );
+    expect(failed).toContain(style.red("failed, exiting"));
+    expect(failed).toContain(style.red("x Env"));
+  });
+
+  it("accepts this machine when the platform and architecture are supported", () => {
+    const machine = checkMachine();
+    if (!machine.ok) {
+      throw new Error(machine.error);
+    }
+    expect(["darwin", "linux", "win32"]).toContain(machine.platform);
+    expect(["arm64", "x64"]).toContain(machine.arch);
+    expect(machine.hostname.length).toBeGreaterThan(0);
+  });
+});