@elaraai/east 1.0.83 → 1.0.85

package/dist/src/query/jq/spans.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Where the nodes of a jq program are in its text.
+ *
+ * A {@link JqType} value is an East value and carries no positions, so the
+ * parser and the printer return them beside it: a map from each node's path
+ * in the tree to its range of text.
+ *
+ * @packageDocumentation
+ */
+import type { ValueTypeOf } from "../../types.js";
+import type { JqPatternType, JqType, QuerySpanType } from "../types.js";
+/** A node of a jq program. */
+export type JqNode = ValueTypeOf<typeof JqType>;
+/** A destructuring pattern of a jq program. */
+export type JqPattern = ValueTypeOf<typeof JqPatternType>;
+/** A range of text: `from` to `to`, exclusive, in UTF-16 code units. */
+export interface JqRange {
+    /** Its first offset. */
+    from: number;
+    /** The offset after its last. */
+    to: number;
+}
+/**
+ * The ranges of text a program's nodes cover, by the nodes' paths.
+ *
+ * @remarks
+ * A node's path lists, from the root, each ancestor's case and the field or
+ * index that leads to the next node: `"pipe.left.call.args[1]"` is the second
+ * argument of the call on the left of the root pipe. The root's path is `""`.
+ * An option's payload is its case, `some`: `"array.some"` is the body of
+ * `[f]`. Patterns are nodes too: `"bind.patterns[0].array[1]"`.
+ */
+export type JqSpans = ReadonlyMap<string, JqRange>;
+/**
+ * A child of a node, with the step that leads to it.
+ *
+ * @internal
+ */
+export type JqChild = {
+    step: string;
+    node: JqNode;
+    pattern?: undefined;
+} | {
+    step: string;
+    pattern: JqPattern;
+    node?: undefined;
+};
+/**
+ * Joins a node's path and a step to a child.
+ *
+ * @param path - the node's path
+ * @param step - the step, as {@link jqChildren} gives it
+ * @returns the child's path
+ *
+ * @internal
+ */
+export declare function childPath(path: string, step: string): string;
+/**
+ * The children of a node, in the order they are written, with the steps that
+ * lead to them.
+ *
+ * @param node - a program node
+ * @returns its children
+ *
+ * @internal
+ */
+export declare function jqChildren(node: JqNode): JqChild[];
+/**
+ * The children of a pattern, with the steps that lead to them.
+ *
+ * @param pattern - a pattern
+ * @returns its sub-patterns
+ *
+ * @internal
+ */
+export declare function jqPatternChildren(pattern: JqPattern): {
+    step: string;
+    pattern: JqPattern;
+}[];
+/**
+ * The range a node covers.
+ *
+ * @param spans - a program's spans, from the parser or the printer
+ * @param path - the node's path
+ * @returns its range, or `undefined` when the program has no such node
+ *
+ * @example
+ * ```ts
+ * const { spans } = parseJq(".orders | length");
+ * spanOf(spans, "pipe.right");   // { from: 10, to: 16 }
+ * ```
+ */
+export declare function spanOf(spans: JqSpans, path: string): JqRange | undefined;
+/**
+ * The innermost node covering an offset.
+ *
+ * @param spans - a program's spans, from the parser or the printer
+ * @param offset - an offset in the text, from 0 to its length
+ * @returns the path of the smallest range that holds the offset (its ends
+ *   included), the deeper of two equal ranges; `undefined` when none does
+ *
+ * @example
+ * ```ts
+ * const { spans } = parseJq(".orders | length");
+ * pathAt(spans, 12);   // "pipe.right"
+ * ```
+ */
+export declare function pathAt(spans: JqSpans, offset: number): string | undefined;
+/**
+ * Locates a range of text as a {@link QuerySpanType} value: its offset and
+ * length, and the line and column it starts at.
+ *
+ * @param text - the text
+ * @param from - the range's first offset, in UTF-16 code units
+ * @param to - the offset after its last
+ * @returns the span: `offset` 0-based, `line` and `column` 1-based, all in
+ *   UTF-16 code units
+ *
+ * @remarks
+ * A line ends at `\n`, `\r\n` or a lone `\r`. A tab is one column, and a
+ * character outside the Basic Multilingual Plane is two.
+ *
+ * @example
+ * ```ts
+ * toQuerySpan(".a\n| .b", 5, 7);   // { column: 3n, length: 2n, line: 2n, offset: 5n }
+ * ```
+ */
+export declare function toQuerySpan(text: string, from: number, to: number): ValueTypeOf<typeof QuerySpanType>;
+//# sourceMappingURL=spans.d.ts.map

