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

package/dist/shared/pagePlans.d.ts

@@ -0,0 +1,52 @@
+/** Section planning only: callers own page validation, root lookup and access. */
+import { breakdownPlan, chartPlan, customReadView, customTotalPlan, listView, metricView, type OfKeys, type PageDef } from './page.js';
+import { groupsView, totalsView } from './pagePaths.js';
+import { type KindsReading } from './pageModel.js';
+import type { RootValues } from './pagePaths.js';
+import { type DatabaseSchema } from './schema.js';
+type HttpPagePlan = {
+    index: number;
+    kind: KindsReading<'none' | 'record'>;
+} | ({
+    index: number;
+    kind: 'breakdown';
+    breakdown?: ReturnType<typeof breakdownPlan>['def'];
+} & Pick<ReturnType<typeof breakdownPlan>, 'empty' | 'error'>) | ({
+    index: number;
+    kind: 'chart';
+    breakdown?: ReturnType<typeof chartPlan>['def'];
+} & Pick<ReturnType<typeof chartPlan>, 'empty' | 'error'>) | {
+    index: number;
+    kind: 'timeline';
+    streams: Array<{
+        from: string;
+        at: string;
+        show: string;
+        detail?: string;
+        by?: string;
+        /** With a `side`: the stream's key columns, and the same read narrowed to the other party's rows. */
+        key?: string[];
+        side?: ReturnType<typeof listView>;
+    } & ReturnType<typeof listView>>;
+} | {
+    index: number;
+    kind: 'custom';
+    reads: Record<string, ReturnType<typeof customReadView>>;
+    /** Its aggregate reads, each a breakdown (page.ts, customTotalPlan). */
+    aggregates: Record<string, Pick<ReturnType<typeof customTotalPlan>, 'empty' | 'error'> & {
+        breakdown?: ReturnType<typeof customTotalPlan>['def'];
+    }>;
+} | ({
+    index: number;
+    kind: 'list' | 'metric';
+    query?: string;
+    viewText?: string;
+    totals?: ReturnType<typeof totalsView>['breakdown'];
+    /** A grouped list's groups: one row for each record its rows share, read before the rows of each (pagePaths.ts, groupsView). */
+    groups?: ReturnType<typeof groupsView>['breakdown'];
+} & ReturnType<typeof metricView>);
+/** One supplied date keeps relative filters consistent across all sections.
+ * No reads or authorization occur here; `ofKeys` and `rootValues` (the
+ * record's own values, for a similar list) are already read by the caller. */
+export declare function planPageSections(schema: DatabaseSchema, page: PageDef, key: Record<string, string | number>, ofKeys: OfKeys, now?: Date, rootValues?: RootValues): HttpPagePlan[];
+export {};

package/dist/shared/pagePlans.js

