@veducio/keja 0.0.0-stage → 0.3.0

package/src/repository/sql.ts

@@ -0,0 +1,282 @@
+import { projectError } from "../errors/framework-errors.ts";
+
+export type ColumnType =
+  | "text"
+  | "boolean"
+  | "timestamptz"
+  | "integer"
+  | "bigint"
+  | "numeric"
+  | "jsonb";
+
+export type DomainColumn = {
+  name: string;
+  type: ColumnType;
+  nullable: boolean;
+};
+
+export type TableSchema = {
+  name: string;
+  columns: DomainColumn[];
+};
+
+const reservedTypes = {
+  _id: "text",
+  _object: "text",
+  _tenant: "text",
+  _archived: "boolean",
+  _createdAt: "timestamptz",
+  _updatedAt: "timestamptz",
+} as const;
+
+const typePatterns: readonly { pattern: RegExp; type: ColumnType }[] = [
+  { pattern: /^timestamptz\b/i, type: "timestamptz" },
+  { pattern: /^timestamp\s+with\s+time\s+zone\b/i, type: "timestamptz" },
+  { pattern: /^boolean\b/i, type: "boolean" },
+  { pattern: /^bool\b/i, type: "boolean" },
+  { pattern: /^bigint\b/i, type: "bigint" },
+  { pattern: /^int8\b/i, type: "bigint" },
+  { pattern: /^integer\b/i, type: "integer" },
+  { pattern: /^int4\b/i, type: "integer" },
+  { pattern: /^int\b/i, type: "integer" },
+  { pattern: /^numeric\b/i, type: "numeric" },
+  { pattern: /^decimal\b/i, type: "numeric" },
+  { pattern: /^jsonb\b/i, type: "jsonb" },
+  { pattern: /^text\b/i, type: "text" },
+  { pattern: /^varchar\b/i, type: "text" },
+  { pattern: /^character\s+varying\b/i, type: "text" },
+];
+
+type ParsedColumn = DomainColumn;
+
+type WorkingTable = {
+  name: string;
+  reserved: Map<string, ParsedColumn>;
+  columns: DomainColumn[];
+};
+
+export function readTables(files: readonly { file: string; sql: string }[]) {
+  const tables = new Map<string, WorkingTable>();
+  for (const file of files) {
+    for (const statement of statements(stripComments(file.sql))) {
+      applyStatement(tables, file.file, statement);
+    }
+  }
+  return [...tables.values()]
+    .map((table) => finishTable(table))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function applyStatement(
+  tables: Map<string, WorkingTable>,
+  file: string,
+  statement: string,
+) {
+  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]);
+    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());
+  }
+}
+
+function createTable(
+  tables: Map<string, WorkingTable>,
+  file: string,
+  rest: string,
+) {
+  const open = rest.indexOf("(");
+  const close = rest.lastIndexOf(")");
+  if (open === -1 || close === -1 || close < open) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} has a CREATE TABLE Keja cannot read`,
+    );
+  }
+  const name = tableName(rest.slice(0, open).trim(), file);
+  if (tables.has(name)) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} creates ${name} more than once`,
+    );
+  }
+  const table: WorkingTable = {
+    name,
+    reserved: new Map(),
+    columns: [],
+  };
+  for (const part of splitTopLevel(rest.slice(open + 1, close))) {
+    if (isConstraint(part)) {
+      continue;
+    }
+    const column = readColumn(part, file, name);
+    storeColumn(table, column, file);
+  }
+  tables.set(name, table);
+}
+
+function addColumn(
+  tables: Map<string, WorkingTable>,
+  file: string,
+  tableToken: string,
+  definition: string,
+) {
+  const name = tableName(tableToken, file);
+  const table = tables.get(name);
+  if (!table) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} adds a column to missing table ${name}`,
+    );
+  }
+  const column = readColumn(definition, file, name);
+  storeColumn(table, column, file);
+}
+
+function storeColumn(table: WorkingTable, column: ParsedColumn, file: string) {
+  if (column.name in reservedTypes) {
+    if (table.reserved.has(column.name)) {
+      throw projectError(
+        "invalidRepositorySql",
+        `${file} defines ${table.name}.${column.name} more than once`,
+      );
+    }
+    table.reserved.set(column.name, column);
+    return;
+  }
+  if (column.name.startsWith("_")) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} column ${table.name}.${column.name} is reserved`,
+    );
+  }
+  if (table.columns.some((item) => item.name === column.name)) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} defines ${table.name}.${column.name} more than once`,
+    );
+  }
+  table.columns.push(column);
+}
+
+function finishTable(table: WorkingTable): TableSchema {
+  for (const [name, type] of Object.entries(reservedTypes)) {
+    const column = table.reserved.get(name);
+    if (!column || column.nullable || column.type !== type) {
+      throw projectError(
+        "invalidRepositorySql",
+        `${table.name}.${name} must be ${type} not null`,
+      );
+    }
+  }
+  return { name: table.name, columns: table.columns };
+}
+
+function readColumn(definition: string, file: string, table: string) {
+  const ident = readIdent(definition.trim());
+  if (!ident) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} has a column in ${table} Keja cannot read`,
+    );
+  }
+  const mapped = typePatterns.find((item) => item.pattern.test(ident.rest));
+  if (!mapped) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} column ${table}.${ident.name} has no TypeScript type`,
+    );
+  }
+  const nullable = !/\b(?:not\s+null|primary\s+key)\b/i.test(ident.rest);
+  return { name: ident.name, type: mapped.type, nullable };
+}
+
+function tableName(token: string, file: string) {
+  const parts = token
+    .trim()
+    .split(".")
+    .map((part) => readIdent(part.trim())?.name)
+    .filter((part): part is string => part !== undefined);
+  const name = parts.at(-1);
+  if (!name || !/^[a-z_][a-z0-9_]*$/.test(name)) {
+    throw projectError(
+      "invalidRepositorySql",
+      `${file} has a table name Keja cannot read`,
+    );
+  }
+  return name;
+}
+
+function isConstraint(part: string) {
+  return /^(?:check|constraint|primary|unique|foreign)\b/i.test(part.trim());
+}
+
+function readIdent(value: string) {
+  const quoted = value.match(/^"([^"]+)"(.*)$/s);
+  if (quoted?.[1] !== undefined) {
+    return { name: quoted[1], rest: quoted[2]?.trim() ?? "" };
+  }
+  const plain = value.match(/^([A-Za-z_][A-Za-z0-9_]*)(.*)$/s);
+  if (!plain?.[1]) {
+    return null;
+  }
+  return { name: plain[1].toLowerCase(), rest: plain[2]?.trim() ?? "" };
+}
+
+function stripComments(sql: string) {
+  return sql.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--.*$/gm, " ");
+}
+
+function statements(sql: string) {
+  return splitTopLevel(sql, ";").filter((statement) => statement.trim() !== "");
+}
+
+function splitTopLevel(value: string, separator = ",") {
+  const parts: string[] = [];
+  let current = "";
+  let depth = 0;
+  let quote: "'" | '"' | null = null;
+  for (let index = 0; index < value.length; index++) {
+    const char = value[index] ?? "";
+    if (quote) {
+      current += char;
+      if (char === quote && value[index + 1] === quote) {
+        current += value[index + 1];
+        index += 1;
+        continue;
+      }
+      if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if (char === "(") {
+      depth += 1;
+    }
+    if (char === ")") {
+      depth -= 1;
+    }
+    if (char === separator && depth === 0) {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) {
+    parts.push(current.trim());
+  }
+  return parts;
+}

package/src/route/define.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineRoute, response } from "./define.ts";
+
+const ok = response({ code: 200, json: z.object({ id: z.string() }) });
+
+describe("defineRoute", () => {
+  it("rejects a method, a path, and a schema that are not usable", () => {
+    expect(() =>
+      route({
+        method: "GET" as "get",
+        path: "/posts",
+        responses: { Ok: ok },
+      }),
+    ).toThrow("Method GET must be get, post, put, patch, or delete");
+    expect(() =>
+      route({
+        method: "get",
+        path: "posts",
+        responses: { Ok: ok },
+      }),
+    ).toThrow("Path posts must start with /");
+    expect(() =>
+      route({
+        method: "get",
+        path: "/posts",
+        responses: {
+          Posts: response({
+            code: 200,
+            json: z.array(undefined as never),
+          }),
+        },
+      }),
+    ).toThrow("GET /posts response Posts must be a Zod schema");
+  });
+
+  it("accepts a nested path and a response array", () => {
+    expect(() =>
+      route({
+        method: "get",
+        path: "/orgs/:orgId/teams/:teamId",
+        responses: {
+          Teams: response({
+            code: 200,
+            json: z.object({
+              teams: z.array(z.object({ id: z.string() })),
+            }),
+          }),
+        },
+      }),
+    ).not.toThrow();
+  });
+});
+
+function route(definition: {
+  method: "get" | "post" | "put" | "patch" | "delete";
+  path: string;
+  responses: Record<string, { code: number; json: z.ZodType }>;
+}) {
+  return defineRoute({
+    ...definition,
+    version: "v1",
+    handler: () => new Response(),
+  });
+}

package/src/route/define.ts

@@ -0,0 +1,307 @@
+import type { ZodType } from "zod";
+import { frameworkError, projectError } from "../errors/framework-errors.ts";
+import { readVersionNumber, type VersionId } from "../versioning/define.ts";
+import { isMiddleware, type MiddlewareDefinition } from "./middleware.ts";
+
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+
+export type RequestSchemas = {
+  params?: ZodType;
+  query?: ZodType;
+  body?: ZodType;
+};
+
+export type RouteResponse = {
+  name: string;
+  code: number;
+  schema: ZodType;
+};
+
+type DefinedInput<Request extends RequestSchemas> = {
+  [Key in keyof Request & keyof RequestSchemas as Request[Key] extends ZodType
+    ? Key
+    : never]: Request[Key] extends ZodType ? Request[Key]["_output"] : never;
+};
+
+type ResponseDefinition = {
+  code: number;
+  json: ZodType;
+};
+
+type ResponseMap = Record<string, ResponseDefinition>;
+
+type JsonOutput<Schema> = Schema extends ZodType ? Schema["_output"] : never;
+
+type ResponseSchema<Definition> = Definition extends { json: infer Schema }
+  ? Schema
+  : never;
+
+type ResponseConstants<Definition> = Definition extends {
+  const: infer Constants extends object;
+}
+  ? Constants
+  : never;
+
+type VariableBody<Definition> =
+  ResponseConstants<Definition> extends never
+    ? JsonOutput<ResponseSchema<Definition>>
+    : Omit<
+        JsonOutput<ResponseSchema<Definition>>,
+        keyof ResponseConstants<Definition>
+      >;
+
+type RespondFns<Responses extends ResponseMap> = {
+  [Name in keyof Responses]: keyof VariableBody<Responses[Name]> extends never
+    ? () => Response
+    : (body: VariableBody<Responses[Name]>) => Response;
+};
+
+type UnionToIntersection<Union> = (
+  Union extends unknown
+    ? (value: Union) => void
+    : never
+) extends (value: infer Intersection) => void
+  ? Intersection
+  : never;
+
+type FieldsOf<Middleware> =
+  Middleware extends MiddlewareDefinition<infer Fields>
+    ? Fields
+    : Record<never, never>;
+
+type MergedFields<List extends readonly MiddlewareDefinition<object>[]> =
+  List extends readonly []
+    ? Record<never, never>
+    : UnionToIntersection<FieldsOf<List[number]>>;
+
+export type RouteDefinition = {
+  method: HttpMethod;
+  path: string;
+  version: string;
+  request: RequestSchemas;
+  responses: RouteResponse[];
+  middleware: readonly MiddlewareDefinition<object>[];
+  handle: (input: {
+    params?: unknown;
+    query?: unknown;
+    body?: unknown;
+    fields: Record<string, unknown>;
+  }) => Response | Promise<Response>;
+};
+
+const routeBrand = "keja.route";
+const httpMethods = ["get", "post", "put", "patch", "delete"] as const;
+
+const routePath =
+  /^\/(?:$|(?:[A-Za-z0-9._~-]+|:[A-Za-z_][A-Za-z0-9_]*)(?:\/(?:[A-Za-z0-9._~-]+|:[A-Za-z_][A-Za-z0-9_]*))*\/?)$/;
+
+export function response<
+  const Code extends number,
+  Schema extends ZodType,
+>(definition: { code: Code; json: Schema }): { code: Code; json: Schema };
+export function response<
+  const Code extends number,
+  Schema extends ZodType,
+  const Constants extends Partial<Schema["_output"]>,
+>(definition: {
+  code: Code;
+  json: Schema;
+  const: Constants;
+}): { code: Code; json: Schema; const: Constants };
+export function response(definition: {
+  code: number;
+  json: ZodType;
+  const?: object;
+}) {
+  return definition;
+}
+
+export function defineRoute<
+  const Version extends string,
+  const Request extends RequestSchemas,
+  const Responses extends ResponseMap,
+  const MiddlewareList extends readonly MiddlewareDefinition<object>[] = [],
+>(definition: {
+  method: HttpMethod;
+  path: string;
+  version: VersionId<Version> extends never
+    ? "Version must use the form v1, v2, v3"
+    : Version;
+  request?: Request;
+  middleware?: MiddlewareList;
+  responses: Responses;
+  handler: (
+    input: DefinedInput<Request> &
+      MergedFields<MiddlewareList> & { respond: RespondFns<Responses> },
+  ) => Response | Promise<Response>;
+}): RouteDefinition {
+  if (
+    typeof definition.method !== "string" ||
+    !httpMethods.includes(definition.method)
+  ) {
+    throw projectError(
+      "invalidRoute",
+      `Method ${String(definition.method)} must be get, post, put, patch, or delete`,
+    );
+  }
+  if (typeof definition.path !== "string" || !routePath.test(definition.path)) {
+    throw projectError(
+      "invalidRoute",
+      `Path ${String(definition.path)} must start with /`,
+    );
+  }
+  const request = definition.request as RequestSchemas | undefined;
+  if (request) {
+    for (const key of ["params", "query", "body"] as const) {
+      if (request[key] !== undefined) {
+        assertSchema(
+          request[key],
+          `${definition.method.toUpperCase()} ${definition.path} request.${key}`,
+        );
+      }
+    }
+  }
+  if (readVersionNumber(definition.version) === null) {
+    throw projectError(
+      "invalidVersionId",
+      `Version ${definition.version} must use the form v1, v2, v3`,
+    );
+  }
+  const responses = Object.entries(definition.responses).map(
+    ([name, defined]) => {
+      if (!defined || typeof defined !== "object" || !("json" in defined)) {
+        throw projectError(
+          "invalidRoute",
+          `${definition.method.toUpperCase()} ${definition.path} response ${name} must be created with response(...)`,
+        );
+      }
+      assertSchema(
+        defined.json,
+        `${definition.method.toUpperCase()} ${definition.path} response ${name}`,
+      );
+      if (
+        !Number.isInteger(defined.code) ||
+        defined.code < 100 ||
+        defined.code > 599
+      ) {
+        throw projectError(
+          "invalidStatusCode",
+          `Response ${name} has an invalid status code`,
+        );
+      }
+      return {
+        name,
+        code: defined.code,
+        schema: defined.json,
+      };
+    },
+  );
+  const respond = Object.fromEntries(
+    Object.entries(definition.responses).map(([name, defined]) => [
+      name,
+      (body: unknown) => {
+        const fixed = defined as ResponseDefinition & { const?: object };
+        const parsed = fixed.json.safeParse({
+          ...(isRecord(body) ? body : {}),
+          ...(fixed.const ?? {}),
+        });
+        if (!parsed.success) {
+          return Response.json(
+            frameworkError("invalidResponse", { issues: parsed.error.issues }),
+            { status: 500 },
+          );
+        }
+        return Response.json(parsed.data, { status: defined.code });
+      },
+    ]),
+  ) as RespondFns<Responses>;
+  const middleware: MiddlewareDefinition<object>[] = [];
+  for (const item of definition.middleware ?? []) {
+    if (!isMiddleware(item)) {
+      throw projectError(
+        "invalidRouteMiddleware",
+        `${definition.method.toUpperCase()} ${definition.path} middleware must be created with defineMiddleware(...)`,
+      );
+    }
+    middleware.push(item);
+  }
+  const route: RouteDefinition = {
+    method: definition.method,
+    path: definition.path,
+    version: definition.version,
+    request: definition.request ?? {},
+    responses,
+    middleware,
+    handle: (input) =>
+      definition.handler({
+        ...input.fields,
+        ...(input.params === undefined ? {} : { params: input.params }),
+        ...(input.query === undefined ? {} : { query: input.query }),
+        ...(input.body === undefined ? {} : { body: input.body }),
+        respond,
+      } as DefinedInput<Request> &
+        MergedFields<MiddlewareList> & { respond: RespondFns<Responses> }),
+  };
+  return Object.assign(route, { [routeBrand]: true });
+}
+
+function assertSchema(value: unknown, label: string, seen = new Set<object>()) {
+  if (!isSchema(value)) {
+    throw projectError("invalidRoute", `${label} must be a Zod schema`);
+  }
+  if (seen.has(value)) {
+    return;
+  }
+  seen.add(value);
+  const def = value._zod.def;
+  if (!def) {
+    return;
+  }
+  if ("element" in def) {
+    assertSchema(def.element, label, seen);
+  }
+  if ("innerType" in def) {
+    assertSchema(def.innerType, label, seen);
+  }
+  if (def.shape && typeof def.shape === "object") {
+    for (const nested of Object.values(def.shape)) {
+      assertSchema(nested, label, seen);
+    }
+  }
+  if (Array.isArray(def.options)) {
+    for (const option of def.options) {
+      assertSchema(option, label, seen);
+    }
+  }
+  if (Array.isArray(def.items)) {
+    for (const item of def.items) {
+      assertSchema(item, label, seen);
+    }
+  }
+}
+
+function isSchema(value: unknown): value is {
+  _zod: { def?: Record<string, unknown> };
+} {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "_zod" in value &&
+    typeof (value as { safeParse?: unknown }).safeParse === "function"
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isRoute(value: unknown): value is RouteDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    routeBrand in value &&
+    (value as Record<string, unknown>)[routeBrand] === true &&
+    "method" in value &&
+    "path" in value
+  );
+}

package/src/route/middleware.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import {
+  defineMiddleware,
+  middlewareList,
+  runMiddleware,
+} from "./middleware.ts";
+
+const context = {
+  request: new Request("http://127.0.0.1/v1/items/ada"),
+  version: "v1",
+  params: { id: "ada" },
+};
+
+describe("middlewareList", () => {
+  it("accepts one middleware or a list of them", () => {
+    const step = defineMiddleware(async ({ next }) => next());
+    expect(middlewareList(step)).toEqual([step]);
+    expect(middlewareList([step, step])).toEqual([step, step]);
+    expect(middlewareList({})).toBeNull();
+  });
+});
+
+describe("runMiddleware", () => {
+  it("rejects a second next() call", async () => {
+    const step = defineMiddleware(async ({ next }) => {
+      await next();
+      return next();
+    });
+    await expect(
+      runMiddleware(
+        [{ definition: step, allowFields: true }],
+        context,
+        () => new Response(),
+      ),
+    ).rejects.toThrow("next() was already called");
+  });
+
+  it("rejects values passed by server middleware", async () => {
+    const step = defineMiddleware(async ({ next }) => next({ user: "ada" }));
+    await expect(
+      runMiddleware(
+        [{ definition: step, allowFields: false }],
+        context,
+        () => new Response(),
+      ),
+    ).rejects.toThrow("Server middleware cannot pass values to next()");
+  });
+
+  it("rejects handler fields named params, query, body, or respond", async () => {
+    for (const key of ["params", "query", "body", "respond"] as const) {
+      const step = defineMiddleware(async ({ next }) =>
+        next({ [key]: true } as never),
+      );
+      await expect(
+        runMiddleware(
+          [{ definition: step, allowFields: true }],
+          context,
+          () => new Response(),
+        ),
+      ).rejects.toThrow(`Middleware cannot pass reserved field ${key}`);
+    }
+  });
+});