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

package/dist/shared/autoBucket.js

@@ -0,0 +1,305 @@
+/**
+ * The time unit a chart cuts its dates into when its author did not fix one: `chart('Signups', 'account', 'auto
+ * created_at', { over: 'created_at' })`.
+ *
+ * A fixed unit is right for one window and wrong for the next: `day` over 34 days with three days of data drew 34
+ * bars, 31 of them empty, and `day` over a year draws 365. The right unit depends on the window the reader picks and
+ * on how the data falls, so `auto` is decided where both are known, on the client, before the read. It is not a SQL
+ * bucket: the server never sees the word (`withUnit` writes the unit in), and the grammar's `DATE_UNITS` is unchanged.
+ *
+ * Two rules choose the unit, both pure so a table of cases can hold them:
+ *  1. The span picks a base unit: up to 45 days a day, up to 26 weeks a week, up to 36 months a month, past that a
+ *     quarter.
+ *  2. Where the measure can be added up again (count, sum, min, max, avg as sum over count, and arithmetic of those),
+ *     the base answer is coarsened locally while fewer than a third of its buckets hold data, as long as at least four
+ *     buckets would remain. No second read. A median cannot be added up from its parts, so it follows the span only.
+ */
+import { dateWindow } from './queryDates.js';
+/** Finest to coarsest: the order a sparse chart steps up through. */
+const AUTO_UNITS = ['day', 'week', 'month', 'quarter'];
+/** A bucket needs a third of its periods to hold data before the chart is left at the unit the span chose. */
+const DENSE = 1 / 3;
+/** Stepping up stops before the chart is left with fewer buckets than this. */
+const FEWEST_BUCKETS = 4;
+/* ---------- the word in a `by` ---------- */
+const AUTO_KEY = /^auto\s+([\w.$+]+)(\s+as\s+[\w$]+)?$/i;
+/** The key of a `by` written `auto <column>`, wherever it stands in the list: its place and its column. */
+export function autoKeyOf(by) {
+    const keys = (by ?? '').split(',');
+    for (const [index, key] of keys.entries()) {
+        const m = AUTO_KEY.exec(key.trim());
+        if (m)
+            return { index, column: m[1] };
+    }
+    return null;
+}
+/** The `by` with its `auto` key written as the unit the chart chose, which is the word the grammar reads. */
+export function withUnit(by, unit) {
+    const at = autoKeyOf(by);
+    if (!at)
+        return by;
+    return by
+        .split(',')
+        .map((key, index) => (index === at.index ? key.trim().replace(/^auto/i, unit) : key.trim()))
+        .join(', ');
+}
+/* ---------- the span ---------- */
+const DAY = 86_400_000;
+/**
+ * The days a section's query asks about on its `over` column — `created_at = last 90 days`, `this month` — or null
+ * where it sets no window the date grammar can bound (the data's own extent is then the span).
+ */
+export function spanDaysOf(query, over, now) {
+    const phrase = windowPhraseOf(query, over);
+    const window = phrase ? dateWindow(phrase, now) : undefined;
+    return window ? Math.max(1, Math.round((window.end.getTime() - window.start.getTime()) / DAY)) : null;
+}
+/** The phrase a query windows its `over` column by — `last 90 days` in `due_on = last 90 days` — or null. */
+export function windowPhraseOf(query, over) {
+    if (!query || !over)
+        return null;
+    const escaped = over.replace(/[.$+]/g, '\\$&');
+    const found = new RegExp(`(?:^|[\\s(])${escaped}\\s*=\\s*(.+?)(?=\\s+(?:and|or)\\b|\\)|$)`, 'i').exec(query);
+    return found ? found[1].trim() : null;
+}
+/** The days between two dates the data holds, both ends counted. Null where either is not a date. */
+export function spanDaysBetween(min, max) {
+    const from = dayNumber(String(min ?? '').slice(0, 10));
+    const to = dayNumber(String(max ?? '').slice(0, 10));
+    return from === null || to === null || to < from ? null : to - from + 1;
+}
+/** The unit a span of this many days is drawn in, before the data is looked at. */
+export function unitForSpan(days) {
+    if (days <= 45)
+        return 'day';
+    if (days <= 26 * 7)
+        return 'week';
+    if (days <= 36 * 30.4375)
+        return 'month';
+    return 'quarter';
+}
+/**
+ * The unit the read asks the server for. Where the measure adds up again, a day or a week is read as days and
+ * bucketed here: a week crosses a month's edge, so weeks read from the server could not be coarsened into months
+ * without handing a whole week to one of them. Months and quarters nest, so those are read as they are drawn.
+ */
+export function readUnit(base, addsUp) {
+    return addsUp && (base === 'day' || base === 'week') ? 'day' : base;
+}
+/* ---------- periods, by their labels ---------- */
+const pad = (n) => String(n).padStart(2, '0');
+function dayNumber(key) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(key);
+    return m ? Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])) / DAY : null;
+}
+const dayKey = (n) => {
+    const d = new Date(n * DAY);
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+};
+/** The label of the period a day, month or quarter label falls in, spelled as the server spells it. */
+export function bucketKey(key, unit, weekStart = 1) {
+    if (unit === 'day')
+        return key;
+    if (unit === 'week') {
+        const n = dayNumber(key);
+        if (n === null)
+            return key;
+        /* ISO weekday 1..7; a day is that many days past its week's first. */
+        const weekday = ((new Date(n * DAY).getUTCDay() + 6) % 7) + 1;
+        return dayKey(n - ((weekday - weekStart + 7) % 7));
+    }
+    const month = Number(key.slice(5, 7));
+    if (unit === 'month')
+        return key.slice(0, 7);
+    return /Q[1-4]$/.test(key) ? key : `${key.slice(0, 4)}-Q${Math.ceil(month / 3)}`;
+}
+function nextKey(key, unit) {
+    if (unit === 'day' || unit === 'week')
+        return dayKey((dayNumber(key) ?? 0) + (unit === 'week' ? 7 : 1));
+    if (unit === 'month') {
+        const [y, m] = [Number(key.slice(0, 4)), Number(key.slice(5, 7))];
+        return m === 12 ? `${y + 1}-01` : `${y}-${pad(m + 1)}`;
+    }
+    const [y, q] = [Number(key.slice(0, 4)), Number(key.slice(6))];
+    return q === 4 ? `${y + 1}-Q1` : `${y}-Q${q + 1}`;
+}
+const SPELLED = {
+    day: /^\d{4}-\d{2}-\d{2}$/,
+    week: /^\d{4}-\d{2}-\d{2}$/,
+    month: /^\d{4}-\d{2}$/,
+    quarter: /^\d{4}-Q[1-4]$/,
+};
+/** The local calendar day of a date, as the server spells a day. */
+const localDay = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+/**
+ * A trend's points over its window: the periods that held no rows put back as zero, from the window's first period
+ * to today's, and the read periods added up into the unit the span is drawn in. A count of nothing is 0, and a line
+ * drawn through only the days that had rows said a quiet week was a steady one; three busy days of a week drew no
+ * line at all. Only a count or a sum adds up so: any other measure's points are drawn as read, and labels the read
+ * unit does not spell are left as they came.
+ */
+export function trendPoints(rows, read, unit, measure, window, now) {
+    if (!/^(count|sum\s+[\w.$+]+)(\s+as\s+[\w$]+)?$/i.test((measure ?? 'count').trim()))
+        return [...rows];
+    const keys = rows.map((row) => String(row.key ?? ''));
+    if (keys.some((key) => !SPELLED[read].test(key)))
+        return [...rows];
+    const ends = window ? [window.start, new Date(Math.min(window.end.getTime() - 1, now.getTime()))] : [];
+    const sorted = [...keys, ...ends.map((d) => bucketKey(localDay(d), read))].sort();
+    if (!sorted.length)
+        return [...rows];
+    const held = new Map(rows.map((row) => [String(row.key), Number(row.value) || 0]));
+    const into = new Map();
+    for (let key = sorted[0], n = 0; key <= sorted[sorted.length - 1] && n < 5000; key = nextKey(key, read), n++) {
+        const label = bucketKey(key, unit);
+        into.set(label, (into.get(label) ?? 0) + (held.get(key) ?? 0));
+    }
+    return [...into].map(([key, value]) => ({ key, value }));
+}
+/** How many periods of the unit run from the first label to the last, both ends counted. */
+function periodsBetween(first, last, unit) {
+    let count = 1;
+    for (let key = first; key < last && count < 5000; key = nextKey(key, unit))
+        count++;
+    return count;
+}
+/**
+ * The unit a chart is drawn in: the span's, stepped up while the data is sparse in it.
+ *
+ * `keys` are the labels of the buckets that hold data, as read (days, or months or quarters, per `readUnit`).
+ * `addsUp` is whether the measure can be re-aggregated; without it the span alone decides.
+ */
+export function chooseUnit({ spanDays, base: given, keys, addsUp, weekStart = 1, }) {
+    const base = given ?? unitForSpan(spanDays ?? 0);
+    if (!addsUp || !keys.length || base === 'quarter')
+        return { base, unit: base };
+    const at = (unit) => {
+        const labels = [...new Set(keys.map((k) => bucketKey(k, unit, weekStart)))].sort();
+        return { filled: labels.length, total: periodsBetween(labels[0], labels[labels.length - 1], unit) };
+    };
+    let unit = base;
+    for (;;) {
+        const here = at(unit);
+        if (here.filled / here.total >= DENSE)
+            break;
+        const next = AUTO_UNITS[AUTO_UNITS.indexOf(unit) + 1];
+        if (!next || at(next).total < FEWEST_BUCKETS)
+            break;
+        unit = next;
+    }
+    return { base, unit };
+}
+const TERM = /^(count|sum|avg|min|max)\s*([\w.$+]+)?$/i;
+/**
+ * A measure as the aggregates it is made of, or null where it cannot be added up again: a median, a distinct
+ * count, a `when` count, or words this does not read. `avg x` is `sum x` over `count x`, which can.
+ */
+export function planMeasure(measure) {
+    const text = (measure ?? 'count').replace(/\s+as\s+[\w$]+\s*$/i, '').trim();
+    if (/\b(distinct|when|median)\b|[,[\]()]/i.test(text))
+        return null;
+    const parts = text.split(/\s+([+\-*/])\s+/);
+    const reads = [];
+    const combine = [];
+    const read = (aggregate, how) => {
+        const at = reads.indexOf(aggregate);
+        if (at >= 0)
+            return at;
+        reads.push(aggregate);
+        combine.push(how);
+        return reads.length - 1;
+    };
+    const operands = [];
+    for (let i = 0; i < parts.length; i += 2) {
+        const part = parts[i].trim();
+        if (/^\d+(?:\.\d+)?$/.test(part)) {
+            operands.push({ number: Number(part) });
+            continue;
+        }
+        const m = TERM.exec(part);
+        if (!m)
+            return null;
+        const fn = m[1].toLowerCase();
+        const column = m[2];
+        if (fn !== 'count' && !column)
+            return null;
+        if (fn === 'avg')
+            operands.push({ ratio: [read(`sum ${column}`, 'add'), read(`count ${column}`, 'add')] });
+        else
+            operands.push({ term: read(column ? `${fn} ${column}` : fn, fn === 'min' ? 'min' : fn === 'max' ? 'max' : 'add') });
+    }
+    const ops = parts.filter((_, i) => i % 2 === 1);
+    const value = (terms) => {
+        const values = operands.map((o) => {
+            if ('number' in o)
+                return o.number;
+            if ('term' in o)
+                return terms[o.term];
+            const [sum, count] = [terms[o.ratio[0]], terms[o.ratio[1]]];
+            return sum === null || !count ? null : sum / count;
+        });
+        /* SQL's precedence: `*` and `/` bind first; a division by zero is null, as the server's is. */
+        const sums = [values[0]];
+        const signs = [];
+        for (const [i, op] of ops.entries()) {
+            const right = values[i + 1];
+            const left = sums[sums.length - 1];
+            if (op === '*' || op === '/') {
+                sums[sums.length - 1] =
+                    left === null || right === null || (op === '/' && right === 0) ? null : op === '*' ? left * right : left / right;
+            }
+            else {
+                sums.push(right);
+                signs.push(op);
+            }
+        }
+        return sums.reduce((acc, v, i) => {
+            if (i === 0)
+                return v;
+            return acc === null || v === null ? null : signs[i - 1] === '+' ? acc + v : acc - v;
+        }, sums[0] === undefined ? null : sums[0]);
+    };
+    return { reads, combine, value };
+}
+/** The read buckets cut into the chosen unit, each aggregate added up (or min'd, or max'd) across the ones it takes in. */
+export function coarsen(buckets, plan, unit, weekStart = 1) {
+    /* A chart over a second key (a line or a stack per value) is coarsened per value: a cross is the period and the series. */
+    const into = new Map();
+    const SPLIT = '\u0000';
+    for (const bucket of buckets) {
+        const key = `${bucketKey(bucket.key, unit, weekStart)}${bucket.series === undefined ? '' : SPLIT + bucket.series}`;
+        const held = into.get(key);
+        if (!held) {
+            into.set(key, [...bucket.terms]);
+            continue;
+        }
+        plan.combine.forEach((how, i) => {
+            const [a, b] = [held[i], bucket.terms[i]];
+            held[i] = a === null ? b : b === null ? a : how === 'add' ? a + b : how === 'min' ? Math.min(a, b) : Math.max(a, b);
+        });
+    }
+    return [...into.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .flatMap(([joined, terms]) => {
+        const value = plan.value(terms);
+        const [key, series] = joined.split(SPLIT);
+        return value === null || !Number.isFinite(value) ? [] : [{ key, ...(series === undefined ? {} : { series }), value }];
+    });
+}
+/* ---------- what a section asks, for the check ---------- */
+/** The most days a window may span before a fixed `day` chart over it is worth a word. */
+export const DAY_BARS_ADVISED = 90;
+/**
+ * The days a dashboard window phrase covers, as it would be said ("last 12 months" is 365): the nominal length of a
+ * `last N unit`, else the dates the phrase resolves to, or null where it is not one the date grammar bounds. (A
+ * resolved `last N` runs to tomorrow, a day more than it is called, which a count of bars should not repeat.)
+ */
+export function windowDays(phrase, now) {
+    const last = /^last\s+(\d+)\s+(day|week|month|year)s?$/i.exec(phrase.trim());
+    if (last)
+        return Math.round(Number(last[1]) * { day: 1, week: 7, month: 365 / 12, year: 365 }[last[2].toLowerCase()]);
+    const window = dateWindow(phrase, now);
+    return window ? Math.round((window.end.getTime() - window.start.getTime()) / DAY) : null;
+}
+/** Whether a chart's `by` cuts days: `day created_at`, in any position. */
+export const cutsDays = (by) => (by ?? '').split(',').some((key) => /^day\s+[\w.$+]+/i.test(key.trim()));

package/dist/shared/autoValues.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The values a form or a fixed action fills in rather than states: the day
+ * (`today`), the moment (`now`) and the signed-in person (`me`). They are
+ * written as the constants `@mistriwork/mistri/app` exports — `defaults: { due_on:
+ * today, owner_id: me }`, `set: { resolved_at: now }` — which are
+ * `{ auto: 'today' }` and so on in JSON, so a word can never be read out of
+ * a literal: a status of "now" is not the moment, and a text column's "me"
+ * is not an email.
+ *
+ * The model carries the word, as it always has (formDefaults.ts in the
+ * client, appStamps.ts on the server read it), so the word itself is
+ * reserved there: a literal that spells one is refused here, since past
+ * this point it would be read as the value filled in.
+ */
+type AutoWord = 'today' | 'now' | 'me';
+/**
+ * An authored default or `set` value, as the model carries it: a filled-in
+ * value becomes its word, and a literal passes through. `words` are the ones
+ * this place fills in — a fixed action writes `now` and `me`, a form also
+ * `today`.
+ */
+export declare function authoredValue(value: unknown, at: string, words?: readonly AutoWord[]): unknown;
+/** The authored spelling of a model value: its word back as `{ auto }`, any other value as itself. */
+export declare function authoredSpelling(value: unknown, words?: readonly AutoWord[]): unknown;
+export {};

package/dist/shared/autoValues.js

@@ -0,0 +1,25 @@
+const AUTO_WORDS = ['today', 'now', 'me'];
+const said = (word) => `${word} ({ auto: '${word}' })`;
+/**
+ * An authored default or `set` value, as the model carries it: a filled-in
+ * value becomes its word, and a literal passes through. `words` are the ones
+ * this place fills in — a fixed action writes `now` and `me`, a form also
+ * `today`.
+ */
+export function authoredValue(value, at, words = AUTO_WORDS) {
+    if (value && typeof value === 'object' && !Array.isArray(value) && Object.hasOwn(value, 'auto')) {
+        const auto = value.auto;
+        if (Object.keys(value).length !== 1 || typeof auto !== 'string' || !words.includes(auto)) {
+            throw new Error(`${at} fills in ${JSON.stringify(auto)}; this place fills in ${words.map(said).join(', ')}.`);
+        }
+        return auto;
+    }
+    if (typeof value === 'string' && AUTO_WORDS.includes(value)) {
+        throw new Error(`${at} is the text '${value}', which reads as the value filled in: write the constant ${said(value)}, or another literal.`);
+    }
+    return value;
+}
+/** The authored spelling of a model value: its word back as `{ auto }`, any other value as itself. */
+export function authoredSpelling(value, words = AUTO_WORDS) {
+    return typeof value === 'string' && words.includes(value) ? { auto: value } : value;
+}

package/dist/shared/breakdown.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Counting things by something: GROUP BY, as a shape rather than as text.
+ *
+ * This was the last real hole in the query language. "How many invoices per
+ * month", "which countries have the most customers", "what does each status
+ * add up to" are the questions anybody asks of a database in the first ten
+ * minutes, and until now the only way to ask them here was to drop into `sql`
+ * — which means an agent leaves the checked path exactly where the question
+ * gets interesting, and a person leaves the tool.
+ *
+ * A breakdown is deliberately *not* a view with a `groupBy` bolted on. A view
+ * promises one row per base record, and every part of it — the correlated
+ * aggregates, the LEFT JOIN rule, the row-click that opens a record — leans on
+ * that promise. Grouping breaks it: the rows that come back are not records
+ * and cannot be opened, and a column that is neither a key nor an aggregate is
+ * a bug on two engines and a silent wrong answer on the third. So it is a
+ * sibling type with its own compiler, sharing the parts that are genuinely the
+ * same: path resolution, the join planner, and `buildWhere`.
+ *
+ *     invoice  count  by status
+ *     invoice  sum total  by month invoice_date
+ *     invoice  count, avg total  by customer_id.country_code.name  sort count desc
+ *
+ * Two rules the shape enforces, both of which SQL leaves to the author:
+ *
+ *   - **Every selected expression is a key or a measure.** There is nowhere to
+ *     put a third thing, so `SELECT status, name, COUNT(*) … GROUP BY status`
+ *     — which a lenient engine would answer with an arbitrary `name` — cannot be
+ *     written.
+ *   - **The result is bounded like every other read.** A breakdown over a
+ *     high-cardinality column is a million-row answer, and `sort count desc
+ *     limit 20` is what somebody meant anyway.
+ */
+import { type DateUnit, type SqlStyle } from './filter.js';
+import { type DatabaseSchema, type ForeignKey } from './schema.js';
+import { type ViewFilter } from './view.js';
+import { type RowScope } from './rowScope.js';
+import { type ViewDef } from './viewPaths.js';
+import type { ComputedPath } from './rollups.js';
+/** What a measure can do. `count` is the only one that needs no column. `median` is PostgreSQL's
+    `percentile_cont(0.5)`: SQLite has no median aggregate, so it is refused there. */
+export type MeasureFn = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'median';
+export declare const MEASURE_FUNCTIONS: MeasureFn[];
+/** The arithmetic a computed measure joins its terms with. SQL's precedence: `*` and `/` before `+` and `-`. */
+export type MeasureOp = '+' | '-' | '*' | '/';
+export declare const MEASURE_OPS: readonly MeasureOp[];
+/** Why a dialect cannot answer a measure function, or undefined when it can. */
+export declare function measureRefusal(fn: MeasureFn, dialect: string | undefined): string | undefined;
+/** The periods a date key can be cut into. */
+export declare const DATE_UNITS: DateUnit[];
+/**
+ * One thing to group by: a path, optionally cut down to a period.
+ *
+ * The path is a reference path like a view's, so "customers by country name"
+ * is `customer … by country_code.name` and needs no join written by hand.
+ */
+export interface BreakdownKey {
+    path: string;
+    /** Cut a date or timestamp down to a period. Refused on anything else. */
+    bucket?: DateUnit;
+    alias?: string;
+}
+/** One aggregate: a function and the column it reads. */
+export interface MeasureTerm {
+    fn: MeasureFn;
+    /** The column to measure. Absent means `COUNT(*)`, and is only valid there. */
+    path?: string;
+    /** COUNT DISTINCT. Meaningless on the others and refused there. */
+    distinct?: boolean;
+    /**
+     * `count when [status = open]`: only the rows that hold these conditions are counted, in the same statement as the
+     * other measures (`COUNT(CASE WHEN … THEN 1 END)`), so a funnel's stages are one snapshot and can never disagree.
+     * Only a bare `count` takes it. `when` is the conditions as written; `where` is what they parsed to, which is what
+     * runs: the parser fills it, and a request's own is held to the same shape a filter is (resourceReadOperations.ts).
+     */
+    when?: string;
+    where?: ViewFilter;
+}
+/**
+ * A measure: one aggregate, or a computed measure — aggregates and numbers
+ * joined by arithmetic, `sum paid / sum total`, `sum total - sum cost`. A
+ * ratio is the `/` case, not a function of its own. A division never
+ * truncates and never fails: its divisor is read as a decimal and a zero
+ * one answers null.
+ */
+export interface Measure extends MeasureTerm {
+    alias?: string;
+    /** The terms after the first, each with the operator before it. */
+    steps?: {
+        op: MeasureOp;
+        term: MeasureTerm | number;
+    }[];
+}
+/** A measure as it is written: `sum paid / sum total as rate`. */
+export declare function measureToText(m: Measure): string;
+/** The name a measure answers under when it has no alias: `sum(total)`, `sum(paid) / sum(total)`. */
+export declare function measureName(m: Measure, path?: string | undefined): string;
+/** Every column a measure reads. */
+export declare function measurePaths(m: Measure): string[];
+/** Every `when` among a breakdown's measures, in order: what a reader's grants and the stitched-read check must also hold. */
+export declare const measureConditions: (measures: readonly Measure[] | undefined) => ViewFilter[];
+/** The paths a filter's conditions walk, and the paths they compare against. */
+export declare const filterPaths: (filter: ViewFilter | undefined) => string[];
+export interface BreakdownOrder {
+    /** A key's or a measure's output name. Breakdowns sort by what they show. */
+    name: string;
+    direction: 'asc' | 'desc';
+    /** On a key: this entry only moves the empty group (a null key) after every other, whatever the entries after it
+        say; it orders nothing else, so `direction` is not read. The groups of a grouped list use it to draw "No sprint"
+        last under any sort — done in the query because the groups are paged, so no page could place it by itself. */
+    emptyLast?: boolean;
+}
+export interface BreakdownDef {
+    base: string;
+    by: BreakdownKey[];
+    /** `table.column` of text columns an App declares dates (declaredDates.ts), which this catalog reads as TEXT:
+        a period bucket over one is allowed. Carried by the App's resource facade, never taken from a request. */
+    dateColumns?: string[];
+    measures: Measure[];
+    filter?: ViewFilter;
+    orderBy?: BreakdownOrder[];
+    limit?: number;
+    /** The breakdown written down, when it came from text. */
+    text?: string;
+    /** The ISO weekday a `week` bucket's weeks start on, 1 (Monday) to 7 (Sunday); Monday when unsaid. An App's
+        server sets it from `ui.locale` (weekStart.ts), whatever a request carried. */
+    weekStart?: number;
+    /**
+     * The rollups its paths name (rollups.ts), by path — a measure `sum
+     * on_hand`, a key, a condition. Filled by the server from the App's
+     * catalog (withBreakdownComputed), never taken from a request, and read
+     * by the compiler where the adapter's catalog does not carry them.
+     */
+    computed?: Record<string, ComputedPath>;
+    /** The computed columns its paths name (computed.ts), pinned the same way. */
+    expressions?: ViewDef['expressions'];
+    /** The record tags its conditions ask (`tags has vpn`, tagLists.ts), pinned the same way: a filter rail's
+        counts under a tags filter ask them where the adapter's catalog has no tags. */
+    tagged?: ViewDef['tagged'];
+    /** The App's declared references it may walk, as a view carries them (ViewDef.references); never a request's. */
+    references?: ForeignKey[];
+    /**
+     * The keys that are references, each with the path of the name of the
+     * record it points at (`customer_id` → `customer_id.name`): a group of
+     * `customer_id` is a customer, and is said by the customer's name, as a
+     * grid's cell says it. Each such key answers that name in a `label` column
+     * after the measures. Filled by the server from the catalog
+     * (withBreakdownComputed), never taken from a request, as are `labels`,
+     * the record-name templates a `$label` name needs (a view's `labels`).
+     */
+    names?: Record<string, string>;
+    labels?: Record<string, string>;
+}
+export interface CompiledMeasure {
+    name: string;
+    /** A key, a measure, or a key's record name (`of` names the key). */
+    kind: 'key' | 'measure' | 'label';
+    of?: string;
+    fn?: MeasureFn;
+    /** The path this came from, for the interface to label it with. */
+    path?: string;
+    /** What the values are, as far as the schema knows. */
+    type: string;
+    bucket?: DateUnit;
+}
+interface CompiledBreakdown {
+    text: string;
+    params: unknown[];
+    columns: CompiledMeasure[];
+    limit: number;
+}
+/**
+ * Compile a breakdown to one parameterised SELECT.
+ *
+ * The order of work matches `compileView`'s and for the same reason: keys,
+ * then measures, then the filter, then the sort — so aliases are handed out in
+ * first-use order and the same breakdown always compiles to the same text.
+ */
+export declare function compileBreakdown(schema: DatabaseSchema, def: BreakdownDef, style: SqlStyle, offset?: number | unknown, scope?: RowScope): CompiledBreakdown;
+/** Who says a catalog cannot change, beside the scope catalog's own captures. */
+export declare function keepBreakdownsAgainst(fixed: (schema: DatabaseSchema) => boolean): void;
+/** For tests: how many breakdowns were compiled rather than found. */
+export declare function breakdownsCompiledSoFar(): number;
+/**
+ * The breakdown with the rollups its paths name, read from a catalog that
+ * serves them (an App's) — and with any it arrived with dropped, as
+ * withViewComputed does for a view: which rows a number sums is the
+ * catalog's to say, never a request's.
+ */
+export declare function withBreakdownComputed(schema: DatabaseSchema, def: BreakdownDef): BreakdownDef;
+/**
+ * How many groups there are, ignoring the page.
+ *
+ * `SELECT COUNT(*) FROM (the grouped statement)` — the only honest way to
+ * count groups, because the number is a property of the grouping rather than
+ * of the base table. Without the limit and offset, which is the whole point of
+ * asking.
+ */
+export declare function compileBreakdownCount(schema: DatabaseSchema, def: BreakdownDef, style: SqlStyle, scope?: RowScope, limit?: number): {
+    text: string;
+    params: unknown[];
+};
+/**
+ * Render a breakdown as the SQL it will become, values inline.
+ *
+ * The exact counterpart of `explainView`, and here for the same reason: the
+ * SQL pane is how somebody learns what a line of the language did on their
+ * behalf, and a statement full of `?` teaches nothing about the filter that
+ * produced it. It also has to be a statement that runs, because the pane
+ * offers to open it in the SQL editor.
+ */
+export declare function explainBreakdown(schema: DatabaseSchema, def: BreakdownDef, style: SqlStyle, offset?: number | unknown): string;
+/** A breakdown's groups said by name: key column → the key's value as text → the record's name. */
+export type GroupNames = Record<string, Record<string, string>>;
+/**
+ * The answer as its readers take it — the keys first and the measures after,
+ * by position — with each reference key's names (compileBreakdown's `label`
+ * columns) lifted out beside it: a chart reads its key and measure by index,
+ * a board its count last, and a name among them would be read as either.
+ */
+export declare function withGroupNames<R extends {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    resolved: CompiledMeasure[];
+}>(result: R): R & {
+    names?: GroupNames;
+};
+export {};