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

package/dist/shared/queryDates.d.ts

@@ -0,0 +1,12 @@
+interface DateWindow {
+    label: string;
+    start: Date;
+    end: Date;
+}
+/**
+ * `now` is a parameter rather than a call to the clock, so the compiler is a
+ * pure function of its inputs. That is what makes the tests below able to
+ * assert on an exact timestamp instead of a range.
+ */
+export declare function dateWindow(phrase: string, now: Date): DateWindow | undefined;
+export {};

package/dist/shared/queryDates.js

@@ -0,0 +1,101 @@
+/*
+ * Relative dates for the query language: `today`, `last 30 days`,
+ * `previous 3 months` resolved to two concrete timestamps against a given
+ * now, so they bind as parameters and mean the same on every engine.
+ */
+function startOfDay(d) {
+    const c = new Date(d);
+    c.setHours(0, 0, 0, 0);
+    return c;
+}
+function addDays(d, n) {
+    const c = new Date(d);
+    c.setDate(c.getDate() + n);
+    return c;
+}
+/**
+ * `now` is a parameter rather than a call to the clock, so the compiler is a
+ * pure function of its inputs. That is what makes the tests below able to
+ * assert on an exact timestamp instead of a range.
+ */
+export function dateWindow(phrase, now) {
+    const p = phrase.toLowerCase().trim();
+    const today = startOfDay(now);
+    const fixed = {
+        today: [today, addDays(today, 1)],
+        yesterday: [addDays(today, -1), today],
+        tomorrow: [addDays(today, 1), addDays(today, 2)],
+    };
+    if (fixed[p])
+        return { label: p, start: fixed[p][0], end: fixed[p][1] };
+    if (p === 'this week' || p === 'last week') {
+        // Weeks start Monday, which is what a working calendar means by "this week".
+        const dow = (today.getDay() + 6) % 7;
+        const monday = addDays(today, -dow);
+        const start = p === 'this week' ? monday : addDays(monday, -7);
+        return { label: p, start, end: addDays(start, 7) };
+    }
+    if (p === 'this month' || p === 'last month') {
+        const base = new Date(today.getFullYear(), today.getMonth() + (p === 'last month' ? -1 : 0), 1);
+        const end = new Date(base.getFullYear(), base.getMonth() + 1, 1);
+        return { label: p, start: base, end };
+    }
+    if (p === 'this quarter' || p === 'last quarter' || p === 'next quarter') {
+        /* Calendar quarters, from January, April, July and October: an App declares no fiscal year, so a quarter is the
+           calendar's. `Date` carries a month before January or after December into the year beside it. */
+        const shift = p === 'last quarter' ? -3 : p === 'next quarter' ? 3 : 0;
+        const start = new Date(today.getFullYear(), Math.floor(today.getMonth() / 3) * 3 + shift, 1);
+        return { label: p, start, end: new Date(start.getFullYear(), start.getMonth() + 3, 1) };
+    }
+    if (p === 'this year' || p === 'last year') {
+        const year = today.getFullYear() + (p === 'last year' ? -1 : 0);
+        return { label: p, start: new Date(year, 0, 1), end: new Date(year + 1, 0, 1) };
+    }
+    const span = p.match(/^(last|next|previous)\s+(\d+)\s+(minute|hour|day|week|month|year)s?$/);
+    if (span) {
+        const [, dir, amountRaw, unit] = span;
+        const amount = Number(amountRaw);
+        const past = dir === 'last';
+        /* `previous N` is the window immediately before `last N`, the same
+           length, ending where `last N` starts. It exists so a metric's
+           "previous period" compare is equal-span *by construction*: `last 30
+           days` runs from thirty days ago to tomorrow (31 calendar days, today
+           included), and any rewrite in terms of `last` was a day short. */
+        const previous = dir === 'previous';
+        /* A span of the clock, from the instant: `last 30 minutes` is an update just now, `next 2 hours` what falls due
+           before then. */
+        if (unit === 'hour' || unit === 'minute') {
+            const ms = amount * (unit === 'hour' ? 3600_000 : 60_000);
+            if (previous)
+                return { label: p, start: new Date(now.getTime() - 2 * ms), end: new Date(now.getTime() - ms) };
+            return past
+                ? { label: p, start: new Date(now.getTime() - ms), end: now }
+                : { label: p, start: now, end: new Date(now.getTime() + ms) };
+        }
+        const days = unit === 'week' ? amount * 7 : amount;
+        if (unit === 'month' || unit === 'year') {
+            /* Counted in calendar units rather than in days, so `last 3 months`
+               from the 31st lands on a date that exists and `last 1 year` from a
+               leap day does not drift. `Date` normalises an overflowing day of the
+               month, which is the behaviour wanted here: three months before the
+               31st of May is the 28th of February, not a date in March. */
+            const months = unit === 'year' ? amount * 12 : amount;
+            const other = new Date(today.getFullYear(), today.getMonth() + (past || previous ? -months : months), today.getDate());
+            if (previous) {
+                /* `last N months` is N months and a day (to tomorrow); the window
+                   before it is the same: N months back from its start, less a day. */
+                const start = new Date(other.getFullYear(), other.getMonth() - months, other.getDate() - 1);
+                return { label: p, start, end: other };
+            }
+            return past ? { label: p, start: other, end: addDays(today, 1) } : { label: p, start: today, end: other };
+        }
+        if (previous) {
+            const end = addDays(today, -days);
+            return { label: p, start: addDays(end, -(days + 1)), end };
+        }
+        return past
+            ? { label: p, start: addDays(today, -days), end: addDays(today, 1) }
+            : { label: p, start: today, end: addDays(today, days) };
+    }
+    return undefined;
+}

