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

package/dist/shared/recordLabel.js

@@ -0,0 +1,123 @@
+/**
+ * A record's name as a template: `recordLabel: 'PO-{id}'`, `'{product_id.name} × {qty}'`.
+ *
+ * A record label used to be one column or one path, and a table with no name
+ * of its own — a purchase order, an order line — was titled by its key: "3".
+ * A template says the name in words around the columns that make it, and
+ * the name is computed where every other value is, in the statement: a list,
+ * a picker, a breadcrumb and a reference to the record all read the same
+ * `$label` path, sort by it and search it, on every engine, with nothing for
+ * the browser to assemble from columns it may not have fetched.
+ *
+ * `$label` is a path's last segment (`purchase_order_id.$label`), legal
+ * where a table carries a template (`TableMeta.labelTemplate`, which an App
+ * serves), and compiled from the view's `labels` (prefix → template), which
+ * the server's read fills from that catalog — never from a request.
+ */
+/** The last segment that names a record's templated label. */
+export const LABEL_SEGMENT = '$label';
+const MASK_MARK = '|masked';
+/* Or its words: `{token|words:…}`, the column's display rule (`values`,
+   `humanize`, a vocabulary's words) reaching the name the way it reaches a
+   cell, so a visit is "Ada Park · Annual physical", not "… · annual
+   physical". The map is URI-encoded JSON, so no brace or bar in a word
+   ends the field early. */
+const WORDS_MARK = '|words:';
+/** Whether an authored record label is a template rather than a path. */
+export const isLabelTemplate = (text) => typeof text === 'string' && text.includes('{');
+/** The prefix a `$label` path hangs off ('' for the base's own), or undefined for any other path. */
+export function labelPrefix(path) {
+    if (path === LABEL_SEGMENT)
+        return '';
+    return path.endsWith(`.${LABEL_SEGMENT}`) ? path.slice(0, -LABEL_SEGMENT.length - 1) : undefined;
+}
+/* Literal text is written into the statement as a quoted string, so it is
+   held to what every engine reads the same way inside quotes: no backslash
+   (some engines' escape), no control characters. A quote is doubled when written. */
+const unsafe = (character) => character === '\\' || character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f;
+const FIELD = /^[A-Za-z_$][\w$]*(?:\+[A-Za-z_$][\w$]*)*(?:\.[A-Za-z_$][\w$]*(?:\+[A-Za-z_$][\w$]*)*)*$/;
+/** A template's parts, or why it is not one. */
+export function parseLabelTemplate(template) {
+    /* The author's length: the words the server marks a field with are not theirs. */
+    if (template.replace(/\|words:[^}]*/g, '').length > 200)
+        return { problem: 'a record label template is at most 200 characters.' };
+    const parts = [];
+    const paths = [];
+    let rest = template;
+    while (rest) {
+        const open = rest.indexOf('{');
+        const close = rest.indexOf('}');
+        if (close !== -1 && (open === -1 || close < open))
+            return { problem: `"${template}" has a "}" with no "{" before it.` };
+        if (open === -1) {
+            parts.push({ text: rest });
+            break;
+        }
+        if (open > 0)
+            parts.push({ text: rest.slice(0, open) });
+        const end = rest.indexOf('}', open);
+        if (end === -1)
+            return { problem: `"${template}" opens a "{" it never closes.` };
+        let field = rest.slice(open + 1, end);
+        let words;
+        const worded = field.indexOf(WORDS_MARK);
+        if (worded !== -1) {
+            words = readWords(field.slice(worded + WORDS_MARK.length));
+            if (!words)
+                return { problem: `"{${field}}" in "${template}" is not a column or a reference path, like {id} or {customer_id.name}.` };
+            field = field.slice(0, worded);
+        }
+        const marked = field.indexOf(MASK_MARK);
+        const path = (marked === -1 ? field : field.slice(0, marked)).trim();
+        const after = marked === -1 ? undefined : field.slice(marked + MASK_MARK.length);
+        if (!FIELD.test(path) || path.split('.').includes(LABEL_SEGMENT) || (after !== undefined && after !== '' && !after.startsWith(':'))) {
+            return { problem: `"{${field}}" in "${template}" is not a column or a reference path, like {id} or {customer_id.name}.` };
+        }
+        parts.push({ path, ...(after === undefined ? {} : { mask: after ? { prefix: after.slice(1) } : {} }), ...(words ? { words } : {}) });
+        paths.push(path);
+        rest = rest.slice(end + 1);
+    }
+    if (!paths.length)
+        return { problem: `"${template}" names no column; put one in braces, like "PO-{id}".` };
+    for (const part of parts) {
+        if ('text' in part && [...part.text].some(unsafe)) {
+            return { problem: `"${template}" holds a backslash or a control character, which a record label cannot.` };
+        }
+    }
+    return { parts, paths };
+}
+/* A words map as a field carries it, or undefined when it is not one: every
+   key and word a string every engine reads alike inside quotes. */
+function readWords(encoded) {
+    let map;
+    try {
+        map = JSON.parse(decodeURIComponent(encoded));
+    }
+    catch {
+        return undefined;
+    }
+    if (!map || typeof map !== 'object' || Array.isArray(map))
+        return undefined;
+    const entries = Object.entries(map);
+    if (!entries.length || entries.some(([key, word]) => typeof word !== 'string' || [...key, ...word].some(unsafe)))
+        return undefined;
+    return Object.fromEntries(entries);
+}
+/** A template field for a path whose stored values are said as words, as the server writes it into a served template. */
+export const wordedField = (path, words) => `{${path}${WORDS_MARK}${encodeURIComponent(JSON.stringify(words))}}`;
+/** A template field for a masked path, as the server writes it into a served template. */
+export const maskedField = (path, prefix) => `{${path}${MASK_MARK}${prefix ? `:${prefix}` : ''}}`;
+/** Whether an authored template writes a mask itself: that is the column's display rule's to say. */
+export const writesMask = (template) => template.includes(MASK_MARK) || template.includes(WORDS_MARK);
+/**
+ * The name a record with no name of its own is given: its noun and its key,
+ * "Purchase order #3", rather than the bare key a title and a breadcrumb
+ * used to show. One key column only: a composite key is not one number.
+ */
+export function nounTemplate(noun, key) {
+    const word = [...noun]
+        .filter((character) => character !== '{' && character !== '}' && !unsafe(character))
+        .join('')
+        .trim() || 'Record';
+    return `${word.charAt(0).toUpperCase()}${word.slice(1)} #{${key}}`;
+}

