@veducio/keja 0.0.0-stage → 0.2.3

package/src/project/load.ts

@@ -0,0 +1,158 @@
+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 { isRoute, type RouteDefinition } from "../route/define.ts";
+import {
+  type MiddlewareDefinition,
+  middlewareList,
+} from "../route/middleware.ts";
+import { isVersions, type VersionDefinition } from "../versioning/define.ts";
+import {
+  type ArgusConfig,
+  type DatabaseConfig,
+  loadConfig,
+  type ProjectPaths,
+  type VaultConfig,
+} from "./config.ts";
+import { beginProjectReload, freshImportUrl } from "./reload-graph.ts";
+
+export type LoadedProject = {
+  paths: ProjectPaths;
+  name: string | null;
+  argus: ArgusConfig;
+  vault: VaultConfig;
+  database: DatabaseConfig;
+  versions: VersionDefinition[];
+  publicRoutes: RouteDefinition[];
+  publicMiddleware: MiddlewareDefinition<object>[];
+  serviceRoutes: RouteDefinition[];
+  serviceMiddleware: MiddlewareDefinition<object>[];
+};
+
+export async function loadProject(
+  root: string,
+  options?: { generation?: string },
+): Promise<LoadedProject> {
+  const generation = options?.generation;
+  if (generation) {
+    beginProjectReload(root, generation);
+  }
+  const loaded = await loadConfig(root, generation);
+  const paths = loaded;
+  if (!existsSync(paths.versioning)) {
+    throw projectError("missingVersionFile", `Missing ${paths.versioning}`);
+  }
+  const versioning = await import(projectHref(paths.versioning, generation));
+  if (!isVersions(versioning.default)) {
+    throw projectError(
+      "invalidVersionFile",
+      `${paths.versioning} must default-export defineVersions(...)`,
+    );
+  }
+  const publicDirectory = paths.public;
+  const serviceDirectory = paths.service;
+  return {
+    paths,
+    name: loaded.name,
+    argus: loaded.argus,
+    vault: loaded.vault,
+    database: loaded.database,
+    versions: versioning.default.versions,
+    publicRoutes: await loadRoutes(publicDirectory, generation),
+    publicMiddleware: await loadServerMiddleware(publicDirectory, generation),
+    serviceRoutes: await loadRoutes(serviceDirectory, generation),
+    serviceMiddleware: await loadServerMiddleware(serviceDirectory, generation),
+  };
+}
+
+function projectHref(file: string, generation?: string) {
+  return generation
+    ? freshImportUrl(file, generation)
+    : pathToFileURL(file).href;
+}
+
+async function loadRoutes(directory: string, generation?: string) {
+  if (!existsSync(directory)) {
+    throw projectError("missingRouteDirectory", `Missing ${directory}`);
+  }
+  const routes: RouteDefinition[] = [];
+  for (const file of await collectRouteFiles(directory)) {
+    const loaded = await import(
+      projectHref(path.join(directory, file), generation)
+    );
+    const exported = routesFromModule(loaded);
+    if (exported.length === 0) {
+      throw projectError(
+        "invalidRouteFile",
+        `${file} must export defineRoute(...)`,
+      );
+    }
+    routes.push(...exported);
+  }
+  return routes;
+}
+
+async function loadServerMiddleware(directory: string, generation?: string) {
+  const file = path.join(directory, "_middleware.ts");
+  if (!existsSync(file)) {
+    return [];
+  }
+  const loaded = await import(projectHref(file, generation));
+  const exported = middlewareList(loaded.default);
+  if (!exported) {
+    throw projectError(
+      "invalidMiddlewareFile",
+      `${file} must default-export defineMiddleware(...)`,
+    );
+  }
+  return exported;
+}
+
+export function routesFromModule(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 routes: RouteDefinition[] = [];
+  for (const name of ordered) {
+    const value = record[name];
+    if (isRoute(value)) {
+      routes.push(value);
+    }
+  }
+  return routes;
+}
+
+export async function collectRouteFiles(directory: string) {
+  const files = await walk(directory, "");
+  return files.filter(
+    (file) =>
+      file.endsWith(".ts") &&
+      !file.endsWith(".test.ts") &&
+      !isServerMiddlewareFile(file),
+  );
+}
+
+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;
+}
+
+function isServerMiddlewareFile(file: string) {
+  const normalized = file.replaceAll("\\", "/");
+  return (
+    normalized === "_middleware.ts" || normalized.endsWith("/_middleware.ts")
+  );
+}