package/dist/src/query/jq/spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.d.ts","sourceRoot":"","sources":["../../../../src/query/jq/spans.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAExE,8BAA8B;AAC9B,MAAM,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,MAAM,CAAC,CAAC;AAEhD,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,wEAAwE;AACxE,MAAM,WAAW,OAAO;IACtB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAmElD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,CAAA;CAAE,EAAE,CAU5F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAExE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAgBrG"}

package/dist/src/query/jq/spans.js

@@ -0,0 +1,195 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Joins a node's path and a step to a child.
+ *
+ * @param path - the node's path
+ * @param step - the step, as {@link jqChildren} gives it
+ * @returns the child's path
+ *
+ * @internal
+ */
+export function childPath(path, step) {
+    return path === "" ? step : `${path}.${step}`;
+}
+/**
+ * The children of a node, in the order they are written, with the steps that
+ * lead to them.
+ *
+ * @param node - a program node
+ * @returns its children
+ *
+ * @internal
+ */
+export function jqChildren(node) {
+    const n = (step, child) => ({ step, node: child });
+    const p = (step, child) => ({ step, pattern: child });
+    const some = (step, option) => option.type === "some" ? [n(`${step}.some`, option.value)] : [];
+    switch (node.type) {
+        case "alternative":
+        case "comma":
+        case "pipe":
+        case "binary":
+            return [n(`${node.type}.left`, node.value.left), n(`${node.type}.right`, node.value.right)];
+        case "array":
+            return some("array", node.value);
+        case "bind":
+            return [
+                n("bind.source", node.value.source),
+                ...node.value.patterns.map((pattern, i) => p(`bind.patterns[${i}]`, pattern)),
+                n("bind.body", node.value.body),
+            ];
+        case "call":
+            return node.value.args.map((arg, i) => n(`call.args[${i}]`, arg));
+        case "def":
+            return [n("def.body", node.value.body), n("def.rest", node.value.rest)];
+        case "field":
+            return [n("field.target", node.value.target)];
+        case "foreach":
+            return [
+                n("foreach.source", node.value.source), p("foreach.pattern", node.value.pattern),
+                n("foreach.init", node.value.init), n("foreach.update", node.value.update),
+                ...some("foreach.extract", node.value.extract),
+            ];
+        case "format":
+            return some("format.string", node.value.string);
+        case "if":
+            return [
+                ...node.value.branches.flatMap((branch, i) => [
+                    n(`if.branches[${i}].condition`, branch.condition), n(`if.branches[${i}].then`, branch.then),
+                ]),
+                ...some("if.otherwise", node.value.otherwise),
+            ];
+        case "index":
+            return [n("index.target", node.value.target), n("index.index", node.value.index)];
+        case "iterate":
+            return [n("iterate.target", node.value.target)];
+        case "label":
+            return [n("label.body", node.value.body)];
+        case "negate":
+            return [n("negate", node.value)];
+        case "object":
+            return node.value.flatMap((entry, i) => [
+                ...(entry.key.type === "computed" ? [n(`object[${i}].key.computed`, entry.key.value)] : []),
+                ...some(`object[${i}].value`, entry.value),
+            ]);
+        case "reduce":
+            return [
+                n("reduce.source", node.value.source), p("reduce.pattern", node.value.pattern),
+                n("reduce.init", node.value.init), n("reduce.update", node.value.update),
+            ];
+        case "slice":
+            return [n("slice.target", node.value.target), ...some("slice.from", node.value.from), ...some("slice.to", node.value.to)];
+        case "string":
+            return node.value.flatMap((part, i) => part.type === "interpolate" ? [n(`string[${i}].interpolate`, part.value)] : []);
+        case "try":
+            return [n("try.body", node.value.body), ...some("try.catch", node.value.catch)];
+        case "update":
+            return [n("update.path", node.value.path), n("update.value", node.value.value)];
+        case "break":
+        case "descend":
+        case "identity":
+        case "literal":
+        case "variable":
+            return [];
+    }
+}
+/**
+ * The children of a pattern, with the steps that lead to them.
+ *
+ * @param pattern - a pattern
+ * @returns its sub-patterns
+ *
+ * @internal
+ */
+export function jqPatternChildren(pattern) {
+    switch (pattern.type) {
+        case "array":
+            return pattern.value.map((item, i) => ({ step: `array[${i}]`, pattern: item }));
+        case "object":
+            return pattern.value.flatMap((entry, i) => entry.value.type === "some" ? [{ step: `object[${i}].value.some`, pattern: entry.value.value }] : []);
+        case "variable":
+            return [];
+    }
+}
+/**
+ * The range a node covers.
+ *
+ * @param spans - a program's spans, from the parser or the printer
+ * @param path - the node's path
+ * @returns its range, or `undefined` when the program has no such node
+ *
+ * @example
+ * ```ts
+ * const { spans } = parseJq(".orders | length");
+ * spanOf(spans, "pipe.right");   // { from: 10, to: 16 }
+ * ```
+ */
+export function spanOf(spans, path) {
+    return spans.get(path);
+}
+/**
+ * The innermost node covering an offset.
+ *
+ * @param spans - a program's spans, from the parser or the printer
+ * @param offset - an offset in the text, from 0 to its length
+ * @returns the path of the smallest range that holds the offset (its ends
+ *   included), the deeper of two equal ranges; `undefined` when none does
+ *
+ * @example
+ * ```ts
+ * const { spans } = parseJq(".orders | length");
+ * pathAt(spans, 12);   // "pipe.right"
+ * ```
+ */
+export function pathAt(spans, offset) {
+    let best;
+    for (const [path, { from, to }] of spans) {
+        if (offset < from || offset > to)
+            continue;
+        const width = to - from;
+        if (best === undefined || width < best.width || (width === best.width && path.length > best.path.length)) {
+            best = { path, width };
+        }
+    }
+    return best?.path;
+}
+/**
+ * Locates a range of text as a {@link QuerySpanType} value: its offset and
+ * length, and the line and column it starts at.
+ *
+ * @param text - the text
+ * @param from - the range's first offset, in UTF-16 code units
+ * @param to - the offset after its last
+ * @returns the span: `offset` 0-based, `line` and `column` 1-based, all in
+ *   UTF-16 code units
+ *
+ * @remarks
+ * A line ends at `\n`, `\r\n` or a lone `\r`. A tab is one column, and a
+ * character outside the Basic Multilingual Plane is two.
+ *
+ * @example
+ * ```ts
+ * toQuerySpan(".a\n| .b", 5, 7);   // { column: 3n, length: 2n, line: 2n, offset: 5n }
+ * ```
+ */
+export function toQuerySpan(text, from, to) {
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < from && i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if (c === 10 || (c === 13 && text.charCodeAt(i + 1) !== 10)) {
+            line += 1;
+            lineStart = i + 1;
+        }
+    }
+    return {
+        column: BigInt(from - lineStart + 1),
+        length: BigInt(to - from),
+        line: BigInt(line),
+        offset: BigInt(from),
+    };
+}
+//# sourceMappingURL=spans.js.map