package/dist/shared/recordReadKeys.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How a composed record page's answers are matched to the requests they
+ * answer (shared/recordReads.ts, client/composedReads.ts): one text per
+ * request, and the record's own row answered a part at a time. Imports
+ * nothing, so the client's request path carries no more than this.
+ */
+/** A value as one text, its object keys in order: two requests built alike are one request. */
+export declare function canonicalText(value: unknown): string;
+/** A read of the record's own row, as `rowBody` builds it: its base, its filter and its columns; otherwise undefined. */
+export declare function rowRead(body: Record<string, unknown>): {
+    base: string;
+    filter: string;
+    columns: string[];
+} | undefined;
+interface RowReply {
+    view: {
+        columns: Array<{
+            path: string;
+        }>;
+    } & Record<string, unknown>;
+    columns: string[];
+    rows: Array<Record<string, unknown>>;
+    resolved?: Array<{
+        path: string;
+        name?: string;
+    }>;
+}
+/** Exactly what a read of some of the row's columns would have been answered alone: its columns, their descriptions, its values. */
+export declare function rowPart<T extends RowReply>(reply: T, columns: readonly string[]): T;
+export {};

package/dist/shared/recordReadKeys.js

@@ -0,0 +1,51 @@
+/**
+ * How a composed record page's answers are matched to the requests they
+ * answer (shared/recordReads.ts, client/composedReads.ts): one text per
+ * request, and the record's own row answered a part at a time. Imports
+ * nothing, so the client's request path carries no more than this.
+ */
+/** A value as one text, its object keys in order: two requests built alike are one request. */
+export function canonicalText(value) {
+    return JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : item);
+}
+/** A read of the record's own row, as `rowBody` builds it: its base, its filter and its columns; otherwise undefined. */
+export function rowRead(body) {
+    const keys = Object.keys(body).sort().join(',');
+    if (keys !== 'count,view' || body.count !== 'none')
+        return undefined;
+    const view = body.view;
+    if (!view ||
+        typeof view !== 'object' ||
+        typeof view.id !== 'string' ||
+        !view.id.startsWith('page:') ||
+        typeof view.base !== 'string' ||
+        view.limit !== 1 ||
+        !Array.isArray(view.columns) ||
+        Object.keys(view).sort().join(',') !== 'base,columns,filter,id,limit,name')
+        return undefined;
+    const columns = [];
+    for (const column of view.columns) {
+        if (!column ||
+            typeof column !== 'object' ||
+            Object.keys(column).join(',') !== 'path' ||
+            typeof column.path !== 'string')
+            return undefined;
+        columns.push(column.path);
+    }
+    return { base: view.base, filter: canonicalText(view.filter), columns };
+}
+/** Exactly what a read of some of the row's columns would have been answered alone: its columns, their descriptions, its values. */
+export function rowPart(reply, columns) {
+    const asked = new Set(columns);
+    const resolved = reply.resolved?.filter((column) => asked.has(column.path));
+    const named = new Set(columns.map((path) => reply.resolved?.find((column) => column.path === path)?.name ?? path));
+    return {
+        ...reply,
+        view: { ...reply.view, columns: reply.view.columns.filter((column) => asked.has(column.path)) },
+        columns: reply.columns.filter((name) => named.has(name)),
+        rows: reply.rows.map((row) => Object.fromEntries(Object.entries(row).filter(([name]) => named.has(name)))),
+        ...(resolved ? { resolved } : {}),
+    };
+}

