@ai-matrx/data 0.22.33 → 0.24.0

package/bin/generate.mjs

@@ -0,0 +1,225 @@
+/**
+ * generate.mjs — `matrx-data generate`: the database description → typed doors,
+ * written INSIDE the app that uses them (Prisma's model: the package ships the
+ * runtime and this generator, never the generated tables, so a new column never
+ * waits on a package release).
+ *
+ * One file per schema (`<schema>.ts`), each self-contained (no file imports
+ * another), so importing one schema loads no other; every table and function is
+ * its own top-level `const` (flags + names only, no row data), so a bundler keeps
+ * exactly the descriptors used. Types: Row (client-excluded columns removed),
+ * Insert (defaulted / nullable / org-filled columns optional; generated and
+ * client-read-only columns removed), Update (Partial of Insert). Functions: one
+ * descriptor per name; overloads become a union of named-argument shapes.
+ *
+ *   matrx-data generate --from <description dir> --out <dir> [--schemas a,b] [--check]
+ *                       [--flags-index]   also write flags-index.ts for tableByName()
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "node:zlib";
+
+const RESERVED = new Set(
+  "break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(
+    " ",
+  ),
+);
+
+const camel = (s) => s.replace(/^_+/, "").replace(/_+([a-z0-9])/g, (_, c) => c.toUpperCase());
+const pascal = (s) => {
+  const c = camel(s);
+  return c.charAt(0).toUpperCase() + c.slice(1);
+};
+const ident = (s) => {
+  let c = camel(s) || "_";
+  if (/^[0-9]/.test(c)) c = `_${c}`;
+  return RESERVED.has(c) ? `${c}Table` : c;
+};
+const key = (s) => (/^[A-Za-z_$][\w$]*$/.test(s) ? s : JSON.stringify(s));
+
+const NUMBER = new Set(["smallint", "integer", "bigint", "real", "double precision", "numeric", "oid", "int2", "int4", "int8", "float4", "float8"]);
+const STRING_PREFIX = /^(?:text|uuid|character|char|varchar|citext|name|date|time|timestamp|interval|inet|cidr|macaddr|tsvector|tsquery|bytea|money|xml|bit|ltree|regclass|regproc|regtype|point|line|box|path|polygon|circle|int4range|int8range|tsrange|tstzrange|daterange|numrange|halfvec|vector|sparsevec)/;
+
+function tsType(t, enums) {
+  let base;
+  if (t.enum) base = (enums[t.enum] ?? []).map((v) => JSON.stringify(v)).join(" | ") || "string";
+  else if (NUMBER.has(t.type)) base = "number";
+  else if (t.type === "boolean") base = "boolean";
+  else if (t.type === "json" || t.type === "jsonb") base = "Json";
+  else if (t.type === "void") base = "undefined";
+  else if (STRING_PREFIX.test(t.type)) base = "string";
+  else base = "unknown";
+  return t.array ? (base.includes("|") ? `(${base})[]` : `${base}[]`) : base;
+}
+
+function tableTypes(P, t, enums) {
+  const reg = t.registry ?? null;
+  const excluded = new Set(reg?.clientExcludedColumns ?? []);
+  const readOnly = new Set(reg?.clientReadOnlyColumns ?? []);
+  const rowLines = [];
+  const insLines = [];
+  for (const c of t.columns) {
+    const ty = tsType(c, enums);
+    if (!excluded.has(c.name)) rowLines.push(`  ${key(c.name)}: ${ty}${c.nullable ? " | null" : ""};`);
+    if (t.kind !== "table" || c.generated || readOnly.has(c.name) || excluded.has(c.name)) continue;
+    const orgFilled = c.name === "organization_id" && (t.org.rule === "binding" || t.org.rule === "parent");
+    const optional = c.nullable || c.default || c.identity || orgFilled;
+    insLines.push(`  ${key(c.name)}${optional ? "?" : ""}: ${ty}${c.nullable ? " | null" : ""};`);
+  }
+  let out = `export interface ${P}Row {\n${rowLines.join("\n")}\n}\n`;
+  if (t.kind === "table") {
+    out += `export interface ${P}Insert {\n${insLines.join("\n")}\n}\nexport type ${P}Update = Partial<${P}Insert>;\n`;
+  } else {
+    out += `export type ${P}Insert = never;\nexport type ${P}Update = never;\n`;
+  }
+  return out;
+}
+
+function tableDescriptor(schema, name, t) {
+  const reg = t.registry ?? null;
+  const archive = t.lifecycle.archived_at ? "archived_at" : t.lifecycle.is_archived ? "is_archived" : null;
+  const flags = {
+    schema,
+    name,
+    kind: t.kind,
+    type: reg?.type ?? null,
+    pk: t.primaryKey,
+    org: t.org,
+    versioned: !!(reg ? reg.versioned && t.lifecycle.version : t.lifecycle.version),
+    softDelete: !!(reg ? reg.softDelete && t.lifecycle.deleted_at : t.lifecycle.deleted_at),
+    archive,
+    readOnly: !!reg?.clientReadOnly,
+    deletesRefused: !!reg?.clientDeletesRefused,
+    readOnlyColumns: reg?.clientReadOnlyColumns ?? [],
+    listScope: reg?.listScope ?? null,
+    realtime: (t.realtime ?? []).includes("supabase_realtime"),
+  };
+  return flags;
+}
+
+function fnTypes(P, overloads, enums) {
+  const shapes = [];
+  let result = "unknown";
+  for (const f of overloads) {
+    const inputs = f.args.filter((a) => a.mode === "in" || a.mode === "inout" || a.mode === "variadic");
+    if (inputs.some((a) => !a.name)) {
+      shapes.push("never /* positional arguments: PostgREST calls by name */");
+      continue;
+    }
+    shapes.push(inputs.length ? `{ ${inputs.map((a) => `${key(a.name)}${a.optional ? "?" : ""}: ${tsType(a, enums)}`).join("; ")} }` : "Record<string, never>");
+    const outs = f.args.filter((a) => a.mode === "table" || a.mode === "out" || a.mode === "inout");
+    let r;
+    if (outs.length && (f.returns.type === "record" || f.args.some((a) => a.mode === "table"))) {
+      r = `{ ${outs.map((a) => `${key(a.name || "value")}: ${tsType(a, enums)} | null`).join("; ")} }`;
+    } else r = tsType(f.returns, enums);
+    if (f.returns.set) r = r.startsWith("{") || !r.includes("|") ? `${r}[]` : `(${r})[]`;
+    result = r;
+  }
+  const args = [...new Set(shapes)];
+  return `export type ${P}Args = ${args.join(" | ")};\nexport type ${P}Result = ${result};\n`;
+}
+
+const HEADER = (schema, src, importFrom) => `/**
+ * GENERATED by \`matrx-data generate\` from the database description — never edit by hand.
+ * schema: ${schema} · description ${src.slice(0, 12)}
+ * Regenerate: matrx-data generate (see @ai-matrx/data README).
+ */
+/* eslint-disable */
+import type { FunctionDescriptor, TableDescriptor } from "${importFrom}";
+
+type Json = string | number | boolean | null | { [key: string]: Json | undefined } | Json[];
+`;
+
+export function renderSchema(desc, schemaSha, importFrom) {
+  const { schema, tables, views, functions, enums } = desc;
+  const used = new Set();
+  const take = (base) => {
+    let n = base;
+    while (used.has(n)) n = `${n}_`;
+    used.add(n);
+    return n;
+  };
+  let out = HEADER(schema, schemaSha, importFrom);
+  const rels = [...Object.entries(tables), ...Object.entries(views)].sort(([a], [b]) => a.localeCompare(b));
+  for (const [name, t] of rels) {
+    const id = take(ident(name));
+    const P = pascal(id);
+    out += `\n${tableTypes(P, t, enums)}export const ${id} = ${JSON.stringify(tableDescriptor(schema, name, t))} as unknown as TableDescriptor<${P}Row, ${P}Insert, ${P}Update>;\n`;
+  }
+  for (const [name, overloads] of Object.entries(functions).sort(([a], [b]) => a.localeCompare(b))) {
+    let id = ident(name);
+    if (used.has(id)) id = `${id}Fn`;
+    id = take(id);
+    const P = pascal(id);
+    const roles = [...new Set(overloads.flatMap((f) => f.roles))].sort();
+    const fd = { schema, name, roles, registered: overloads.some((f) => f.registered) };
+    out += `\n${fnTypes(P, overloads, enums)}export const ${id} = ${JSON.stringify(fd)} as unknown as FunctionDescriptor<${P}Args, ${P}Result>;\n`;
+  }
+  return out;
+}
+
+/** One schema's flags (`<schema>.flags.ts`) — loaded only when a runtime name names that schema. */
+export function renderSchemaFlags(desc, importFrom) {
+  const index = {};
+  for (const [name, t] of Object.entries({ ...desc.tables, ...desc.views })) index[`${desc.schema}.${name}`] = tableDescriptor(desc.schema, name, t);
+  return `/** GENERATED by \`matrx-data generate --flags-index\` — ${desc.schema}'s table flags for tableByName(). Never edit by hand. */
+/* eslint-disable */
+import type { FlagsIndex } from "${importFrom}";
+
+export const flags: FlagsIndex = ${JSON.stringify(index)} as unknown as FlagsIndex;
+`;
+}
+
+/** Per-schema loaders: `loadTableByName(flagLoaders, "schema.table")` imports only that schema's flags. */
+export function renderFlagLoaders(schemas, importFrom) {
+  return `/** GENERATED by \`matrx-data generate --flags-index\` — never edit by hand. */
+/* eslint-disable */
+import type { FlagLoaders } from "${importFrom}";
+
+export const flagLoaders: FlagLoaders = {
+${schemas.map((s) => `  ${key(s)}: () => import("./${s}.flags").then((m) => m.flags),`).join("\n")}
+};
+`;
+}
+
+/** The description ships inside @ai-matrx/data (gzipped); `--from` points at a fresher one. */
+export const BUNDLED_DESCRIPTION = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "description");
+
+function readDescriptionFile(dir, name) {
+  const plain = path.join(dir, name);
+  if (existsSync(plain)) return readFileSync(plain, "utf8");
+  const gz = `${plain}.gz`;
+  if (existsSync(gz)) return gunzipSync(readFileSync(gz)).toString("utf8");
+  throw new Error(`${name} not found in ${dir} (neither ${name} nor ${name}.gz)`);
+}
+
+export function generate({ from = BUNDLED_DESCRIPTION, out, schemas, check, importFrom, flagsIndex = process.argv.includes("--flags-index") }) {
+  const index = JSON.parse(readDescriptionFile(from, "index.json"));
+  const names = schemas?.length ? schemas : Object.keys(index.schemas).sort();
+  const files = {};
+  const descs = [];
+  for (const s of names) {
+    if (!index.schemas[s]) throw new Error(`schema "${s}" is not in the description (${Object.keys(index.schemas).length} schemas)`);
+    const desc = JSON.parse(readDescriptionFile(from, `${s}.json`));
+    descs.push(desc);
+    files[`${s}.ts`] = renderSchema(desc, index.schemas[s].sha256, importFrom);
+  }
+  if (flagsIndex) {
+    for (const d of descs) files[`${d.schema}.flags.ts`] = renderSchemaFlags(d, importFrom);
+    files["flags-index.ts"] = renderFlagLoaders(descs.map((d) => d.schema), importFrom);
+  }
+  if (check) {
+    const stale = Object.entries(files).filter(([n, t]) => !existsSync(path.join(out, n)) || readFileSync(path.join(out, n), "utf8") !== t).map(([n]) => n);
+    if (stale.length) {
+      console.error(`matrx-data generate --check: stale against the description: ${stale.join(", ")}`);
+      return 1;
+    }
+    console.log(`matrx-data generate --check: ${Object.keys(files).length} file(s) current (contract ${index.contractSha256.slice(0, 12)})`);
+    return 0;
+  }
+  mkdirSync(out, { recursive: true });
+  for (const [n, t] of Object.entries(files)) writeFileSync(path.join(out, n), t);
+  console.log(`matrx-data generate: ${Object.keys(files).join(", ")} → ${out} (contract ${index.contractSha256.slice(0, 12)})`);
+  return 0;
+}