package/src/project/reload-graph.test.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { freshImportUrl, resolveProjectImport } from "./reload-graph.ts";
+
+describe("project reload imports", () => {
+  const root = path.resolve("keja-app");
+  const route = path.join(root, "src", "public", "posts.ts");
+
+  it("adds a generation to a project file import", () => {
+    expect(freshImportUrl(route, "4")).toBe(`keja:${route}?keja=4`);
+  });
+
+  it("follows a relative import out of the route directory", () => {
+    const resolved = resolveProjectImport({
+      importer: `keja:${route}`,
+      specifier: "../data.ts",
+      projectRoot: root,
+      generation: "4",
+    });
+    const file = path.join(root, "src", "data.ts");
+    expect(resolved).toEqual({
+      path: `${file}?keja=4`,
+      namespace: "keja",
+      file,
+      outside: false,
+    });
+  });
+
+  it("follows the next file imported by that dependency", () => {
+    const data = path.join(root, "src", "data.ts");
+    const resolved = resolveProjectImport({
+      importer: `keja:${data}?keja=4`,
+      specifier: "./schema.ts",
+      projectRoot: root,
+      generation: "4",
+    });
+    const file = path.join(root, "src", "schema.ts");
+    expect(resolved?.path).toBe(`${file}?keja=4`);
+    expect(resolved?.file).toBe(file);
+  });
+
+  it("leaves package imports cached", () => {
+    expect(
+      resolveProjectImport({
+        importer: `keja:${route}`,
+        specifier: "@veducio/keja",
+        projectRoot: root,
+        generation: "4",
+      }),
+    ).toBeNull();
+  });
+});

package/src/project/reload-graph.ts