package/dist/shared/recordReads.d.ts

@@ -0,0 +1,268 @@
+/**
+ * What a record page reads, as the requests its sections send.
+ *
+ * A record page used to reach its reader in three waves of requests — the
+ * root and the plan, then a request or two per section, then the history —
+ * and at 20 ms to the database each wave was a round of admissions and
+ * statements: a lender's loan finished at 0.9 s. The server now answers the
+ * whole page in one request (server/http/recordCompose.ts, and the tenant
+ * host's own): it plans the page, then asks each section's read on the
+ * section's behalf, through the same route and the same grants as the
+ * section's own request, and hands every answer back beside the plan. The
+ * client keeps them for the requests they answer (client/composedReads.ts),
+ * and a section that asks finds its answer waiting.
+ *
+ * So the one rule is that server and client build each request alike, and
+ * the builders live here, used by both: the sections' own modules call them
+ * for the request they send, and the server calls them to know what the
+ * sections will ask. A request built differently is only asked again — the
+ * section sends it, as it always did — so a drift costs a request, never a
+ * wrong answer.
+ *
+ * The record's own row is the one read that is not asked alike: every fields
+ * section, the header, the root probe and a custom section's record fields
+ * read the one row, each for its columns, and which of them ask together
+ * depends on what is drawn (a tab not yet opened asks nothing). The server
+ * reads every column any of them names, once, and each is answered with
+ * exactly its part (`rowPart`), as the client's own shared read already was
+ * (pageFieldsRead.ts).
+ */
+import { type DatabaseSchema, type TableMeta } from './schema.js';
+import { type PageSection } from './pageModel.js';
+import type { HttpBreakdownDefinition, HttpFilter } from './resourceHttp.js';
+import { type AppTarget } from './appLinks.js';
+/** The route a record page is composed on. */
+export declare const RECORD_COMPOSE_PATH = "/api/pages/compose";
+/** Where a table's rows are named, as the reader's App says it (`recordLabel`, false where it is withheld). */
+export interface RecordReadNames {
+    readonly schema: DatabaseSchema;
+    /** Reads in an App's words: references carry their record's name, lists their keys. */
+    readonly app: boolean;
+    readonly recordLabel: (tableId: string) => string | false | undefined;
+    /** Where a table's rows are named, where the reader already knows (the client's labelPath, which is this rule over the same three). */
+    readonly namePath?: (table: TableMeta) => string | undefined;
+    /** A table by id, where the reader already holds it (the client's findTable, over the same schema). */
+    readonly table?: (id: string) => TableMeta | undefined;
+    /** A table's row-defined JSON columns (`resources.<r>.defined`): a section showing one also reads its `per`. */
+    readonly defined?: (tableId: string) => Readonly<Record<string, {
+        per?: string;
+    }>> | undefined;
+}
+/** The parts of a section its reads are built from (client pageModel.ts PageSection, shared page.ts). */
+export interface ReadSection {
+    readonly kind: PageSection['kind'];
+    readonly hidden?: boolean;
+    readonly emptyMode?: 'hide' | 'collapse';
+    /** A grouped related list reads its groups, then each group's rows (the rows wait on the groups). */
+    readonly group?: unknown;
+    readonly presentation?: unknown;
+    readonly paths?: readonly string[];
+    readonly status?: string;
+    readonly subfigure?: string;
+    readonly was?: string;
+    readonly actions?: ReadonlyArray<{
+        readonly prefill?: Readonly<Record<string, string>>;
+        readonly to?: AppTarget;
+    }>;
+    readonly names?: boolean;
+    readonly workflow?: {
+        readonly field: string;
+    };
+    readonly from?: string;
+    readonly limit?: number;
+    readonly record?: readonly string[];
+    readonly when?: string;
+    readonly region?: string;
+    readonly tab?: string;
+    readonly title?: string;
+    readonly width?: unknown;
+}
+/** A planned view, as the server builds it (ViewDef) or the client reads it off the wire (HttpViewDefinition). */
+interface ReadView {
+    readonly base: string;
+    readonly columns?: ReadonlyArray<{
+        readonly path: string;
+        readonly alias?: string;
+    }>;
+    readonly filter?: unknown;
+    readonly limit?: number;
+}
+/** The parts of a section's plan its reads are built from (pagePlans.ts). */
+export interface ReadPlan<V extends ReadView = ReadView> {
+    readonly index: number;
+    readonly error?: string;
+    readonly empty?: boolean;
+    readonly view?: V;
+    readonly counts?: boolean;
+    readonly totals?: HttpBreakdownDefinition;
+    readonly groups?: HttpBreakdownDefinition;
+    readonly breakdown?: HttpBreakdownDefinition;
+    readonly streams?: ReadonlyArray<TimelineReadStream<V>>;
+    readonly reads?: Readonly<Record<string, {
+        readonly error?: string;
+        readonly empty?: boolean;
+        readonly view?: V;
+    }>>;
+    /** A custom section's aggregate reads, each a breakdown. */
+    readonly aggregates?: Readonly<Record<string, {
+        readonly error?: string;
+        readonly empty?: boolean;
+        readonly breakdown?: HttpBreakdownDefinition;
+    }>>;
+}
+/** A timeline stream's plan, as far as its reads go (pagePlans.ts): its table, its author, its rows and its far side. */
+interface TimelineReadStream<V extends ReadView = ReadView> {
+    readonly error?: string;
+    readonly empty?: boolean;
+    readonly from?: string;
+    readonly by?: string;
+    readonly view?: V;
+    readonly key?: readonly string[];
+    readonly side?: {
+        readonly error?: string;
+        readonly view?: V;
+    };
+}
+/**
+ * A timeline stream's reads, as its section asks them (kit PageTimeline.tsx): its rows, where its author is a
+ * reference with the person's name beside it, read through the reference as a list column of it is; and where the
+ * stream has a far side, that side's rows. One rule for the section and the page's planned reads (`recordReads`),
+ * so a composed page's answer is the very read the section asks: a record page whose timeline was planned without
+ * the author's name asked it again, alone, once the page had drawn (a field report: a fifth round on a record).
+ */
+export declare function timelineReads<V extends ReadView>(names: {
+    readonly table: (id: string) => TableMeta | undefined;
+    readonly namePath: (table: TableMeta) => string | undefined;
+}, stream: TimelineReadStream<V>): {
+    view: V;
+    side?: V;
+} | undefined;
+/** One request, as a section sends it: its route and its body, without the owner the transport adds. */
+export interface ReadAsk {
+    readonly path: string;
+    readonly body: Record<string, unknown>;
+}
+/**
+ * The fields a section shows when it names none. In the Workbench, every
+ * column: it is the database as it is. In an App, every column a reader
+ * reads — not a key the database handed out (a lone numeric or uuid primary
+ * key, which opened a lead on "ID 2") and not a row version, the same two
+ * the scaffold leaves out of the fields it writes (server/scaffold.ts).
+ */
+export declare function defaultFieldPaths(base: TableMeta, app: boolean): string[];
+/** A fields section's columns: what it shows, the names of what it references, the record's name, and its workflow's field. */
+export declare function fieldsColumns(names: RecordReadNames, base: TableMeta, section: ReadSection): {
+    fetched: string[];
+    labels: Map<string, string>;
+};
+/**
+ * The row-defined column a fields path ends on (`resources.<r>.defined`):
+ * the record's own (`specs`) or one through references
+ * (`requested_item_id.answers`), with the table it lives on, the hops before
+ * it, and its binding. Undefined for any other path. A record shows the
+ * column's fields wherever its path is shown, not only on its own page.
+ */
+export declare function definedThrough<B extends {
+    per?: string;
+}>(schema: DatabaseSchema, baseId: string, path: string, defined: (tableId: string) => Readonly<Record<string, B>> | undefined): {
+    table: TableMeta;
+    column: string;
+    prefix: string;
+    binding: B;
+} | undefined;
+/** A record header's columns: its status, its facts, the names of what they reference, and the record's name. */
+export declare function headerColumns(names: RecordReadNames, base: TableMeta, section: ReadSection): {
+    fetched: string[];
+    labels: Map<string, string>;
+};
+/** A read of the record's own row, for columns: the probe (`root`), a fields section (`fields`), the header (`header`), a custom section's record (`<index>:record`). */
+export declare function rowBody(pageId: string, base: TableMeta, key: Readonly<Record<string, unknown>>, columns: readonly string[], part: string): {
+    count: 'none';
+    view: {
+        id: string;
+        name: string;
+        base: string;
+        columns: {
+            path: string;
+        }[];
+        filter: HttpFilter<"path">;
+        limit: 1;
+    };
+};
+/** A related list's first request: its planned view at the reader's page size, with the names and keys a row needs. */
+export declare function listView<V extends ReadView>(names: RecordReadNames, section: ReadSection, plan: ReadPlan<V>, rows: number): {
+    view: (V & {
+        columns: {
+            path: string;
+            alias?: string;
+        }[];
+    }) | undefined;
+    labelColumns: Record<string, string>;
+    hidden: string[];
+    keyColumns: Array<{
+        column: string;
+        index: number;
+    }>;
+    labelColumn: {
+        path: string;
+        index: number;
+    } | undefined;
+};
+/** A grouped list's page of groups, as `/api/breakdown` takes it: the request the page's compose asks and the list asks again. */
+export declare function groupsBody(groups: HttpBreakdownDefinition, offset: number): {
+    def: HttpBreakdownDefinition;
+    limit: number | undefined;
+    offset: number;
+};
+/** A metric's measure: a count asked as a breakdown with no key, or the plan's own breakdown; none for a plain aggregate. */
+export declare function metricMeasure(plan: ReadPlan<ReadView>): HttpBreakdownDefinition | undefined;
+/** Whether the record satisfies a `when`: one bounded query, key and condition composed the way every fold is. */
+export declare function whenBody(base: TableMeta, key: Readonly<Record<string, unknown>>, when: string): {
+    q: string;
+    limit: number;
+    offset: number;
+    count: 'none';
+};
+/** The first page of a record's history. */
+export declare function historyBody(base: TableMeta, key: Readonly<Record<string, unknown>>, limit: number): {
+    table: string;
+    key: Readonly<Record<string, unknown>>;
+    limit: number;
+};
+/**
+ * The sections a page draws when it opens on `tab`, as PageSections.tsx lays
+ * them out: a strip of named tabs draws the one asked for (the first, when
+ * none is) and every panel holding the record's own fields; a run of lists
+ * made into tabs draws the one asked for; everything else is drawn. The
+ * header is drawn in the head. What a closed tab would read is read when it
+ * is opened, as ever, and asked for nothing here.
+ */
+export declare function drawnSections(schema: DatabaseSchema, page: {
+    sections: readonly ReadSection[];
+    listTabs?: boolean;
+}, tab: string | undefined, appPage: boolean): Set<number>;
+/**
+ * Every read a record page's sections will ask for when it opens on `tab`,
+ * given its plan: the record's row (every column any section drawn reads),
+ * and each other request as the section builds it. A hidden section, and
+ * one in a closed tab, reads nothing; a section behind a `when` is read
+ * too, and its condition asked, since the answer is only kept until it is
+ * asked for.
+ */
+export declare function recordPageReads(names: RecordReadNames, page: {
+    id: string;
+    sections: readonly ReadSection[];
+    listTabs?: boolean;
+}, base: TableMeta, plans: readonly ReadPlan[], key: Readonly<Record<string, unknown>>, options: {
+    rows: number;
+    history: boolean;
+    tab?: string;
+}): {
+    row: string[];
+    parts: Array<{
+        part: string;
+        columns: string[];
+    }>;
+    reads: ReadAsk[];
+};
+export {};