package/bin/matrx-data.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * matrx-data — @ai-matrx/data's build-time CLI.
+ *
+ *   matrx-data emit     [--out <dir>] [--check]      live database → the database description (read-only)
+ *   matrx-data generate --out <dir> [--from <dir>] [--schemas a,b] [--flags-index] [--check]
+ *                       description → typed doors in THIS app (--from defaults to the description
+ *                       shipped inside this package version)
+ *
+ * The package ships the runtime and this CLI; each app generates its own doors
+ * locally (Prisma's model), so a new column never waits on a package release.
+ */
+import path from "node:path";
+
+const [command, ...rest] = process.argv.slice(2);
+const flag = (name) => {
+  const i = rest.indexOf(name);
+  return i >= 0 ? rest[i + 1] : undefined;
+};
+
+async function main() {
+  if (command === "emit") {
+    const { emit } = await import("./emit.mjs");
+    return emit({ out: path.resolve(flag("--out") ?? "db-contract"), check: rest.includes("--check") });
+  }
+  if (command === "generate") {
+    const { generate } = await import("./generate.mjs");
+    const from = flag("--from");
+    const out = flag("--out");
+    if (!out) {
+      console.error("matrx-data generate: --out <dir> is required (--from defaults to the description shipped in this package)");
+      return 2;
+    }
+    return generate({
+      ...(from ? { from: path.resolve(from) } : {}),
+      out: path.resolve(out),
+      schemas: flag("--schemas")?.split(",").map((s) => s.trim()).filter(Boolean),
+      check: rest.includes("--check"),
+      importFrom: flag("--import-from") ?? "@ai-matrx/data/db",
+    });
+  }
+  console.error("usage: matrx-data emit [--out <dir>] [--check] | matrx-data generate --from <dir> --out <dir> [--schemas a,b] [--check]");
+  return 2;
+}
+
+main().then((code) => process.exit(code ?? 0), (err) => {
+  console.error(`matrx-data ${command ?? ""}: ${err?.message ?? err}`);
+  process.exit(1);
+});