@veducio/keja 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veducio/keja",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "packageManager": "bun@1.4.4",
   "description": "Veducio Keja - RESTFUL Web Server, Based on Lightweight Hono Framework, Written in TypeScript, Powered by Bun",
   "license": "MIT",

package/src/cli/dev-reload.ts

@@ -10,6 +10,7 @@ import {
   printServers,
   readProjectFailure,
 } from "./run-project.ts";
+import { scaffoldEmptyRoutes } from "./scaffold-empty-route.ts";
 
 export const reloadDebounceMs = 50;
 
@@ -111,6 +112,7 @@ export async function runDev(root = process.cwd()) {
       const token = String(generation);
       if (running) {
         printReloading();
+        await scaffoldEmptyRoutes(running.paths.public, running.paths.service);
       }
       const result = await refreshDevProject({
         running: running !== null,

package/src/cli/scaffold-empty-route.test.ts

@@ -0,0 +1,67 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  emptyRouteSource,
+  routePathFromFile,
+  scaffoldEmptyRouteFile,
+  scaffoldEmptyRoutes,
+} from "./scaffold-empty-route.ts";
+
+describe("scaffold empty route", () => {
+  it("derives a path from the file name", () => {
+    expect(routePathFromFile("src/public/notes.ts")).toBe("/notes");
+    expect(routePathFromFile("hello.world.ts")).toBe("/hello.world");
+    expect(routePathFromFile("bad name.ts")).toBe("/route");
+  });
+
+  it("writes a public get stub and a service post stub", () => {
+    expect(emptyRouteSource("public", "/items")).toContain('method: "get"');
+    expect(emptyRouteSource("public", "/items")).toContain('path: "/items"');
+    expect(emptyRouteSource("service", "/jobs")).toContain('method: "post"');
+  });
+
+  it("fills an empty route file once", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "keja-scaffold-"));
+    const file = path.join(directory, "items.ts");
+    await writeFile(file, "");
+    expect(await scaffoldEmptyRouteFile(file, "public")).toBe(true);
+    const first = await readFile(file, "utf8");
+    expect(first).toContain('path: "/items"');
+    expect(await scaffoldEmptyRouteFile(file, "public")).toBe(false);
+    expect(await readFile(file, "utf8")).toBe(first);
+  });
+
+  it("fills empty route modules under public and service folders", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "keja-scaffold-dirs-"));
+    const publicDir = path.join(root, "public");
+    const serviceDir = path.join(root, "service");
+    mkdirSync(publicDir);
+    mkdirSync(serviceDir);
+    writeFileSync(path.join(publicDir, "notes.ts"), "   \n");
+    writeFileSync(path.join(publicDir, "_middleware.ts"), "");
+    writeFileSync(path.join(serviceDir, "jobs.ts"), "");
+    writeFileSync(path.join(publicDir, "ready.ts"), "export {}\n");
+    const written = await scaffoldEmptyRoutes(publicDir, serviceDir);
+    expect(written.sort()).toEqual(
+      [
+        path.join(publicDir, "notes.ts"),
+        path.join(serviceDir, "jobs.ts"),
+      ].sort(),
+    );
+    expect(await readFile(path.join(publicDir, "notes.ts"), "utf8")).toContain(
+      'method: "get"',
+    );
+    expect(await readFile(path.join(serviceDir, "jobs.ts"), "utf8")).toContain(
+      'method: "post"',
+    );
+    expect(await readFile(path.join(publicDir, "_middleware.ts"), "utf8")).toBe(
+      "",
+    );
+    expect(await readFile(path.join(publicDir, "ready.ts"), "utf8")).toBe(
+      "export {}\n",
+    );
+  });
+});

package/src/cli/scaffold-empty-route.ts

