@vaultgradient/pipequery-lang 1.12.2 → 1.13.0

package/dist/builder/index.d.cts

@@ -0,0 +1,458 @@
+import { E as Expression, O as Operation, P as Pipeline, C as CompiledQuery, D as DataContext } from '../types-CukH_v-n.cjs';
+
+/**
+ * Compile-time types of the builder. Nothing here exists at runtime except three
+ * phantom symbols: every expression is an `Expr` instance, these interfaces are
+ * only views that decide which methods and positions type-check.
+ *
+ * An expression carries:
+ *  - a value type (`NumExpr`, `StrExpr`, `BoolExpr`, `GenericExpr<T>`)
+ *  - a scope: `'row'` (plain fields and operators), `'agg'` (contains an aggregate) or
+ *    `'win'` (contains a window function). Scopes are unioned when expressions combine,
+ *    so `where` and `sort`, which accept `'row'` only, reject both.
+ *  - whether it is aliased (`.as(name)`). Aliased expressions cannot go where the
+ *    grammar forbids `as` (sort, groupBy, distinct, ...).
+ */
+
+declare const TYPE: unique symbol;
+declare const SCOPE: unique symbol;
+declare const ALIAS: unique symbol;
+declare const NULLISH: unique symbol;
+type Scope = 'row' | 'agg' | 'win';
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** What every expression looks like to positions that take any of them (aliased or not). */
+interface ExprBase<T = any, S extends Scope = Scope> {
+    readonly [TYPE]?: T;
+    readonly [SCOPE]?: S;
+    readonly [ALIAS]?: boolean;
+}
+/** An expression that is not aliased. */
+type Plain<T = any, S extends Scope = Scope> = ExprBase<T, S> & {
+    readonly [ALIAS]?: false;
+};
+/** `expr.as('name')`: usable in `select`, `map`, `rollup` and `pivot`, and nowhere that forbids `as`. */
+interface AliasedExpr<N extends string = string, T = any, S extends Scope = Scope> extends ExprBase<T, S> {
+    readonly [ALIAS]: true;
+    /** Phantom: the output column name. */
+    readonly __name?: N;
+}
+type Nullish = null | undefined;
+/** Operands also accept nullable expressions (a nullable field is still a number/string/boolean field). */
+type NumOperand<B extends Scope = 'row'> = number | Plain<number | Nullish, B>;
+type StrOperand<B extends Scope = 'row'> = string | Plain<string | Nullish, B>;
+type BoolOperand<B extends Scope = 'row'> = boolean | Plain<boolean | Nullish, B>;
+/**
+ * Phantom marker for expressions that may be `null`/`undefined` (nullable or optional fields,
+ * `win.lag`, ...). The kind interfaces (`NumExpr`, ...) stay the same so operators and positions
+ * are unaffected; only `ValueOf`, and so the output row types, see it.
+ */
+type WithNull<E, N> = [N] extends [never] ? E : E & {
+    readonly [NULLISH]: N;
+};
+type NullOf<X> = X extends {
+    readonly [NULLISH]: infer N;
+} ? N : never;
+type Undef<N> = [N] extends [never] ? never : undefined;
+interface Common<T, S extends Scope> extends ExprBase<T, S> {
+    readonly [ALIAS]?: false;
+    eq<O extends T | Nullish | Plain<T | Nullish, Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    ne<O extends T | Nullish | Plain<T | Nullish, Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    /** First non-null value of this expression and the fallbacks. */
+    coalesce<O extends T | Plain<T | Nullish, Scope>>(...rest: O[]): ExprFor<T, S | ScopeOf<O>>;
+    as<N extends string>(name: N): AliasedExpr<N, T, S>;
+    asc(): SortKey<S>;
+    desc(): SortKey<S>;
+}
+/** An expression of a type with no dedicated operators (arrays, `unknown`, mixed unions). */
+interface GenericExpr<T = unknown, S extends Scope = 'row'> extends Common<T, S> {
+}
+interface NumExpr<S extends Scope = 'row'> extends Common<number, S> {
+    gt<O extends NumOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    gte<O extends NumOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    lt<O extends NumOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    lte<O extends NumOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    plus<O extends NumOperand<Scope>>(other: O): NumExpr<S | ScopeOf<O>>;
+    minus<O extends NumOperand<Scope>>(other: O): NumExpr<S | ScopeOf<O>>;
+    times<O extends NumOperand<Scope>>(other: O): NumExpr<S | ScopeOf<O>>;
+    div<O extends NumOperand<Scope>>(other: O): NumExpr<S | ScopeOf<O>>;
+    mod<O extends NumOperand<Scope>>(other: O): NumExpr<S | ScopeOf<O>>;
+    neg(): NumExpr<S>;
+    abs(): NumExpr<S>;
+    round<O extends NumOperand<Scope> = number>(precision?: O): NumExpr<S | ScopeOf<O>>;
+}
+interface StrExpr<S extends Scope = 'row'> extends Common<string, S> {
+    gt<O extends StrOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    gte<O extends StrOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    lt<O extends StrOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    lte<O extends StrOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    lower(): StrExpr<S>;
+    upper(): StrExpr<S>;
+    trim(): StrExpr<S>;
+    len(): NumExpr<S>;
+    concat<A extends Array<string | number | boolean | Plain<any, Scope>>>(...rest: A): StrExpr<S | ScopeOf<A[number]>>;
+    contains<O extends StrOperand<Scope>>(search: O): BoolExpr<S | ScopeOf<O>>;
+    startsWith<O extends StrOperand<Scope>>(prefix: O): BoolExpr<S | ScopeOf<O>>;
+    endsWith<O extends StrOperand<Scope>>(suffix: O): BoolExpr<S | ScopeOf<O>>;
+    substring<N1 extends NumOperand<Scope>, N2 extends NumOperand<Scope> = number>(start: N1, length?: N2): StrExpr<S | ScopeOf<N1 | N2>>;
+    replace<A extends StrOperand<Scope>, B extends StrOperand<Scope>>(search: A, replacement: B): StrExpr<S | ScopeOf<A | B>>;
+}
+interface BoolExpr<S extends Scope = 'row'> extends Common<boolean, S> {
+    and<O extends BoolOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    /** Logical or. Printed as `if(a, true, b)`, because the lexer cannot read `||`. */
+    or<O extends BoolOperand<Scope>>(other: O): BoolExpr<S | ScopeOf<O>>;
+    not(): BoolExpr<S>;
+}
+/** The expression type for a value type `T` in scope `S`. `any` stays `any`. */
+type ExprFor<T, S extends Scope = 'row'> = 0 extends 1 & T ? any : [T] extends [number] ? NumExpr<S> : [T] extends [string] ? StrExpr<S> : [T] extends [boolean] ? BoolExpr<S> : GenericExpr<T, S>;
+/** Like `ExprFor`, but `null`/`undefined` in `V` become the nullish marker instead of being dropped. */
+type ExprOf<V, S extends Scope = 'row'> = 0 extends 1 & V ? any : [NonNullable<V>] extends [never] ? GenericExpr<V, S> : WithNull<ExprFor<NonNullable<V>, S>, Extract<V, Nullish>>;
+/** The value type of an expression (or of a JS literal used as an operand). */
+type ValueOf<X> = 0 extends 1 & X ? any : X extends number ? number : X extends string ? string : X extends boolean ? boolean : X extends null ? null : X extends ExprBase<infer T, any> ? T | NullOf<X> : unknown;
+/** The scope of an expression (`'row'` for literals). */
+type ScopeOf<X> = IsAny<X> extends true ? 'row' : X extends number | string | boolean | null ? 'row' : X extends ExprBase<any, infer S> ? IsAny<S> extends true ? 'row' : S : 'row';
+/** Names that exist on `Expr` at runtime, so a nested field of that name is not addressable as `o.a.name`. */
+type Clashes = keyof Expr | 'constructor' | 'valueOf' | 'toLocaleString' | 'hasOwnProperty' | 'isPrototypeOf' | 'propertyIsEnumerable';
+/** A nested object is itself an expression of type `V`, so it can be selected, grouped or compared as a whole. */
+type NestedFields<V, N = never> = Plain<V, 'row'> & {
+    readonly [K in keyof V & string as K extends Clashes ? never : K]-?: FieldOf<V[K], N>;
+} & {
+    /** Reach a nested field whose name clashes with an expression method: `o.meta.$('len')`. */
+    $(...segments: string[]): any;
+};
+/** The expression (or nested proxy) for a field of type `V`. */
+type FieldOf<V, P = never> = 0 extends 1 & V ? any : unknown extends V ? GenericExpr<unknown, 'row'> : [NonNullable<V>] extends [never] ? GenericExpr<V, 'row'> : WithNull<[
+    NonNullable<V>
+] extends [number | string | boolean] ? ExprFor<NonNullable<V>, 'row'> : [NonNullable<V>] extends [readonly unknown[] | Date] ? GenericExpr<NonNullable<V>, 'row'> : [NonNullable<V>] extends [object] ? NestedFields<NonNullable<V>, Undef<Extract<V, Nullish> | P>> : GenericExpr<NonNullable<V>, 'row'>, Extract<V, Nullish> | Undef<P>>;
+/**
+ * The row object handed to builder callbacks: `o.total` is a `NumExpr` when the row's
+ * `total` is a number, `o.customer.name` follows nested objects. For `Row = any` every field is `any`.
+ */
+type Fields<Row = any> = 0 extends 1 & Row ? Record<string, any> : {
+    readonly [K in keyof Row & string]-?: FieldOf<Row[K]>;
+};
+/** A field argument of an aggregate or window function: a row expression or a raw pipequery expression. */
+type NumField = string | Plain<number | Nullish, 'row'>;
+type AnyField = string | Plain<any, 'row'>;
+/** A branch/fallback value: expression or JS literal. */
+type Branch = ExprBase<any, Scope> | string | number | boolean | null;
+type Def<T> = NonNullable<T>;
+/** The 24 aggregates as expression builders: `agg.sum(o.total)`, `agg.count()`. */
+interface AggregateHelpers {
+    sum(field: NumField): NumExpr<'agg'>;
+    avg(field: NumField): NumExpr<'agg'>;
+    median(field: NumField): NumExpr<'agg'>;
+    stddev(field: NumField): NumExpr<'agg'>;
+    var(field: NumField): NumExpr<'agg'>;
+    skew(field: NumField): NumExpr<'agg'>;
+    kurt(field: NumField): NumExpr<'agg'>;
+    drawdown(field: NumField): NumExpr<'agg'>;
+    pct(field: NumField): NumExpr<'agg'>;
+    sharpe(field: NumField): NumExpr<'agg'>;
+    calmar(field: NumField): NumExpr<'agg'>;
+    sortino(field: NumField): NumExpr<'agg'>;
+    sum_abs(field: NumField): NumExpr<'agg'>;
+    abs_sum(field: NumField): NumExpr<'agg'>;
+    distinct_count(field: AnyField): NumExpr<'agg'>;
+    count(field?: AnyField): NumExpr<'agg'>;
+    min<E extends Plain<any, 'row'>>(field: E | string): ExprFor<Def<ValueOf<E>>, 'agg'>;
+    max<E extends Plain<any, 'row'>>(field: E | string): ExprFor<Def<ValueOf<E>>, 'agg'>;
+    first_value<E extends Plain<any, 'row'>>(field: E | string): ExprFor<Def<ValueOf<E>>, 'agg'>;
+    last_value<E extends Plain<any, 'row'>>(field: E | string): ExprFor<Def<ValueOf<E>>, 'agg'>;
+    percentile(field: NumField, p: number | Plain<number, 'row'>): NumExpr<'agg'>;
+    vwap(price: NumField, volume: NumField): NumExpr<'agg'>;
+    wavg(value: NumField, weight: NumField): NumExpr<'agg'>;
+    info_ratio(returns: NumField, benchmark: NumField): NumExpr<'agg'>;
+}
+/** Window functions. Valid as a top-level (optionally aliased) field of `select` outside `groupBy`. */
+interface WindowHelpers {
+    running_sum(field: NumField): NumExpr<'win'>;
+    running_avg(field: NumField): NumExpr<'win'>;
+    running_min(field: NumField): NumExpr<'win'>;
+    running_max(field: NumField): NumExpr<'win'>;
+    running_count(field?: AnyField): NumExpr<'win'>;
+    row_number(): NumExpr<'win'>;
+    /** `null` at the edges of the window, so the value is typed `T | null`. */
+    lag<E extends Plain<any, 'row'>>(field: E | string, offset?: number): ExprOf<ValueOf<E> | null, 'win'>;
+    lead<E extends Plain<any, 'row'>>(field: E | string, offset?: number): ExprOf<ValueOf<E> | null, 'win'>;
+}
+/** Scalar functions as free functions. A string argument is a string literal. */
+interface FnHelpers {
+    if<C extends BoolOperand<Scope>, X extends Branch = Branch, Y extends Branch = null>(cond: C, then: X, otherwise?: Y): ExprOf<ValueOf<X> | ValueOf<Y>, ScopeOf<C> | ScopeOf<X> | ScopeOf<Y>>;
+    coalesce<A extends Branch[]>(...args: A): ExprFor<Def<ValueOf<A[number]>>, ScopeOf<A[number]>>;
+    lower<O extends StrOperand<Scope>>(value: O): StrExpr<ScopeOf<O>>;
+    upper<O extends StrOperand<Scope>>(value: O): StrExpr<ScopeOf<O>>;
+    trim<O extends StrOperand<Scope>>(value: O): StrExpr<ScopeOf<O>>;
+    len<O extends StrOperand<Scope>>(value: O): NumExpr<ScopeOf<O>>;
+    abs<O extends NumOperand<Scope>>(value: O): NumExpr<ScopeOf<O>>;
+    round<V extends NumOperand<Scope>, P extends NumOperand<Scope> = number>(value: V, precision?: P): NumExpr<ScopeOf<V | P>>;
+    concat<A extends Array<string | number | boolean | Plain<any, Scope>>>(...args: A): StrExpr<ScopeOf<A[number]>>;
+    contains<V extends StrOperand<Scope>, A extends StrOperand<Scope>>(value: V, search: A): BoolExpr<ScopeOf<V | A>>;
+    startsWith<V extends StrOperand<Scope>, A extends StrOperand<Scope>>(value: V, prefix: A): BoolExpr<ScopeOf<V | A>>;
+    endsWith<V extends StrOperand<Scope>, A extends StrOperand<Scope>>(value: V, suffix: A): BoolExpr<ScopeOf<V | A>>;
+    substring<V extends StrOperand<Scope>, N1 extends NumOperand<Scope>, N2 extends NumOperand<Scope> = number>(value: V, start: N1, length?: N2): StrExpr<ScopeOf<V | N1 | N2>>;
+    replace<V extends StrOperand<Scope>, A extends StrOperand<Scope>, B extends StrOperand<Scope>>(value: V, search: A, replacement: B): StrExpr<ScopeOf<V | A | B>>;
+}
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** The row type of `select({ a: expr, ... })`. */
+type Shape<R> = Simplify<{
+    [K in keyof R]: ValueOf<R[K]>;
+}>;
+/**
+ * The row type of a `select`/`map` object literal after `groupBy`. The engine evaluates fields
+ * against `{ ...keyColumns, _group }`: key columns are named after the last path segment (or `key`),
+ * so any row-scope field may be missing. Aggregate-only values stay precise; JS literals too.
+ */
+type GroupedShape<R> = Simplify<{
+    [K in keyof R]: R[K] extends number | string | boolean | null ? ValueOf<R[K]> : 'row' extends ScopeOf<R[K]> ? ValueOf<R[K]> | undefined : ValueOf<R[K]>;
+}>;
+/** Row type after `map`/`join`: the right keys win. `any` on either side gives `any`. */
+type Merge<A, B> = 0 extends 1 & A ? any : 0 extends 1 & B ? any : Simplify<Omit<A, keyof B> & B>;
+
+declare const NODE: unique symbol;
+
+/** Values accepted as operands: expressions or JS literals (strings are always string literals). */
+type Operand = Expr | string | number | boolean | null;
+/** Field positions of aggregates / window functions: an expression, or a raw pipequery expression string. */
+type FieldInput = Expr | string;
+/** A sort key from `asc()`/`desc()`. The scope is a compile-time tag: `sort` accepts `'row'` keys only. */
+declare class SortKey<S extends Scope = 'row'> {
+    readonly expression: Expression;
+    readonly direction: 'asc' | 'desc';
+    readonly __scope?: S;
+    constructor(expression: Expression, direction: 'asc' | 'desc');
+}
+/** The AST node behind an expression. */
+declare function toAst(value: unknown, what?: string): Expression;
+/**
+ * A pipequery expression. Immutable: every method returns a new expression.
+ *
+ * Inside builder callbacks, `o.total` is an `Expr` (a field access) whose unknown
+ * property names extend the path: `o.customer.name`. Names that collide with an
+ * `Expr` method (`len`, `round`, `replace`, ...) are reached with `.$('len')` or `col()`.
+ */
+declare class Expr {
+    readonly [NODE]: Expression;
+    readonly [TYPE]?: any;
+    readonly [SCOPE]?: 'row';
+    readonly [ALIAS]?: false;
+    constructor(node: Expression);
+    gt(other: Operand): Expr;
+    gte(other: Operand): Expr;
+    lt(other: Operand): Expr;
+    lte(other: Operand): Expr;
+    eq(other: Operand): Expr;
+    ne(other: Operand): Expr;
+    and(other: Operand): Expr;
+    /**
+     * Logical or. The AST uses `if(a, true, b)` for proven boolean `a`, and
+     * `if(a, a, b)` otherwise: the lexer cannot parse `||` (it reads two PIPE tokens).
+     * Both forms have the engine's `a || b` value semantics and round-trip through
+     * `parseQuery`. In the latter, `a` is evaluated twice; expressions are pure.
+     *
+     * Unknown-valued chains stay linear by associating right: `a.or(b).or(c)`
+     * becomes `if(a, a, if(b, b, c))`.
+     */
+    or(other: Operand): Expr;
+    not(): Expr;
+    plus(other: Operand): Expr;
+    minus(other: Operand): Expr;
+    times(other: Operand): Expr;
+    div(other: Operand): Expr;
+    mod(other: Operand): Expr;
+    neg(): Expr;
+    lower(): Expr;
+    upper(): Expr;
+    len(): Expr;
+    abs(): Expr;
+    round(precision?: Operand): Expr;
+    trim(): Expr;
+    concat(...rest: Operand[]): Expr;
+    coalesce(...rest: Operand[]): Expr;
+    contains(search: Operand): Expr;
+    startsWith(prefix: Operand): Expr;
+    endsWith(suffix: Operand): Expr;
+    substring(start: Operand, length?: Operand): Expr;
+    replace(search: Operand, replacement: Operand): Expr;
+    /** `expr as name`. Re-aliasing replaces the previous alias. */
+    as<N extends string>(name: N): AliasedExpr<N, any, 'row'>;
+    asc(): SortKey;
+    desc(): SortKey;
+    /** Extend a field path with names that collide with `Expr` methods: `o.customer.$('len')`. */
+    $(...segments: string[]): Expr;
+    /** The pipequery text of this expression. */
+    toString(): string;
+}
+/**
+ * Field access from a dotted path: `col('customer.name')` or `col('customer', 'name')`.
+ * Give the field's type to get typed operators: `col<number>('total').gt(1)`.
+ */
+declare function col<V = any>(...path: string[]): FieldOf<V>;
+/** A literal value (strings are string literals, never field names). */
+declare function lit(value: number): NumExpr;
+declare function lit(value: string): StrExpr;
+declare function lit(value: boolean): BoolExpr;
+declare function lit(value: null): GenericExpr<null>;
+
+declare const agg: AggregateHelpers;
+declare const fn: FnHelpers;
+declare const win: WindowHelpers;
+
+/** Row-scope expression without alias: the position of where/sort/groupBy keys and join conditions. */
+type RowExpr = Plain<any, 'row'> | Expr;
+/** A single expression: raw pipequery string, expression, or a callback receiving the row. */
+type ExprInput<Row = any, X = ExprBase> = string | X | Expr | ((o: Fields<Row>) => X | Expr);
+/** One or more expressions. */
+type ExprListInput<Row = any, X = ExprBase> = string | X | Expr | ((o: Fields<Row>) => X | X[] | Expr | Expr[]);
+/** Values of an object literal passed to `select`/`map`. */
+type SelectValue<S extends Scope = Scope> = string | number | boolean | null | ExprBase<any, S>;
+/** `select`/`map` item: also accepts `{ alias: expression }` objects. */
+type SelectInput<Row = any, S extends Scope = Scope> = string | ExprBase<any, S> | Record<string, SelectValue<S>> | ((o: Fields<Row>) => ExprBase<any, S> | ExprBase<any, S>[] | Record<string, SelectValue<S>>);
+type SortInput<Row = any> = string | RowExpr | SortKey | ((o: Fields<Row>) => RowExpr | SortKey | Array<RowExpr | SortKey>);
+/** A join condition: raw string, expression, `(left, right) => expression`, or `{ on: [left, right] }`. */
+type JoinInput<Row = any, Right = any> = string | BoolExpr<'row'> | Expr | ((left: Fields<Row>, right: Fields<Right>) => BoolExpr<'row'> | Expr) | {
+    on: [string | RowExpr, string | RowExpr];
+};
+/** Rows seen by operations that follow `groupBy`: `{ ...keys, _group }`, so untyped. */
+type Cur<Row, G extends boolean> = G extends true ? any : Row;
+/** Scopes `select` accepts: aggregates after `groupBy`, window functions otherwise. */
+type SelectScope<G extends boolean> = G extends true ? 'row' | 'agg' : 'row' | 'win';
+/** Scopes `map` accepts: aggregates after `groupBy`, plain row expressions otherwise. */
+type MapScope<G extends boolean> = G extends true ? 'row' | 'agg' : 'row';
+type NumArg<Row> = NumField | ((o: Fields<Row>) => Plain<number, 'row'>);
+type AnyArg<Row> = AnyField | ((o: Fields<Row>) => Plain<any, 'row'>);
+type ScalarOf<E> = Scalar<ValueOf<E> | null>;
+/** Terminal aggregates exist only before `groupBy` (after it they are `never`). */
+type Ungrouped<G extends boolean, F> = G extends true ? never : F;
+type NumericAggregate = 'sum' | 'avg' | 'median' | 'stddev' | 'var' | 'skew' | 'kurt' | 'drawdown' | 'pct' | 'sharpe' | 'calmar' | 'sortino' | 'sum_abs' | 'abs_sum';
+type AnyAggregate = 'min' | 'max' | 'first_value' | 'last_value';
+/**
+ * Terminal aggregate methods. They end the pipeline and return a `Scalar`.
+ * After `groupBy` they are `never`: use `select`, `map`, `rollup` or `pivot` there.
+ */
+type TerminalAggregates<Row = any, G extends boolean = false> = {
+    [K in NumericAggregate]: Ungrouped<G, (field: NumArg<Row>) => Scalar<number>>;
+} & {
+    [K in AnyAggregate]: Ungrouped<G, <E extends Plain<any, 'row'>>(field: E | string | ((o: Fields<Row>) => E)) => ScalarOf<E>>;
+} & {
+    distinct_count: Ungrouped<G, (field: AnyArg<Row>) => Scalar<number>>;
+    count: Ungrouped<G, (field?: AnyArg<Row>) => Scalar<number>>;
+    percentile: Ungrouped<G, (field: NumArg<Row>, p: number | Plain<number, 'row'>) => Scalar<number>>;
+    vwap: Ungrouped<G, (price: NumArg<Row>, volume: NumArg<Row>) => Scalar<number>>;
+    wavg: Ungrouped<G, (value: NumArg<Row>, weight: NumArg<Row>) => Scalar<number>>;
+    info_ratio: Ungrouped<G, (returns: NumArg<Row>, benchmark: NumArg<Row>) => Scalar<number>>;
+};
+declare abstract class Built {
+    protected readonly sourceName: string;
+    protected readonly ops: readonly Operation[];
+    protected constructor(sourceName: string, ops: readonly Operation[]);
+    private compiled?;
+    /** The pipeline AST (a fresh object each time; expression nodes are shared). */
+    get ast(): Pipeline;
+    /** Canonical pipequery text, via `printQuery`. */
+    toString(): string;
+    /** Compile the AST directly (no print + re-parse). */
+    compile(): CompiledQuery;
+    protected execute(context: DataContext | readonly unknown[]): unknown;
+}
+/** The result of a terminal operation (`sum`, `count`, `reduce`, ...): one value, no further ops. */
+declare class Scalar<T = unknown> extends Built {
+    /** @internal */
+    constructor(source: string, ops: readonly Operation[]);
+    /** Run against `{ source: rows, ... }` or, for plain arrays, the rows of this query's source. */
+    run(context: DataContext | readonly unknown[]): T;
+}
+interface Query<Row = any, G extends boolean = false> extends TerminalAggregates<Row, G> {
+}
+/**
+ * Immutable fluent pipeline. Every method returns a new `Query` (or a `Scalar` for
+ * terminal operations), validated as it is added.
+ */
+declare class Query<Row = any, G extends boolean = false> extends Built {
+    /** @internal use `from()` */
+    constructor(source: string, ops?: readonly Operation[]);
+    private isGrouped;
+    /** Validate and append operations. */
+    private extend;
+    private terminal;
+    /** Run against `{ source: rows, ... }` or, for plain arrays, the rows of this query's source. */
+    run<T = Cur<Row, G>[]>(context: DataContext | readonly unknown[]): T;
+    /** Rows matching the condition. Aggregates and window functions are not allowed here. */
+    where(condition: ExprInput<Cur<Row, G>, BoolExpr<'row'>>): Query<Cur<Row, G>, false>;
+    /**
+     * Pick fields. An object literal gives a typed output row:
+     * `select((o) => ({ id: o.id, name: o.customer.name }))`. Aggregates are allowed after
+     * `groupBy`, window functions (`win.*`) before it. Other forms give untyped rows.
+     */
+    select<R extends Record<string, SelectValue<SelectScope<G>>>>(fields: R | ((o: Fields<Row>) => R)): Query<G extends true ? GroupedShape<R> : Shape<R>, false>;
+    select(...fields: SelectInput<Row, SelectScope<G>>[]): Query<any, false>;
+    /** Sort keys must be row expressions: no aliases, no aggregates. */
+    sort(...keys: SortInput<Cur<Row, G>>[]): Query<Cur<Row, G>, false>;
+    /**
+     * Group rows. Follow with `select`/`map` (aggregates allowed), `rollup` or `pivot`.
+     * A bare `groupBy` yields `{ ...keys, _group }` rows and is rarely what you want to run.
+     * No keys groups everything into one group.
+     */
+    groupBy(...keys: ExprListInput<Row, RowExpr>[]): Query<Row, true>;
+    /**
+     * Join with another source from the run context. The engine merges rows as
+     * `{ ...left, ...right }`, so on a name collision the right value wins.
+     * `FieldAccess == FieldAccess` conditions (also `{ on: [left, right] }`) use the hash join.
+     * In callbacks both arguments are plain row proxies; for non-equi conditions the
+     * condition sees the merged row, so qualify nothing and avoid colliding names.
+     */
+    join<Right = any>(right: string, on: JoinInput<Cur<Row, G>, Right>): Query<Merge<Cur<Row, G>, Right>, false>;
+    first(count: number): Query<Cur<Row, G>, false>;
+    /**
+     * The last `count` rows. Engine quirk, passed through unchanged: `last(0)` returns
+     * every row (the engine does `slice(-0)`), unlike `first(0)` which returns none.
+     */
+    last(count: number): Query<Cur<Row, G>, false>;
+    /** Distinct rows, or distinct by the given fields. */
+    distinct(...fields: ExprListInput<Cur<Row, G>, RowExpr>[]): Query<Cur<Row, G>, false>;
+    /** Flatten nested arrays, or the array held in `field`. */
+    flatten(field?: ExprInput<Cur<Row, G>, RowExpr>): Query<any, false>;
+    transpose(headerField?: ExprInput<Cur<Row, G>, RowExpr>): Query<any, false>;
+    /**
+     * Group keys first, then at least one aggregate:
+     * `rollup('region', agg.sum(o.total).as('total'))`.
+     */
+    rollup(...items: ExprListInput<Cur<Row, G>, ExprBase<any, 'row' | 'agg'>>[]): Query<any, false>;
+    /** Pivot on `field`, computing the given aggregates for each pivot value. */
+    pivot(field: ExprInput<Cur<Row, G>, RowExpr>, ...aggregates: ExprListInput<Cur<Row, G>, ExprBase<any, 'agg'>>[]): Query<any, false>;
+    /** Add or overwrite fields, keeping the others (unlike `select`). */
+    /**
+     * With an object literal the output row is typed: the input row with the new fields on top.
+     * After `groupBy` rows are untyped and aggregates are allowed (the query stays grouped).
+     */
+    map<R extends Record<string, SelectValue<MapScope<G>>>>(fields: R | ((o: Fields<Row>) => R)): Query<Merge<Cur<Row, G>, Shape<R>>, G>;
+    map(...fields: SelectInput<Row, MapScope<G>>[]): Query<any, G>;
+    /**
+     * Fold rows into one value. `initial` cannot reference fields; the accumulator sees the
+     * row's fields plus `_acc`: `reduce(0, (o) => o._acc.plus(o.total))`.
+     * Strings are raw pipequery fragments; use `lit()` for string literals.
+     */
+    reduce<T = any>(initial: Operand | ExprInput<Row, RowExpr>, accumulator: ExprInput<Row & {
+        _acc: T;
+    }, RowExpr>): Scalar<T>;
+    /**
+     * Escape hatch: splice raw pipequery operations, parsed with the real parser.
+     * Accepts `'where(x > 1)'`, `'where(x > 1) | first(3)'` (optional leading `|`), or an AST operation.
+     */
+    pipe(raw: string | Operation): Query<any, boolean>;
+    /** @internal used by the terminal aggregate methods installed below. */
+    protected aggregate(name: string, args: unknown[]): Scalar<any>;
+}
+/**
+ * Start a query. `from<Order>('orders')` reads from the `orders` source; with no name the
+ * query reads from `_data`, the source the engine uses for plain row arrays.
+ */
+declare function from<Row = any>(source?: string): Query<Row, false>;
+
+/** Error thrown by the builder for invalid input (bad names, arities, misplaced expressions). */
+declare class BuilderError extends Error {
+    constructor(message: string);
+}
+
+export { type AggregateHelpers, type AliasedExpr, type BoolExpr, BuilderError, Expr, type ExprBase, type ExprFor, type ExprInput, type ExprListInput, type ExprOf, Expression, type FieldInput, type FieldOf, type Fields, type FnHelpers, type GenericExpr, type GroupedShape, type JoinInput, type Merge, type Nullish, type NumExpr, type Operand, Operation, Pipeline, type Plain, Query, Scalar, type Scope, type SelectInput, type SelectValue, type Shape, type SortInput, SortKey, type StrExpr, type TerminalAggregates, type ValueOf, type WindowHelpers, agg, col, fn, from, lit, toAst, win };