pgkiln 0.47.0 → 0.49.0

package/src/datamodel.ts

@@ -0,0 +1,324 @@
+import { html, raw, type Raw } from './html.ts';
+
+// (sprint 98, Database Actions DA-10: Data Modeler) A relational diagram of some tables and views of one schema:
+// the catalog read for them (columns, keys, foreign keys, comments), each box's size, an automatic layout, the
+// foreign key lines with crow's feet, and the whole diagram as one SVG. The same SVG is the page's diagram (the
+// boxes at their saved positions, so it shows without JavaScript), the Export SVG file and the source of the
+// PNG export. It uses SVG presentation attributes only (no style attributes, no <style>): the strict CSP allows
+// them, the builder's stylesheet themes them on the page, and a downloaded file looks the same anywhere.
+// public/data-modeler.js moves the boxes and draws the lines again with the same geometry (fkPath).
+
+export interface ModelColumn {
+  name: string;
+  type: string;
+  notNull: boolean;
+  default: string | null;
+  comment: string | null;
+}
+export interface ModelConstraint {
+  name: string;
+  /** p primary key, u unique, f foreign key, c check */
+  type: 'p' | 'u' | 'f' | 'c';
+  cols: string[];
+  refSchema: string | null;
+  refTable: string | null;
+  refCols: string[];
+  def: string;
+}
+export interface ModelTable {
+  name: string;
+  kind: 'table' | 'view' | 'materialized view';
+  /** the regclass text (schema-qualified, quoted when needed) */
+  ref: string;
+  comment: string | null;
+  columns: ModelColumn[];
+  constraints: ModelConstraint[];
+}
+export interface Placed {
+  name: string;
+  x: number;
+  y: number;
+}
+
+type Q = { query: <T extends Record<string, any> = any>(sql: string, params?: unknown[]) => Promise<{ rows: T[] }> };
+
+/** Names of the tables and views of a schema (not partitions), for the Add objects search. */
+export async function modelNames(db: Q, schema: string): Promise<{ name: string; kind: ModelTable['kind'] }[]> {
+  return (await db.query<{ name: string; kind: ModelTable['kind'] }>(
+    `select c.relname as name, case when c.relkind in ('r', 'p') then 'table' when c.relkind = 'm' then 'materialized view' else 'view' end as kind
+       from pg_class c join pg_namespace n on n.oid = c.relnamespace
+      where n.nspname = $1 and c.relkind in ('r', 'p', 'v', 'm') and not c.relispartition
+      order by c.relname limit 5000`, [schema])).rows;
+}
+
+/** The named tables and views of a schema as the diagram shows them (missing names are left out). */
+export async function readModel(db: Q, schema: string, names: string[]): Promise<ModelTable[]> {
+  if (!names.length) return [];
+  return (await db.query<ModelTable>(
+    `select c.relname as name, case when c.relkind in ('r', 'p') then 'table' when c.relkind = 'm' then 'materialized view' else 'view' end as kind,
+            c.oid::regclass::text as ref, obj_description(c.oid, 'pg_class') as comment,
+            coalesce((select json_agg(json_build_object('name', a.attname, 'type', format_type(a.atttypid, a.atttypmod), 'notNull', a.attnotnull,
+                        'default', case when a.attidentity = 'a' then 'generated always as identity' when a.attidentity = 'd' then 'generated by default as identity'
+                                        when a.attgenerated = 's' then 'generated always as (' || pg_get_expr(d.adbin, d.adrelid) || ') stored'
+                                        else pg_get_expr(d.adbin, d.adrelid) end,
+                        'comment', col_description(c.oid, a.attnum)) order by a.attnum)
+                        from pg_attribute a left join pg_attrdef d on d.adrelid = a.attrelid and d.adnum = a.attnum
+                       where a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped), '[]') as columns,
+            coalesce((select json_agg(json_build_object('name', k.conname, 'type', k.contype,
+                        'cols', array(select a.attname from unnest(k.conkey) with ordinality u(n, i) join pg_attribute a on a.attrelid = k.conrelid and a.attnum = u.n order by u.i),
+                        'refSchema', fn.nspname, 'refTable', f.relname,
+                        'refCols', coalesce(array(select a.attname from unnest(k.confkey) with ordinality u(n, i) join pg_attribute a on a.attrelid = k.confrelid and a.attnum = u.n order by u.i), '{}'),
+                        'def', pg_get_constraintdef(k.oid)) order by position(k.contype in 'pufc'), k.conname)
+                        from pg_constraint k left join pg_class f on f.oid = k.confrelid left join pg_namespace fn on fn.oid = f.relnamespace
+                       where k.conrelid = c.oid and k.contype in ('p', 'u', 'f', 'c')), '[]') as constraints
+       from pg_class c join pg_namespace n on n.oid = c.relnamespace
+      where n.nspname = $1 and c.relname = any ($2::text[]) and c.relkind in ('r', 'p', 'v', 'm') and not c.relispartition
+      order by c.relname`, [schema, names])).rows;
+}
+
+/**
+ * The names a search picks: `*` all of them; a pattern with `*` (emp*, *_log) matches whole names; other words match
+ * a part of a name (any case). Several words or patterns, separated by spaces or commas, add up.
+ */
+export function matchNames(all: string[], q: string, opts: { exact?: boolean } = {}): string[] {
+  const terms = q.split(/[\s,]+/).map((t) => t.trim()).filter(Boolean).slice(0, 50);
+  if (!terms.length) return [];
+  const tests = terms.map((t) => {
+    if (t.includes('*')) {
+      const re = new RegExp(`^${t.split('*').map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`, 'i');
+      return (n: string) => re.test(n);
+    }
+    const low = t.toLowerCase();
+    return opts.exact ? (n: string) => n === t || n.toLowerCase() === low : (n: string) => n.toLowerCase().includes(low);
+  });
+  return all.filter((n) => tests.some((f) => f(n)));
+}
+
+/** A diagram's saved objects, cleaned: names (unique) and positions within 0..20000. */
+export function cleanObjects(v: unknown): Placed[] {
+  if (!Array.isArray(v)) return [];
+  const seen = new Set<string>();
+  const out: Placed[] = [];
+  for (const o of v.slice(0, 500)) {
+    if (!o || typeof o !== 'object') continue;
+    const name = (o as any).name;
+    if (typeof name !== 'string' || !name || name.length > 63 || seen.has(name)) continue;
+    seen.add(name);
+    const n = (x: unknown) => (Number.isFinite(Number(x)) ? Math.min(20000, Math.max(0, Math.round(Number(x)))) : 0);
+    out.push({ name, x: n((o as any).x), y: n((o as any).y) });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- geometry
+
+export const HEAD = 30;
+export const ROW = 20;
+const FOOT = 8;
+/** columns drawn per box; the others are counted in a last row */
+export const MAX_ROWS = 40;
+const CHAR = 7;
+const TYPE_CHAR = 6.4;
+const cut = (s: string, n: number) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+export interface Box {
+  name: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** The rows a box shows: its columns (at most MAX_ROWS) and a "more" row. */
+const shownColumns = (t: ModelTable) => t.columns.slice(0, t.columns.length > MAX_ROWS ? MAX_ROWS - 1 : MAX_ROWS);
+
+export function boxSize(t: ModelTable): { w: number; h: number } {
+  const cols = shownColumns(t);
+  const rows = cols.length + (cols.length < t.columns.length ? 1 : 0);
+  const widest = Math.max(0, ...cols.map((c) => 30 + cut(c.name, 36).length * CHAR + 18 + cut(c.type, 24).length * TYPE_CHAR + 10));
+  const title = 24 + cut(t.name, 48).length * 7.6 + (t.kind === 'table' ? 0 : 50);
+  return { w: Math.round(Math.min(480, Math.max(160, widest, title))), h: HEAD + Math.max(1, rows) * ROW + 6 };
+}
+
+/** The y offset (in its box) of a column's row; the header for a column not drawn. */
+export function rowOffset(t: ModelTable, column: string) {
+  const i = shownColumns(t).findIndex((c) => c.name === column);
+  return i < 0 ? HEAD / 2 : HEAD + i * ROW + ROW / 2;
+}
+
+/**
+ * A foreign key line from a child's row (a, ay) to its parent's row (b, by): an orthogonal path, the crow's foot
+ * (many) at the child and a bar (one) at the parent. The same function is in public/data-modeler.js.
+ */
+export function fkPath(a: Box, ay: number, b: Box, by: number) {
+  const y1 = a.y + ay;
+  const y2 = b.y + by;
+  let x1: number, x2: number, d1: number, d2: number, path: string;
+  if (a.x + a.w + 40 <= b.x) {
+    [x1, x2, d1, d2] = [a.x + a.w, b.x, 1, -1];
+    const mx = Math.round((x1 + x2) / 2);
+    path = `M ${x1} ${y1} H ${mx} V ${y2} H ${x2}`;
+  } else if (b.x + b.w + 40 <= a.x) {
+    [x1, x2, d1, d2] = [a.x, b.x + b.w, -1, 1];
+    const mx = Math.round((x1 + x2) / 2);
+    path = `M ${x1} ${y1} H ${mx} V ${y2} H ${x2}`;
+  } else {
+    // one above the other (or the same table): around the right-hand sides
+    [x1, x2, d1, d2] = [a.x + a.w, b.x + b.w, 1, 1];
+    const lx = Math.max(x1, x2) + (a === b ? 18 : 30);
+    const yy = a === b && y1 === y2 ? y2 + 10 : y2;
+    path = `M ${x1} ${y1} H ${lx} V ${yy} H ${x2}`;
+  }
+  const foot = `M ${x1 + d1 * 14} ${y1} L ${x1} ${y1 - 7} M ${x1 + d1 * 14} ${y1} L ${x1} ${y1 + 7} M ${x1 + d1 * 14} ${y1 - 7} V ${y1 + 7}`;
+  const bar = `M ${x2 + d2 * 10} ${y2 - 7} V ${y2 + 7}`;
+  return { path, ends: `${foot} ${bar}`, circle: { cx: x2 + d2 * 20, cy: y2 } };
+}
+
+export interface Line {
+  from: string;
+  to: string;
+  name: string;
+  fy: number;
+  ty: number;
+  optional: boolean;
+  label: string;
+}
+
+/** The foreign key lines between the shown tables. */
+export function lines(schema: string, tables: ModelTable[]): Line[] {
+  const by = new Map(tables.map((t) => [t.name, t]));
+  return tables.flatMap((t) =>
+    t.constraints.filter((k) => k.type === 'f' && k.refSchema === schema && k.refTable && by.has(k.refTable)).map((k) => ({
+      from: t.name,
+      to: k.refTable!,
+      name: k.name,
+      fy: rowOffset(t, k.cols[0]),
+      ty: rowOffset(by.get(k.refTable!)!, k.refCols[0]),
+      optional: k.cols.some((c) => !t.columns.find((x) => x.name === c)?.notNull),
+      label: `${t.name}(${k.cols.join(', ')}) → ${k.refTable}(${k.refCols.join(', ')}): ${k.name}`,
+    })),
+  );
+}
+
+/**
+ * Positions for all tables: parents left of their children (by foreign key levels), each level a column, a column
+ * wraps when it gets taller than the others need.
+ */
+export function autoLayout(schema: string, tables: ModelTable[]): Placed[] {
+  const size = new Map(tables.map((t) => [t.name, boxSize(t)]));
+  const parents = new Map(tables.map((t) => [t.name, [...new Set(t.constraints.filter((k) => k.type === 'f' && k.refSchema === schema && k.refTable !== t.name && size.has(k.refTable!)).map((k) => k.refTable!))]]));
+  const level = new Map<string, number>();
+  const visiting = new Set<string>();
+  const levelOf = (n: string): number => {
+    if (level.has(n)) return level.get(n)!;
+    if (visiting.has(n)) return 0; // a cycle: this edge doesn't count
+    visiting.add(n);
+    const l = Math.max(-1, ...parents.get(n)!.map(levelOf)) + 1;
+    visiting.delete(n);
+    level.set(n, l);
+    return l;
+  };
+  for (const t of tables) levelOf(t.name);
+  const total = tables.reduce((s, t) => s + size.get(t.name)!.h + 40, 0);
+  const maxH = Math.max(900, Math.sqrt(total * 900), ...tables.map((t) => size.get(t.name)!.h));
+  const levels = [...new Set(level.values())].sort((a, b) => a - b);
+  const index = new Map<string, number>();
+  const out: Placed[] = [];
+  let x = 20;
+  for (const l of levels) {
+    const members = tables.filter((t) => level.get(t.name) === l).map((t) => t.name);
+    // near their parents: by the parents' mean position, then by name
+    const key = (n: string) => {
+      const p = parents.get(n)!.filter((x) => index.has(x));
+      return p.length ? p.reduce((s, x) => s + index.get(x)!, 0) / p.length : Number.MAX_SAFE_INTEGER;
+    };
+    members.sort((a, b) => key(a) - key(b) || a.localeCompare(b));
+    let y = 20;
+    let colW = 0;
+    for (const n of members) {
+      const s = size.get(n)!;
+      if (y > 20 && y + s.h > maxH) {
+        x += colW + 60;
+        y = 20;
+        colW = 0;
+      }
+      index.set(n, index.size);
+      out.push({ name: n, x, y });
+      y += s.h + 40;
+      colW = Math.max(colW, s.w);
+    }
+    x += colW + 100;
+  }
+  return out;
+}
+
+/** Saved positions for the shown tables; tables without one get the automatic layout's (below the others when some are placed). */
+export function placeAll(schema: string, tables: ModelTable[], saved: Placed[]): Placed[] {
+  const known = new Map(saved.map((p) => [p.name, p]));
+  const missing = tables.filter((t) => !known.has(t.name));
+  if (!missing.length) return tables.map((t) => known.get(t.name)!);
+  const placedTables = tables.filter((t) => known.has(t.name));
+  if (!placedTables.length) return autoLayout(schema, tables);
+  const bottom = Math.max(...placedTables.map((t) => known.get(t.name)!.y + boxSize(t).h)) + 60;
+  const extra = autoLayout(schema, missing).map((p) => ({ ...p, y: p.y + bottom - 20 }));
+  return tables.map((t) => known.get(t.name) ?? extra.find((p) => p.name === t.name)!);
+}
+
+// ---------------------------------------------------------------- SVG
+
+export const COLORS = { bg: '#ffffff', frame: '#94a3b8', head: '#e8eefc', title: '#1e293b', text: '#334155', muted: '#64748b', key: '#b45309', line: '#475569', view: '#f1f5f9' };
+
+/** Where a box's title links: Table Properties for a table, the Object Browser for a view. */
+export const objectHref = (schema: string, t: ModelTable) =>
+  t.kind === 'table'
+    ? `/builder/sql/objects/table?${new URLSearchParams({ o: t.ref })}`
+    : `/builder/sql/objects?${new URLSearchParams({ schema, k: t.kind === 'view' ? 'view' : 'matview', o: t.ref })}`;
+
+/** Key markers of a column: P primary key, F foreign key, U unique. */
+export function markers(t: ModelTable, column: string) {
+  const has = (type: string) => t.constraints.some((k) => k.type === type && k.cols.includes(column));
+  return `${has('p') ? 'P' : ''}${has('f') ? 'F' : ''}${!has('p') && has('u') ? 'U' : ''}`;
+}
+
+/** The whole diagram. `title` names it; `links` makes box titles links (the page; not an exported file); `auto`: each box's automatic position (data-ax/ay, for the page's Auto layout). */
+export function diagramSvg(schema: string, title: string, tables: ModelTable[], placed: Placed[], opts: { links?: boolean; id?: string; auto?: Placed[] } = {}): Raw {
+  const autoAt = new Map((opts.auto ?? []).map((p) => [p.name, p]));
+  const pos = new Map(placed.map((p) => [p.name, p]));
+  const boxes = new Map(tables.map((t) => [t.name, { ...pos.get(t.name)!, ...boxSize(t) } as Box]));
+  const all = [...boxes.values()];
+  const W = Math.max(400, ...all.map((b) => b.x + b.w + 60));
+  const H = Math.max(240, ...all.map((b) => b.y + b.h + 40));
+  const c = COLORS;
+  const fk = lines(schema, tables).map((l) => {
+    const p = fkPath(boxes.get(l.from)!, l.fy, boxes.get(l.to)!, l.ty);
+    return html`<g class="dm-fk${l.optional ? ' dm-optional' : ''}" data-from="${l.from}" data-to="${l.to}" data-fy="${l.fy}" data-ty="${l.ty}"><title>${l.label}</title>
+      <path class="dm-line" d="${p.path}" fill="none" stroke="${c.line}" stroke-width="1.5"${l.optional ? raw(' stroke-dasharray="6 4"') : ''}/>
+      <path class="dm-end" d="${p.ends}" fill="none" stroke="${c.line}" stroke-width="1.5"/>${l.optional ? html`<circle class="dm-opt" cx="${p.circle.cx}" cy="${p.circle.cy}" r="4" fill="${c.bg}" stroke="${c.line}" stroke-width="1.5"/>` : ''}</g>`;
+  });
+  const box = (t: ModelTable) => {
+    const b = boxes.get(t.name)!;
+    const cols = shownColumns(t);
+    const titleText = html`<text class="dm-title" x="10" y="20" font-weight="600" font-size="13" fill="${c.title}">${cut(t.name, 48)}</text>`;
+    return html`<g class="dm-box dm-${t.kind === 'table' ? 'table' : 'view'}" data-name="${t.name}" data-x="${b.x}" data-y="${b.y}" data-w="${b.w}" data-h="${b.h}"${autoAt.has(t.name) ? html` data-ax="${autoAt.get(t.name)!.x}" data-ay="${autoAt.get(t.name)!.y}"` : ''} transform="translate(${b.x} ${b.y})"${opts.links ? raw(' tabindex="0"') : ''} aria-label="${t.kind} ${t.name}">
+      <title>${t.kind} ${schema}.${t.name}${t.comment ? `: ${t.comment}` : ''}</title>
+      <rect class="dm-frame" width="${b.w}" height="${b.h}" rx="4" fill="${t.kind === 'table' ? c.bg : c.view}" stroke="${c.frame}"/>
+      <path class="dm-head" d="M 0.5 4.5 a 4 4 0 0 1 4 -4 H ${b.w - 4.5} a 4 4 0 0 1 4 4 V ${HEAD} H 0.5 Z" fill="${c.head}" stroke="${c.frame}"/>
+      ${opts.links ? html`<a class="dm-link" href="${objectHref(schema, t)}">${titleText}</a>` : titleText}
+      ${t.kind === 'table' ? '' : html`<text class="dm-kind" x="${b.w - 8}" y="20" text-anchor="end" font-size="10" fill="${c.muted}">${t.kind === 'view' ? 'view' : 'mat. view'}</text>`}
+      ${cols.map((col, i) => {
+        const y = HEAD + i * ROW + 14;
+        return html`<g class="dm-row"><title>${col.name} ${col.type}${col.notNull ? ' not null' : ''}${col.comment ? `: ${col.comment}` : ''}</title>
+          <text class="dm-key" x="6" y="${y}" font-size="10" font-weight="700" fill="${c.key}">${markers(t, col.name)}</text>
+          <text class="dm-col" x="26" y="${y}" font-size="12" fill="${c.text}"${col.notNull ? raw(' font-weight="600"') : ''}>${col.notNull ? '* ' : ''}${cut(col.name, 36)}</text>
+          <text class="dm-type" x="${b.w - 8}" y="${y}" text-anchor="end" font-size="11" fill="${c.muted}">${cut(col.type, 24)}</text></g>`;
+      })}
+      ${cols.length < t.columns.length ? html`<text class="dm-more" x="26" y="${HEAD + cols.length * ROW + 14}" font-size="11" font-style="italic" fill="${c.muted}">… ${t.columns.length - cols.length} more columns</text>` : ''}
+      ${!t.columns.length ? html`<text class="dm-more" x="26" y="${HEAD + 14}" font-size="11" font-style="italic" fill="${c.muted}">no columns</text>` : ''}
+    </g>`;
+  };
+  return html`<svg xmlns="http://www.w3.org/2000/svg" class="dm-svg"${opts.id ? raw(` id="${opts.id.replace(/[^a-z0-9-]/g, '')}"`) : ''} width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" role="group" aria-label="Diagram ${title}">
+    <title>${title}: ${tables.length} objects of schema ${schema}</title>
+    <rect class="dm-bg" width="100%" height="100%" fill="${c.bg}"/>
+    <g class="dm-content"><g class="dm-lines">${fk}</g><g class="dm-boxes">${tables.map(box)}</g></g>
+  </svg>`;
+}