measurr 0.1.0

package/dist/dataset.d.ts

@@ -0,0 +1,303 @@
+import { type Expr, type ExprNode, type SqlType, type Table, type TableRef, type TimeBucketUnit, type TimePartName } from './expr.js';
+declare const ratioBrand: unique symbol;
+/** A share or ratio between 0 and 1. Branded so nobody renders 0.42 as "0.42%". */
+export type Ratio = number & {
+    readonly [ratioBrand]: 'zeroToOne';
+};
+type Described = {
+    label: string;
+    description?: string | undefined;
+};
+/**
+ * `count` results are never null. `number` results (sum, avg, median) are null for an empty
+ * group. `ratio` results (share, ratio) are a 0-1 `Ratio`, null when the base is zero.
+ */
+export type MeasureResult = 'count' | 'number' | 'ratio';
+export type AggregateMeasure<R extends 'count' | 'number' = 'count' | 'number'> = {
+    readonly kind: 'aggregate';
+    readonly result: R;
+    readonly label: string;
+    readonly description: string | undefined;
+    readonly node: Extract<ExprNode, {
+        kind: 'aggregate';
+    }>;
+};
+export type ShareMeasure = {
+    readonly kind: 'share';
+    readonly result: 'ratio';
+    readonly label: string;
+    readonly description: string | undefined;
+    readonly numerator: ExprNode;
+    readonly denominator: ExprNode | null;
+};
+export type RatioMeasure<A extends string = string, B extends string = string> = {
+    readonly kind: 'ratio';
+    readonly result: 'ratio';
+    readonly label: string;
+    readonly description: string | undefined;
+    readonly numerator: A;
+    readonly denominator: B;
+};
+export type AnyMeasure = AggregateMeasure | ShareMeasure | RatioMeasure;
+/** The TypeScript type of a measure's value in a result row. */
+export type MeasureValue<M> = M extends {
+    result: 'count';
+} ? number : M extends {
+    result: 'number';
+} ? number | null : Ratio | null;
+type Filtered = Described & {
+    where?: Expr<'boolean'> | undefined;
+};
+export declare const measure: {
+    /** Number of rows, optionally only those matching `where`. */
+    count(options: Filtered): AggregateMeasure<'count'>;
+    /** Number of rows matching `condition`. */
+    countWhere(condition: Expr<'boolean'>, options: Described): AggregateMeasure<'count'>;
+    /** Number of distinct non-null values of `expr`. */
+    countDistinct(expr: Expr<SqlType>, options: Filtered): AggregateMeasure<'count'>;
+    sum(expr: Expr<'number'>, options: Filtered): AggregateMeasure<'number'>;
+    avg(expr: Expr<'number'>, options: Filtered): AggregateMeasure<'number'>;
+    median(expr: Expr<'number'>, options: Filtered): AggregateMeasure<'number'>;
+    /**
+     * The share of rows matching `numerator` among rows matching `denominator` (all rows when
+     * omitted). A `Ratio` from 0 to 1.
+     */
+    share(options: Described & {
+        numerator: Expr<'boolean'>;
+        denominator?: Expr<'boolean'> | undefined;
+    }): ShareMeasure;
+    /**
+     * One measure of this dataset over another, computed after aggregation. Both keys must be
+     * measures of the same dataset; `defineDataset` checks them.
+     */
+    ratio<const A extends string, const B extends string>(numerator: A, denominator: B, options: Described): RatioMeasure<A, B>;
+};
+/**
+ * How a dimension filters:
+ * - `closed`: a fixed set of keys (enum, computed) - `in`, `notIn`, `isEmpty`, `isNotEmpty`;
+ * - `open`: keys from the data (relation, many-to-many) - the same operators, with values given
+ *   as keys or labels and resolved at query time;
+ * - `numeric`: numbers (numeric columns, weekday, hour) - `between`, `isEmpty`, `isNotEmpty`;
+ * - `time`: time buckets keyed by ISO date - `between`, `isEmpty`, `isNotEmpty`.
+ */
+export type DimensionCategory = 'closed' | 'open' | 'numeric' | 'time';
+type DimensionOptions<G extends boolean = boolean, F extends boolean = boolean> = Described & {
+    /** Only offered for grouping. */
+    groupOnly?: G | undefined;
+    /** Only offered for filtering. */
+    filterOnly?: F | undefined;
+};
+/** Time dimensions name themselves after their unit unless given a label. */
+type TimeDimensionOptions<G extends boolean, F extends boolean, Key> = Omit<DimensionOptions<G, F>, 'label'> & {
+    label?: string | undefined;
+    labelFor?: ((key: Key) => string) | undefined;
+};
+/**
+ * `groupOnly: true` makes `filterable` the literal `false` (and `filterOnly`, `groupable`), so
+ * queries cannot filter or group by what the dimension does not offer.
+ */
+export type DimensionAccess<G extends boolean, F extends boolean> = {
+    readonly groupable: [F] extends [true] ? false : boolean;
+    readonly filterable: [G] extends [true] ? false : boolean;
+};
+type DimensionBase<C extends DimensionCategory, Key> = {
+    readonly category: C;
+    readonly label: string;
+    readonly description: string | undefined;
+    readonly groupable: boolean;
+    readonly filterable: boolean;
+    /** Phantom: the key type in result rows. */
+    readonly keyType?: Key;
+};
+/** `Empty` is `null` when the expression can be null, `never` when it cannot. */
+export type EnumDimension<K extends string = string, Empty extends null = null> = DimensionBase<'closed', K | Empty> & {
+    readonly kind: 'enum' | 'computed';
+    readonly expr: ExprNode;
+    readonly values: Readonly<Record<K, string>>;
+    readonly empty: string | undefined;
+};
+export type RelationDimension<K = unknown> = DimensionBase<'open', K> & {
+    readonly kind: 'relation';
+    readonly key: ExprNode;
+    readonly name: ExprNode;
+    readonly empty: string | undefined;
+};
+export type ManyToManyDimension = DimensionBase<'open', string> & {
+    readonly kind: 'manyToMany';
+    readonly table: TableRef;
+    readonly on: ExprNode;
+    readonly key: ExprNode;
+    readonly name: ExprNode;
+    readonly empty: string | undefined;
+    readonly note: string | undefined;
+};
+export type NumberDimension = DimensionBase<'numeric', number> & {
+    readonly kind: 'number';
+    readonly expr: ExprNode;
+    readonly labelFor: ((key: number) => string) | undefined;
+};
+export type TimePartDimension<T extends string = string> = DimensionBase<'numeric', number> & {
+    readonly kind: 'timePart';
+    readonly time: T;
+    readonly part: TimePartName;
+    readonly labelFor: ((key: number) => string) | undefined;
+};
+export type TimeBucketDimension<T extends string = string> = DimensionBase<'time', string> & {
+    readonly kind: 'timeBucket';
+    readonly time: T;
+    readonly unit: TimeBucketUnit;
+    readonly labelFor: ((key: string) => string) | undefined;
+};
+export type AnyDimension = EnumDimension | RelationDimension | ManyToManyDimension | NumberDimension | TimePartDimension | TimeBucketDimension;
+/**
+ * `{ key, label }` as it appears in a result row for this dimension. Enum and computed keys
+ * are null only when their expression can be null; any other key is null when the row has no
+ * value (no related row, a null column, a time field the period does not apply to).
+ */
+export type DimensionValue<Dim> = Dim extends {
+    kind: 'enum' | 'computed';
+    keyType?: infer K;
+} ? {
+    key: K;
+    label: string;
+} : Dim extends {
+    keyType?: infer K;
+} ? {
+    key: K | null;
+    label: string;
+} : never;
+/** `null` when an expression's values `V` include null, otherwise `never`. */
+type EmptyOf<V> = null extends V ? null : never;
+/**
+ * Makes `expr` fail typecheck when it can produce a value `Allowed` does not list, naming the
+ * missing values. Expressions typed only as `string` pass; `defineDataset` checks those.
+ */
+type CoversValues<V, Allowed> = string extends NonNullable<V> ? unknown : [Exclude<NonNullable<V>, Allowed>] extends [never] ? unknown : {
+    readonly missingFromValues: Exclude<NonNullable<V>, Allowed>;
+};
+/** What a closed dimension's null key is called. */
+type EmptyOption = {
+    /** The label of rows whose value is null. "None" when omitted. */
+    empty?: string | undefined;
+};
+export declare const dimension: {
+    /**
+     * A column holding one value of a closed set, such as a Prisma enum. `labels` must name
+     * every value, so adding an enum value fails typecheck until it has a label, and a column
+     * typed with values outside `values` fails too. A nullable column gives null keys.
+     */
+    enum<const E extends Record<string, string>, V extends string | null, G extends boolean = boolean, F extends boolean = boolean>(expr: Expr<'string', V> & CoversValues<V, E[keyof E]>, values: E, options: DimensionOptions<G, F> & EmptyOption & {
+        labels: Record<E[keyof E], string>;
+    }): EnumDimension<E[keyof E], EmptyOf<V>> & DimensionAccess<G, F>;
+    /**
+     * A value computed from other columns with the expression builders, usually `caseWhen`.
+     * `values` lists every value the expression can produce, with its label; a plain value of
+     * the expression missing from `values` fails typecheck. A `caseWhen` without `otherwise`
+     * gives null keys.
+     */
+    computed<V extends string | null, const K extends string, G extends boolean = boolean, F extends boolean = boolean>(options: DimensionOptions<G, F> & EmptyOption & {
+        expr: Expr<'string', V> & CoversValues<V, NoInfer<K>>;
+        values: Record<K, string>;
+    }): EnumDimension<K, EmptyOf<V>> & DimensionAccess<G, F>;
+    /**
+     * A to-one relation such as a team. The key type comes from the `key` column, so a branded
+     * id column types the key in filters and rows. Rows without a related record get the
+     * `empty` label and a null key.
+     */
+    relation<Key extends string | number, G extends boolean = boolean, F extends boolean = boolean>(options: DimensionOptions<G, F> & {
+        key: Expr<Key extends number ? 'number' : 'string', Key | null>;
+        name: Expr<'string'>;
+        empty?: string | undefined;
+    }): RelationDimension<Key> & DimensionAccess<G, F>;
+    /**
+     * A to-many relation through a link table, such as tags. Grouping counts a row once per
+     * related value, so totals for such a grouping come from a separate query. Filtering
+     * compiles to `EXISTS`, so it never multiplies rows.
+     *
+     * `through.table` is the link table as a standalone `table()` (further joins hang off it),
+     * and `through.on` links it to the dataset's table.
+     */
+    manyToMany<Row = unknown, G extends boolean = boolean, F extends boolean = boolean>(options: DimensionOptions<G, F> & {
+        through: {
+            table: Table<Row>;
+            on: Expr<'boolean'>;
+            key: Expr<'string' | 'number'>;
+            name: Expr<'string'>;
+        };
+        /** Explains the overlap to the reader of a grouped result. */
+        note?: string | undefined;
+        empty?: string | undefined;
+    }): ManyToManyDimension & DimensionAccess<G, F>;
+    /** A numeric column, grouped by its exact values and filtered with `between`. */
+    number<G extends boolean = boolean, F extends boolean = boolean>(expr: Expr<'number'>, options: DimensionOptions<G, F> & {
+        labelFor?: ((key: number) => string) | undefined;
+    }): NumberDimension & DimensionAccess<G, F>;
+    /** Day, ISO week (starting Monday) or month of a time field, in the tenant's timezone. */
+    timeBucket<const T extends string, G extends boolean = boolean, F extends boolean = boolean>(time: T, unit: TimeBucketUnit, options?: TimeDimensionOptions<G, F, string>): TimeBucketDimension<T> & DimensionAccess<G, F>;
+    /** ISO weekday (1 = Monday) or hour (0-23) of a time field, in the tenant's timezone. */
+    timePart<const T extends string, G extends boolean = boolean, F extends boolean = boolean>(time: T, part: TimePartName, options?: TimeDimensionOptions<G, F, number>): TimePartDimension<T> & DimensionAccess<G, F>;
+};
+export type TimeField = {
+    readonly column: ExprNode;
+    readonly label: string;
+};
+export type Dataset<K extends string = string, M extends Record<string, AnyMeasure> = Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension> = Record<string, AnyDimension>, T extends string = string> = {
+    readonly key: K;
+    readonly label: string;
+    readonly description: string;
+    readonly from: TableRef;
+    readonly source: string | undefined;
+    readonly tenantColumn: ExprNode;
+    readonly scope: ExprNode | null;
+    readonly time: Readonly<Record<T, TimeField>>;
+    readonly defaultTime: T;
+    readonly measures: M;
+    readonly dimensions: Dm;
+};
+export type AnyDataset = Dataset<string, any, any, string>;
+/** Ratio measures may only name other measures of the same dataset. */
+type CheckMeasures<M> = {
+    [Key in keyof M]: M[Key] extends {
+        kind: 'ratio';
+    } ? {
+        numerator: Exclude<keyof M & string, Key>;
+        denominator: Exclude<keyof M & string, Key>;
+    } : unknown;
+};
+/** Time dimensions may only name declared time fields. */
+type CheckDimensions<Dm, T extends string> = {
+    [Key in keyof Dm]: Dm[Key] extends {
+        kind: 'timeBucket' | 'timePart';
+    } ? {
+        time: T;
+    } : unknown;
+};
+export type DatasetDefinition<K extends string, M extends Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension>, T extends string> = {
+    key: K;
+    label: string;
+    /** Tells a reader (and a model) what one row of the dataset is. */
+    description: string;
+    from: {
+        readonly ref: TableRef;
+    };
+    /** Which source (database) the dataset runs on; the default when there is one source. */
+    source?: string | undefined;
+    /** The column every query is filtered by; the value comes from `tenant(ctx)`. */
+    tenantColumn: Expr<SqlType>;
+    /** Always applied, for example excluding test rows. */
+    scope?: Expr<'boolean'> | undefined;
+    time: Record<T, {
+        column: Expr<'timestamp'>;
+        label: string;
+    }>;
+    /** The time field periods apply to when a query names none; the first one by default. */
+    defaultTime?: NoInfer<T> | undefined;
+    measures: M & CheckMeasures<M>;
+    dimensions: Dm & CheckDimensions<Dm, NoInfer<T>>;
+};
+/**
+ * Declares a dataset: one fact table with its tenant column, time fields, measures and
+ * dimensions. Keys stay literal types, so queries and result rows are typed from it.
+ */
+export declare function defineDataset<const K extends string, const M extends Record<string, AnyMeasure>, const Dm extends Record<string, AnyDimension>, const T extends string>(definition: DatasetDefinition<K, M, Dm, T>): Dataset<K, M, Dm, T>;
+export {};

