tina4-nodejs 3.13.148 → 3.13.150

package/packages/orm/src/crudHelpers.ts

@@ -0,0 +1,194 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+/**
+ * Crud (ADR-0094) — the pure helpers behind the HTML admin page.
+ *
+ * No I/O, no templates, no DB: column/label/alignment derivation, safe-sort
+ * resolution, the pre-joined table-data hash, the pagination controls, the
+ * injected JS config, and the two linear SQL-listing parsers. Kept in their own
+ * module so `crud.ts` stays a thin orchestrator and no single file carries the
+ * whole feature (the second-pass split by concern).
+ */
+
+import { escapeHtml } from "../../frond/src/engine.js";
+
+/** A BaseModel-like class: the statics Crud reads + the query statics it calls. */
+export interface CrudModel {
+  tableName: string;
+  fields: Record<string, { type?: string; primaryKey?: boolean; [k: string]: unknown }>;
+  fieldMapping?: Record<string, string>;
+  softDelete?: boolean;
+  tableFilter?: string;
+  name?: string;
+  all(limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<any>;
+  where(conditions: string, params?: unknown[], limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<any>;
+  count(conditions?: string, params?: unknown[]): Promise<number>;
+}
+
+/** Escape alias used throughout the CRUD HTML assembly. */
+export const h = escapeHtml;
+
+/** The whitespace characters the SQL scanners treat as separators (no regex). */
+const SQL_WS = " \t\n\r\f\v";
+
+/** The DB column a property name maps to (fieldMapping or the property itself). */
+export function columnOf(model: CrudModel, prop: string): string {
+  return model.fieldMapping?.[prop] ?? prop;
+}
+
+/** The primary-key property name (the field flagged primaryKey, else "id"). */
+export function primaryKeyProp(model: CrudModel): string {
+  for (const [name, def] of Object.entries(model.fields)) {
+    if (def.primaryKey) return name;
+  }
+  return "id";
+}
+
+/** The model's declared string/text property names. */
+export function searchableProps(model: CrudModel): string[] {
+  return Object.entries(model.fields)
+    .filter(([, def]) => def.type === "string" || def.type === "text")
+    .map(([name]) => name);
+}
+
+/** Column alignment from the field type: numeric right, everything else left. */
+export function columnAlignment(model: CrudModel | null, col: string): string {
+  const type = model?.fields?.[col]?.type;
+  return type === "integer" || type === "number" || type === "float" || type === "decimal"
+    ? "text-end"
+    : "text-start";
+}
+
+/** Pretty label from a column name: "user_name" => "User Name". */
+export function prettyLabel(col: string): string {
+  return String(col)
+    .split("_")
+    .map((p) => (p ? p.charAt(0).toUpperCase() + p.slice(1) : p))
+    .join(" ");
+}
+
+/**
+ * ADR-0069 safe sort: resolve the requested sort to a declared field PROPERTY
+ * (the grid's headers + client state are keyed by property), else the primary
+ * key. A request may name the field by its property or its mapped column; the
+ * DB column for the ORDER BY is derived with columnOf(). A rendered page ignores
+ * a bad sort rather than erroring.
+ */
+export function crudSortProp(model: CrudModel, requested: string | undefined, pkProp: string): string {
+  const req = (requested ?? "").trim();
+  if (req === "") return pkProp;
+  if (Object.hasOwn(model.fields, req)) return req;
+  for (const name of Object.keys(model.fields)) {
+    if (columnOf(model, name) === req) return name;
+  }
+  return pkProp;
+}
+
+/** Read one column value from a record hash (keyed by property name). */
+export function cellValue(record: Record<string, unknown>, col: string): unknown {
+  return record[col];
+}
+
+/** Build the pre-joined <td> run for one row (every value escaped + aligned). */
+export function buildCells(
+  columns: string[],
+  record: Record<string, unknown>,
+  editable: boolean,
+  aligns: string[],
+): string {
+  return columns
+    .map((col, index) => {
+      const raw = cellValue(record, col);
+      const value = h(raw === null || raw === undefined ? "" : raw);
+      const css = aligns[index];
+      return editable
+        ? `<td class="${css}" contenteditable="true" data-field="${h(col)}">${value}</td>`
+        : `<td class="${css}">${value}</td>`;
+    })
+    .join("");
+}
+
+/**
+ * Drop a trailing ORDER BY / LIMIT clause from each line of a custom listing SQL.
+ * Pure string scanning — no backtracking regex.
+ */
+export function stripOrderAndLimit(sql: string): string {
+  const cut = (line: string, keyword: string): string => {
+    const hasNewline = line.endsWith("\n");
+    const content = hasNewline ? line.slice(0, -1) : line;
+    const at = content.toUpperCase().indexOf(keyword);
+    if (at < 0) return line;
+    const after = at + keyword.length;
+    if (content.length <= after) return line;
+    return content.slice(0, at) + (hasNewline ? "\n" : "");
+  };
+  const src = String(sql);
+  const lines: string[] = [];
+  let start = 0;
+  for (let i = 0; i < src.length; i++) {
+    if (src[i] === "\n") { lines.push(src.slice(start, i + 1)); start = i + 1; }
+  }
+  lines.push(src.slice(start));
+  return lines.map((line) => cut(cut(line, "ORDER BY "), "LIMIT ")).join("").trim();
+}
+
+/**
+ * The column names a custom listing SQL selects (for the search CAST LIKE).
+ * Linear string scan: locate the first SELECT / FROM keywords (whitespace
+ * bounded, case-insensitive) and split the projection on commas — no
+ * backtracking regex over caller-supplied SQL (ReDoS-safe), mirroring the
+ * Ruby master's plain-string SQL parsing.
+ */
+export function extractColumns(sql: string): string[] {
+  const colsStr = selectProjection(sql);
+  if (colsStr === null || colsStr === "*") return ["*"];
+  return colsStr.split(",").map((c) => columnAlias(c.trim()));
+}
+
+/** The text between the first SELECT and its matching FROM, or null. */
+function selectProjection(sql: string): string | null {
+  const upper = sql.toUpperCase();
+  const selectAt = keywordIndex(upper, "SELECT", 0);
+  if (selectAt < 0) return null;
+  const colsStart = selectAt + "SELECT".length;
+  const fromAt = keywordIndex(upper, "FROM", colsStart);
+  if (fromAt < 0) return null;
+  return sql.slice(colsStart, fromAt).trim();
+}
+
+/** The alias/column name a single projection item resolves to. */
+function columnAlias(trimmed: string): string {
+  const asAt = keywordIndex(trimmed.toUpperCase(), "AS", 0);
+  if (asAt >= 0) {
+    const after = trimmed.slice(asAt + "AS".length).trim();
+    let endIdx = 0;
+    while (endIdx < after.length && !SQL_WS.includes(after[endIdx]) && after[endIdx] !== ",") endIdx++;
+    const word = after.slice(0, endIdx);
+    if (word) return word;
+  }
+  if (trimmed.includes(".")) return trimmed.split(".").pop()!.trim();
+  return trimmed;
+}
+
+/**
+ * Index of a whitespace-delimited keyword at or after `from`, or -1. Linear
+ * scan; the keyword must be flanked by a boundary (string edge or whitespace)
+ * so "FROM" inside "FROMAGE" never matches.
+ */
+function keywordIndex(upperHaystack: string, keyword: string, from: number): number {
+  let at = upperHaystack.indexOf(keyword, from);
+  while (at >= 0) {
+    const afterIdx = at + keyword.length;
+    const boundaryBefore = at === 0 || SQL_WS.includes(upperHaystack[at - 1]);
+    const boundaryAfter = afterIdx >= upperHaystack.length || SQL_WS.includes(upperHaystack[afterIdx]);
+    if (boundaryBefore && boundaryAfter) return at;
+    at = upperHaystack.indexOf(keyword, at + 1);
+  }
+  return -1;
+}

package/packages/orm/src/crudRender.ts

@@ -0,0 +1,202 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+/**
+ * Crud (ADR-0094) — the Frond rendering layer of the HTML admin page.
+ *
+ * Resolves the crud/<name>.twig templates app-first-then-framework (an app copy
+ * at src/templates/crud/ wins over the framework's shipped copy, the same
+ * resolution the error pages use), caches one Frond engine per directory, and
+ * exposes the two synchronous public generators (generateTable / generateForm)
+ * plus the modal shell renderer toCrud uses.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve as pathResolve, join as pathJoin, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Frond, setCspNonceProvider } from "../../frond/src/engine.js";
+import { currentCspNonce } from "../../core/src/csp.js";
+import { h, prettyLabel } from "./crudHelpers.js";
+import { tableData } from "./crudTable.js";
+
+/**
+ * Framework crud/ templates dir. The templates ship with @tina4/core
+ * (packages/core/templates/crud); from this module (packages/orm/{src,dist})
+ * that is two levels up then into core/templates — the same relative path in
+ * both the monorepo source tree and the published dist layout.
+ */
+const FRAMEWORK_TEMPLATES_DIR = pathResolve(
+  dirname(fileURLToPath(import.meta.url)), "..", "..", "core", "templates",
+);
+
+/** Cache one Frond engine per template directory. */
+const frondCache = new Map<string, InstanceType<typeof Frond>>();
+
+function frondFor(dir: string): InstanceType<typeof Frond> {
+  let engine = frondCache.get(dir);
+  if (!engine) {
+    // Make {{ csp_nonce() }} resolve to the current request's nonce (ADR-0088).
+    setCspNonceProvider(currentCspNonce);
+    engine = new Frond(dir);
+    frondCache.set(dir, engine);
+  }
+  return engine;
+}
+
+/**
+ * Render a crud/<name>.twig template, app-first-then-framework: an app override
+ * at src/templates/crud/<name>.twig wins over the framework's shipped copy (the
+ * same resolution the error pages use).
+ */
+export function renderCrudTemplate(name: string, data: Record<string, unknown>): string {
+  const templateFile = `crud/${name}.twig`;
+  const userDir = pathResolve(process.cwd(), "src", "templates");
+  if (existsSync(pathJoin(userDir, templateFile))) {
+    return frondFor(userDir).render(templateFile, data);
+  }
+  return frondFor(FRAMEWORK_TEMPLATES_DIR).render(templateFile, data);
+}
+
+/** A modal's create/edit form via crud/form.twig. */
+function renderModalForm(mode: string, columns: string[], pk: string, edit: boolean): string {
+  const fields = columns.map((col) => {
+    const label = prettyLabel(col);
+    return {
+      id: `${mode}-${col}`,
+      name: h(col),
+      label: h(label),
+      value: "",
+      placeholder: h(`Enter ${label.toLowerCase()}`),
+      type: "text",
+      required_attr: "",
+      input: true,
+    };
+  });
+  return renderCrudTemplate("form", {
+    wrap: true,
+    form_id_attr: ` id="form-${mode}"`,
+    action: "",
+    form_method: "POST",
+    method_override: null,
+    edit,
+    mode,
+    pk: h(pk),
+    modal_footer: true,
+    submit_button: false,
+    fields,
+  });
+}
+
+/** Render the create/edit/delete modal shell (crud/modals.twig). */
+export function renderModals(editableColumns: string[], pk: string): string {
+  return renderCrudTemplate("modals", {
+    create_form: renderModalForm("create", editableColumns, pk, false),
+    edit_form: renderModalForm("edit", editableColumns, pk, true),
+  });
+}
+
+/**
+ * Render an HTML table fragment from an array of record hashes via crud/table.twig.
+ * Inline-editable (contenteditable cells + Save/Delete wired by the template's
+ * delegated listener). Synchronous — no model, no DB.
+ */
+export function generateTable(
+  records: Array<Record<string, unknown>> | null | undefined,
+  options: { tableName?: string; primaryKey?: string; editable?: boolean } = {},
+): string {
+  const rows = records ?? [];
+  const tableName = String(options.tableName ?? "data");
+  const primaryKey = String(options.primaryKey ?? "id");
+  const editable = options.editable ?? true;
+  const columns = rows.length === 0 ? [] : Object.keys(rows[0]);
+
+  return renderCrudTemplate(
+    "table",
+    tableData({
+      columns, records: rows, pk: primaryKey, tableName, editable, sortable: false,
+      inlineScript: editable, requestPath: "", search: "", sortCol: "", sortDir: "asc",
+      page: 1, limit: 10, tableId: `crud-${tableName}`, model: null,
+    }),
+  );
+}
+
+export interface FormFieldDef {
+  name: string;
+  type?: string;
+  label?: string;
+  value?: unknown;
+  required?: boolean;
+  options?: Array<{ value: unknown; label: unknown }>;
+}
+
+function buildOptions(options: Array<{ value: unknown; label: unknown }> | undefined, selectedValue: unknown): string {
+  return (options ?? [])
+    .map((opt) => {
+      const selected = String(opt.value) === String(selectedValue) ? " selected" : "";
+      return `<option value="${h(opt.value)}"${selected}>${h(opt.label)}</option>`;
+    })
+    .join("");
+}
+
+/** The type-specific input descriptor layered onto the shared base field. */
+function fieldInputShape(field: FormFieldDef, base: Record<string, unknown>): Record<string, unknown> {
+  const value = field.value;
+  switch (field.type ?? "string") {
+    case "text":
+      return { ...base, textarea: true };
+    case "boolean":
+      return { ...base, checkbox: true, checked_attr: value ? " checked" : "" };
+    case "select":
+      return { ...base, select: true, options_html: buildOptions(field.options, value) };
+    case "date":
+      return { ...base, input: true, type: "date" };
+    case "integer":
+    case "number":
+    case "float":
+    case "decimal":
+      return { ...base, input: true, type: "number" };
+    default:
+      return { ...base, input: true, type: "text" };
+  }
+}
+
+function buildCustomField(field: FormFieldDef): Record<string, unknown> {
+  const name = String(field.name ?? "");
+  const label = field.label ?? (name.charAt(0).toUpperCase() + name.slice(1));
+  const base: Record<string, unknown> = {
+    id: h(name),
+    name: h(name),
+    label: h(String(label)),
+    value: h(field.value ?? ""),
+    placeholder: "",
+    required_attr: field.required ? " required" : "",
+  };
+  return fieldInputShape(field, base);
+}
+
+/**
+ * Render an HTML form from a field-definition array via crud/form.twig.
+ * Synchronous — no model, no DB.
+ */
+export function generateForm(
+  fields: FormFieldDef[],
+  options: { action?: string; method?: string; tableName?: string } = {},
+): string {
+  const verb = String(options.method ?? "POST").toUpperCase();
+  return renderCrudTemplate("form", {
+    wrap: true,
+    form_id_attr: "",
+    action: h(options.action ?? "/"),
+    form_method: h(verb),
+    method_override: ["PUT", "PATCH", "DELETE"].includes(verb) ? verb : null,
+    edit: false,
+    modal_footer: false,
+    submit_button: true,
+    fields: (fields ?? []).map((f) => buildCustomField(f)),
+  });
+}

package/packages/orm/src/crudTable.ts

@@ -0,0 +1,171 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+/**
+ * Crud (ADR-0094) — table + pagination assembly.
+ *
+ * The sort links, the pagination controls, the injected JS config, and the
+ * pre-joined table-data hash the crud/table.twig template consumes. Split from
+ * crudHelpers so neither file carries the whole feature (one concern per file).
+ */
+
+import {
+  type CrudModel,
+  h,
+  columnAlignment,
+  prettyLabel,
+  cellValue,
+  buildCells,
+} from "./crudHelpers.js";
+
+export function sortIndicator(sortCol: string, col: string, sortDir: string): string {
+  if (String(sortCol) !== String(col)) return "";
+  const arrow = sortDir === "asc" ? "▲" : "▼";
+  return ` <span class="sort-indicator">${arrow}</span>`;
+}
+
+export function sortUrl(
+  requestPath: string,
+  col: string,
+  nextDir: string,
+  page: number,
+  search: string,
+  limit: number,
+): string {
+  const query =
+    `sort=${encodeURIComponent(col)}&sort_dir=${nextDir}` +
+    `&page=${page}&search=${encodeURIComponent(search)}&limit=${limit}`;
+  return h(`${requestPath}?${query}`);
+}
+
+export function pageUrl(
+  requestPath: string,
+  p: number,
+  search: string,
+  sortCol: string,
+  sortDir: string,
+  limit: number,
+): string {
+  const query =
+    `page=${p}&search=${encodeURIComponent(search)}` +
+    `&sort=${encodeURIComponent(sortCol)}&sort_dir=${sortDir}&limit=${limit}`;
+  return h(`${requestPath}?${query}`);
+}
+
+/** One flat list of pagination controls (Prev, numbered pages, Next). */
+export function pageControls(
+  page: number,
+  totalPages: number,
+  requestPath: string,
+  search: string,
+  sortCol: string,
+  sortDir: string,
+  limit: number,
+): Array<Record<string, unknown>> {
+  if (totalPages <= 1) return [];
+  const controls: Array<Record<string, unknown>> = [];
+  if (page > 1) {
+    controls.push({
+      label: "Prev", page: page - 1, active: false, inactive: true,
+      url: pageUrl(requestPath, page - 1, search, sortCol, sortDir, limit),
+    });
+  }
+  let startPage = Math.max(page - 3, 1);
+  const endPage = Math.min(startPage + 6, totalPages);
+  startPage = Math.max(endPage - 6, 1);
+  for (let p = startPage; p <= endPage; p++) {
+    controls.push({
+      label: p, page: p, active: p === page, inactive: p !== page,
+      url: pageUrl(requestPath, p, search, sortCol, sortDir, limit),
+    });
+  }
+  if (page < totalPages) {
+    controls.push({
+      label: "Next", page: page + 1, active: false, inactive: true,
+      url: pageUrl(requestPath, page + 1, search, sortCol, sortDir, limit),
+    });
+  }
+  return controls;
+}
+
+/** The JSON config injected into the page's nonce'd <script>. */
+export function jsConfig(opts: {
+  apiPath: string; pk: string; columns: string[]; editable: string[]; model: CrudModel;
+  limit: number; search: string; sortCol: string; sortDir: string; page: number;
+}): string {
+  const aligns: Record<string, string> = {};
+  const labels: Record<string, string> = {};
+  for (const col of opts.columns) {
+    aligns[col] = columnAlignment(opts.model, col);
+    labels[col] = prettyLabel(col);
+  }
+  const config = {
+    api: opts.apiPath,
+    pk: opts.pk,
+    columns: opts.columns,
+    editable: opts.editable,
+    aligns,
+    labels,
+    limit: opts.limit,
+    search: opts.search,
+    sort: opts.sortCol,
+    sort_dir: opts.sortDir,
+    page: opts.page,
+  };
+  // Unicode-escape < > & so the literal is safe inside the <script> element.
+  return JSON.stringify(config)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026");
+}
+
+export interface TableDataOpts {
+  columns: string[]; records: Array<Record<string, unknown>>; pk: string; tableName: string;
+  editable: boolean; sortable: boolean; inlineScript: boolean; requestPath: string;
+  search: string; sortCol: string; sortDir: string; page: number; limit: number;
+  tableId: string | null; model: CrudModel | null;
+}
+
+/** Build one sortable/plain header cell for the given column. */
+function headerCell(opts: TableDataOpts, col: string, align: string): Record<string, unknown> {
+  const header: Record<string, unknown> = { label: h(prettyLabel(col)), align };
+  if (!opts.sortable) {
+    header.plain = true;
+    return header;
+  }
+  const nextDir = String(opts.sortCol) === String(col) && opts.sortDir === "asc" ? "desc" : "asc";
+  header.sortable = true;
+  header.col = h(col);
+  header.next_dir = nextDir;
+  header.url = sortUrl(opts.requestPath, col, nextDir, opts.page, opts.search, opts.limit);
+  header.indicator = sortIndicator(opts.sortCol, col, opts.sortDir);
+  return header;
+}
+
+/** Build the data hash crud/table.twig consumes (headers + pre-joined rows). */
+export function tableData(opts: TableDataOpts): Record<string, unknown> {
+  const aligns = opts.columns.map((col) => columnAlignment(opts.model, col));
+  const headers = opts.columns.map((col, index) => headerCell(opts, col, aligns[index]));
+  const rows = opts.records.map((record) => ({
+    id: h(cellValue(record, opts.pk) ?? ""),
+    cells: buildCells(opts.columns, record, opts.editable, aligns),
+  }));
+
+  return {
+    headers,
+    rows,
+    empty: opts.records.length === 0,
+    colspan: opts.columns.length + 1,
+    editable: opts.editable,
+    readonly: !opts.editable,
+    inline_script: opts.inlineScript,
+    table_name: h(opts.tableName),
+    table_id_attr: opts.tableId ? ` id="${h(opts.tableId)}"` : "",
+  };
+}
+

package/packages/orm/src/index.ts

@@ -60,7 +60,13 @@ export {
 export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { AutoCrud, generateCrudRoutes, crudEligibleModels } from "./autoCrud.js";
 export type { AutoCrudOptions } from "./autoCrud.js";
-export { buildQuery, parseQueryString, UnknownFieldError, InvalidQueryParameterError } from "./query.js";
+
+// Crud (ADR-0094) — the server-rendered HTML admin page over AutoCrud. Moved
+// from @tina4/core so it stays out of core's eager import graph; import it from
+// "tina4-nodejs/orm".
+export { Crud, CRUD, toCrud, registerBackend, generateTable, generateForm, stripOrderAndLimit, _resetCrudRegistrations } from "./crud.js";
+export type { ToCrudOptions, CrudModel, FormFieldDef } from "./crud.js";
+export { buildQuery, parseQueryString, resolveField, resolveFieldColumn, UnknownFieldError, InvalidQueryParameterError } from "./query.js";
 export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";