@veducio/keja 0.0.0-stage → 0.3.0

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(", ")} },`;
+}

package/src/repository/query.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { buildListSql, encodeCursor } from "./query.ts";
+import type { DomainColumn } from "./sql.ts";
+
+const columns: DomainColumn[] = [
+  { name: "name", type: "text", nullable: false },
+  { name: "email", type: "text", nullable: false },
+  { name: "active", type: "boolean", nullable: false },
+];
+
+describe("buildListSql", () => {
+  it("filters live rows for a tenant and searches text columns", () => {
+    const built = buildListSql({
+      table: "users",
+      columns,
+      tenant: "tenant_1",
+      query: { q: "ada_%", name: "Ada", limit: 2 },
+    });
+    expect(built.limit).toBe(2);
+    expect(built.text).toContain(`"name" = $3`);
+    expect(built.text).toContain(`ilike $4 escape '\\'`);
+    expect(built.text).toContain(`order by "_id" asc`);
+    expect(built.text).toContain("limit $6");
+    expect(built.values.slice(0, 5)).toEqual([
+      "tenant_1",
+      false,
+      "Ada",
+      "%ada\\_\\%%",
+      "%ada\\_\\%%",
+    ]);
+  });
+
+  it("pages with a cursor for a descending domain sort", () => {
+    const cursor = encodeCursor({
+      column: "name",
+      direction: "desc",
+      value: "Ada",
+      id: "users_a",
+    });
+    const built = buildListSql({
+      table: "users",
+      columns,
+      tenant: "tenant_1",
+      query: { sort: "-name", cursor, archived: "true" },
+    });
+    expect(built.values[1]).toBe(true);
+    expect(built.text).toContain(`"name" < $3`);
+    expect(built.text).toContain(`"_id" < $4`);
+    expect(built.text).toContain(`order by "name" desc, "_id" desc`);
+  });
+
+  it("applies a default limit, an allowlist, and extra where checks", () => {
+    const built = buildListSql({
+      table: "users",
+      columns,
+      tenant: "tenant_1",
+      query: { name: "Ada", email: "skip@example.com" },
+      filters: ["name"],
+      limitDefault: 20,
+      where: { email: "ada@example.com", active: null },
+    });
+    expect(built.limit).toBe(20);
+    expect(built.text).toContain(`"email" = $3`);
+    expect(built.text).toContain(`"active" is null`);
+    expect(built.text).toContain(`"name" = $4`);
+    expect(built.text).not.toContain(`"email" = $4`);
+    expect(built.values.slice(2, 4)).toEqual(["ada@example.com", "Ada"]);
+  });
+
+  it("includes archived rows when asked", () => {
+    const built = buildListSql({
+      table: "users",
+      columns,
+      tenant: "tenant_1",
+      query: { archived: "true" },
+      includeArchived: true,
+    });
+    expect(built.text).not.toContain(`"_archived" =`);
+    expect(built.values[0]).toBe("tenant_1");
+    expect(built.values).not.toContain(true);
+  });
+
+  it("rejects a cursor for a different sort", () => {
+    const cursor = encodeCursor({
+      column: "name",
+      direction: "asc",
+      value: "Ada",
+      id: "users_a",
+    });
+    expect(() =>
+      buildListSql({
+        table: "users",
+        columns,
+        tenant: "tenant_1",
+        query: { cursor },
+      }),
+    ).toThrow("invalid cursor");
+  });
+});