@@ -0,0 +1,72 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { collectRouteFiles } from "../project/load.ts";
+
+export function routePathFromFile(file: string) {
+  const base = path.basename(file, ".ts");
+  if (/^[A-Za-z0-9._~-]+$/.test(base)) {
+    return `/${base}`;
+  }
+  return "/route";
+}
+
+export function emptyRouteSource(
+  surface: "public" | "service",
+  routePath: string,
+) {
+  const method = surface === "service" ? "post" : "get";
+  return `import { defineRoute, response } from "@veducio/keja";
+import { z } from "zod";
+
+export default defineRoute({
+  method: "${method}",
+  path: "${routePath}",
+  version: "v1",
+  responses: {
+    Ok: response({
+      code: 200,
+      json: z.object({ ok: z.literal(true) }),
+    }),
+  },
+  handler: ({ respond }) => respond.Ok({ ok: true }),
+});
+`;
+}
+
+export async function scaffoldEmptyRouteFile(
+  file: string,
+  surface: "public" | "service",
+) {
+  if (!existsSync(file)) {
+    return false;
+  }
+  const content = await readFile(file, "utf8");
+  if (content.trim() !== "") {
+    return false;
+  }
+  await writeFile(file, emptyRouteSource(surface, routePathFromFile(file)));
+  return true;
+}
+
+export async function scaffoldEmptyRoutes(
+  publicDir: string,
+  serviceDir: string,
+) {
+  const written: string[] = [];
+  for (const [surface, directory] of [
+    ["public", publicDir],
+    ["service", serviceDir],
+  ] as const) {
+    if (!existsSync(directory)) {
+      continue;
+    }
+    for (const relative of await collectRouteFiles(directory)) {
+      const file = path.join(directory, relative);
+      if (await scaffoldEmptyRouteFile(file, surface)) {
+        written.push(file);
+      }
+    }
+  }
+  return written;
+}

package/src/repository/generate.test.ts

@@ -55,4 +55,20 @@ describe("renderRepositories", () => {
     );
     expect(source).toContain('list: { filters: ["name"], limit: 20 },');
   });
+
+  it("writes enum columns with their values", () => {
+    const tables = readTables([
+      {
+        file: "0001_example.sql",
+        sql: `
+          create type post_status as enum ('draft', 'published');
+          create table posts (${owned}, status post_status not null);
+        `,
+      },
+    ]);
+    const source = renderRepositories(tables, new Map());
+    expect(source).toContain(
+      'status: { type: "enum", values: ["draft", "published"], nullable: false },',
+    );
+  });
 });

package/src/repository/generate.ts

@@ -82,10 +82,7 @@ function renderRepository(
   flags: { list: ResolvedList; get: boolean } | undefined,
 ) {
   const columns = table.columns
-    .map(
-      (column) =>
-        `    ${column.name}: { type: "${column.type}", nullable: ${column.nullable} },`,
-    )
+    .map((column) => renderColumn(column))
     .join("\n");
   const options = [
     renderList(flags?.list),
@@ -115,3 +112,13 @@ function renderList(list: ResolvedList | undefined) {
   ].filter((part) => part !== "");
   return `  list: { ${parts.join(", ")} },`;
 }
+
+function renderColumn(column: TableSchema["columns"][number]) {
+  if (column.type === "enum") {
+    const values = column.values
+      .map((value) => JSON.stringify(value))
+      .join(", ");
+    return `    ${column.name}: { type: "enum", values: [${values}], nullable: ${column.nullable} },`;
+  }
+  return `    ${column.name}: { type: "${column.type}", nullable: ${column.nullable} },`;
+}

package/src/repository/query.ts

@@ -245,6 +245,11 @@ function parseValue(column: DomainColumn, value: string) {
     }
     return value;
   }
+  if (column.type === "enum" && !column.values.includes(value)) {
+    throw new Error(
+      `${column.name} filter must be ${column.values.join(", ")}`,
+    );
+  }
   return value;
 }
 

package/src/repository/runtime.test.ts

@@ -29,6 +29,23 @@ describe("repository", () => {
     }
   });
 
