tina4-nodejs 3.13.147 → 3.13.149

package/types/orm/src/crudHelpers.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 declare const h: typeof escapeHtml;
+/** The DB column a property name maps to (fieldMapping or the property itself). */
+export declare function columnOf(model: CrudModel, prop: string): string;
+/** The primary-key property name (the field flagged primaryKey, else "id"). */
+export declare function primaryKeyProp(model: CrudModel): string;
+/** The model's declared string/text property names. */
+export declare function searchableProps(model: CrudModel): string[];
+/** Column alignment from the field type: numeric right, everything else left. */
+export declare function columnAlignment(model: CrudModel | null, col: string): string;
+/** Pretty label from a column name: "user_name" => "User Name". */
+export declare function prettyLabel(col: string): string;
+/**
+ * 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 declare function crudSortProp(model: CrudModel, requested: string | undefined, pkProp: string): string;
+/** Read one column value from a record hash (keyed by property name). */
+export declare function cellValue(record: Record<string, unknown>, col: string): unknown;
+/** Build the pre-joined <td> run for one row (every value escaped + aligned). */
+export declare function buildCells(columns: string[], record: Record<string, unknown>, editable: boolean, aligns: string[]): string;
+/**
+ * Drop a trailing ORDER BY / LIMIT clause from each line of a custom listing SQL.
+ * Pure string scanning — no backtracking regex.
+ */
+export declare function stripOrderAndLimit(sql: string): string;
+/**
+ * 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 declare function extractColumns(sql: string): string[];

package/types/orm/src/crudRender.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare function renderCrudTemplate(name: string, data: Record<string, unknown>): string;
+/** Render the create/edit/delete modal shell (crud/modals.twig). */
+export declare function renderModals(editableColumns: string[], pk: string): string;
+/**
+ * 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 declare function generateTable(records: Array<Record<string, unknown>> | null | undefined, options?: {
+    tableName?: string;
+    primaryKey?: string;
+    editable?: boolean;
+}): string;
+export interface FormFieldDef {
+    name: string;
+    type?: string;
+    label?: string;
+    value?: unknown;
+    required?: boolean;
+    options?: Array<{
+        value: unknown;
+        label: unknown;
+    }>;
+}
+/**
+ * Render an HTML form from a field-definition array via crud/form.twig.
+ * Synchronous — no model, no DB.
+ */
+export declare function generateForm(fields: FormFieldDef[], options?: {
+    action?: string;
+    method?: string;
+    tableName?: string;
+}): string;

package/types/orm/src/crudTable.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 } from "./crudHelpers.js";
+export declare function sortIndicator(sortCol: string, col: string, sortDir: string): string;
+export declare function sortUrl(requestPath: string, col: string, nextDir: string, page: number, search: string, limit: number): string;
+export declare function pageUrl(requestPath: string, p: number, search: string, sortCol: string, sortDir: string, limit: number): string;
+/** One flat list of pagination controls (Prev, numbered pages, Next). */
+export declare function pageControls(page: number, totalPages: number, requestPath: string, search: string, sortCol: string, sortDir: string, limit: number): Array<Record<string, unknown>>;
+/** The JSON config injected into the page's nonce'd <script>. */
+export declare function jsConfig(opts: {
+    apiPath: string;
+    pk: string;
+    columns: string[];
+    editable: string[];
+    model: CrudModel;
+    limit: number;
+    search: string;
+    sortCol: string;
+    sortDir: string;
+    page: number;
+}): string;
+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 the data hash crud/table.twig consumes (headers + pre-joined rows). */
+export declare function tableData(opts: TableDataOpts): Record<string, unknown>;

package/types/orm/src/index.d.ts

@@ -15,7 +15,9 @@ export { syncModels, ensureMigrationTable, getNextBatch, isMigrationApplied, rec
 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";
+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";

package/types/orm/src/migration.d.ts

@@ -181,24 +181,6 @@ export declare function splitStatements(sql: string, delimiter?: string): string
  * AFTER the numbered ones, then lexically. Mirrors Python's `_migration_sort_key`.
  */
 export declare function sortMigrationFiles(files: string[]): string[];
-/**
- * Run all pending SQL-file migrations.
- *
- * Supports both naming patterns:
- * - Sequential: 000001_description.sql
- * - Timestamp: YYYYMMDDHHMMSS_description.sql
- *
- * 1. Creates the `tina4_migration` tracking table if it doesn't exist.
- * 2. Scans `migrationsDir` for `.sql` files (excluding `.down.sql`), sorted.
- * 3. Skips files already recorded as applied.
- * 4. Splits file content on `delimiter` and executes each statement.
- * 5. On success records the migration with the current batch number.
- * 6. On error logs and continues.
- * 7. Returns a summary of applied / skipped / failed files.
- *
- * @param adapter - A DatabaseAdapter instance (or omit to use the global adapter).
- * @param options - Optional configuration.
- */
 export declare function migrate(adapter?: DatabaseAdapter, options?: {
     migrationsDir?: string;
     delimiter?: string;

package/types/orm/src/query.d.ts

@@ -36,18 +36,6 @@ export declare class UnknownFieldError extends Error {
 export declare class InvalidQueryParameterError extends Error {
     constructor(message: string);
 }
-/**
- * Build the list SQL from parsed query options.
- *
- * `quote` renders every table/column name the builder emits - pass the bound
- * adapter's dialect (`(name) => quoteIdentifier(adapter, name)`); the default is
- * the ANSI `"name"`.
- *
- * Every filter key and sort field is passed through `resolveColumn` (see
- * resolveFieldColumn) and only the column it returns is emitted; a key it does
- * not resolve throws UnknownFieldError before any SQL exists. With no
- * resolver, no filter or sort key resolves (ADR-0069).
- */
 export declare function buildQuery(tableName: string, options: QueryOptions, extraConditions?: string[], quote?: (name: string) => string, resolveColumn?: (key: string) => string | null): {
     sql: string;
     countSql: string;

package/types/orm/src/types.d.ts

@@ -187,4 +187,23 @@ export interface QueryOptions {
     sort?: string;
     page?: number;
     limit?: number;
+    /**
+     * ADR-0094: full-text search term. LIKE %term% is OR'd across `searchColumns`
+     * and added to the WHERE before limit/offset, so the total reflects the
+     * filtered set. The CRUD admin grid (and any client) drives this via ?search=.
+     */
+    search?: string;
+    /**
+     * DB columns the `search` term matches against (the model's declared
+     * string/text columns, already resolved to their mapped column names). The
+     * caller resolves these from the model; buildQuery only quotes and binds them,
+     * so nothing but a declared column can reach SQL (ADR-0069).
+     */
+    searchColumns?: string[];
+    /**
+     * ADR-0094: direction for a single bare ?sort=column (the CRUD grid's
+     * spelling). "desc" sorts descending; anything else ascending. Ignored for a
+     * Mongo-style "-field,field" sort, which carries its own inline direction.
+     */
+    sortDir?: string;
 }