package/dist/shared/queryOperands.d.ts

@@ -0,0 +1,99 @@
+/**
+ * What a condition's right-hand side can stand for besides a literal: another
+ * column (`on_hand < product_id.reorder_level`) or the signed-in person
+ * (`owner_id = me`). Kept beside the query language rather than in it, since
+ * each is a judgement about two columns or a session the grammar itself never
+ * needs; query.ts asks these where a value would otherwise be read.
+ */
+import type { Condition, Op } from './filter.js';
+import { type ColumnKind, type ColumnMeta, type MachineStates, type TableMeta } from './schema.js';
+/**
+ * Who `me` is, for one request: the signed-in account, as the server's own
+ * session says. Absent from a parse, `me` is refused rather than read as the
+ * two letters, which made `owner != me` every row wherever a path forgot the
+ * person; `"me"` quoted is the word.
+ */
+export interface QueryPerson {
+    /** The account's email; null when nobody is signed in. */
+    email: string | null;
+    /** Signed in, with an email not yet proven where anyone may sign up: someone, and no one's `me` (appMe.ts unprovenPerson). */
+    unproven?: true;
+    /**
+     * Nobody in particular: a catalog asking whether a segment reads at all, before
+     * any request (appSegments.ts servedSegments). `me` and `me.<table>.<column>` are
+     * read as no one's, so a segment about the person is judged by the rest of what it says.
+     */
+    anyone?: true;
+    /**
+     * The table people are rows of (an App's `auth.me`), and the signed-in
+     * account's row key there — null when no row carries their email, which
+     * then matches nothing rather than failing the list.
+     */
+    person?: {
+        table: string;
+        key: string | number | null;
+    };
+    /**
+     * `me.<table>.<column>` in a value list, by `table.column`:
+     * the values of `column` in the rows of `table` that point at the person —
+     * their teams, their territories — read for this request through its own
+     * reader, so a row its grants, row policy or tenant hide is none of them;
+     * or why they cannot be read.
+     */
+    sets?: Readonly<Record<string, MeSet>>;
+}
+/** Nobody in particular (`anyone` above): what a check that runs before any request reads `me` as. */
+export declare const ANYONE: QueryPerson;
+/** One `me.<table>.<column>`: its values and their kind, or the sentence that refuses it. */
+export type MeSet = {
+    values: readonly (string | number)[];
+    kind: ColumnKind;
+} | {
+    error: string;
+};
+/** `me.<table>.<column>`, written as one item of a value list. */
+export declare const ME_SET: RegExp;
+export interface CompileContext {
+    table: TableMeta | undefined;
+    now: Date;
+    /** Admit a column on the right-hand side (a view's compiler resolves it). */
+    columnValues: boolean;
+    me?: QueryPerson | null;
+    /** A machine's states by column, where the catalog does not carry them (a parse with no schema). */
+    states?: Readonly<Record<string, MachineStates>>;
+}
+/**
+ * The column an unquoted right-hand side names, when it names one.
+ *
+ * A reference path always does, on any column: no value is spelled
+ * `product_id.reorder_level`, and reading it as text was a comparison
+ * between a number and a word that SQLite answers "less" for every row. A
+ * bare word does only beside a number, date or flag, which it could never
+ * be the value of; beside text, `source = email` is the value "email" even
+ * where the table has an `email` column, because that is what a status tab
+ * means by it. Quoted, it is text everywhere.
+ */
+export declare function columnOperand(ctx: CompileContext, left: ColumnMeta | undefined, op: Op, value: string): {
+    other?: ColumnMeta;
+    error?: string;
+};
+/**
+ * What `me.<table>.<column>` stands for in a value list beside one column:
+ * the values read for this request, of the column's own kind. An empty set
+ * leaves the list holding nothing of the person's, which matches nothing.
+ */
+export declare function meSetOperand(ctx: CompileContext, column: ColumnMeta | undefined, word: string): {
+    values?: (string | number)[];
+    error?: string;
+};
+/**
+ * What `me` stands for beside one column: the person's row key where the
+ * column points at the table people are rows of (or is that table's key),
+ * their email where it holds text. Anything else is refused by name —
+ * comparing a date with an email is the silent empty tab this exists to stop.
+ */
+export declare function meOperand(ctx: CompileContext, column: ColumnMeta | undefined, op: Op): {
+    value?: string | number;
+    conditions?: Condition[];
+    error?: string;
+};