@@ -0,0 +1,108 @@
+/** Section planning only: callers own page validation, root lookup and access. */
+import { breakdownPlan, chartPlan, customReadView, customTotalPlan, listView, metricView, sectionQuery, timelineMarkColumns, timelineSides, } from './page.js';
+import { groupsView, totalsView } from './pagePaths.js';
+import { sectionReading } from './pageModel.js';
+import { findTable, primaryKey } from './schema.js';
+import { andQuery } from './query.js';
+import { viewToTextWithSchema } from './viewtext.js';
+/** One supplied date keeps relative filters consistent across all sections.
+ * No reads or authorization occur here; `ofKeys` and `rootValues` (the
+ * record's own values, for a similar list) are already read by the caller. */
+export function planPageSections(schema, page, key, ofKeys, now = new Date(), rootValues) {
+    return page.sections.map((section, index) => {
+        // A note reads nothing, the fields read the record the caller already has, and a
+        // history is the record's own, read through its own route (server/recordHistory.ts), and so are its flow runs (server/recordFlows.ts).
+        if (!sectionReading(section, 'rows'))
+            return { index, kind: section.kind };
+        // Breakdown root filters can walk paths the text grammar cannot express.
+        if (section.kind === 'breakdown') {
+            const built = breakdownPlan(schema, page, section, key, index, now, ofKeys);
+            return { index, kind: section.kind, breakdown: built.def, empty: built.empty, error: built.error };
+        }
+        // A chart is the same related rows as a breakdown, measured and keyed its own way.
+        if (section.kind === 'chart') {
+            const built = chartPlan(schema, page, section, key, index, now, ofKeys);
+            return { index, kind: section.kind, breakdown: built.def, empty: built.empty, error: built.error };
+        }
+        // Streams remain independent list views; the client merges their rows.
+        if (section.kind === 'timeline') {
+            /* Each stream's far side, if it has one: its own, or the section's where its table can read it. */
+            const { sides } = timelineSides(schema, section);
+            const streamMarks = (stream) => timelineMarkColumns(section, stream, findTable(schema, stream.from));
+            return {
+                index,
+                kind: section.kind,
+                streams: section.streams.map((stream, s) => {
+                    /* A side is the same read narrowed by its condition, its rows told apart by their keys: the condition is
+                       asked where the rows are read, through the reader's grants, rather than by the client. */
+                    const side = sides[s];
+                    const table = side === undefined ? undefined : findTable(schema, stream.from);
+                    const keyColumns = table ? primaryKey(table) : [];
+                    const asList = {
+                        kind: 'list',
+                        from: stream.from,
+                        path: stream.path,
+                        columns: [
+                            ...new Set([stream.at, stream.show, stream.detail, stream.by, ...streamMarks(stream), ...keyColumns].filter((c) => Boolean(c))),
+                        ],
+                        filter: stream.filter,
+                        orderBy: [{ column: stream.at, direction: 'desc' }],
+                        limit: section.limit ?? 20,
+                        ...(stream.of ? { of: stream.of } : {}),
+                    };
+                    const built = listView(schema, page, asList, key, index, now, ofKeys);
+                    const others = side !== undefined && keyColumns.length && built.view
+                        ? listView(schema, page, { ...asList, columns: keyColumns, filter: andQuery(stream.filter, side) }, key, index, now, ofKeys)
+                        : undefined;
+                    return {
+                        from: stream.from,
+                        at: stream.at,
+                        show: stream.show,
+                        detail: stream.detail,
+                        by: stream.by,
+                        view: built.view,
+                        empty: built.empty,
+                        error: built.error,
+                        ...(others ? { key: keyColumns, side: others } : {}),
+                    };
+                }),
+            };
+        }
+        // Each declared read is its own view; the client runs them beside each other.
+        if (section.kind === 'custom') {
+            return {
+                index,
+                kind: section.kind,
+                reads: Object.fromEntries(Object.entries(section.reads ?? {}).map(([name, read]) => [name, customReadView(schema, page, name, read, key, index, now)])),
+                aggregates: Object.fromEntries(Object.entries(section.aggregates ?? {}).map(([name, total]) => {
+                    const built = customTotalPlan(schema, page, name, total, key, index, now);
+                    return [name, { breakdown: built.def, empty: built.empty, error: built.error }];
+                })),
+            };
+        }
+        const built = section.kind === 'metric'
+            ? metricView(schema, page, section, key, index, now, ofKeys)
+            : listView(schema, page, section, key, index, now, ofKeys, rootValues);
+        // A related list's footer: its sums over every row it matches, planned beside it.
+        const totals = section.kind === 'list' && section.totals?.length && built.view
+            ? totalsView(schema, page, section, key, ofKeys, rootValues)
+            : undefined;
+        const groups = section.kind === 'list' && section.group && built.view ? groupsView(schema, page, section, key, ofKeys, now) : undefined;
+        return {
+            index,
+            kind: section.kind,
+            view: built.view,
+            ...(totals?.breakdown ? { totals: totals.breakdown } : {}),
+            ...(groups?.breakdown ? { groups: groups.breakdown } : {}),
+            empty: built.empty,
+            // Count metrics consume the total, not a value from the loaded rows.
+            counts: built.counts,
+            // A narrowed or distant measure reads its one figure from a breakdown.
+            ...(built.breakdown ? { breakdown: built.breakdown } : {}),
+            // A simple filter can open the grid; more distant paths need a view.
+            query: built.view ? sectionQuery(built.view) : undefined,
+            viewText: built.view ? viewToTextWithSchema(schema, built.view) : undefined,
+            error: built.error ?? totals?.error ?? groups?.error,
+        };
+    });
+}

package/dist/shared/pageRoutes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A free-form page's two words on the wire, said by the client that sends
+ * them and the server that reads them (server/http/pageLoad.ts). Apart from
+ * the SDK's module lists so the shell's first chunk carries only these.
+ */
+/** Where a page's loader is run for the reader: `POST { page, params }`. */
+export declare const PAGE_LOAD_PATH = "/api/pages/load";
+/** The header a page's own requests carry: its path. */
+export declare const PAGE_HEADER = "x-mistri-page";