package/dist/dialects/postgres.d.ts

@@ -0,0 +1,16 @@
+import { type Dialect } from '../compile.js';
+export type PostgresDialectOptions = {
+    /**
+     * How time columns are stored:
+     * - `timestamptz` (default): `timestamp with time zone`;
+     * - `utc`: `timestamp without time zone` holding UTC wall-clock time, which is what Prisma's
+     *   `DateTime` creates.
+     */
+    timestamps?: 'timestamptz' | 'utc';
+};
+/**
+ * Postgres: `$n` parameters, double-quoted identifiers, `FILTER (WHERE ...)` aggregates and
+ * buckets with `AT TIME ZONE`. Values are passed untyped so Postgres infers them from the
+ * column they meet, which keeps enum columns working.
+ */
+export declare function postgresDialect(options?: PostgresDialectOptions): Dialect;

package/dist/dialects/postgres.js

@@ -0,0 +1,51 @@
+import {
+  decodeNumber2,
+  renderStatement2
+} from "../index-nrjdssft.js";
+
+// src/dialects/postgres.ts
+function postgresDialect(options = {}) {
+  const timestamps = options.timestamps ?? "timestamptz";
+  const local = (expr, timezone) => timestamps === "utc" ? `((${expr}) AT TIME ZONE 'UTC' AT TIME ZONE '${timezone}')` : `((${expr}) AT TIME ZONE '${timezone}')`;
+  const renderer = {
+    name: "postgres",
+    quote: (identifier) => `"${identifier.replaceAll('"', '""')}"`,
+    param(value, index) {
+      const placeholder = `$${index}`;
+      if (!(value instanceof Date))
+        return { placeholder, value };
+      const iso = value.toISOString();
+      return {
+        placeholder,
+        value: timestamps === "utc" ? iso.replace("T", " ").replace("Z", "") : iso
+      };
+    },
+    aggregate(fn, arg, where) {
+      const filter = where ? ` FILTER (WHERE ${where})` : "";
+      switch (fn) {
+        case "count":
+          return `count(*)${filter}`;
+        case "countDistinct":
+          return `count(DISTINCT ${arg})${filter}`;
+        case "sum":
+          return `sum(${arg})${filter}`;
+        case "avg":
+          return `avg(${arg})${filter}`;
+        case "median":
+          return `percentile_cont(0.5) WITHIN GROUP (ORDER BY (${arg})::double precision)${filter}`;
+      }
+    },
+    divide: (left, right) => `((${left})::double precision / NULLIF(${right}, 0))`,
+    toText: (expr) => `CAST(${expr} AS text)`,
+    timeBucket: (unit, expr, timezone) => `to_char(date_trunc('${unit}', ${local(expr, timezone)}), 'YYYY-MM-DD')`,
+    timePart: (part, expr, timezone) => `CAST(extract(${part} FROM ${local(expr, timezone)}) AS integer)`
+  };
+  return {
+    name: "postgres",
+    compile: (statement) => renderStatement2(statement, renderer),
+    decodeNumber: decodeNumber2
+  };
+}
+export {
+  postgresDialect
+};