package/dist/shared/queryOperands.js

@@ -0,0 +1,131 @@
+import { columnKind } from './schema.js';
+/** Nobody in particular (`anyone` above): what a check that runs before any request reads `me` as. */
+export const ANYONE = Object.freeze({ email: null, anyone: true });
+/** `me.<table>.<column>`, written as one item of a value list. */
+export const ME_SET = /^me\.([A-Za-z_]\w*)\.([A-Za-z_]\w*)$/;
+const COMPARISON_OPS = new Set(['=', '!=', '<', '<=', '>', '>=']);
+const BARE_WORD = /^[A-Za-z_$][\w$]*$/;
+const PATH_WORD = /^[A-Za-z_$][\w$+]*(?:\.[A-Za-z_$][\w$+]*)+$/;
+/**
+ * The column an unquoted right-hand side names, when it names one.
+ *
+ * A reference path always does, on any column: no value is spelled
+ * `product_id.reorder_level`, and reading it as text was a comparison
+ * between a number and a word that SQLite answers "less" for every row. A
+ * bare word does only beside a number, date or flag, which it could never
+ * be the value of; beside text, `source = email` is the value "email" even
+ * where the table has an `email` column, because that is what a status tab
+ * means by it. Quoted, it is text everywhere.
+ */
+export function columnOperand(ctx, left, op, value) {
+    const table = ctx.table;
+    if (!table)
+        return {};
+    const path = PATH_WORD.test(value);
+    if (!path && !BARE_WORD.test(value))
+        return {};
+    const named = table.columns.find((c) => c.name === value);
+    if (!path) {
+        const kind = left ? columnKind(left.type) : 'other';
+        if (!named || kind === 'text' || kind === 'other')
+            return {};
+    }
+    else if (!named) {
+        /* A dotted word whose first hop is a column is a path that did not
+           resolve here — in a plain query because paths need a view, in a view
+           because it goes nowhere (the view parser reports which). */
+        if (!table.columns.some((c) => c.name === value.split('.')[0].split('+')[0]))
+            return {};
+        return {
+            error: `"${value}" is a path, and a condition here compares ${table.name}'s own columns with a value. Quote it ("${value}") to mean the text.`,
+        };
+    }
+    if (!ctx.columnValues) {
+        return {
+            error: `"${value}" is a column, and a condition here compares a column with a value. Quote it ("${value}") to mean the text.`,
+        };
+    }
+    if (!COMPARISON_OPS.has(op))
+        return { error: `"${value}" is a column; compare it with =, !=, <, <=, > or >=.` };
+    const a = left ? columnKind(left.type) : 'other';
+    const b = columnKind(named.type);
+    if (a !== 'other' && b !== 'other' && a !== b) {
+        return {
+            error: `"${left.name}" is ${left.type || 'untyped'} and "${value}" is ${named.type || 'untyped'}, so comparing them says nothing. Compare columns of one kind.`,
+        };
+    }
+    return { other: named };
+}
+/**
+ * What `me.<table>.<column>` stands for in a value list beside one column:
+ * the values read for this request, of the column's own kind. An empty set
+ * leaves the list holding nothing of the person's, which matches nothing.
+ */
+export function meSetOperand(ctx, column, word) {
+    const me = ctx.me ?? { email: null };
+    if (me.anyone)
+        return { values: [] };
+    if (me.email === null && !me.unproven)
+        return { error: 'me is the signed-in person, and nobody is signed in.' };
+    const set = me.sets?.[word.slice(3)];
+    if (!set)
+        return { error: `${word} is read only where a request names the signed-in person: a list, a tab, a count or an export of an App.` };
+    if ('error' in set)
+        return { error: set.error };
+    const kind = column ? columnKind(column.type) : 'other';
+    if (kind !== 'other' && set.kind !== 'other' && kind !== set.kind)
+        return {
+            error: `"${column.name}" is ${column.type || 'untyped'}, and ${word} holds ${set.kind} values, so comparing them says nothing.`,
+        };
+    return { values: [...set.values] };
+}
+/**
+ * What `me` stands for beside one column: the person's row key where the
+ * column points at the table people are rows of (or is that table's key),
+ * their email where it holds text. Anything else is refused by name —
+ * comparing a date with an email is the silent empty tab this exists to stop.
+ */
+export function meOperand(ctx, column, op) {
+    const me = ctx.me ?? { email: null };
+    /* Anyone's, for a check before any request: the word, which every column takes. */
+    if (me.anyone)
+        return { value: 'me' };
+    const table = ctx.table;
+    const name = column?.name ?? 'this column';
+    const person = me.person;
+    const points = person && column && (column.references?.table === person.table || (table?.id === person.table && column.primaryKey));
+    /* Signed in, but nothing they said is proven: nothing is theirs. As for a person without a row. */
+    const nothing = () => op === '='
+        ? { conditions: [{ column: name, op: 'in', value: [] }] }
+        : op === '!='
+            ? { conditions: [{ column: name, op: 'isNotNull' }] }
+            : { error: `me is compared with ${name} by = or != only.` };
+    if (points) {
+        if (me.email === null)
+            return me.unproven ? nothing() : { error: 'me is the signed-in person, and nobody is signed in.' };
+        if (person.key !== null)
+            return { value: person.key };
+        /* Signed in, but no row carries the email: nothing is theirs. Said as
+           conditions the builder already speaks, so no engine binds a null. */
+        if (op === '=')
+            return { conditions: [{ column: name, op: 'in', value: [] }] };
+        if (op === '!=')
+            return { conditions: [{ column: name, op: 'isNotNull' }] };
+        return { error: `me is compared with ${name} by = or != only.` };
+    }
+    if (column?.references) {
+        return {
+            error: person
+                ? `"${name}" references ${column.references.table}, and me is a row of ${person.table} or the signed-in account's email. Compare a column that points at ${person.table}, or a text column like ${name}.email.`
+                : `"${name}" references ${column.references.table}, and me is the signed-in account's email. Say which table people are rows of — auth: { me: { from: '${column.references.table}', column: 'email' } } — or compare a text column (${name}.email = me).`,
+        };
+    }
+    if (column && columnKind(column.type) !== 'text') {
+        return {
+            error: `"${name}" is ${column.type || 'untyped'}, and me is the signed-in account's email${person ? ` or their ${person.table} row` : ''}, which only a text column${person ? ' or a reference to it' : ''} holds.`,
+        };
+    }
+    if (me.email === null)
+        return me.unproven ? nothing() : { error: 'me is the signed-in person, and nobody is signed in.' };
+    return { value: me.email };
+}

