@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/shared/pageModel.js

@@ -0,0 +1,121 @@
+import {} from './tableSizing.js';
+import { maskQuoted } from './maskQuoted.js';
+export const WIDTHS = ['full', 'half', 'third', 'two-thirds'];
+export const OFFSETS = ['quarter', 'third', 'half', 'two-thirds'];
+export const SECTION_REGIONS = ['main', 'aside'];
+export const FIELD_COLUMNS = [1, 2, 3];
+/* A group opens to at most GROUP_ROWS_MOST rows ("Show all"), and a page of groups holds at most GROUPS_MOST: a header's
+   facts ride on its rows, so the bound is also the bound on the reads. */
+/**
+ * A related list read as groups: one header for each record (or value) its rows point at through `by`, and that group's
+ * rows under it, a page of groups at a time. One level only — the second level of a chain is a fact on the header.
+ */
+export const GROUP_ROWS_MOST = 50;
+export const GROUP_ROWS_DEFAULT = 5;
+export const GROUPS_MOST = 10;
+export const GROUPS_DEFAULT = 5;
+/** Every `about` a page's sections and streams name, once each: the referenced rows the planner reads first. */
+export function pageAbouts(page) {
+    return [
+        ...new Set(page.sections.flatMap((section) => section.kind === 'timeline'
+            ? section.streams.flatMap((stream) => (stream.of ? [stream.of] : []))
+            : section.kind !== 'fields' &&
+                section.kind !== 'note' &&
+                section.kind !== 'history' &&
+                section.kind !== 'flows' &&
+                section.kind !== 'diagram' &&
+                section.kind !== 'custom' &&
+                section.of
+                ? [section.of]
+                : [])),
+    ];
+}
+/**
+ * The columns a timeline's tone and compact rules read. Given a stream and its table, those its rows carry: a rule is
+ * read on each stream whose table has its column, as `side` is, and not on one that says its own `tone` or `compact`
+ *, so time logged need not carry a `kind` only so a rule can name it. Without a stream, every rule's column.
+ */
+export function timelineMarkColumns(section, stream, table) {
+    const named = [
+        ...new Set([
+            ...(stream?.tone === undefined ? Object.keys(section.tone ?? {}) : []),
+            ...(stream?.compact === undefined ? Object.keys(section.compact ?? {}) : []),
+        ]),
+    ];
+    return stream ? named.filter((column) => Boolean(table?.columns.some((c) => c.name === column))) : named;
+}
+/**
+ * A timeline's `side` as one stream asks it: `record.<column>` is the page's record, reached by the stream's own way
+ * back to it, so `author_id = record.caller_id` over a stream `whose: 'ticket_id'` is `author_id =
+ * ticket_id.caller_id` — one condition the query language already reads, run where the stream's rows are read.
+ * Undefined where the stream's rows lead to another row (`about`), which has no way back to the record.
+ */
+export function timelineSide(side, stream) {
+    const masked = maskQuoted(side);
+    const at = [...masked.matchAll(/(?<![\w$.])record\.(?=[A-Za-z_])/g)].map((match) => match.index);
+    if (at.length && stream.of)
+        return undefined;
+    let out = side;
+    for (const i of at.reverse())
+        out = `${out.slice(0, i)}${stream.path}.${out.slice(i + 'record.'.length)}`;
+    return out;
+}
+/** How many streams one timeline is allowed to merge. */
+export const MAX_STREAMS = 4;
+/** The most writes one history section shows before asking for more. */
+export const MAX_HISTORY_LIMIT = 100;
+/** Writes a history section shows before "Show earlier changes" when its `limit` says none. */
+export const DEFAULT_HISTORY_LIMIT = 8;
+/** Every section kind's traits (SectionTraits). The union is closed: a kind is added here, with its row. */
+export const SECTION_TRAITS = {
+    fields: { reads: 'record', relation: false },
+    metric: { reads: 'rows', relation: true },
+    list: { reads: 'rows', relation: true },
+    breakdown: { reads: 'rows', relation: true },
+    chart: { reads: 'rows', relation: true },
+    note: { reads: 'none', relation: false },
+    timeline: { reads: 'rows', relation: true },
+    history: { reads: 'none', relation: false },
+    flows: { reads: 'none', relation: false },
+    diagram: { reads: 'none', relation: false },
+    custom: { reads: 'rows', relation: false },
+};
+/** Whether a section reads one of these ways (SectionTraits.reads), narrowed to the kinds that do. */
+export function sectionReading(section, ...reads) {
+    return reads.includes(SECTION_TRAITS[section.kind].reads);
+}
+/** Whether a section kind reads one of these ways, for a shape that is not the section union (recordReads.ts ReadSection). */
+export function kindReading(kind, ...reads) {
+    return reads.includes(SECTION_TRAITS[kind].reads);
+}
+/** Whether a section walks a path from the root (SectionTraits.relation), narrowed to the kinds that do. */
+export const walksRelation = (section) => SECTION_TRAITS[section.kind].relation;
+/** Rows a list section shows before it needs a page of its own. */
+export const DEFAULT_PAGE_LIST_LIMIT = 10;
+/** Sections one screen of a page may draw: in each region, those in no tab and the largest tab's. A page is a
+    screen, not a report; a record's tabs are more screens of it, so they are counted one at a time. */
+export const MAX_SECTIONS = 24;
+/** Sections a page may hold in all, every tab's included. */
+export const MAX_PAGE_SECTIONS = 96;
+/** How many sections a page draws on its fullest screen: per region, those in no tab and its largest tab's. */
+export function screenSections(sections) {
+    const regions = new Map();
+    for (const section of sections) {
+        const region = section.region ?? 'main';
+        const counted = regions.get(region) ?? { untabbed: 0, tabs: new Map() };
+        regions.set(region, counted);
+        if (section.tab === undefined)
+            counted.untabbed += 1;
+        else
+            counted.tabs.set(section.tab, (counted.tabs.get(section.tab) ?? 0) + 1);
+    }
+    let most = 0;
+    for (const { untabbed, tabs } of regions.values())
+        most += untabbed + Math.max(0, ...tabs.values());
+    return most;
+}
+/** A workflow step's label when it names none: `in_review` reads "In review". */
+export function workflowLabel(value) {
+    const words = value.replaceAll('_', ' ');
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}