package/dist/src/query/jq/spans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.js","sourceRoot":"","sources":["../../../../src/query/jq/spans.ts"],"names":[],"mappings":"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"}

package/dist/src/query/jq/split.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import type { FunctionExpr } from "../../expr/function.js";
+import { type EastType } from "../../types.js";
+import type { CheckJqResult } from "./check.js";
+import { type JqRange } from "./spans.js";
+/** Options for {@link splitJq}. */
+export interface SplitJqOptions {
+    /** A `many` query's limit, as `translateJq`'s: the final function keeps this many outputs, and one more, so a caller can tell they were cut short. */
+    maxOutputs?: number;
+    /**
+     * The rows a piece folds into its table before it sends the table's entries
+     * on; 32,768 when omitted. A test forces small flushes with it.
+     *
+     * @internal
+     */
+    flushRows?: number;
+    /**
+     * The share of a flush's rows its table's keys may be: at one key more, a
+     * piece sends the table on and the rest of its rows straight on; 1/32 when
+     * omitted. A test forces the bypass with 0, and stops it with 1.
+     *
+     * @internal
+     */
+    bypassRatio?: number;
+}
+/** A query split over one dataset's pieces, or why it runs as one unit. */
+export type JqSplit = JqSplitCall | JqWhole;
+/**
+ * A query split over one root dataset's pieces: the parts of a split call.
+ *
+ * @remarks
+ * A split call's arguments are the query's inputs, in {@link JqSplitCall.inputs}'
+ * order, the one named {@link JqSplitCall.over} partitioned. Each piece runs
+ * {@link JqSplitCall.piece} over its piece of that dataset and the other inputs
+ * whole, emitting into {@link JqSplitCall.output}'s kind; {@link JqSplitCall.then}
+ * runs once over the assembled output and then the inputs, and gives the
+ * query's result, exactly as `translateJq`'s translation gives it.
+ */
+export interface JqSplitCall {
+    readonly kind: "split";
+    /** The root field whose dataset the pieces are cut from. */
+    readonly over: string;
+    /** The inputs the piece program and the final function take, in order: the root fields the query reads, as `translateJq`'s. */
+    readonly inputs: readonly {
+        readonly name: string;
+        readonly type: EastType;
+    }[];
+    /** The query's result type, as `translateJq`'s: `T`, `Option<T>` or `Array<T>` by its multiplicity. */
+    readonly resultType: EastType;
+    /** How the pieces' outputs combine: the split call's output kind. */
+    readonly output: JqSplitOutput;
+    /**
+     * The program each piece runs: a function of the inputs and then `emit`,
+     * which gives nothing; `over`'s input is the piece.
+     *
+     * @returns the function
+     */
+    piece(): FunctionExpr<any[], any>;
+    /**
+     * The final function, of the assembled output and then the inputs, which
+     * gives the query's result; `null` when the assembled output is the result.
+     *
+     * @returns the function, or `null`
+     */
+    then(): FunctionExpr<any[], any> | null;
+    /** What the split does, for its explanation. */
+    readonly stages: JqSplitStages;
+    /** The root fields bound before the stream: every piece reads each whole. */
+    readonly broadcast: readonly string[];
+    /**
+     * The root fields bound before the stream that the pieces read only at the
+     * row's key: dicts keyed as the dataset is, which a split call partitions
+     * with it, cut at the same keys (#942).
+     */
+    readonly copartitioned: readonly string[];
+    /**
+     * A join the pieces could read by key instead of whole: the split call's
+     * rows re-keyed first, then joined cut at the same keys; `null` when the
+     * query has none (#942).
+     */
+    readonly rekey: JqRekey | null;
+    /** The reads that skip what they don't need. */
+    readonly pruning: readonly JqPruning[];
+}
+/**
+ * A join a split can make by key instead of reading the other side whole in
+ * every piece (#942): when both datasets are large, the rows are first
+ * re-keyed by the join key in a split call of their own, and the query's
+ * split call then reads the re-keyed rows and the other side cut at the same
+ * keys, every row meeting its key in its piece.
+ *
+ * @remarks
+ * Re-keyed rows reach the pieces grouped by key, not in input order, so only
+ * a query whose combine does not depend on the rows' order re-keys: totals
+ * that count, add numbers, take the least or the greatest, test, or unite, a
+ * grouping by such totals, `unique`, and a `reduce` that adds numbers. The
+ * join call's answer is the split's: its output kind, programs and final
+ * function, a Float sum added in another grouping.
+ */
+export interface JqRekey {
+    /** The root field the pieces read by key: the join's other side, a dict. */
+    readonly name: string;
+    /** The join key's jq: a field of the row, each lookup's. */
+    readonly key: JqRange;
+    /** The join key's type: the other side's keys'. */
+    readonly keyType: EastType;
+    /** The re-key call's output: each key's rows, concatenated in input order. */
+    readonly output: {
+        readonly kind: "dict";
+        readonly type: EastType;
+        merge(): FunctionExpr<any[], any>;
+    };
+    /**
+     * The program each piece of the re-key call runs: a function of the
+     * dataset's piece and then `emit`, which sends each row under its key.
+     *
+     * @returns the function
+     */
+    piece(): FunctionExpr<any[], any>;
+    /** The join call's inputs: the split's, the dataset's re-keyed. */
+    readonly inputs: readonly {
+        readonly name: string;
+        readonly type: EastType;
+    }[];
+    /**
+     * The program each piece of the join call runs: the split's, over the
+     * re-keyed rows, each key's in turn.
+     *
+     * @returns the function
+     */
+    joinPiece(): FunctionExpr<any[], any>;
+    /**
+     * The join call's final function: the split's, of the assembled output and
+     * then the join call's inputs; `null` when the assembled output is the
+     * result.
+     *
+     * @returns the function, or `null`
+     */
+    joinThen(): FunctionExpr<any[], any> | null;
+}
+/**
+ * How a split call's pieces combine: its output kind, with its programs and
+ * its zero.
+ *
+ * @remarks
+ * - `array`: the pieces' rows concatenated in input order.
+ * - `set`: the distinct rows.
+ * - `dict`: rows by key, the values of equal keys folded with `merge`, a
+ *   function of the key and two values, in input order; no `merge` keeps the
+ *   first.
+ * - `fold`: every piece's value folded with `combine`, a function of two
+ *   values, starting from `zero`, in input order.
+ */
+export type JqSplitOutput = {
+    readonly kind: "array";
+    readonly type: EastType;
+} | {
+    readonly kind: "set";
+    readonly type: EastType;
+} | {
+    readonly kind: "dict";
+    readonly type: EastType;
+    merge(): FunctionExpr<any[], any>;
+} | {
+    readonly kind: "fold";
+    readonly type: EastType;
+    readonly zero: unknown;
+    combine(): FunctionExpr<any[], any>;
+};
+/** The parts of a query a split runs where, as ranges of its text. */
+export interface JqSplitStages {
+    /** What each piece runs: from the read of the dataset through the last step done row by row. */
+    readonly piece: JqRange;
+    /** How the pieces' outputs combine. */
+    readonly combine: JqCombine;
+    /** What the final function runs once over the combined result; `null` when nothing follows the combine. */
+    readonly then: JqRange | null;
+}
+/**
+ * How a split's pieces' outputs combine, as its explanation says it.
+ *
+ * @remarks
+ * - `concat`: the rows, concatenated in input order.
+ * - `totals`: totals over every row, each combined by its rule.
+ * - `group`: rows grouped by a key, each group's totals combined by their
+ *   rules; with no totals, each group's rows are collected.
+ * - `distinct`: the distinct rows (`unique`).
+ * - `distinct_by`: the first row of each key (`unique_by`).
+ * - `reduce`: a `reduce` into a dict, its updates combined by key, added
+ *   (`+=`) or the last kept (`=`).
+ * - `top`: the first `rows` rows of a sort (`sort_by(g) | .[:n]`,
+ *   `sort | first`), each piece's kept and merged by the key `g` gives
+ *   (`null` for `sort`, by the row), then by input order (#942).
+ */
+export type JqCombine = {
+    readonly kind: "concat";
+} | {
+    readonly kind: "totals";
+    readonly range: JqRange;
+    readonly totals: readonly JqTotal[];
+} | {
+    readonly kind: "group";
+    readonly range: JqRange;
+    readonly key: JqRange;
+    readonly totals: readonly JqTotal[] | null;
+} | {
+    readonly kind: "distinct";
+    readonly range: JqRange;
+} | {
+    readonly kind: "distinct_by";
+    readonly range: JqRange;
+    readonly key: JqRange;
+} | {
+    readonly kind: "reduce";
+    readonly range: JqRange;
+    readonly key: JqRange;
+    readonly update: "add" | "replace";
+} | {
+    readonly kind: "top";
+    readonly range: JqRange;
+    readonly key: JqRange | null;
+    readonly rows: number;
+};
+/**
+ * One total, and the rule its pieces' parts combine by: `count` counted,
+ * `add` added as `add` adds, `min` and `max` the least and the greatest (by a
+ * key, for `min_by` and `max_by`), `first` and `last`, `any` (or) and `all`
+ * (and), and `union`, the distinct values.
+ */
+export interface JqTotal {
+    /** The total's jq. */
+    readonly range: JqRange;
+    /** How its parts combine. */
+    readonly rule: "count" | "add" | "min" | "max" | "first" | "last" | "any" | "all" | "union";
+}
+/** A query that runs as one unit, and why. */
+export interface JqWhole {
+    readonly kind: "whole";
+    /** Why it is not split. */
+    readonly reason: JqWholeReason;
+    /** The reads that skip what they don't need. */
+    readonly pruning: readonly JqPruning[];
+}
+/**
+ * Why a query runs as one unit.
+ *
+ * @remarks
+ * - `no_stream`: it works through no dataset's rows: it reads a count, a key,
+ *   or a value whole.
+ * - `nested`: it works through a dataset's rows inside an expression, not as
+ *   its own pipeline.
+ * - `stops_early`: it keeps only its first outputs, which one unit stops for
+ *   as soon as it has them; `range` is the step that keeps them, or `null`
+ *   for a stream's own outputs, which a caller caps.
+ * - `position`: a step takes rows by their position, which one unit reads only
+ *   as far as it needs.
+ * - `every_row`: a step needs every row at once, as a sort does, and no work
+ *   is done row by row before it.
+ * - `state`: a step carries state from row to row.
+ * - `calls`: the work done row by row calls a function value, which may call a
+ *   platform function the runner does not load.
+ * - `reads_again`: it reads the dataset it works through again, outside the
+ *   stream.
+ * - `key`: it groups by a key that is not one value a dict can hold.
+ * - `shape`: it is not a pipeline the planner splits.
+ */
+export interface JqWholeReason {
+    readonly code: "no_stream" | "nested" | "stops_early" | "position" | "every_row" | "state" | "calls" | "reads_again" | "key" | "shape";
+    /** The jq the reason is about, when it is about some. */
+    readonly range: JqRange | null;
+    /** The builtin or the dataset the reason names, when it names one. */
+    readonly name: string | null;
+}
+/**
+ * A read that skips what it doesn't need.
+ *
+ * @remarks
+ * - `count`: `.D | length` reads the count from the dataset's index, and no
+ *   segment.
+ * - `seek`: `.D[k]` or `.D | has(k)` reads only the segment that holds the key.
+ * - `stop`: a stream that stops early reads only the segments it reaches.
+ */
+export interface JqPruning {
+    readonly kind: "count" | "seek" | "stop";
+    /** The dataset, by its root field. */
+    readonly name: string;
+    /** The jq that reads it. */
+    readonly range: JqRange;
+}
+/**
+ * Splits a checked query over one dataset's pieces, or says why it runs as one
+ * unit.
+ *
+ * @param checked - what `checkJq` made of the query, checked as an e3 root; it
+ *   must have no error
+ * @param options - `maxOutputs` for a `many` query's limit
+ * @returns the split call's parts, or the reason it runs as one unit, with the
+ *   reads that skip what they don't need either way
+ * @throws {TranslationError} When the query does not check, or was not checked
+ *   as an e3 root.
+ *
+ * @remarks
+ * A query splits when its pipeline reads one root dataset, `.D`, `.D[]` or
+ * `[.D[] | f]`, and works through its rows: `map(f)`, `[.[] | f]`, `flatten`,
+ * and every step of a stream. Then:
+ * - **totals** over the rows (`length`, `add`, `min` / `max` and `_by`,
+ *   `.[0]` / `first`, `.[-1]` / `last`, `any`, `all`, `unique`, each perhaps
+ *   after `map(g)`, inside any expression of them) fold;
+ * - `group_by(k) | map(E)` combines by key, `E`'s totals field by field, or
+ *   each group's rows collected when `E` is not made of totals;
+ * - `unique` is a set, and `unique_by(g)` a dict keeping each key's first row;
+ * - `reduce .[] as $x ({}; .[k] += v)`, or `= v`, combines by key;
+ * - anything else after the row work runs once, over the rows concatenated.
+ *
+ * Bindings before the stream, `.C as $c | …`, reach every piece: each piece
+ * reads their datasets whole. A query whose row work stops early (a stream's
+ * own outputs, `first`, `limit`) runs as one unit, which reads only as far as
+ * it needs.
+ *
+ * @example
+ * ```ts
+ * const Order = StructType({ region: StringType, total: FloatType });
+ * const root = StructType({ orders: ArrayType(Order) });
+ * const checked = checkJq(".orders | group_by(.region) | map({region: .[0].region, revenue: map(.total) | add})", root, { root: true });
+ * const split = splitJq(checked);
+ * split.kind;                       // "split"
+ * split.output.kind;                // "dict": revenue by region, added
+ * ```
+ */
+export declare function splitJq(checked: CheckJqResult, options?: SplitJqOptions): JqSplit;
+//# sourceMappingURL=split.d.ts.map