@@ -0,0 +1,175 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const namespace = "keja";
+const generationKey = "keja";
+
+let projectRoot: string | null = null;
+let generation: string | null = null;
+let pluginInstalled = false;
+const outsideProject = new Set<string>();
+
+export function freshImportUrl(file: string, token: string) {
+  return `${namespace}:${path.resolve(file)}?${generationKey}=${token}`;
+}
+
+export function resolveProjectImport(input: {
+  importer: string;
+  specifier: string;
+  projectRoot: string;
+  generation: string;
+}) {
+  const specifier = input.specifier.split("?")[0] ?? input.specifier;
+  if (!isRelativeSpecifier(specifier)) {
+    return null;
+  }
+  const importerFile = filePath(input.importer);
+  if (!importerFile || isNodeModules(importerFile)) {
+    return null;
+  }
+  const inProject = isInside(importerFile, input.projectRoot);
+  const inGraph =
+    input.importer.startsWith(`${namespace}:`) ||
+    input.importer.includes(`${generationKey}=`);
+  if (!inProject && !inGraph) {
+    return null;
+  }
+  const resolved = path.resolve(path.dirname(importerFile), specifier);
+  if (isNodeModules(resolved)) {
+    return null;
+  }
+  return {
+    path: `${resolved}?${generationKey}=${input.generation}`,
+    namespace,
+    file: resolved,
+    outside: !isInside(resolved, input.projectRoot),
+  };
+}
+
+export function beginProjectReload(root: string, token: string) {
+  projectRoot = path.resolve(root);
+  generation = token;
+  outsideProject.clear();
+  installPlugin();
+}
+
+export function projectDependenciesOutsideRoot() {
+  return [...outsideProject];
+}
+
+function installPlugin() {
+  if (pluginInstalled) {
+    return;
+  }
+  const runtime = globalThis as {
+    Bun?: { plugin?: (plugin: BunPlugin) => void };
+  };
+  if (!runtime.Bun?.plugin) {
+    return;
+  }
+  pluginInstalled = true;
+  runtime.Bun.plugin({
+    name: "keja-dev-reload",
+    setup(build) {
+      build.onResolve({ filter: /^\.{1,2}(?:[\\/]|$)/ }, (args) => {
+        if (!projectRoot || !generation) {
+          return null;
+        }
+        if (!args.importer.startsWith(`${namespace}:`)) {
+          return null;
+        }
+        const resolved = resolveProjectImport({
+          importer: args.importer,
+          specifier: args.path,
+          projectRoot,
+          generation,
+        });
+        if (!resolved) {
+          return null;
+        }
+        if (resolved.outside) {
+          outsideProject.add(resolved.file);
+        }
+        return { path: resolved.path, namespace: resolved.namespace };
+      });
+      build.onLoad({ filter: /.*/, namespace }, (args) => {
+        const file = filePath(args.path);
+        if (!file) {
+          return null;
+        }
+        return {
+          contents: readFileSync(file, "utf8"),
+          loader: loaderFor(file),
+        };
+      });
+    },
+  });
+}
+
+type BunPlugin = {
+  name: string;
+  setup: (build: {
+    onResolve: (
+      constraints: { filter: RegExp },
+      callback: (args: { importer: string; path: string }) => {
+        path: string;
+        namespace: string;
+      } | null,
+    ) => void;
+    onLoad: (
+      constraints: { filter: RegExp; namespace: string },
+      callback: (args: { path: string }) => {
+        contents: string;
+        loader: "js" | "jsx" | "ts" | "tsx" | "json";
+      } | null,
+    ) => void;
+  }) => void;
+};
+
+function loaderFor(file: string) {
+  const extension = path.extname(file).toLowerCase();
+  if (extension === ".tsx") {
+    return "tsx" as const;
+  }
+  if (extension === ".jsx") {
+    return "jsx" as const;
+  }
+  if (extension === ".js" || extension === ".mjs" || extension === ".cjs") {
+    return "js" as const;
+  }
+  if (extension === ".json") {
+    return "json" as const;
+  }
+  return "ts" as const;
+}
+
+function isRelativeSpecifier(specifier: string) {
+  return specifier.startsWith("./") || specifier.startsWith("../");
+}
+
+function filePath(importer: string) {
+  const withoutQuery = importer.split("?")[0] ?? importer;
+  const clean = withoutQuery.startsWith(`${namespace}:`)
+    ? withoutQuery.slice(namespace.length + 1)
+    : withoutQuery;
+  if (clean.startsWith("file:")) {
+    return fileURLToPath(clean);
+  }
+  if (path.isAbsolute(clean)) {
+    return clean;
+  }
+  return null;
+}
+
+function isNodeModules(file: string) {
+  return file.split(/[\\/]/).includes("node_modules");
+}
+
+function isInside(file: string, root: string) {
+  const relative = path.relative(root, file);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}

package/src/repository/define.ts