package/dist/shared/pagePaths.d.ts

@@ -0,0 +1,180 @@
+import { type DatabaseSchema, type ForeignKey, type TableMeta } from './schema.js';
+import { type ViewDef, type ViewFilter } from './view.js';
+import { type PageMetric, type PageList, type PageDef, type PageCustom } from './pageModel.js';
+import type { PageCustomRead } from './appComponents.js';
+import type { BreakdownDef } from './breakdown.js';
+/**
+ * A path from a table back to the root, one foreign key per hop.
+ *
+ * Returned rather than a boolean because the caller needs the same thing the
+ * validator does: which columns to compare, and whether the last hop actually
+ * lands on the root. Composite keys are carried whole — a path that resolved
+ * only the first column of a two-column key would build a filter that matched
+ * every row sharing that column.
+ */
+export interface ResolvedPath {
+    hops: ForeignKey[];
+    /** The table the path ends at. Must be the page's base for the path to be usable. */
+    endsAt: string;
+}
+/**
+ * Follow `a.b.c` from a table, hop by hop, and say where it lands.
+ *
+ * Each segment names a foreign key on the current table by its canonical
+ * column(s), as in view paths (`a+b` for a composite), or by its constraint
+ * name, which tells apart two references over the same columns; a dotted
+ * constraint name is not a forward path segment.
+ */
+export declare function resolvePath(schema: DatabaseSchema, from: string, path: string): {
+    path?: ResolvedPath;
+    error?: string;
+};
+/** Prefer column-based paths, retaining explicit names when columns alone
+ * cannot identify the relationship. Never emit a dotted name as one hop. */
+export declare function pageHop(schema: DatabaseSchema, fk: ForeignKey): string | undefined;
+/**
+ * The filter that ties a section to one root record.
+ *
+ * Built as a structured `ViewFilter` rather than as text, for the reason the
+ * whole tool is built that way: a key value that happens to contain a quote
+ * or the word `and` is a value, and text would make it grammar.
+ *
+ * The path is written into the column, so the compiler does the joining —
+ * `invoice_id.customer_id` is a path it already knows how to walk, and the
+ * one place that knows how to join is better than a second one here.
+ */
+export declare function rootFilter(path: string, key: Record<string, string | number>, resolved: ResolvedPath): ViewFilter;
+/**
+ * Resolve a section's `of` — the forward reference naming which record the
+ * section is about.
+ *
+ * One hop, deliberately. `of: 'site_id.address_id'` is expressible in the
+ * type and refused here: each extra hop is another row the planner must read
+ * before any section can run, and nobody has yet asked for a section about
+ * the address of the site of the record they are looking at. The error says
+ * the limit rather than pretending the path is malformed.
+ */
+export declare function resolveOf(schema: DatabaseSchema, baseId: string, of: string): {
+    fk?: ForeignKey;
+    table?: TableMeta;
+    error?: string;
+};
+/**
+ * The keys of the records the page's `of` sections are about, by prefix.
+ *
+ * `null` says the root's reference is empty — a work order with no site —
+ * which is different from "unknown": a section given null renders its empty
+ * state instead of a filter that can never match.
+ */
+export type OfKeys = Record<string, Record<string, string | number> | null>;
+/** The record's own values, read on the server from its row for the sections that match on them (a similar list). */
+export type RootValues = Record<string, unknown>;
+/**
+ * What is wrong with a list's match (`same`, `near`) against this schema, or
+ * undefined. Said at startup (validatePage) and again when the list is
+ * planned, in the same words, so a page that loads is a page whose matched
+ * list can run. Each column is one of the listed table and of the page's own,
+ * the record's value being read off the page's row.
+ */
+export declare function similarProblem(schema: DatabaseSchema, page: PageDef, section: PageList): string | undefined;
+/**
+ * What is wrong with a related list's footer of sums (`totals`) against this
+ * schema, or undefined — said at startup and again when the list is planned.
+ * A total is a number column of the rows, or one of their numeric rollups or
+ * computed columns (`refunded`, the refunds of each order), through any
+ * reference `whose` walks.
+ */
+export declare function relatedMatchProblem(schema: DatabaseSchema, page: PageDef, section: PageList): string | undefined;
+/** The grouped record's columns a header says, as paths from the listed rows: read with each group's rows, so a header costs no read. */
+export declare function groupFactPaths(section: Pick<PageList, 'group'>): string[];
+/** The table a group's header is a record of, or undefined where the groups are plain values (or the path does not resolve). */
+export declare function groupTable(schema: DatabaseSchema, section: Pick<PageList, 'from' | 'group'>): TableMeta | undefined;
+/**
+ * What is wrong with a grouped list against this schema, or undefined — said at startup and again when the list is
+ * planned. The header is the record the rows point at through `by`; where `by` ends at a plain column the groups are
+ * its values, and there is no record to take facts or an order from.
+ */
+export declare function groupProblem(schema: DatabaseSchema, page: PageDef, section: PageList): string | undefined;
+/**
+ * The groups of a grouped list: one row for each record (or value) the listed rows point at through `by`, with how
+ * many rows it holds, its subtotals when the list has `totals`, and, when the groups are ordered by a column of the
+ * grouped record, the largest of that column — the sort column depends on the key, so the maximum is exact. It is a
+ * plain breakdown over the same rows the list reads, so it adds no SQL shape of its own and the reader's grants,
+ * row policy and tenant scope narrow it as they narrow every breakdown.
+ */
+export declare function groupsView(schema: DatabaseSchema, page: PageDef, section: PageList, key: Record<string, string | number>, ofKeys?: OfKeys, now?: Date): {
+    breakdown?: BreakdownDef;
+    empty?: boolean;
+    error?: string;
+};
+/**
+ * The sums a related list's footer says, as a breakdown with no key over the
+ * rows the list's reference matches — one row, a `sum` a column, as a
+ * narrowed page metric is measured — so the footer counts every row, not the
+ * page of them the list has loaded, and a rollup of the rows sums as a column
+ * does.
+ */
+export declare function totalsView(schema: DatabaseSchema, page: PageDef, section: PageList, key: Record<string, string | number>, ofKeys?: OfKeys, rootValues?: RootValues): {
+    breakdown?: BreakdownDef;
+    empty?: boolean;
+    error?: string;
+};
+/**
+ * What a list section needs to run, as a view the existing compiler can take.
+ *
+ * A page adds no query machinery of its own. Every section is a view — that
+ * is the point of having built one — so a page is an arrangement of views
+ * around a shared root rather than a second way to ask a database questions.
+ */
+export declare function listView(schema: DatabaseSchema, page: PageDef, section: PageList, key: Record<string, string | number>, index: number, now?: Date, ofKeys?: OfKeys, rootValues?: RootValues): {
+    view?: ViewDef;
+    empty?: boolean;
+    error?: string;
+};
+export declare function sectionQuery(view: ViewDef | undefined): string | undefined;
+export declare function metricView(schema: DatabaseSchema, page: PageDef, section: PageMetric, key: Record<string, string | number>, index: number, now?: Date, ofKeys?: OfKeys): {
+    view?: ViewDef;
+    counts?: boolean;
+    breakdown?: BreakdownDef;
+    empty?: boolean;
+    error?: string;
+};
+/**
+ * Columns worth showing in a list nobody has configured.
+ *
+ * The path back to the root is dropped: every row in the section has the same
+ * value for it, so a column of forty identical numbers is the one column that
+ * cannot tell two rows apart. The key and the label come first, because they
+ * are what a row is called.
+ */
+export declare function defaultColumns(table: TableMeta, path: string, resolved?: ResolvedPath): string[];
+/**
+ * One declared read of a custom section, planned as the list it is: with
+ * `whose`, exactly a related list (listView), the same join back to the
+ * record; without, the resource's own rows narrowed by its query — the
+ * dashboard's rows section, on a page. Either way the result is a view the
+ * server compiles and authorizes on every run, like any section's.
+ */
+export declare function customReadView(schema: DatabaseSchema, page: PageDef, name: string, read: PageCustomRead, key: Record<string, string | number>, index: number, now?: Date): {
+    view?: ViewDef;
+    empty?: boolean;
+    error?: string;
+};
+/**
+ * What is wrong with a custom section against this schema, or undefined:
+ * the record's fields judged as a fields section's, each read as the list it
+ * is planned as — its `whose` leading home, its columns, order and query
+ * through the compiler that will run them. Said at startup, so a misspelled
+ * column is refused before a reader sees the section.
+ */
+export declare function customProblem(schema: DatabaseSchema, page: PageDef, section: PageCustom, index: number): string | undefined;
+/** The hop every path shares, where each is one field past it (`dealer_id.name`, `dealer_id.city` → `dealer_id`), or ''. */
+export declare function sharedPrefix(paths: readonly string[] | undefined): string;
+/**
+ * The hop a card's facts are captioned without. A card's title is the record
+ * (`bike_id`, the reference itself) and its facts are that record's own fields
+ * (`bike_id.make`, `bike_id.serial_number`): read with the title, the paths
+ * share no hop, and a fact that is the parent's label column was captioned as
+ * the reference ("Bike" over a serial number). Its own name is what it is there.
+ */
+export declare function cardStem(paths: readonly string[] | undefined): string;