+  it("validates enum columns against declared values", () => {
+    const posts = repository({
+      table: "posts",
+      columns: {
+        status: {
+          type: "enum",
+          values: ["draft", "published"],
+          nullable: false,
+        },
+      },
+    });
+    expect(posts.schema.parse({ status: "draft" })).toEqual({
+      status: "draft",
+    });
+    expect(() => posts.schema.parse({ status: "archived" })).toThrow();
+  });
+
   it("exposes a row schema with and without meta", () => {
     const users = repository({ table: "users", columns });
     const at = new Date("2026-01-15T00:00:00.000Z");
@@ -38,6 +55,7 @@ describe("repository", () => {
       name: "Ada",
       email: "ada@example.com",
     });
+
     expect(
       users.meta.parse({
         ...row("users_a", "Ada"),

package/src/repository/runtime.ts

@@ -10,31 +10,42 @@ import {
 } from "./query.ts";
 import type { ColumnType, DomainColumn } from "./sql.ts";
 
-export type ColumnSpec = {
-  readonly type: ColumnType;
-  readonly nullable: boolean;
-};
+export type ColumnSpec =
+  | {
+      readonly type: Exclude<ColumnType, "enum">;
+      readonly nullable: boolean;
+    }
+  | {
+      readonly type: "enum";
+      readonly values: readonly [string, ...string[]];
+      readonly nullable: boolean;
+    };
 
-type TsValue<Type extends ColumnType> = Type extends "text"
-  ? string
-  : Type extends "boolean"
-    ? boolean
-    : Type extends "timestamptz"
-      ? Date
-      : Type extends "integer"
-        ? number
-        : Type extends "bigint"
-          ? string
-          : Type extends "numeric"
+type SpecValue<Spec extends ColumnSpec> = Spec extends {
+  type: "enum";
+  values: readonly (infer Value)[];
+}
+  ? Value
+  : Spec["type"] extends "text"
+    ? string
+    : Spec["type"] extends "boolean"
+      ? boolean
+      : Spec["type"] extends "timestamptz"
+        ? Date
+        : Spec["type"] extends "integer"
+          ? number
+          : Spec["type"] extends "bigint"
             ? string
-            : Type extends "jsonb"
-              ? unknown
-              : never;
+            : Spec["type"] extends "numeric"
+              ? string
+              : Spec["type"] extends "jsonb"
+                ? unknown
+                : never;
 
 export type DomainRow<Columns extends Record<string, ColumnSpec>> = {
   [Key in keyof Columns]: Columns[Key]["nullable"] extends true
-    ? TsValue<Columns[Key]["type"]> | null
-    : TsValue<Columns[Key]["type"]>;
+    ? SpecValue<Columns[Key]> | null
+    : SpecValue<Columns[Key]>;
 };
 
 export type RepositoryRow<Columns extends Record<string, ColumnSpec>> = {
@@ -133,11 +144,21 @@ export function repository<
 }): Repository<Columns> &
   (List extends false ? object : { list: ListProcessor<Columns, List> }) &
   (Get extends true ? { get: GetProcessor<Columns> } : object) {
-  const columns = Object.entries(input.columns).map(([name, column]) => ({
-    name,
-    type: column.type,
-    nullable: column.nullable,
-  }));
+  const columns = Object.entries(input.columns).map(
+    ([name, column]): DomainColumn =>
+      column.type === "enum"
+        ? {
+            name,
+            type: "enum",
+            nullable: column.nullable,
+            values: column.values,
+          }
+        : {
+            name,
+            type: column.type,
+            nullable: column.nullable,
+          },
+  );
   const shape = rowSchemas(columns);
   const base: Repository<Columns> = {
     table: input.table,
@@ -240,7 +261,7 @@ function listFilters(
 function rowSchemas(columns: readonly DomainColumn[]) {
   const domain: Record<string, z.ZodType> = {};
   for (const column of columns) {
-    domain[column.name] = columnSchema(column.type, column.nullable);
+    domain[column.name] = columnSchema(column);
   }
   return {
     schema: z.object(domain),
@@ -256,20 +277,22 @@ function rowSchemas(columns: readonly DomainColumn[]) {
   };
 }
 
-function columnSchema(type: ColumnType, nullable: boolean) {
+function columnSchema(column: DomainColumn) {
   const schema =
-    type === "boolean"
+    column.type === "boolean"
       ? z.boolean()
-      : type === "timestamptz"
+      : column.type === "timestamptz"
         ? z.date()
-        : type === "integer"
+        : column.type === "integer"
           ? z.number().int()
-          : type === "bigint" || type === "numeric"
+          : column.type === "bigint" || column.type === "numeric"
             ? z.string()
-            : type === "jsonb"
+            : column.type === "jsonb"
               ? z.unknown()
-              : z.string();
-  return nullable ? schema.nullable() : schema;
+              : column.type === "enum"
+                ? z.enum(column.values)
+                : z.string();
+  return column.nullable ? schema.nullable() : schema;
 }
 
 function builtQuerySort(sort: string | undefined) {

package/src/repository/sql.test.ts

@@ -75,4 +75,37 @@ describe("readTables", () => {
       ]),
     ).toThrow("users.photo has no TypeScript type");
   });
+
+  it("reads create type enums and columns that use them", () => {
+    const tables = readTables([
+      {
+        file: "0001_status.sql",
+        sql: `
+          create type post_status as enum ('draft', 'published');
+          create table posts (${owned}, status post_status not null);
+          alter type post_status add value 'archived';
+          alter table posts add column visibility post_status;
+        `,
+      },
+    ]);
+    expect(tables).toEqual([
+      {
+        name: "posts",
+        columns: [
+          {
+            name: "status",
+            type: "enum",
+            nullable: false,
+            values: ["draft", "published", "archived"],
+          },
+          {
+            name: "visibility",
+            type: "enum",
+            nullable: true,
+            values: ["draft", "published", "archived"],
+          },
+        ],
+      },
+    ]);
+  });
 });

package/src/repository/sql.ts

@@ -7,13 +7,21 @@ export type ColumnType =
   | "integer"
   | "bigint"
   | "numeric"
-  | "jsonb";
+  | "jsonb"
+  | "enum";
 
-export type DomainColumn = {
-  name: string;
-  type: ColumnType;
-  nullable: boolean;
-};
+export type DomainColumn =
+  | {
+      name: string;
+      type: Exclude<ColumnType, "enum">;
+      nullable: boolean;
+    }
+  | {
+      name: string;
+      type: "enum";
+      nullable: boolean;
+      values: readonly [string, ...string[]];
+    };
 
 export type TableSchema = {
   name: string;
@@ -29,7 +37,10 @@ const reservedTypes = {
   _updatedAt: "timestamptz",
 } as const;
 
-const typePatterns: readonly { pattern: RegExp; type: ColumnType }[] = [
+const typePatterns: readonly {
+  pattern: RegExp;
+  type: Exclude<ColumnType, "enum">;
+}[] = [
   { pattern: /^timestamptz\b/i, type: "timestamptz" },
   { pattern: /^timestamp\s+with\s+time\s+zone\b/i, type: "timestamptz" },
   { pattern: /^boolean\b/i, type: "boolean" },
@@ -47,48 +58,114 @@ const typePatterns: readonly { pattern: RegExp; type: ColumnType }[] = [
   { pattern: /^character\s+varying\b/i, type: "text" },
 ];
 
-type ParsedColumn = DomainColumn;
+type WorkingColumn =
+  | {
+      name: string;
+      type: Exclude<ColumnType, "enum">;
+      nullable: boolean;
+    }
+  | {
+      name: string;
+      type: "enum";
+      nullable: boolean;
+      enumName: string;
+    };
 
 type WorkingTable = {
   name: string;
-  reserved: Map<string, ParsedColumn>;
-  columns: DomainColumn[];
+  reserved: Map<string, WorkingColumn>;
+  columns: WorkingColumn[];
 };
 
 export function readTables(files: readonly { file: string; sql: string }[]) {
   const tables = new Map<string, WorkingTable>();
+  const enums = new Map<string, [string, ...string[]]>();
   for (const file of files) {
     for (const statement of statements(stripComments(file.sql))) {
-      applyStatement(tables, file.file, statement);
+      applyStatement(tables, enums, file.file, statement);
     }
   }
   return [...tables.values()]
-    .map((table) => finishTable(table))
+    .map((table) => finishTable(table, enums))
     .sort((left, right) => left.name.localeCompare(right.name));
 }
 
 function applyStatement(
   tables: Map<string, WorkingTable>,
+  enums: Map<string, [string, ...string[]]>,
   file: string,
   statement: string,
 ) {
+  const createType = statement.match(
+    /^create\s+type\s+(?:if\s+not\s+exists\s+)?(.+?)\s+as\s+enum\s*\(([\s\S]*)\)\s*$/i,
+  );
+  if (createType?.[1] && createType[2] !== undefined) {
+    createEnum(enums, file, createType[1].trim(), createType[2]);
+    return;
+  }
+  const alterType = statement.match(
+    /^alter\s+type\s+(.+?)\s+add\s+value\s+(?:if\s+not\s+exists\s+)?([\s\S]+)$/i,
+  );
+  if (alterType?.[1] && alterType[2]) {
+    addEnumValue(enums, file, alterType[1].trim(), alterType[2].trim());
+    return;
+  }
   const create = statement.match(
     /^create\s+table\s+(?:if\s+not\s+exists\s+)?([\s\S]+)$/i,
   );
   if (create?.[1]) {
-    createTable(tables, file, create[1]);
+    createTable(tables, enums, file, create[1]);
     return;
   }
   const alter = statement.match(
     /^alter\s+table\s+(.+?)\s+add\s+(?:column\s+)?(?:if\s+not\s+exists\s+)?([\s\S]+)$/i,
   );
   if (alter?.[1] && alter[2]) {
-    addColumn(tables, file, alter[1].trim(), alter[2].trim());
+    addColumn(tables, enums, file, alter[1].trim(), alter[2].trim());
+  }
+}
+
+function createEnum(
+  enums: Map<string, [string, ...string[]]>,
+  file: string,
+  token: string,
+  body: string,
+) {
+  const name = typeName(token, file);
+  if (enums.has(name)) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} creates type ${name} more than once`,
+    );
   }
+  const values = readEnumValues(body, file, name);
+  enums.set(name, values);
+}
+
+function addEnumValue(
+  enums: Map<string, [string, ...string[]]>,
+  file: string,
+  token: string,
+  rest: string,
+) {
+  const name = typeName(token, file);
+  const current = enums.get(name);
+  if (!current) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} adds a value to missing type ${name}`,
+    );
+  }
+  const value = readEnumLiteral(rest, file, name);
+  if (current.includes(value)) {
+    return;
+  }
+  enums.set(name, [...current, value]);
 }
 
 function createTable(
   tables: Map<string, WorkingTable>,
+  enums: Map<string, [string, ...string[]]>,
   file: string,
   rest: string,
 ) {
@@ -116,7 +193,7 @@ function createTable(
     if (isConstraint(part)) {
       continue;
     }
-    const column = readColumn(part, file, name);
+    const column = readColumn(part, file, name, enums);
     storeColumn(table, column, file);
   }
   tables.set(name, table);
@@ -124,6 +201,7 @@ function createTable(
 
 function addColumn(
   tables: Map<string, WorkingTable>,
+  enums: Map<string, [string, ...string[]]>,
   file: string,
   tableToken: string,
   definition: string,
@@ -136,11 +214,11 @@ function addColumn(
       `${file} adds a column to missing table ${name}`,
     );
   }
-  const column = readColumn(definition, file, name);
+  const column = readColumn(definition, file, name, enums);
   storeColumn(table, column, file);
 }
 
-function storeColumn(table: WorkingTable, column: ParsedColumn, file: string) {
+function storeColumn(table: WorkingTable, column: WorkingColumn, file: string) {
   if (column.name in reservedTypes) {
     if (table.reserved.has(column.name)) {
       throw projectError(
@@ -166,7 +244,10 @@ function storeColumn(table: WorkingTable, column: ParsedColumn, file: string) {
   table.columns.push(column);
 }
 
-function finishTable(table: WorkingTable): TableSchema {
+function finishTable(
+  table: WorkingTable,
+  enums: Map<string, [string, ...string[]]>,
+): TableSchema {
   for (const [name, type] of Object.entries(reservedTypes)) {
     const column = table.reserved.get(name);
     if (!column || column.nullable || column.type !== type) {
@@ -176,26 +257,78 @@ function finishTable(table: WorkingTable): TableSchema {
       );
     }
   }
-  return { name: table.name, columns: table.columns };
+  return {
+    name: table.name,
+    columns: table.columns.map((column) => finishColumn(column, enums)),
+  };
 }
 
-function readColumn(definition: string, file: string, table: string) {
-  const ident = readIdent(definition.trim());
-  if (!ident) {
+function finishColumn(
+  column: WorkingColumn,
+  enums: Map<string, [string, ...string[]]>,
+): DomainColumn {
+  if (column.type !== "enum") {
+    return column;
+  }
+  const values = enums.get(column.enumName);
+  if (!values) {
     throw projectError(
       "invalidRepositorySql",
-      `${file} has a column in ${table} Keja cannot read`,
+      `${column.name} references missing type ${column.enumName}`,
     );
   }
-  const mapped = typePatterns.find((item) => item.pattern.test(ident.rest));
-  if (!mapped) {
+  return {
+    name: column.name,
+    type: "enum",
+    nullable: column.nullable,
+    values,
+  };
+}
+
+function readColumn(
+  definition: string,
+  file: string,
+  table: string,
+  enums: Map<string, [string, ...string[]]>,
+): WorkingColumn {
+  const ident = readIdent(definition.trim());
+  if (!ident) {
     throw projectError(
       "invalidRepositorySql",
-      `${file} column ${table}.${ident.name} has no TypeScript type`,
+      `${file} has a column in ${table} Keja cannot read`,
     );
   }
+  const mapped = typePatterns.find((item) => item.pattern.test(ident.rest));
   const nullable = !/\b(?:not\s+null|primary\s+key)\b/i.test(ident.rest);
-  return { name: ident.name, type: mapped.type, nullable };
+  if (mapped) {
+    return { name: ident.name, type: mapped.type, nullable };
+  }
+  const enumName = readTypeReference(ident.rest);
+  if (enumName && enums.has(enumName)) {
+    return { name: ident.name, type: "enum", nullable, enumName };
+  }
+  throw projectError(
+    "invalidRepositorySql",
+    `${file} column ${table}.${ident.name} has no TypeScript type`,
+  );
+}
+
+function readTypeReference(rest: string) {
+  const parts: string[] = [];
+  let remaining = rest.trim();
+  while (remaining !== "") {
+    const ident = readIdent(remaining);
+    if (!ident) {
+      break;
+    }
+    parts.push(ident.name);
+    remaining = ident.rest;
+    if (!remaining.startsWith(".")) {
+      break;
+    }
+    remaining = remaining.slice(1).trim();
+  }
+  return parts.at(-1);
 }
 
 function tableName(token: string, file: string) {
@@ -214,6 +347,45 @@ function tableName(token: string, file: string) {
   return name;
 }
 
+function typeName(token: string, file: string) {
+  const name = readTypeReference(token);
+  if (!name || !/^[a-z_][a-z0-9_]*$/.test(name)) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} has a type name Keja cannot read`,
+    );
+  }
+  return name;
+}
+
+function readEnumValues(body: string, file: string, type: string) {
+  const values: string[] = [];
+  for (const part of splitTopLevel(body)) {
+    if (part.trim() === "") {
+      continue;
+    }
+    values.push(readEnumLiteral(part.trim(), file, type));
+  }
+  if (values.length === 0) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} type ${type} has no enum values`,
+    );
+  }
+  return values as [string, ...string[]];
+}
+
+function readEnumLiteral(value: string, file: string, type: string) {
+  const match = value.match(/^'((?:[^']|'')*)'(?:\s+.*)?$/s);
+  if (!match?.[1]) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} type ${type} has an enum value Keja cannot read`,
+    );
+  }
+  return match[1].replaceAll("''", "'");
+}
+
 function isConstraint(part: string) {
   return /^(?:check|constraint|primary|unique|foreign)\b/i.test(part.trim());
 }