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

package/dist/shared/view.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Multi-table views, built out of **reference paths**.
+ *
+ * The `Filter` in filter.ts addresses exactly one table and must keep doing
+ * so: it is the shape every read goes through, and widening it to carry joins
+ * would put join-building into every code path that filters anything. So the
+ * multi-table story is a separate idea rather than a bigger filter, and the
+ * idea is dot-walking:
+ *
+ *     invoice     customer_id.name contains Harbour
+ *     work_order  assigned_to.last_name = Petrova
+ *                 and customer_id.country_code.name = Australia
+ *
+ * A path is a chain of foreign keys starting at the base table, ending at a
+ * column. `customer_id.name` means "follow invoice.customer_id to customer,
+ * then take name". Nothing about it is guessed: the foreign key graph is
+ * already introspected, so every hop is derivable, checkable, and reversible
+ * into SQL — a path compiles to a LEFT JOIN chain and a qualified column.
+ *
+ * One mechanism answers three separate questions. Filtering across a long
+ * walk, showing a field from a related table, and the composer UI are all the
+ * same thing seen from three angles; the composer is a visual editor for the
+ * path set.
+ *
+ * Two properties are load-bearing and are pinned by tests:
+ *
+ *   - **LEFT JOIN, never INNER.** A null foreign key must leave the base row
+ *     in the result with nulls beside it. A composer that quietly drops rows
+ *     is worse than no composer at all, because the number it shows you is
+ *     wrong in a direction you cannot see.
+ *   - **Every value is a bound parameter.** Only identifiers are ever quoted
+ *     into the text, and they are quoted by the dialect's `SqlStyle`. The
+ *     WHERE clause is still built by `buildWhere`, which now takes an
+ *     identifier resolver so a path can become `"customer_1"."name"` without
+ *     a second predicate builder existing to disagree with the first.
+ */
+import { type SqlFragment, type SqlStyle } from './filter.js';
+import { type DatabaseSchema, type ForeignKey, type TableMeta } from './schema.js';
+import { type QueryError, type QueryPerson } from './query.js';
+import { type RowScope } from './rowScope.js';
+import { type ViewFilter, type ViewOrder, type AggregateFn, type ViewDef, type ResolvedPath } from './viewPaths.js';
+export { withViewComputed, withViewLabels } from './viewLabels.js';
+export { type ViewColumn, type ViewFilter, type ViewOrder, type AggregateFn, type ViewAggregate, type ViewDef, MAX_PATH_DEPTH, PathError, hopName, type Hop, hopsFrom, type ResolvedPath, resolvePath, backrefsTo, resolveAggregate, tableAtPrefix, tryResolvePath, } from './viewPaths.js';
+export interface CompiledColumn {
+    /** The path this column came from. */
+    path: string;
+    /** The output name in the result set. */
+    name: string;
+    /** Table the value actually lives on, for the UI's grouping. */
+    table: string;
+    column: string;
+    type: string;
+    nullable: boolean;
+    primaryKey: boolean;
+    /** How many references were followed to reach it. 0 is the base table. */
+    hops: number;
+    /** Set when the column is a summary of a many-valued relationship; `latest` is a rollup's newest row (rollups.ts). */
+    aggregate?: AggregateFn | 'latest';
+}
+export interface CompiledJoin {
+    alias: string;
+    table: string;
+    /** The path prefix this join corresponds to, e.g. `customer_id.country_code`. */
+    path: string;
+}
+interface CompiledView {
+    text: string;
+    params: unknown[];
+    columns: CompiledColumn[];
+    joins: CompiledJoin[];
+    limit: number;
+}
+/**
+ * Alias generation.
+ *
+ * Two requirements pull in opposite directions. Aliases must never collide —
+ * `work_order` in the demo has three separate references to `employee`, so a
+ * scheme keyed on the target table alone produces three joins all called
+ * `employee` and a statement that does not parse. And they must be stable, so
+ * the same view compiles to the same SQL every time and a diff of the explain
+ * panel means something.
+ *
+ * Both fall out of keying on the *path prefix* rather than the table: a prefix
+ * identifies a join uniquely, so the same path used twice reuses one join and
+ * two paths through the same table get two. The readable table name is kept as
+ * a prefix and made unique by an ordinal assigned in first-use order.
+ */
+export declare class JoinPlan {
+    private schema;
+    private style;
+    private relation;
+    readonly joins: CompiledJoin[];
+    private byPrefix;
+    private n;
+    constructor(schema: DatabaseSchema, base: TableMeta, style: SqlStyle, relation?: (id: string) => string);
+    get baseAlias(): string;
+    /** The alias for a path prefix, creating the join chain if it is new. */
+    aliasFor(hops: ForeignKey[], hopNames: string[]): string;
+    /** The fully qualified, quoted SQL for a resolved path's final column. */
+    qualify(resolved: ResolvedPath): string;
+    /** The relation a table is read as in this statement: its scoped CTE, or the table itself. */
+    relationOf(id: string): string;
+    /** The alias of a path prefix that has already been planned, or the base. */
+    aliasOfPrefix(prefix: string): string;
+    /**
+     * A fresh alias for something that is not a join — a subquery's table.
+     *
+     * It draws from the same counter as the joins, which is what guarantees a
+     * correlated subquery over `employee` cannot pick the alias a LEFT JOIN
+     * over `employee` is already using. Two `employee_3`s in one statement is
+     * a self-join nobody asked for, and the wrong answer rather than an error.
+     */
+    subAlias(name: string): string;
+    /**
+     * The JOIN clauses, in the order the aliases were created.
+     *
+     * Order matters for more than tidiness: a join may only reference an alias
+     * introduced before it, and creation order is exactly path order, so a
+     * nested hop always follows the hop it hangs off.
+     */
+    clauses(): string[];
+    private fkChain;
+    /** Remember which key produced each join, so `clauses` can rebuild the ON. */
+    record(path: string, fk: ForeignKey): void;
+    private fkFor;
+}
+/**
+ * Compile a view to one parameterised SELECT.
+ *
+ * Order of work is deliberate and is what makes the output deterministic:
+ * columns, then the filter, then the sort. Aliases are handed out on first
+ * use, so the same view always produces the same statement.
+ */
+export declare function compileView(schema: DatabaseSchema, view: ViewDef, style: SqlStyle, offset?: number | unknown, scope?: RowScope): CompiledView;
+export interface ParsedView {
+    filter: ViewFilter;
+    columns: string[];
+    orderBy: ViewOrder[];
+    limit?: number;
+    errors: QueryError[];
+}
+/**
+ * Parse the composer's filter/clause text against a base table.
+ *
+ * Returns errors rather than throwing, because this runs on every keystroke
+ * and a half-typed path is the normal state of the input, not an exception.
+ */
+export declare function parseViewQuery(schema: DatabaseSchema, baseId: string, text: string, now?: Date, options?: {
+    aggregateAliases?: string[];
+    /** Who `me` is for this request; null, nobody signed in; absent, `me` is refused (query.ts). */
+    me?: QueryPerson | null;
+    /** Admit a column on a condition's right-hand side (the default); an API's standing query does not. */
+    columnValues?: boolean;
+}): ParsedView;
+/**
+ * How many rows the view matches, ignoring the page.
+ *
+ * A separate compilation rather than a wrapper around the other one, because
+ * the two differ in more than a keyword: the SELECT list, the ORDER BY and the
+ * page are all irrelevant here, and every aggregate in the view would be a
+ * correlated subquery evaluated per row for a number nobody reads.
+ *
+ * The count is exact rather than estimated, and it is *base rows* — which is
+ * only true because every join is to-one. That is the same property the whole
+ * design rests on: a view never multiplies, so counting it is counting the
+ * table it started from. With `limit`, it stops after that many.
+ */
+export declare function compileViewCount(schema: DatabaseSchema, view: ViewDef, style: SqlStyle, scope?: RowScope, limit?: number): SqlFragment;
+/**
+ * Render a view as the SQL it will become, values inline.
+ *
+ * The mirror of `explain` in query.ts and used the same way: this string never
+ * reaches a database, and showing `"customer_1"."name" LIKE '%Harbour%'` next
+ * to the path that produced it is how someone learns what the composer is
+ * doing on their behalf.
+ */
+export declare function explainView(schema: DatabaseSchema, view: ViewDef, style: SqlStyle): string;
+/**
+ * One parameter, written the way SQL would have to spell it.
+ *
+ * Exported because a breakdown explains itself the same way a view does, and
+ * two spellings of `NULL` — or two different ideas about escaping a quote —
+ * would show up as a difference between two panes that claim to be the same
+ * statement.
+ */
+export declare function sqlLiteral(value: unknown): string;
+export declare function parseViewsConfig(raw: unknown, where: string): ViewDef[];
+/**
+ * Check a view against a schema without running it.
+ *
+ * Used by `GET /api/views` so a config view naming a table that does not exist
+ * on this connection is listed *with its reason*, rather than either vanishing
+ * or blowing up the endpoint for every other view beside it.
+ */
+export declare function validateView(schema: DatabaseSchema, view: ViewDef): string | undefined;