package/dist/expr.d.ts

@@ -0,0 +1,210 @@
+/**
+ * The expression tree datasets are written with. Builders return `Expr` values that carry a
+ * small, dialect-free node tree; no SQL text exists until a dialect renders a planned
+ * statement. Every expression knows its SQL type, so `avg` over a string or `timeBucket` over a
+ * number fails typecheck.
+ */
+export type SqlType = 'number' | 'string' | 'boolean' | 'timestamp';
+/** A value a query parameter can hold. Timestamps are passed as `Date`. */
+export type ParamValue = string | number | boolean | Date | null;
+export type CompareOp = '=' | '<>' | '>' | '>=' | '<' | '<=';
+export type TimeBucketUnit = 'day' | 'week' | 'month';
+export type TimePartName = 'isodow' | 'hour';
+export type AggregateFn = 'count' | 'countDistinct' | 'sum' | 'avg' | 'median';
+/**
+ * A table occurrence. A joined table points at the table it hangs off and carries its own
+ * `ON` clause, so any column read from it brings the join along.
+ */
+export type TableRef = {
+    readonly name: string;
+    readonly alias: string | undefined;
+    readonly join: TableJoin | undefined;
+};
+export type TableJoin = {
+    readonly type: 'left' | 'inner';
+    readonly parent: TableRef;
+    readonly on: ExprNode;
+};
+export type ExprNode = {
+    readonly kind: 'column';
+    readonly table: TableRef;
+    readonly column: string;
+} | {
+    readonly kind: 'param';
+    readonly value: ParamValue;
+} | {
+    readonly kind: 'compare';
+    readonly op: CompareOp;
+    readonly left: ExprNode;
+    readonly right: ExprNode;
+} | {
+    readonly kind: 'logical';
+    readonly op: 'and' | 'or';
+    readonly items: readonly ExprNode[];
+} | {
+    readonly kind: 'not';
+    readonly item: ExprNode;
+} | {
+    readonly kind: 'isNull';
+    readonly item: ExprNode;
+    readonly negated: boolean;
+} | {
+    readonly kind: 'in';
+    readonly item: ExprNode;
+    readonly values: readonly ExprNode[];
+    readonly negated: boolean;
+} | {
+    readonly kind: 'case';
+    readonly branches: readonly {
+        readonly when: ExprNode;
+        readonly result: ExprNode;
+    }[];
+    readonly otherwise: ExprNode | null;
+} | {
+    readonly kind: 'exists';
+    readonly table: TableRef;
+    readonly where: ExprNode;
+    readonly negated: boolean;
+} | {
+    readonly kind: 'coalesce';
+    readonly items: readonly ExprNode[];
+} | {
+    readonly kind: 'arithmetic';
+    readonly op: '+' | '-' | '*' | '/';
+    readonly left: ExprNode;
+    readonly right: ExprNode;
+} | {
+    readonly kind: 'lower';
+    readonly item: ExprNode;
+} | {
+    readonly kind: 'toText';
+    readonly item: ExprNode;
+} | {
+    readonly kind: 'aggregate';
+    readonly fn: AggregateFn;
+    readonly arg: ExprNode | null;
+    readonly where: ExprNode | null;
+} | {
+    readonly kind: 'timeBucket';
+    readonly unit: TimeBucketUnit;
+    readonly item: ExprNode;
+    readonly timezone: string;
+} | {
+    readonly kind: 'timePart';
+    readonly part: TimePartName;
+    readonly item: ExprNode;
+    readonly timezone: string;
+}
+/** The moment the query runs, minus `minutes`; rendered as a timestamp parameter. */
+ | {
+    readonly kind: 'minutesAgo';
+    readonly minutes: number;
+};
+/** What a raw value of a SQL type looks like in TypeScript. */
+export type ValueOf<T extends SqlType> = T extends 'number' ? number : T extends 'string' ? string : T extends 'boolean' ? boolean : Date;
+/**
+ * An expression of SQL type `T`, or a plain value of `V` that becomes a parameter. `V` narrows
+ * plain values, so `eq(order.col('status'), 'PAD')` fails when `status` is an enum. Plain
+ * values are never null: compare with `isNull` instead.
+ */
+export type Operand<T extends SqlType, V = ValueOf<T>> = Expr<T> | V;
+/** The values an operand or a `caseWhen` branch can produce. */
+type ValuesOf<O> = O extends Expr<SqlType, infer V> ? V : O;
+/** `null` when `V` can be null or undefined (an optional field), otherwise `never`. */
+type NullOf<V> = null extends V ? null : undefined extends V ? null : never;
+/**
+ * `T` is the SQL type; `V` is the TypeScript type of its values, including `null` when the
+ * expression can be null. `V` defaults to "any value of `T`, or null", the SQL default; columns,
+ * literals and `caseWhen` narrow it (an enum's members, a branded id, a non-null column).
+ */
+export declare class Expr<T extends SqlType, V = ValueOf<T> | null> {
+    readonly node: ExprNode;
+    /** Phantom: the SQL type this expression evaluates to. Not `declare`: Playwright's Babel transform rejects it. */
+    readonly sqlType: T;
+    /** Phantom: the values this expression can produce. */
+    readonly valueType: V;
+    constructor(node: ExprNode);
+    isNull(): Expr<'boolean', boolean>;
+    isNotNull(): Expr<'boolean', boolean>;
+    add(this: Expr<'number'>, other: Operand<'number'>): Expr<'number'>;
+    sub(this: Expr<'number'>, other: Operand<'number'>): Expr<'number'>;
+    mul(this: Expr<'number'>, other: Operand<'number'>): Expr<'number'>;
+    /** Always a floating-point division, and `null` when dividing by zero. */
+    div(this: Expr<'number'>, other: Operand<'number'>): Expr<'number'>;
+}
+/** Maps a column's TypeScript type to its SQL type; `never` for columns we cannot use. */
+export type SqlTypeOf<V> = [NonNullable<V>] extends [never] ? never : [NonNullable<V>] extends [Date] ? 'timestamp' : [NonNullable<V>] extends [number | bigint] ? 'number' : [NonNullable<V>] extends [boolean] ? 'boolean' : [NonNullable<V>] extends [string] ? 'string' : [NonNullable<V>] extends [{
+    toNumber(): number;
+}] ? 'number' : never;
+/**
+ * The value type a column keeps: its own type when it fits its SQL type (an enum, a branded
+ * id), plus `null` when the field is nullable or optional.
+ */
+export type ColumnValueOf<V> = ([NonNullable<V>] extends [ValueOf<SqlTypeOf<V>>] ? NonNullable<V> : ValueOf<SqlTypeOf<V>>) | NullOf<V>;
+/** Keys of `Row` whose values map to a SQL type (JSON and relation fields are excluded). */
+export type ColumnKey<Row> = {
+    [K in keyof Row]-?: [SqlTypeOf<Row[K]>] extends [never] ? never : K;
+}[keyof Row] & string;
+/**
+ * A typed handle on a table. `Row` is any object type (a Prisma model, a hand-written type);
+ * `col` only accepts its keys and returns an expression of the matching SQL type.
+ */
+export declare class Table<Row> {
+    readonly ref: TableRef;
+    readonly row: Row;
+    constructor(ref: TableRef);
+    col<K extends ColumnKey<Row>>(key: K): Expr<SqlTypeOf<Row[K]>, ColumnValueOf<Row[K]>>;
+    /** Joins `other` to this table. Columns of the returned handle bring the join with them. */
+    leftJoin<Other>(other: Table<Other>, on: (joined: Table<Other>) => Expr<'boolean'>): Table<Other>;
+    innerJoin<Other>(other: Table<Other>, on: (joined: Table<Other>) => Expr<'boolean'>): Table<Other>;
+    private join;
+}
+/** A table handle. The alias is optional; the compiler makes aliases unique per statement. */
+export declare function table<Row>(name: string, alias?: string): Table<Row>;
+/** A literal value, always sent as a query parameter. */
+export declare function literal<V extends string | number | boolean | Date>(value: V): Expr<V extends number ? 'number' : V extends boolean ? 'boolean' : V extends Date ? 'timestamp' : 'string', V>;
+export declare function eq<T extends SqlType, V extends ParamValue>(left: Expr<T, V>, right: Operand<NoInfer<T>, NonNullable<NoInfer<V>>>): Expr<'boolean'>;
+export declare function ne<T extends SqlType, V extends ParamValue>(left: Expr<T, V>, right: Operand<NoInfer<T>, NonNullable<NoInfer<V>>>): Expr<'boolean'>;
+export declare function gt<T extends SqlType, V extends ParamValue>(left: Expr<T, V>, right: Operand<NoInfer<T>, NonNullable<NoInfer<V>>>): Expr<'boolean'>;
+export declare function gte<T extends SqlType, V extends ParamValue>(left: Expr<T, V>, right: Operand<NoInfer<T>, NonNullable<NoInfer<V>>>): Expr<'boolean'>;
+export declare function lt<T extends SqlType, V extends ParamValue>(left: Expr<T, V>, right: Operand<NoInfer<T>, NonNullable<NoInfer<V>>>): Expr<'boolean'>;
+export declare function lte<T extends SqlType, V extends ParamValue>(left: Expr<T, V>, right: Operand<NoInfer<T>, NonNullable<NoInfer<V>>>): Expr<'boolean'>;
+export declare function and(...items: Expr<'boolean'>[]): Expr<'boolean'>;
+export declare function or(...items: Expr<'boolean'>[]): Expr<'boolean'>;
+export declare function not(item: Expr<'boolean'>): Expr<'boolean'>;
+export declare function isNull(item: Expr<SqlType, unknown>): Expr<'boolean', boolean>;
+export declare function isNotNull(item: Expr<SqlType, unknown>): Expr<'boolean', boolean>;
+type CaseValue = string | number | boolean | Expr<SqlType, unknown>;
+type CaseType<V> = V extends Expr<infer T, unknown> ? T : V extends string ? 'string' : V extends number ? 'number' : V extends boolean ? 'boolean' : never;
+/**
+ * `CASE WHEN ... THEN ... ELSE ... END`. Branches are checked in order. Plain values become
+ * parameters; a computed dimension's `values` must list every plain value used here. Without
+ * `otherwise`, rows matching no branch are null, and the type says so.
+ */
+export declare function caseWhen<const V extends CaseValue>(branches: readonly (readonly [Expr<'boolean', unknown>, V])[]): Expr<CaseType<V>, ValuesOf<V> | null>;
+export declare function caseWhen<const V extends CaseValue, const O extends CaseValue>(branches: readonly (readonly [Expr<'boolean', unknown>, V])[], otherwise: O): Expr<CaseType<V | O>, ValuesOf<V | O>>;
+/**
+ * A correlated `EXISTS`: true when `from` has a row matching `where`. `where` usually links
+ * the subquery table to the outer table, for example
+ * `exists(message, eq(message.col('sessionId'), session.col('id')))`.
+ */
+export declare function exists<Row>(from: Table<Row>, where: Expr<'boolean'>): Expr<'boolean', boolean>;
+/** Null only when every item can be null; a plain fallback value is never null. */
+type Coalesced<V, Rest> = [Rest] extends [never] ? V : null extends Rest ? V | Rest : NonNullable<V> | Rest;
+export declare function coalesce<T extends SqlType, V extends ParamValue, const R extends readonly Operand<NoInfer<T>>[]>(first: Expr<T, V>, ...rest: R): Expr<T, Coalesced<V, ValuesOf<R[number]>>>;
+/** Matches `item` against a fixed list of values. */
+export declare function inList<T extends SqlType, V extends ParamValue>(item: Expr<T, V>, values: readonly NonNullable<NoInfer<V>>[]): Expr<'boolean'>;
+/** `item` as text, for example to compare an enum column with a value outside the enum. */
+export declare function toText<V>(item: Expr<SqlType, V>): Expr<'string', string | NullOf<V>>;
+/**
+ * The moment the query runs, minus `minutes`, such as "created in the last 15 minutes". The
+ * query's clock supplies the moment, so it follows the `now` option of `createAnalytics`.
+ */
+export declare function minutesAgo(minutes: number): Expr<'timestamp', Date>;
+/** Follows the join chain up to the table that is not joined to anything. */
+export declare function rootOf(ref: TableRef): TableRef;
+/** The nodes directly below `node`, including an `exists` subquery's condition. */
+export declare function directChildren(node: ExprNode): readonly ExprNode[];
+/** Visits every node in a tree, depth first. */
+export declare function walk(node: ExprNode, visit: (node: ExprNode) => void): void;
+export {};

package/dist/guidance.d.ts

@@ -0,0 +1,5 @@
+/**
+ * How a model should use an analytics query tool, as markdown bullets for its instructions.
+ * It does not name the tool, so add a line that does.
+ */
+export declare const analyticsToolGuidance = "- Answer every \"how many\", \"how much\", \"per week\" or \"split by\" question with the analytics tool. Never count by hand from lists or pages.\n- Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.\n- Say which period and filters the numbers cover, using the dates in the result (\"1-30 September\").\n- Compare with the previous period (compareToPrevious) when the change is the point, such as \"is it going up\".\n- When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.\n- Ask one short question only when the period is genuinely ambiguous (\"this season\") and someone can answer; otherwise take the natural reading and state it.";