@@ -0,0 +1,123 @@
+import { projectError } from "../errors/framework-errors.ts";
+import { processBrand } from "../process/slot.ts";
+
+const repositoryBrand = processBrand("repositories");
+const tableName = /^[a-z_][a-z0-9_]*$/;
+
+export type ListConstraints = {
+  filters?: readonly string[];
+  limit?: number;
+};
+
+export type RepositoryFlags = {
+  list?: boolean | ListConstraints;
+  get?: boolean;
+};
+
+export type ResolvedList = boolean | ListConstraints;
+
+export function defineRepositories<
+  const Tables extends Record<string, RepositoryFlags>,
+>(tables: Tables) {
+  for (const [name, flags] of Object.entries(tables)) {
+    if (!tableName.test(name)) {
+      throw projectError(
+        "invalidRepositoryFile",
+        `${name} is not a table name`,
+      );
+    }
+    for (const [key, value] of Object.entries(flags)) {
+      if (key === "get") {
+        if (typeof value !== "boolean") {
+          throw projectError(
+            "invalidRepositoryFile",
+            `${name}.get is not a repository flag`,
+          );
+        }
+        continue;
+      }
+      if (key !== "list" || !isListFlag(value)) {
+        throw projectError(
+          "invalidRepositoryFile",
+          `${name}.${key} is not a repository flag`,
+        );
+      }
+      readList(name, value);
+    }
+  }
+  return Object.assign({}, tables, { [repositoryBrand]: true as const });
+}
+
+export function isRepositories(
+  value: unknown,
+): value is Record<string, RepositoryFlags> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    repositoryBrand in value &&
+    (value as Record<symbol, unknown>)[repositoryBrand] === true
+  );
+}
+
+export function repositoryFlags(value: Record<string, RepositoryFlags>) {
+  const flags = new Map<string, { list: ResolvedList; get: boolean }>();
+  for (const [name, entry] of Object.entries(value)) {
+    if (name === "") {
+      continue;
+    }
+    flags.set(name, {
+      list: entry.list === undefined ? false : readList(name, entry.list),
+      get: entry.get === true,
+    });
+  }
+  return flags;
+}
+
+function isListFlag(value: unknown): value is boolean | ListConstraints {
+  return (
+    typeof value === "boolean" ||
+    (typeof value === "object" && value !== null && !Array.isArray(value))
+  );
+}
+
+function readList(
+  name: string,
+  value: boolean | ListConstraints,
+): ResolvedList {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  for (const key of Object.keys(value)) {
+    if (key !== "filters" && key !== "limit") {
+      throw projectError(
+        "invalidRepositoryFile",
+        `${name}.list.${key} is not a list constraint`,
+      );
+    }
+  }
+  if (
+    value.filters !== undefined &&
+    (!Array.isArray(value.filters) ||
+      value.filters.some(
+        (filter) => typeof filter !== "string" || !tableName.test(filter),
+      ))
+  ) {
+    throw projectError(
+      "invalidRepositoryFile",
+      `${name}.list.filters must name columns`,
+    );
+  }
+  if (
+    value.limit !== undefined &&
+    (!Number.isInteger(value.limit) || value.limit < 1 || value.limit > 100)
+  ) {
+    throw projectError(
+      "invalidRepositoryFile",
+      `${name}.list.limit must be from 1 to 100`,
+    );
+  }
+  return {
+    ...(value.filters ? { filters: [...value.filters] } : {}),
+    ...(value.limit !== undefined ? { limit: value.limit } : {}),
+  };
+}

package/src/repository/generate.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { renderRepositories } from "./generate.ts";
+import { readTables } from "./sql.ts";
+
+const owned = `
+  _id text primary key,
+  _object text not null,
+  _tenant text not null,
+  _archived boolean not null,
+  "_createdAt" timestamptz not null,
+  "_updatedAt" timestamptz not null
+`;
+
+describe("renderRepositories", () => {
+  it("writes a repository and the processors that are enabled", () => {
+    const tables = readTables([
+      {
+        file: "0001_example.sql",
+        sql: `create table users (${owned}, name text not null); create table jobs (${owned}, name text not null);`,
+      },
+    ]);
+    const source = renderRepositories(
+      tables,
+      new Map([
+        ["users", { list: true, get: true }],
+        ["jobs", { list: false, get: false }],
+      ]),
+    );
+    expect(source).toContain("export const jobs = repository({");
+    expect(source).toContain("list: true,");
+    expect(source).toContain("get: true,");
+    expect(source.indexOf("export const jobs")).toBeLessThan(
+      source.indexOf("export const users"),
+    );
+    expect(
+      source.slice(
+        source.indexOf("export const jobs"),
+        source.indexOf("export const users"),
+      ),
+    ).not.toContain("list: true");
+  });
+
+  it("writes list filter and limit constraints", () => {
+    const tables = readTables([
+      {
+        file: "0001_example.sql",
+        sql: `create table users (${owned}, name text not null, email text not null);`,
+      },
+    ]);
+    const source = renderRepositories(
+      tables,
+      new Map([
+        ["users", { list: { filters: ["name"], limit: 20 }, get: false }],
+      ]),
+    );
+    expect(source).toContain('list: { filters: ["name"], limit: 20 },');
+  });
+});

