@mistriwork/engine 0.0.0 → 1.0.0-rc.10

package/dist/shared/dashboardAsks.js

@@ -0,0 +1,129 @@
+/**
+ * What a dashboard's sections ask, in the words they ask it: a metric's
+ * figure and its compare window's (its trend's are dashboardTrend.ts), a breakdown's groups, a chart's
+ * and a matrix's crosses, a board's lanes, a list's first rows, a pick's
+ * choices. The client's sections build their requests from these
+ * (client/components/Dashboard.tsx, dashboardModel.ts), and the server
+ * builds a first page's from them too (server/http/firstPaintRooms.ts), so
+ * the answers it carries are for the requests the sections then make.
+ */
+import { andQuery } from './query.js';
+import { labelColumn, primaryKey } from './schema.js';
+import { listPresentationColumns } from './appListColumns.js';
+/** A breakdown's goals, a row per group: the target table's measure by its own `by`, within its query. */
+export function targetText(section) {
+    const goal = section.target;
+    if (typeof goal !== 'object' || !goal.by)
+        return null;
+    return [goal.table, goal.query, `${goal.measure} by ${goal.by}`, `limit ${groupsAskedFor(section)}`].filter(Boolean).join(' ');
+}
+/** The breakdown a section asks for: its measure by its key, within its query. */
+export function breakdownText(section, limit) {
+    /* A scatter asks its two measures in one line: the answer is its key, then `x`, then the measure. */
+    const measured = `${section.x ? `${section.x}, ` : ''}${section.measure ?? 'count'}`;
+    return [section.table, section.query, `${measured} by ${section.by}`, limit ? `limit ${limit}` : ''].filter(Boolean).join(' ');
+}
+/**
+ * A section with the reader's window in place of the author's. The server
+ * hands sections whose query already windows the `over` column a
+ * `windowBase` without that phrase, so the reader's phrase stands where
+ * the author's did rather than intersecting it. A compare derived from
+ * "previous period" is re-derived against the reader's window — `last 30
+ * days` picked compares against `previous 30 days`; a hand-written compare,
+ * or a window phrase with no "previous" (this month), hides the delta rather
+ * than compare the reader's window to the author's.
+ */
+export function windowed(section, windowNow) {
+    if (!section.over || !windowNow)
+        return section;
+    const base = section.windowBase ?? section.query;
+    const out = { ...section, query: andQuery(base, `${section.over} = ${windowNow}`), windowPhrase: windowNow };
+    /* A goal per group follows the reader's window by its own clock: this quarter's quotas beside this quarter's wins. */
+    const goal = section.target;
+    if (typeof goal === 'object' && goal.over)
+        out.target = {
+            ...goal,
+            query: andQuery(section.targetWhole ? (goal.windowBase ?? goal.query) : goal.query, `${goal.over} = ${windowNow}`),
+        };
+    /* A metric with no window of its own is served `comparePeriod` and no
+       compare at all: it has a change only once a window is picked. */
+    if (section.compare || section.comparePeriod) {
+        const m = /^last\s+(\d+)\s+(minute|hour|day|week|month|year)s?$/i.exec(windowNow.trim());
+        out.compare =
+            section.comparePeriod && m ? andQuery(base, `${section.over} = previous ${m[1]} ${m[2]}${m[1] === '1' ? '' : 's'}`) : undefined;
+    }
+    return out;
+}
+/** The period a section with windows of its own is over: the reader's pick, else its first. */
+export const sectionPeriod = (section, periods) => (section.windows?.length ? (section.windowKey && periods[section.windowKey]) || section.windows[0] : null);
+/** A metric's figure over `query` — its own, or its compare window's. */
+export const measureText = (section, query) => [section.table, query, section.measure ?? 'count'].filter(Boolean).join(' ');
+/**
+ * How many groups a breakdown asks for before it orders them itself. The
+ * grammar answers groups in the engine's order — the alphabet, on SQLite —
+ * so a section's `limit` asked of the server kept the first groups by name,
+ * not the biggest. The groups are fetched, ordered on the client and then
+ * cut to the section's limit.
+ */
+const GROUPS_ASKED = 200;
+export const groupsAskedFor = (section) => Math.max(section.limit ?? 0, GROUPS_ASKED);
+/** The groups a chart asks for: stacked bars cross two keys, and bars and a donut order their groups themselves. */
+export function chartLimit(section) {
+    /* A heat map's grid is every cross of its keys: a week of hours is 168. */
+    if (section.shape === 'stacked' || section.shape === 'heatmap')
+        return 400;
+    /* A waterfall's and a treemap's groups are all drawn, as a donut's slices: `limit` keeps the largest. */
+    if (section.shape === 'waterfall' || section.shape === 'treemap' || section.shape === 'scatter')
+        return groupsAskedFor(section);
+    /* A line (or the default chart) over two keys draws one line per second key: every period crossed with every series is a
+       row, and the server's twenty-row default dropped the later periods, so each line fell to zero where the rows ran out. */
+    if (section.shape === 'line' && (section.by ?? '').includes(','))
+        return 400;
+    return section.shape === 'donut' || section.shape === 'bar' ? groupsAskedFor(section) : section.limit;
+}
+/** A board's lane counts. */
+export const boardCountText = (section) => [section.table, section.query, `count by ${section.by}`].filter(Boolean).join(' ');
+/**
+ * A dashboard list's question: its rows with the columns it draws, the names
+ * its references are read by and the keys a row opens by, kept out of sight,
+ * up to its limit. `presentation` is the embedded view's, whose dress reads
+ * columns of its own.
+ */
+export function dashboardListQuery(lookups, section, presentation) {
+    const table = section.table ? lookups.table(section.table) : undefined;
+    const shown = [...new Set([...(section.show ?? []), ...(presentation ? listPresentationColumns(presentation) : [])])];
+    const keys = shown.length ? (table ? primaryKey(table) : []).filter((key) => !shown.includes(key)) : [];
+    const referenceLabels = shown.length ? lookups.referenceNames(section.table, shown) : {};
+    /* The record's own name rides along unseen as its key does: on a phone a
+       row is a card titled by it, and without it a lease was titled "21". */
+    const naming = shown.length && table ? lookups.naming(table) : undefined;
+    const titled = naming && !primaryKey(table).includes(naming) ? [naming] : [];
+    const named = [...new Set([...Object.values(referenceLabels), ...titled])].filter((name) => !shown.includes(name));
+    const query = [
+        section.table,
+        section.query,
+        section.sort ? `sort ${section.sort}` : '',
+        shown.length ? `show ${[...shown, ...named, ...keys].join(', ')}` : '',
+        `limit ${section.limit ?? 5}`,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return { query, keys, named, referenceLabels };
+}
+/**
+ * A pick's choices, where its column is a whole single-column reference: the
+ * records it points at, by name, fifty at most. Null where the column is a
+ * vocabulary (its values are the choices) or no section's table has it.
+ */
+export function pickQuery(lookups, sections, column) {
+    const home = sections.find((section) => section.table && lookups.table(section.table)?.columns.some((c) => c.name === column));
+    const table = home?.table ? lookups.table(home.table) : undefined;
+    const meta = table?.columns.find((c) => c.name === column);
+    const fk = table && !meta?.allowed?.length
+        ? lookups.references(table.id).find((f) => f.from.columns.length === 1 && f.from.columns[0] === column)
+        : undefined;
+    const target = fk ? lookups.table(fk.to.table) : undefined;
+    const naming = target ? labelColumn(target) : undefined;
+    const pk = target ? primaryKey(target)[0] : undefined;
+    return target && naming ? `${target.id} show ${[...new Set([naming, pk])].join(', ')} sort ${naming}` : null;
+}

package/dist/shared/dashboardTrend.d.ts

@@ -0,0 +1,20 @@
+import { type AutoUnit } from './autoBucket.js';
+import type { AskedSection } from './dashboardAsks.js';
+/**
+ * The window a metric's trend is drawn over — the reader's, else the author's own on `over` — and the units it is
+ * read and drawn in: the span's unit (autoBucket.ts), read as days under a week so a week is added up on the client
+ * (`trendPoints`) and never handed whole to one month. Null where the metric has no window the date grammar bounds.
+ */
+export declare function sparkWindow(section: Pick<AskedSection, 'query' | 'over' | 'windowPhrase'>, now?: Date): {
+    phrase: string;
+    read: AutoUnit;
+    unit: AutoUnit;
+} | null;
+/**
+ * A metric's trend. Over a window, the metric over that window in the span's unit, so "last 30 days" draws thirty
+ * days and "last 12 months" twelve months: every windowed metric has one, beside its change, unless its author said
+ * `spark: false`. With no window, the author's `spark: true` is the measure's last twelve months, bucketed monthly by
+ * the section's own clock (`over`), composed with whatever the card is narrowed to by other than time. None without a
+ * clock.
+ */
+export declare function sparkText(section: Pick<AskedSection, 'table' | 'query' | 'windowBase' | 'windowPhrase' | 'measure' | 'over' | 'spark'>): string | null;

package/dist/shared/dashboardTrend.js

@@ -0,0 +1,50 @@
+/**
+ * A metric's trend, in the words it is asked: the window it is drawn over and the read that draws it. Apart from
+ * dashboardAsks.ts because it reads the window's span through autoBucket.ts, which only a drawn dashboard needs:
+ * held there, every App's first page carried the bucketing a chart and a trend use (scripts/bundle-budget.mjs).
+ * Asked by the client's metric (client/components/Dashboard.tsx) and by the server for a first page
+ * (server/http/firstPaintRooms.ts), in the same words.
+ */
+import { andQuery } from './query.js';
+import { unitForSpan, windowDays, windowPhraseOf } from './autoBucket.js';
+/**
+ * The window a metric's trend is drawn over — the reader's, else the author's own on `over` — and the units it is
+ * read and drawn in: the span's unit (autoBucket.ts), read as days under a week so a week is added up on the client
+ * (`trendPoints`) and never handed whole to one month. Null where the metric has no window the date grammar bounds.
+ */
+export function sparkWindow(section, now = new Date()) {
+    if (!section.over)
+        return null;
+    const phrase = section.windowPhrase ?? windowPhraseOf(section.query, section.over);
+    const days = phrase ? windowDays(phrase, now) : null;
+    if (!phrase || !days)
+        return null;
+    /* "today" is one day: a trend of fewer than four points is no line, and no slot is held for it. */
+    if (days < 4)
+        return null;
+    const unit = unitForSpan(days);
+    return { phrase, unit, read: unit === 'week' ? 'day' : unit };
+}
+/** The most periods a windowed trend reads: 182 days, or months and quarters past them, with room to spare. */
+const TREND_PERIODS = 400;
+/**
+ * A metric's trend. Over a window, the metric over that window in the span's unit, so "last 30 days" draws thirty
+ * days and "last 12 months" twelve months: every windowed metric has one, beside its change, unless its author said
+ * `spark: false`. With no window, the author's `spark: true` is the measure's last twelve months, bucketed monthly by
+ * the section's own clock (`over`), composed with whatever the card is narrowed to by other than time. None without a
+ * clock.
+ */
+export function sparkText(section) {
+    /* An authored false is heard over a window too: a card can be a figure alone, which it once could not say. */
+    if (!section.over || section.spark === false)
+        return null;
+    const window = sparkWindow(section);
+    if (window)
+        return [section.table, section.query, `${section.measure ?? 'count'} by ${window.read} ${section.over}`, `limit ${TREND_PERIODS}`]
+            .filter(Boolean)
+            .join(' ');
+    if (!section.spark)
+        return null;
+    const trendBase = section.windowBase ?? section.query;
+    return `${section.table} ${andQuery(trendBase, `${section.over} = last 12 months`)} ${section.measure ?? 'count'} by month ${section.over}`;
+}

package/dist/shared/declaredReferences.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Declared references: an App's soft keys (`references: { product_sku: {
+ * to: 'product', column: 'sku' } }`), a column the database holds no foreign
+ * key for, joined as if it did.
+ *
+ * One edge, two places. In the App's logical catalog it is an ordinary
+ * ForeignKey marked `declared`, so every path, label, link, related list and
+ * rollup that follows a key follows it, and the reader's pruned catalog
+ * (accessibleSchema) drops it with the column or table it touches, as it does
+ * a real one. Below that catalog every layer compiles against the database's
+ * own, which has no such key; there the edge rides in the view
+ * (`ViewDef.references`), attached by the App's resource layer, and the
+ * compilers put it back for that one statement.
+ *
+ * Only a join that cannot multiply the base row is taken: the target column
+ * must be the table's single-column primary key or proven unique. That is
+ * judged when the App loads and again, against the catalog in hand, at every
+ * compile, so an edge that has stopped being true is dropped rather than run.
+ */
+import { type DatabaseSchema, type ForeignKey } from './schema.js';
+/** One declaration as a resource block says it, in the source's local logical names. */
+export interface DeclaredReference {
+    table: string;
+    column: string;
+    to: string;
+    /** Absent: the target's single-column primary key. */
+    toColumn?: string;
+}
+/** The edge a declaration names, or why the catalog refuses it. */
+export declare function declaredEdge(schema: DatabaseSchema, reference: DeclaredReference, at: string): ForeignKey;
+/**
+ * The single-column edges a composite key implies. A tenant's
+ * key `(tenant_id, group_id) → assignment_group (tenant_id, id)`, where `id`
+ * is unique on its own, names one group by `group_id` alone: every other leg
+ * is NOT NULL, so the composite is checked whenever `group_id` is set, and
+ * the row it lands on is the one `id` names. A reader who cannot read
+ * `tenant_id` — every tenant context — still follows the reference by the leg
+ * it reads. Never a smaller key: the target column is already unique alone,
+ * and the database's composite key still decides what may be written.
+ */
+export declare function impliedEdges(schema: DatabaseSchema): ForeignKey[];
+/** The catalog with these edges in it: each column gains its `references`, as a real key's does. */
+export declare function withDeclaredEdges(schema: DatabaseSchema, edges: readonly ForeignKey[]): DatabaseSchema;
+/**
+ * A view's carried edges put back into the catalog it is compiled against,
+ * each only while it still holds there: both ends real columns, the target
+ * unique, the column not already a key. One that does not is dropped, and
+ * a path through it fails as a path through nothing.
+ */
+export declare function withViewReferences(schema: DatabaseSchema, references: readonly ForeignKey[] | undefined): DatabaseSchema;

package/dist/shared/declaredReferences.js

@@ -0,0 +1,202 @@
+/**
+ * Declared references: an App's soft keys (`references: { product_sku: {
+ * to: 'product', column: 'sku' } }`), a column the database holds no foreign
+ * key for, joined as if it did.
+ *
+ * One edge, two places. In the App's logical catalog it is an ordinary
+ * ForeignKey marked `declared`, so every path, label, link, related list and
+ * rollup that follows a key follows it, and the reader's pruned catalog
+ * (accessibleSchema) drops it with the column or table it touches, as it does
+ * a real one. Below that catalog every layer compiles against the database's
+ * own, which has no such key; there the edge rides in the view
+ * (`ViewDef.references`), attached by the App's resource layer, and the
+ * compilers put it back for that one statement.
+ *
+ * Only a join that cannot multiply the base row is taken: the target column
+ * must be the table's single-column primary key or proven unique. That is
+ * judged when the App loads and again, against the catalog in hand, at every
+ * compile, so an edge that has stopped being true is dropped rather than run.
+ */
+import { columnKind, findTable, primaryKey } from './schema.js';
+/** The target column proves one row per value: the whole primary key, or unique on its own. */
+function uniqueIn(table, column) {
+    const key = primaryKey(table);
+    return (key.length === 1 && key[0] === column) || Boolean(table.unique?.includes(column));
+}
+/** The edge a declaration names, or why the catalog refuses it. */
+export function declaredEdge(schema, reference, at) {
+    const from = schema.tables.find((table) => table.id === reference.table);
+    if (!from)
+        throw new Error(`${at}: "${reference.table}" is not a table in this catalog.`);
+    const column = from.columns.find((item) => item.name === reference.column);
+    if (!column)
+        throw new Error(`${at}: "${reference.column}" is not a column of ${reference.table}.`);
+    if (column.primaryKey)
+        throw new Error(`${at}: "${reference.column}" is part of the primary key; a reference is a column that points elsewhere.`);
+    if (column.references || schema.foreignKeys.some((fk) => fk.from.table === from.id && fk.from.columns.includes(column.name))) {
+        throw new Error(`${at}: "${reference.column}" already has a foreign key in the database, which the App follows as it is.`);
+    }
+    const to = schema.tables.find((table) => table.id === reference.to);
+    if (!to)
+        throw new Error(`${at}: "to" names "${reference.to}", which is not a table in this catalog.`);
+    const key = primaryKey(to);
+    const toColumn = reference.toColumn ?? (key.length === 1 ? key[0] : undefined);
+    if (!toColumn)
+        throw new Error(`${at}: ${reference.to} has no single-column primary key, so name the "column" it is looked up by.`);
+    const target = to.columns.find((item) => item.name === toColumn);
+    if (!target)
+        throw new Error(`${at}: "${toColumn}" is not a column of ${reference.to}.`);
+    if (!uniqueIn(to, toColumn)) {
+        throw new Error(`${at}: ${reference.to}.${toColumn} is not proven unique (its primary key, or a unique constraint or index on it alone), ` +
+            `so one ${reference.table} could name several. Add a unique index on ${reference.to}(${toColumn}).`);
+    }
+    if (columnKind(column.type) !== columnKind(target.type)) {
+        throw new Error(`${at}: ${reference.table}.${column.name} is ${column.type} and ${reference.to}.${toColumn} is ${target.type}; ` +
+            'a reference compares like with like.');
+    }
+    return {
+        name: `${from.id}_${column.name}_declared`,
+        from: { table: from.id, columns: [column.name] },
+        to: { table: to.id, columns: [toColumn] },
+        declared: true,
+    };
+}
+/**
+ * The single-column edges a composite key implies. A tenant's
+ * key `(tenant_id, group_id) → assignment_group (tenant_id, id)`, where `id`
+ * is unique on its own, names one group by `group_id` alone: every other leg
+ * is NOT NULL, so the composite is checked whenever `group_id` is set, and
+ * the row it lands on is the one `id` names. A reader who cannot read
+ * `tenant_id` — every tenant context — still follows the reference by the leg
+ * it reads. Never a smaller key: the target column is already unique alone,
+ * and the database's composite key still decides what may be written.
+ */
+export function impliedEdges(schema) {
+    const edges = [];
+    /* Each table's single-column keys, read once: a scan of the graph for every leg of every composite made this a
+       large part of pruning a tenant App's catalog, which startup does once per command footprint and role. */
+    let singles;
+    const singleKeys = () => {
+        const by = new Map();
+        for (const other of schema.foreignKeys)
+            if (other.from.columns.length === 1) {
+                const columns = by.get(other.from.table);
+                if (columns)
+                    columns.add(other.from.columns[0]);
+                else
+                    by.set(other.from.table, new Set(other.from.columns));
+            }
+        return by;
+    };
+    for (const fk of schema.foreignKeys) {
+        if (fk.declared || fk.from.columns.length < 2)
+            continue;
+        const from = findTable(schema, fk.from.table);
+        const to = findTable(schema, fk.to.table);
+        if (!from || !to)
+            continue;
+        fk.from.columns.forEach((name, index) => {
+            const column = from.columns.find((item) => item.name === name);
+            const target = to.columns.find((item) => item.name === fk.to.columns[index]);
+            if (!column || !target || column.primaryKey || !uniqueIn(to, target.name) || columnKind(column.type) !== columnKind(target.type))
+                return;
+            const legs = fk.from.columns.filter((other) => other !== name);
+            if (legs.some((other) => from.columns.find((item) => item.name === other)?.nullable !== false))
+                return;
+            // A column that is already a single-column key is that key's, and needs no second edge.
+            if ((singles ??= singleKeys()).get(from.id)?.has(name))
+                return;
+            edges.push({
+                // Named by what it joins, not after the constraint: a composite's name usually spells the column a tenant never reads.
+                name: `${from.id}.${name}->${to.id}`,
+                from: { table: from.id, columns: [name] },
+                to: { table: to.id, columns: [target.name] },
+                declared: true,
+            });
+        });
+    }
+    return edges;
+}
+const sameEdge = (a, b) => a.from.table === b.from.table &&
+    a.to.table === b.to.table &&
+    a.from.columns[0] === b.from.columns[0] &&
+    a.to.columns[0] === b.to.columns[0];
+/** The catalog with these edges in it: each column gains its `references`, as a real key's does. */
+export function withDeclaredEdges(schema, edges) {
+    if (!edges.length)
+        return schema;
+    return {
+        ...schema,
+        tables: schema.tables.map((table) => {
+            const mine = edges.filter((edge) => edge.from.table === table.id);
+            if (!mine.length)
+                return table;
+            return {
+                ...table,
+                columns: table.columns.map((column) => {
+                    const edge = mine.find((item) => item.from.columns[0] === column.name);
+                    return edge && !column.references ? { ...column, references: { table: edge.to.table, column: edge.to.columns[0] } } : column;
+                }),
+            };
+        }),
+        foreignKeys: [...schema.foreignKeys, ...edges],
+    };
+}
+/**
+ * A view's carried edges put back into the catalog it is compiled against,
+ * each only while it still holds there: both ends real columns, the target
+ * unique, the column not already a key. One that does not is dropped, and
+ * a path through it fails as a path through nothing.
+ */
+export function withViewReferences(schema, references) {
+    if (!references?.length)
+        return schema;
+    /* One catalog per (view's references, catalog): a fresh object each time would also start
+       every cache keyed by the catalog (resolvePath's) empty on every compile. */
+    let byCatalog = viewCatalogs.get(references);
+    if (!byCatalog)
+        viewCatalogs.set(references, (byCatalog = new WeakMap()));
+    let kept = byCatalog.get(schema);
+    if (kept)
+        return kept;
+    /* And by their text: a scoped reader copies every view it is handed before compiling it (scopedReads.ts
+       snapshotScopedData), so the same references arrive as a new array on every read and the identity above never
+       holds there — a field report's large tenant App built this catalog afresh for every list, count and breakdown
+       of an enter. The widened catalog depends on nothing but the edges' words and the catalog, so equal text is the
+       same answer. Bounded per catalog: one App carries one set; past the bound a set is built as before. */
+    const text = JSON.stringify(references);
+    let byText = viewCatalogsByText.get(schema);
+    if (!byText)
+        viewCatalogsByText.set(schema, (byText = new Map()));
+    kept = byText.get(text);
+    if (!kept) {
+        kept = withViewReferencesFresh(schema, references);
+        if (byText.size < VIEW_CATALOGS_BY_TEXT)
+            byText.set(text, kept);
+    }
+    byCatalog.set(schema, kept);
+    return kept;
+}
+const viewCatalogs = new WeakMap();
+const viewCatalogsByText = new WeakMap();
+const VIEW_CATALOGS_BY_TEXT = 64;
+function withViewReferencesFresh(schema, references) {
+    let implied;
+    const holding = references.filter((edge) => {
+        if (edge.from.columns.length !== 1 || edge.to.columns.length !== 1)
+            return false;
+        if (schema.foreignKeys.some((fk) => fk.name === edge.name && fk.from.table === edge.from.table))
+            return false;
+        // A leg of a composite key in this catalog: true here as long as the key is.
+        if ((implied ??= impliedEdges(schema)).some((other) => sameEdge(other, edge)))
+            return true;
+        try {
+            declaredEdge(schema, { table: edge.from.table, column: edge.from.columns[0], to: edge.to.table, toColumn: edge.to.columns[0] }, '');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    return withDeclaredEdges(schema, holding.map((edge) => ({ ...edge, declared: true })));
+}

package/dist/shared/definedFields.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Fields whose definitions are rows: a record's JSON column holds one value
+ * per key, and the keys — their captions, types, choices and whether they
+ * are required — are rows of another resource that an administrator edits
+ * while the App runs, per tenant where the App is a tenant App:
+ *
+ *   product:   { defined: { specs: { from: 'attribute', per: 'category_id' } } }
+ *   attribute: { access: 'write' }
+ *
+ * A product is shaped by the attribute rows whose `category_id` is its own
+ * and by those whose `category_id` is empty (fields every product has).
+ *
+ * The definition rows have fixed column names, so there is one way to say
+ * one: `key`, `label` and `type` always; `options` (one choice per line),
+ * `required`, `help` and `position` where the table has them. A row this
+ * module cannot read (a type outside the set, a key that is not an
+ * identifier) is left out rather than allowed to break a page: definitions
+ * are data, typed by people, at runtime.
+ *
+ * This module is what the declaration says and what a first page needs to
+ * know of it (a path the query language reads, the column served). Reading
+ * definition rows and judging values by them is definedValues.ts's, which
+ * only the server and the parts loaded on demand import.
+ */
+import { type ColumnMeta, type TableMeta } from './schema.js';
+/** The kinds a definition's `type` may name: the command `field.*` words, with `choices` for many of a list. */
+export declare const DEFINED_TYPES: readonly ['text', 'textarea', 'number', 'money', 'date', 'datetime', 'bool', 'choice', 'choices'];
+export type DefinedType = (typeof DEFINED_TYPES)[number];
+/** `resources.<r>.defined.<column>`: which rows define the column's fields, and the column that picks them. */
+export interface DefinedBinding {
+    /** The resource whose rows are the definitions. */
+    from: string;
+    /** A column both tables have: a record is shaped by the definitions whose value matches its own, and those with none. */
+    per?: string;
+}
+/** One definition row, read. */
+export interface DefinedField {
+    key: string;
+    label: string;
+    type: DefinedType;
+    /** The choices of a `choice` or `choices` field, in the order written. */
+    options: string[];
+    required: boolean;
+    help?: string;
+}
+/** The columns every definitions table has, and those it may. */
+export declare const NEEDED: readonly ['key', 'label', 'type'];
+export declare const OPTIONAL: readonly ['options', 'required', 'help', 'position'];
+/** A definition's key, and the key a path reads: written into SQL as a literal, so held to an identifier. */
+export declare const DEFINED_KEY: RegExp;
+/** The most definitions read for one record: a form, not a catalog. */
+export declare const DEFINITIONS_MOST = 200;
+/** `resources.<r>.defined`, read for its shape. Throws the sentence the author reads. */
+export declare function parseDefined(raw: unknown, at: string): Record<string, DefinedBinding>;
+/** The column each binding is on, by resolved table id: what the App serves the browser (`ResolvedResource.defined`). */
+export declare function servedDefined(bindings: Readonly<Record<string, DefinedBinding>> | undefined, table: TableMeta, fromTable: (name: string) => TableMeta | undefined): {
+    served: Record<string, DefinedBinding>;
+    problems: string[];
+};
+/** A JSON key a path reads (`specs.capacity`) is no column of its own: its type says so, and the query language reads its values as they are written. */
+export declare const DEFINED_PATH_TYPE = "defined";
+/** The column a JSON key path reads as: of no declared kind, so `2` compares as a number and `"2"` as text (query.ts `coerce`). */
+export declare function definedColumnMeta(key: string): ColumnMeta;

package/dist/shared/definedFields.js

@@ -0,0 +1,103 @@
+/**
+ * Fields whose definitions are rows: a record's JSON column holds one value
+ * per key, and the keys — their captions, types, choices and whether they
+ * are required — are rows of another resource that an administrator edits
+ * while the App runs, per tenant where the App is a tenant App:
+ *
+ *   product:   { defined: { specs: { from: 'attribute', per: 'category_id' } } }
+ *   attribute: { access: 'write' }
+ *
+ * A product is shaped by the attribute rows whose `category_id` is its own
+ * and by those whose `category_id` is empty (fields every product has).
+ *
+ * The definition rows have fixed column names, so there is one way to say
+ * one: `key`, `label` and `type` always; `options` (one choice per line),
+ * `required`, `help` and `position` where the table has them. A row this
+ * module cannot read (a type outside the set, a key that is not an
+ * identifier) is left out rather than allowed to break a page: definitions
+ * are data, typed by people, at runtime.
+ *
+ * This module is what the declaration says and what a first page needs to
+ * know of it (a path the query language reads, the column served). Reading
+ * definition rows and judging values by them is definedValues.ts's, which
+ * only the server and the parts loaded on demand import.
+ */
+import { isJsonType } from './schema.js';
+/** The kinds a definition's `type` may name: the command `field.*` words, with `choices` for many of a list. */
+export const DEFINED_TYPES = ['text', 'textarea', 'number', 'money', 'date', 'datetime', 'bool', 'choice', 'choices'];
+/** The columns every definitions table has, and those it may. */
+export const NEEDED = ['key', 'label', 'type'];
+export const OPTIONAL = ['options', 'required', 'help', 'position'];
+/** A definition's key, and the key a path reads: written into SQL as a literal, so held to an identifier. */
+export const DEFINED_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The most definitions read for one record: a form, not a catalog. */
+export const DEFINITIONS_MOST = 200;
+/** `resources.<r>.defined`, read for its shape. Throws the sentence the author reads. */
+export function parseDefined(raw, at) {
+    const shape = `${at} has a "defined" that is not an object of the resource's own JSON column → { from, per? }, like defined: { specs: { from: 'attribute', per: 'category_id' } }.`;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !Object.keys(raw).length)
+        throw new Error(shape);
+    const bindings = {};
+    for (const [column, value] of Object.entries(raw)) {
+        const here = `${at}, defined "${column}"`;
+        if (!IDENTIFIER.test(column))
+            throw new Error(`${here}: defined fields are keyed by the resource's own JSON column, never a path.`);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error(shape);
+        const given = value;
+        const unknown = Object.keys(given).find((key) => key !== 'from' && key !== 'per');
+        if (unknown)
+            throw new Error(`${here} has "${unknown}"; it takes from and per.`);
+        if (typeof given.from !== 'string' || !given.from.trim())
+            throw new Error(`${here}: "from" names the resource whose rows define the fields.`);
+        const binding = { from: given.from.trim() };
+        if (given.per !== undefined) {
+            if (typeof given.per !== 'string' || !IDENTIFIER.test(given.per))
+                throw new Error(`${here}: "per" names one column both resources have, like per: 'category_id'.`);
+            binding.per = given.per;
+        }
+        bindings[column] = binding;
+    }
+    return bindings;
+}
+/** Why a binding cannot run on this catalog, or undefined: a JSON column, a definitions table with its columns, and `per` on both. */
+function definedProblem(column, binding, table, from) {
+    const own = table.columns.find((candidate) => candidate.name === column);
+    if (!own)
+        return `defined "${column}": "${table.name}" has no column "${column}".`;
+    if (!isJsonType(own.type))
+        return `defined "${column}" is ${own.type || 'untyped'}; defined fields live in a JSON column (jsonb on PostgreSQL, a column declared JSON on SQLite).`;
+    if (!from)
+        return `defined "${column}": "${binding.from}" is not a declared resource on this connection.`;
+    const missing = NEEDED.filter((name) => !from.columns.some((candidate) => candidate.name === name));
+    if (missing.length)
+        return `defined "${column}": "${from.name}" has no ${missing.map((name) => `"${name}"`).join(', ')}; a definition row has key, label and type (and may have options, required, help and position).`;
+    if (binding.per) {
+        if (!table.columns.some((candidate) => candidate.name === binding.per))
+            return `defined "${column}": "${table.name}" has no column "${binding.per}" for per.`;
+        if (!from.columns.some((candidate) => candidate.name === binding.per))
+            return `defined "${column}": "${from.name}" has no column "${binding.per}" for per.`;
+    }
+    return undefined;
+}
+/** The column each binding is on, by resolved table id: what the App serves the browser (`ResolvedResource.defined`). */
+export function servedDefined(bindings, table, fromTable) {
+    const served = {};
+    const problems = [];
+    for (const [column, binding] of Object.entries(bindings ?? {})) {
+        const from = fromTable(binding.from);
+        const problem = definedProblem(column, binding, table, from);
+        if (problem)
+            problems.push(problem);
+        else
+            served[column] = { from: from.id, ...(binding.per ? { per: binding.per } : {}) };
+    }
+    return { served, problems };
+}
+/** A JSON key a path reads (`specs.capacity`) is no column of its own: its type says so, and the query language reads its values as they are written. */
+export const DEFINED_PATH_TYPE = 'defined';
+/** The column a JSON key path reads as: of no declared kind, so `2` compares as a number and `"2"` as text (query.ts `coerce`). */
+export function definedColumnMeta(key) {
+    return { name: key, type: DEFINED_PATH_TYPE, nullable: true, primaryKey: false };
+}