package/dist/shared/reads.d.ts

@@ -0,0 +1,103 @@
+import { type Filter, type SqlStyle } from './filter.js';
+/** What a caller gets when it does not say. Small on purpose: the first page
+    of a browse should be instant, and paging is one click. */
+export declare const DEFAULT_LIMIT = 20;
+/** The hard ceiling. Nothing may exceed it, including an explicit request. */
+export declare const MAX_LIMIT = 100000;
+/** The most rows one read answers for a table its reader may not export: the largest a screen reads (a tree list,
+    read whole, is 2,000), so the list is never the way round an export grant (resourceReadHttp.ts). */
+export declare const UNEXPORTED_MOST = 2000;
+/**
+ * Above this many rows, an exact count is not worth what it costs.
+ *
+ * `COUNT(*)` is a scan. On a table of a few thousand rows that is free and the
+ * exact number is strictly better; on a table of fifty million it is seconds of
+ * work to compute a number that is stale before it is rendered, and it runs on
+ * *every* query — the header stat is not something anyone asked for.
+ *
+ * The threshold is deliberately well above anything a person would notice the
+ * difference on. Below it you get the true number; above it you get the
+ * catalog's estimate and are told that is what it is.
+ */
+export declare const ESTIMATE_ABOVE = 50000;
+/** A row count, and whether it is the real one. */
+export interface CountResult {
+    count: number;
+    /** False when this came from the catalog's statistics rather than a scan. */
+    exact: boolean;
+    /** Only when a bounded count stopped: `count` is the bound, and more rows match. */
+    capped?: true;
+}
+/**
+ * A count over one relation and its WHERE clause, optionally stopped.
+ *
+ * With `limit`, the inner SELECT reads at most that many matching rows, so
+ * "how many, up to ten thousand" costs ten thousand rows however large the
+ * table is. The relation and WHERE are the caller's own and unchanged: the
+ * bound wraps the plan that already carries the row scope and the filter,
+ * it never builds a second one. Without a limit the text is the plain
+ * COUNT(*) it always was.
+ *
+ * The bound is written as digits, not bound as a parameter: it is an integer
+ * checked here, and one statement shape then serves both drivers and the
+ * scoped compiler — a driver may send a bound number as a DOUBLE, which
+ * `LIMIT` refuses, and the scoped compiler does not know its driver.
+ */
+export declare function countStatement(relation: string, limit?: number): string;
+/** Most counts one statement answers: a list's tabs, a record's references. */
+export declare const COUNT_EACH_MAX = 64;
+/** The most a menu row counts (`countLimit`); past it the row says 10,000+ (client navCounts.ts, and a first page's counts, server/http/firstPaintRooms.ts). */
+export declare const NAV_COUNT_LIMIT = 10000;
+/** One count of a `countEach`: a relation the adapter has already checked
+    against its catalog and quoted, and the filter over it. */
+interface CountEachItem {
+    relation: string;
+    filter?: Filter;
+}
+/**
+ * Several counts in one statement, each as `countStatement` would say it.
+ *
+ * Two shapes, both one round trip and one plan:
+ *
+ * - `together`: every item reads one relation and the caller knows that
+ *   relation is small (at most the bound, by the catalog's figure). One scan
+ *   answers them all, a conditional aggregate each — `COUNT(*) FILTER
+ *   (WHERE …)` on Postgres, `COUNT(CASE WHEN … THEN 1 END)` elsewhere — and
+ *   no count can pass the bound by much, so none needs one.
+ * - otherwise, one bounded count per item joined by UNION ALL, each tagged
+ *   with its position: a large table stops each scan at the bound instead of
+ *   reading every row once for every tab.
+ *
+ * Rows come back as `{ i, n }` in either shape; `countEachRows` reads them.
+ */
+export declare function countEachStatement(items: readonly CountEachItem[], style: SqlStyle, options?: {
+    limit?: number;
+    together?: boolean;
+}): {
+    text: string;
+    params: unknown[];
+};
+/** The counts a `countEachStatement` answered, in the items' order. */
+export declare function countEachRows(rows: readonly Record<string, unknown>[], length: number): number[];
+export declare function clampLimit(value: unknown, fallback?: number): number;
+/** Offsets have no ceiling but must be a real, non-negative integer. */
+export declare function clampOffset(value: unknown): number;
+export interface QueryResult {
+    columns: string[];
+    /** Values as returned by the driver, JSON-safe. */
+    rows: Array<Record<string, unknown>>;
+    /** Milliseconds the database took, for the "is this slow" question. */
+    ms: number;
+    /**
+     * The SQL that ran, with parameters shown separately.
+     *
+     * Surfaced deliberately: a tool that hides its query teaches nothing and
+     * cannot be trusted when the numbers look wrong. Seeing the statement is
+     * how you learn the database as well as read it.
+     */
+    sql: {
+        text: string;
+        params: unknown[];
+    };
+}
+export {};