package/src/repository/generate.ts

@@ -0,0 +1,117 @@
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadMigrations } from "../db/migrate.ts";
+import { projectError } from "../errors/framework-errors.ts";
+import { loadConfig } from "../project/config.ts";
+import {
+  isRepositories,
+  type ResolvedList,
+  repositoryFlags,
+} from "./define.ts";
+import { readTables, type TableSchema } from "./sql.ts";
+
+export const repositoryModule = path.join("src", "db", "repositories.ts");
+
+export function renderRepositories(
+  tables: readonly TableSchema[],
+  flags: ReadonlyMap<string, { list: ResolvedList; get: boolean }>,
+) {
+  const blocks = [...tables]
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((table) => renderRepository(table, flags.get(table.name)));
+  return `import { repository } from "@veducio/keja";\n\n${blocks.join("\n\n")}\n`;
+}
+
+export async function generateRepositories(root: string) {
+  const project = await loadConfig(root);
+  const directory = project.database.enabled
+    ? project.database.migrations
+    : path.resolve(root, "migrations");
+  const tables = readTables(
+    (await loadMigrations(directory)).map((file) => ({
+      file: file.file,
+      sql: file.sql,
+    })),
+  );
+  const flags = await loadRepositoryFlags(root);
+  for (const [name, flag] of flags) {
+    const table = tables.find((item) => item.name === name);
+    if (!table) {
+      throw projectError("invalidRepositoryFile", `${name} is not a table`);
+    }
+    if (typeof flag.list === "object") {
+      for (const filter of flag.list.filters ?? []) {
+        const column = table.columns.find((item) => item.name === filter);
+        if (!column || column.type === "jsonb") {
+          throw projectError(
+            "invalidRepositoryFile",
+            `${name}.list.filters ${filter} is not a filter`,
+          );
+        }
+      }
+    }
+  }
+  const source = renderRepositories(tables, flags);
+  const output = path.join(root, repositoryModule);
+  await mkdir(path.dirname(output), { recursive: true });
+  await writeFile(output, source);
+  return { output, tables: tables.map((table) => table.name) };
+}
+
+async function loadRepositoryFlags(root: string) {
+  const file = path.join(root, "keja.repositories.ts");
+  if (!existsSync(file)) {
+    return new Map<string, { list: boolean; get: boolean }>();
+  }
+  const loaded = (await import(pathToFileURL(file).href)) as {
+    default?: unknown;
+  };
+  if (!isRepositories(loaded.default)) {
+    throw projectError(
+      "invalidRepositoryFile",
+      `${file} must default-export defineRepositories(...)`,
+    );
+  }
+  return repositoryFlags(loaded.default);
+}
+
+function renderRepository(
+  table: TableSchema,
+  flags: { list: ResolvedList; get: boolean } | undefined,
+) {
+  const columns = table.columns
+    .map(
+      (column) =>
+        `    ${column.name}: { type: "${column.type}", nullable: ${column.nullable} },`,
+    )
+    .join("\n");
+  const options = [
+    renderList(flags?.list),
+    flags?.get ? "  get: true," : "",
+  ].filter((line) => line !== "");
+  const optionBlock = options.length > 0 ? `\n${options.join("\n")}` : "";
+  return `export const ${table.name} = repository({
+  table: "${table.name}",
+  columns: {
+${columns}
+  } as const,${optionBlock}
+});`;
+}
+
+function renderList(list: ResolvedList | undefined) {
+  if (!list) {
+    return "";
+  }
+  if (list === true) {
+    return "  list: true,";
+  }
+  const parts = [
+    list.filters
+      ? `filters: [${list.filters.map((name) => `"${name}"`).join(", ")}]`
+      : "",
+    list.limit !== undefined ? `limit: ${list.limit}` : "",
+  ].filter((part) => part !== "");
+  return `  list: { ${parts.join(", ")} },`;
+}