package/dist/shared/pageRoutes.js

@@ -0,0 +1,9 @@
+/**
+ * A free-form page's two words on the wire, said by the client that sends
+ * them and the server that reads them (server/http/pageLoad.ts). Apart from
+ * the SDK's module lists so the shell's first chunk carries only these.
+ */
+/** Where a page's loader is run for the reader: `POST { page, params }`. */
+export const PAGE_LOAD_PATH = '/api/pages/load';
+/** The header a page's own requests carry: its path. */
+export const PAGE_HEADER = 'x-mistri-page';

package/dist/shared/query.d.ts

@@ -0,0 +1,166 @@
+/**
+ * A small query language for browsing.
+ *
+ *   customers country = "Australia" and credit_limit > 1000
+ *   invoices where total >= 50 sort invoice_date desc limit 20
+ *   employees title contains manager show first_name, last_name, email
+ *   orders order_date = last 30 days
+ *
+ * The table comes first, because that is how people say it out loud. Every
+ * other clause is optional, and `where` / `order by` are accepted as aliases
+ * for `filter` / `sort` so SQL habits do not have to be unlearned.
+ *
+ * Why a language at all, when the thing underneath is SQL?
+ *
+ * Because this one compiles to a `Filter` — a structure — and never to SQL
+ * text. The adapter turns that structure into a parameterised statement, so
+ * there is no path from what a user types to what the database parses as
+ * syntax. A tool that let people type SQL directly would have to either trust
+ * them or write a SQL parser to untrust them; this sidesteps both by making
+ * the dangerous shape unrepresentable.
+ *
+ * Two things fall out of it for free. Because the compiler holds the schema,
+ * a mistyped column is an error at the caret instead of a database exception
+ * — and, worse, a mistyped *value* on a real column can be caught too. And
+ * because the compiled statement is shown next to the query, the language
+ * teaches SQL rather than hiding it.
+ */
+import type { Filter } from './filter.js';
+import { type DatabaseSchema, type MachineStates } from './schema.js';
+import { type QueryPerson } from './queryOperands.js';
+export { dateWindow } from './queryDates.js';
+interface ParsedQuery {
+    table: string;
+    filter: Filter;
+    /** Explicit column list from `show`, empty for all columns. */
+    columns: string[];
+    orderBy: {
+        column: string;
+        direction: 'asc' | 'desc';
+    }[];
+    limit?: number;
+}
+export interface QueryError {
+    message: string;
+    /** Character offset into the input, when it can be located. */
+    at?: number;
+}
+/**
+ * A query's problem as an App's author reads it: the message, then where in
+ * the query it stands. The query bar underlines the word; a query written in
+ * an App's source is read in a terminal, where "character 23" and the words
+ * from there are what find it. `text` is what the positions count in, and the
+ * author's own words start at `from` (after a table name the caller added).
+ */
+export declare function saidAt(error: QueryError, text: string, from?: number): string;
+interface ParseResult {
+    query?: ParsedQuery;
+    errors: QueryError[];
+}
+export { columnKind, type ColumnKind } from './schema.js';
+/**
+ * Join query fragments with `and`, parenthesizing any fragment whose
+ * top-level `or` would otherwise regroup: `a or b` composed with `c`
+ * must mean `(a or b) and c`, never `a or (b and c)`. Every place that
+ * folds an authored query into a narrower one goes through this.
+ */
+export declare function andQuery(...parts: Array<string | false | null | undefined>): string;
+/**
+ * A fragment's conditions, and the clauses that follow them: `a = 1 sort b
+ * limit 5` is head `a = 1`, tail `sort b limit 5`. A leading `filter`/`where`
+ * is dropped from the head, since the composition supplies its own. Quoted
+ * values are masked before scanning so `name = "sort of"` stays a value; a
+ * clause word followed by an operator is a column (`limit > 5`), as the
+ * parser itself decides. Mirrored in the client (core.js), kept honest by
+ * test/mirrors.test.ts.
+ */
+export declare function splitClauseTail(text: string): {
+    head: string;
+    tail: string;
+};
+/**
+ * A condition about the rows that point at the record: `any opportunity where
+ * stage = won`, `no task via owner_id`. The child table, the reference it
+ * points through where it has several, and its own conditions — several of
+ * them in parentheses, since a top-level `and` belongs to the record's.
+ */
+export declare const ANY_CONDITION: RegExp;
+/** Each `any …`/`no …` condition in a condition text, where it stands; a column called `any` (`any = 3`) is not one. */
+export declare function anyConditions(text: string): Array<{
+    at: number;
+    text: string;
+}>;
+/**
+ * The conditions a query holds at its top level, segments written out and nested `and`s flattened, each in a
+ * spelling that does not depend on spacing: `a = 1 and (b = 2 and c = 3)` is three. An `or` stays one
+ * condition, its branches in order, since which branch holds is not a question of more or fewer conditions. It is
+ * how one query is shown to ask no more than another (a metric's whole, dashboards: `targetWhole`).
+ */
+export declare function topLevelConditions(text: string, segments?: Readonly<Record<string, string>>): string[];
+/** `me` read by a parse that was handed no person (ParseOptions.me). */
+export declare const NO_ONE_HERE = "me is the signed-in person, and nobody is named here to be it. Quote it (\"me\") to mean the text.";
+interface ExpandedSegments {
+    text: string;
+    /** A position in the expanded text, said in the text as written: inside a segment's words, the segment's own word. */
+    at: (position: number) => number;
+    error?: QueryError;
+}
+/**
+ * A condition text with each segment it names written out, nested ones too.
+ * The positions of what was written stay readable through `at`, so a mistake
+ * in the author's own words is still underlined where they typed it.
+ */
+export declare function expandSegments(text: string, segments: Readonly<Record<string, string>> | undefined, chain?: readonly string[]): ExpandedSegments;
+/**
+ * Write a value back into the grammar, quoting only when it needs it.
+ *
+ * The exact counterpart of `unquoteValue` above, and the reason it lives here
+ * rather than beside the caller: quoting used to be written out wherever a
+ * value had to be turned back into query text — three times in the client and
+ * once here — and the four disagreed about an embedded `"`, so the same value
+ * produced a different filter depending on which button was pressed.
+ *
+ * The backslash is escaped before the quote, or a value ending in one would
+ * escape its own closing quote and swallow the rest of the query. The client
+ * has its own copy in `core.quote`, because the browser cannot import this
+ * file; `mirrors.test.ts` asserts the two agree character for character.
+ */
+export declare function quoteValue(value: unknown): string;
+export type { QueryPerson } from './queryOperands.js';
+export { ANYONE } from './queryOperands.js';
+interface ParseOptions {
+    schema?: DatabaseSchema;
+    /** Injected so compilation is deterministic and testable. */
+    now?: Date;
+    /**
+     * Admit another column on a condition's right-hand side. Only a view's
+     * compiler can write one (`buildWhere` refuses it elsewhere), so a plain
+     * query says so by name and the query bar reads the text again as a view.
+     */
+    columnValues?: boolean;
+    /** Who `me` is: the server's reading of the session; null, nobody signed in. Absent, `me` is refused. */
+    me?: QueryPerson | null;
+    /** A machine's states by column, for a parse with no catalog to carry them (`status is open`). */
+    states?: Readonly<Record<string, MachineStates>>;
+}
+interface Reads {
+    clock: 0 | 1 | 2;
+    reader: boolean;
+}
+/** `work`'s value, and how finely it read the clock (0 not, 1 by day, 2 the instant) and whether it read the reader. */
+export declare function readsOf<T>(work: () => T): {
+    value: T;
+} & Readonly<Reads>;
+/** A read of the clock (1 the day, 2 the instant) or of the reader, told to whatever work is watching (readsOf). */
+export declare function noteRead(clock: 0 | 1 | 2, reader?: boolean): void;
+export declare function parseQuery(input: string, options?: ParseOptions): ParseResult;
+/**
+ * Render a parsed query back as the SQL it will become.
+ *
+ * This is for the explain panel, not for execution — the adapter builds the
+ * real statement from the same `Filter` with bound parameters. Showing values
+ * inline here is safe because the string never reaches a database, and it is
+ * the whole point: seeing `country = $1` next to `country = 'Australia'` is
+ * how someone learns what the tool is doing on their behalf.
+ */
+export declare function explain(query: ParsedQuery): string;