package/dist/shared/reads.js

@@ -0,0 +1,154 @@
+/*
+ * The read contract both sides of the wire share: how many rows one read may
+ * return, how a count is bounded, and what a read answers. The adapters
+ * enforce it; the query language and the client page and export by the same
+ * numbers.
+ */
+import { Refusal } from './refusal.js';
+import { buildWhere } from './filter.js';
+/* ---------- the limit policy ----------
+
+   One place, because a ceiling re-derived in four files is a ceiling that
+   disagrees with itself. Every read goes through `clampLimit`, so there is no
+   path to an unbounded query: a caller that omits a limit gets the default, a
+   caller that asks for too many gets the ceiling, and a caller that sends
+   nonsense gets the default rather than `LIMIT NaN`. */
+/** What a caller gets when it does not say. Small on purpose: the first page
+    of a browse should be instant, and paging is one click. */
+export const DEFAULT_LIMIT = 20;
+/** The hard ceiling. Nothing may exceed it, including an explicit request. */
+export const MAX_LIMIT = 100_000;
+/** The most rows one read answers for a table its reader may not export: the largest a screen reads (a tree list,
+    read whole, is 2,000), so the list is never the way round an export grant (resourceReadHttp.ts). */
+export const UNEXPORTED_MOST = 2_000;
+/**
+ * Above this many rows, an exact count is not worth what it costs.
+ *
+ * `COUNT(*)` is a scan. On a table of a few thousand rows that is free and the
+ * exact number is strictly better; on a table of fifty million it is seconds of
+ * work to compute a number that is stale before it is rendered, and it runs on
+ * *every* query — the header stat is not something anyone asked for.
+ *
+ * The threshold is deliberately well above anything a person would notice the
+ * difference on. Below it you get the true number; above it you get the
+ * catalog's estimate and are told that is what it is.
+ */
+export const ESTIMATE_ABOVE = 50_000;
+/**
+ * A count over one relation and its WHERE clause, optionally stopped.
+ *
+ * With `limit`, the inner SELECT reads at most that many matching rows, so
+ * "how many, up to ten thousand" costs ten thousand rows however large the
+ * table is. The relation and WHERE are the caller's own and unchanged: the
+ * bound wraps the plan that already carries the row scope and the filter,
+ * it never builds a second one. Without a limit the text is the plain
+ * COUNT(*) it always was.
+ *
+ * The bound is written as digits, not bound as a parameter: it is an integer
+ * checked here, and one statement shape then serves both drivers and the
+ * scoped compiler — a driver may send a bound number as a DOUBLE, which
+ * `LIMIT` refuses, and the scoped compiler does not know its driver.
+ */
+export function countStatement(relation, limit) {
+    if (limit === undefined)
+        return `SELECT COUNT(*) AS n FROM ${relation}`;
+    checkBound(limit);
+    return `SELECT COUNT(*) AS n FROM (SELECT 1 AS one FROM ${relation} LIMIT ${limit}) AS bounded`;
+}
+function checkBound(limit) {
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new Refusal('A count bound must be a positive whole number.');
+}
+/** Most counts one statement answers: a list's tabs, a record's references. */
+export const COUNT_EACH_MAX = 64;
+/** The most a menu row counts (`countLimit`); past it the row says 10,000+ (client navCounts.ts, and a first page's counts, server/http/firstPaintRooms.ts). */
+export const NAV_COUNT_LIMIT = 10_000;
+/**
+ * Several counts in one statement, each as `countStatement` would say it.
+ *
+ * Two shapes, both one round trip and one plan:
+ *
+ * - `together`: every item reads one relation and the caller knows that
+ *   relation is small (at most the bound, by the catalog's figure). One scan
+ *   answers them all, a conditional aggregate each — `COUNT(*) FILTER
+ *   (WHERE …)` on Postgres, `COUNT(CASE WHEN … THEN 1 END)` elsewhere — and
+ *   no count can pass the bound by much, so none needs one.
+ * - otherwise, one bounded count per item joined by UNION ALL, each tagged
+ *   with its position: a large table stops each scan at the bound instead of
+ *   reading every row once for every tab.
+ *
+ * Rows come back as `{ i, n }` in either shape; `countEachRows` reads them.
+ */
+export function countEachStatement(items, style, options = {}) {
+    if (!items.length || items.length > COUNT_EACH_MAX)
+        throw new Refusal(`One statement counts 1 to ${COUNT_EACH_MAX} things.`);
+    const { limit, together = false } = options;
+    if (limit !== undefined)
+        checkBound(limit);
+    const params = [];
+    if (together && items.every((item) => item.relation === items[0].relation)) {
+        const measures = items.map((item, i) => {
+            const where = buildWhere(item.filter, style, params.length + 1);
+            params.push(...where.params);
+            const predicate = where.text.replace(/^ WHERE /, '');
+            const measure = predicate ? (style.countWhere?.(predicate) ?? `COUNT(CASE WHEN ${predicate} THEN 1 END)`) : 'COUNT(*)';
+            return `${measure} AS ${style.quote(`n${i}`)}`;
+        });
+        return { text: `SELECT ${measures.join(', ')} FROM ${items[0].relation}`, params };
+    }
+    const branches = items.map((item, i) => {
+        const where = buildWhere(item.filter, style, params.length + 1);
+        params.push(...where.params);
+        const counted = limit === undefined
+            ? `${item.relation}${where.text}`
+            : `(SELECT 1 AS one FROM ${item.relation}${where.text} LIMIT ${limit}) AS ${style.quote(`c${i}`)}`;
+        return `SELECT ${i} AS i, COUNT(*) AS n FROM ${counted}`;
+    });
+    return { text: branches.join('\nUNION ALL\n'), params };
+}
+/** The counts a `countEachStatement` answered, in the items' order. */
+export function countEachRows(rows, length) {
+    const counts = Array.from({ length }, () => 0);
+    if (rows.length === 1 && !('i' in rows[0])) {
+        for (let i = 0; i < length; i++)
+            counts[i] = Number(rows[0][`n${i}`] ?? 0);
+        return counts;
+    }
+    for (const row of rows) {
+        const i = Number(row.i);
+        if (Number.isInteger(i) && i >= 0 && i < length)
+            counts[i] = Number(row.n ?? 0);
+    }
+    return counts;
+}
+/**
+ * Only a number or a numeric string counts as a request. Everything else —
+ * undefined, null, '', [], {}, 'abc' — means "not specified" and gets the
+ * default.
+ *
+ * The `null` case is why this cannot just be `Number(value)`: `Number(null)`
+ * is 0, not NaN, so a null limit passed a finite check and clamped to 1. A
+ * caller that omitted a limit would have got a single row and no error.
+ */
+function asNumber(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+export function clampLimit(value, fallback = DEFAULT_LIMIT) {
+    const n = asNumber(value);
+    if (n === undefined)
+        return fallback;
+    return Math.min(Math.max(Math.floor(n), 1), MAX_LIMIT);
+}
+/** Offsets have no ceiling but must be a real, non-negative integer. */
+export function clampOffset(value) {
+    const n = asNumber(value);
+    if (n === undefined || n < 0)
+        return 0;
+    return Math.floor(n);
+}

package/dist/shared/recordLabel.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 declare const LABEL_SEGMENT = "$label";
+type LabelPart = {
+    text: string;
+} | {
+    path: string;
+    mask?: {
+        prefix?: string;
+    };
+    words?: Record<string, string>;
+};
+/** Whether an authored record label is a template rather than a path. */
+export declare const isLabelTemplate: (text: unknown) => text is string;
+/** The prefix a `$label` path hangs off ('' for the base's own), or undefined for any other path. */
+export declare function labelPrefix(path: string): string | undefined;
+/** A template's parts, or why it is not one. */
+export declare function parseLabelTemplate(template: string): {
+    parts: LabelPart[];
+    paths: string[];
+} | {
+    problem: string;
+};
+/** A template field for a path whose stored values are said as words, as the server writes it into a served template. */
+export declare const wordedField: (path: string, words: Record<string, string>) => string;
+/** A template field for a masked path, as the server writes it into a served template. */
+export declare const maskedField: (path: string, prefix?: string) => string;
+/** Whether an authored template writes a mask itself: that is the column's display rule's to say. */
+export declare const writesMask: (template: string) => boolean;
+/**
+ * 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 declare function nounTemplate(noun: string, key: string): string;
+export {};