@elaraai/e3-ui-components 1.0.83 → 1.0.85

package/dist/query/model/words.d.ts

@@ -0,0 +1,331 @@
+import { EastType, SummaryLeafType, ValueTypeOf } from '@elaraai/east';
+import { SplitCallProgress } from '@elaraai/e3-types';
+import { Formatters } from '@elaraai/east-ui-components';
+import { PlanExplanation, QueryPlan } from '../plan.js';
+import { CheckedSteps, StepDiagnostic, StepFix } from '../steps/check.js';
+import { StepField } from '../steps/fields.js';
+import { Shape } from '../steps/shape.js';
+import { StepParseError } from '../steps/parse.js';
+import { Condition, Step, StepKind, StepQuery, StepValue } from '../steps/values.js';
+import { QueryMessages } from './messages.js';
+/** A summary leaf: what a summary says about one path of the rows. */
+export type SummaryLeaf = ValueTypeOf<typeof SummaryLeafType>;
+/** The words the model says, and how it prints numbers and dates. */
+export interface QueryWords {
+    /** The message table. */
+    readonly messages: QueryMessages;
+    /** The locale's formatters. */
+    readonly formatters: Formatters;
+}
+/**
+ * The words of a locale.
+ *
+ * @param formatters - the locale's formatters (`useFormatters()` in a renderer)
+ * @param messages - the message table; English by default
+ * @returns the words
+ */
+export declare function queryWords(formatters: Formatters, messages?: QueryMessages): QueryWords;
+/** Each step's icon (Font Awesome's names, `Query Editor Spec.md` §4.4). */
+export declare const STEP_ICON: Readonly<Record<StepKind, string>>;
+/**
+ * A field's name as a person reads it: underscores as spaces, and `id` and
+ * `sku` in capitals — `customer_id` is `customer ID`.
+ *
+ * @param name - the name
+ * @returns the label
+ */
+export declare function human(name: string): string;
+/**
+ * The plural of a noun, as English mostly forms it: `order` → `orders`,
+ * `category` → `categories`, `status` → `statuses`; a noun already plural is
+ * itself.
+ *
+ * @param word - the noun
+ * @returns its plural
+ */
+export declare function plural(word: string): string;
+/**
+ * A field's label: its name as a person reads it, and a payload's field
+ * with its case — `shipped date`.
+ *
+ * @param field - the field
+ * @returns the label
+ */
+export declare function fieldLabel(field: StepField): string;
+/**
+ * The label of the field a step names: its field's in the shape, or the
+ * last part of the name when the shape has none.
+ *
+ * @param shape - the rows it is read in
+ * @param ref - how the step names it
+ * @returns the label
+ */
+export declare function refLabel(shape: Shape, ref: string): string;
+/**
+ * Whether a field holds IDs, which print as written: `id`, a name ending
+ * `_id`, or `order`.
+ *
+ * @param name - the field's name
+ * @returns whether it is an ID
+ */
+export declare function isIdName(name: string): boolean;
+/**
+ * A kind of value in plain words (`Query Editor Spec.md` §4.4): `text`,
+ * `whole number`, `number, sometimes missing`, `one of gold, standard`, `list
+ * of lines`, `lookup table`, `calculation`, `record`, `tree of boms`.
+ *
+ * @param type - the type
+ * @param words - the words
+ * @param items - what a list's or a tree's items are called, already plural: a field's or a data source's name
+ * @returns the kind
+ */
+export declare function plainKind(type: EastType, words: QueryWords, items?: string): string;
+/**
+ * A field's kind in plain words, its items named after it.
+ *
+ * @param field - the field
+ * @param words - the words
+ * @returns the kind
+ */
+export declare function fieldKind(field: StepField, words: QueryWords): string;
+/**
+ * The case a shape's rows are narrowed to, as an adjective: `shipped`.
+ *
+ * @param shape - the shape
+ * @returns the first narrowed case, or `""`
+ */
+export declare function adjectiveOf(shape: Shape): string;
+/**
+ * A shape's rows in words, in the number a count gives: `shipped orders`,
+ * `shipped order`.
+ *
+ * @param shape - the shape
+ * @param words - the words
+ * @param n - how many, for the noun's number; plural when omitted
+ * @param adjective - an adjective in place of the shape's own
+ * @returns the rows
+ */
+export declare function rowsWords(shape: Shape, words: QueryWords, n?: number, adjective?: string): string;
+/**
+ * A shape in plain words (`Query Editor Spec.md` §4.3): `Many shipped
+ * orders`, `Up to 10 orders`, `One whole number`, `One bom tree`.
+ *
+ * @param shape - the shape
+ * @param words - the words
+ * @returns the words
+ */
+export declare function shapeWords(shape: Shape, words: QueryWords): string;
+/**
+ * A shape counted: `16 shipped orders`; one value is its shape.
+ *
+ * @param shape - the shape
+ * @param n - how many rows a run counted
+ * @param words - the words
+ * @returns the words
+ */
+export declare function countWords(shape: Shape, n: number, words: QueryWords): string;
+/**
+ * The fields of a shape's rows as a person reads them, payloads aside.
+ *
+ * @param shape - the shape
+ * @returns the labels
+ */
+export declare function fieldLabels(shape: Shape): string[];
+/**
+ * A number from the data as a summary prints it: an ID as written, a whole
+ * number grouped, any other with two decimals.
+ *
+ * @param n - the number
+ * @param field - the field it belongs to
+ * @param words - the words
+ * @returns the text
+ */
+export declare function dataNumber(n: number, field: StepField, words: QueryWords): string;
+/**
+ * A value a step holds, as its slot shows it: text as written, a number as
+ * data — every digit, never grouped.
+ *
+ * @param value - the value
+ * @param words - the words
+ * @returns the text
+ */
+export declare function valueWords(value: StepValue, words: QueryWords): string;
+/**
+ * The jq path from a row a summary keys a field's leaf by: `.total`,
+ * `.status.type`, `.status.value.date`; an item's field under its list —
+ * `.lines[].sku`.
+ *
+ * @param field - the field
+ * @param list - the list field the field is an item's field of, if any
+ * @returns the path
+ */
+export declare function leafPath(field: StepField, list?: StepField): string;
+/**
+ * What a summary says of a field, as a slot's offer shows it
+ * (`Query Editor Spec.md` §4.5): `8 values`, `0.85 – 3,646.84`, `3 cases`,
+ * `1–4 each`, `· 12 missing`.
+ *
+ * @param field - the field
+ * @param leaf - its leaf of the summary
+ * @param words - the words
+ * @returns the words, or `""` when the summary says nothing worth showing
+ */
+export declare function fieldSummaryWords(field: StepField, leaf: SummaryLeaf | undefined, words: QueryWords): string;
+/** A problem in plain words, and its fixes' labels. */
+export interface ProblemWords {
+    /** The sentence. */
+    readonly text: string;
+    /** Each fix, with its label in plain words. */
+    readonly fixes: readonly {
+        readonly fix: StepFix;
+        readonly label: string;
+    }[];
+}
+/**
+ * A problem of the steps in plain words (`Query Editor Spec.md` §4.6), with
+ * its fixes' labels; a problem the words have no sentence for keeps the
+ * checker's.
+ *
+ * @param d - the diagnostic, as `checkSteps` placed it
+ * @param query - the query
+ * @param root - the root's type: a struct of the data sources
+ * @param checked - the query's check
+ * @param words - the words
+ * @returns the sentence and the fixes
+ */
+export declare function problemWords(d: StepDiagnostic, query: StepQuery, root: EastType, checked: CheckedSteps, words: QueryWords): ProblemWords;
+/**
+ * A problem that keeps a program from being steps, in plain words
+ * (`Query Editor Spec.md` §4.6, "the program"); one the words have no
+ * sentence for keeps the parser's or the checker's.
+ *
+ * @param error - the problem `parseSteps` gave
+ * @param words - the words
+ * @returns the sentence
+ */
+export declare function parseErrorWords(error: StepParseError, words: QueryWords): string;
+/** The most a generated description holds (`Query Editor Spec.md` §4.13). */
+export declare const DESCRIPTION_MAX = 140;
+/**
+ * A condition in a sentence: `status is shipped`, `lines has any where SKU
+ * is BRK-100`; a group in brackets.
+ *
+ * @param condition - the condition
+ * @param shape - the rows it tests
+ * @param words - the words
+ * @returns the words, or `""` for a condition not finished
+ */
+export declare function conditionWords(condition: Condition, shape: Shape, words: QueryWords): string;
+/**
+ * How a field's order is said: dates newest or oldest first, text A to Z,
+ * anything else highest or lowest first.
+ *
+ * @param field - the field sorted by, if known
+ * @returns the kind of order
+ */
+export declare function orderKind(field: StepField | undefined): "date" | "text" | "number";
+/**
+ * A step in words, from its own values: what an outline line says
+ * (`Query Editor Spec.md` §5) — `status is shipped and total is at least
+ * 100`, `name and region from customers by customer ID`, `revenue and orders
+ * per region`, `by total, highest first`.
+ *
+ * @param step - the step
+ * @param before - the rows it takes
+ * @param words - the words
+ * @returns the words; a jq step's text as written
+ */
+export declare function stepWords(step: Step, before: Shape, words: QueryWords): string;
+/**
+ * The sentence a saved query shows when its author wrote none
+ * (`Query Editor Spec.md` §4.13): one sentence from the finished steps, at
+ * most {@link DESCRIPTION_MAX} characters, cut at a word.
+ *
+ * @param query - the query
+ * @param checked - its check, for each step's rows
+ * @param words - the words
+ * @returns the sentence, or `""` when no step is finished
+ */
+export declare function describeQuery(query: StepQuery, checked: CheckedSteps, words: QueryWords): string;
+/**
+ * A size in bytes, in words — `1.4 MB`, `16 MB`, `512 B`: in the largest unit
+ * it holds one of, to GB.
+ *
+ * @param bytes - the size
+ * @param words - the words
+ * @returns the size
+ */
+export declare function byteWords(bytes: number | bigint, words: QueryWords): string;
+/** A line of a plan's explanation: a sentence, and the jq it is about. */
+export interface PlanLine {
+    /**
+     * What it says: the path and why; a re-key and its stage (#942); what each
+     * piece runs, what it reads cut at the same keys (#942), how the pieces
+     * combine, a total, what runs once; what every piece reads whole; the
+     * pieces; a read that prunes.
+     */
+    readonly kind: "path" | "rekey" | "piece" | "copartitioned" | "combine" | "total" | "then" | "broadcast" | "pieces" | "pruning";
+    /** Its sentence: one that ends with a colon has its jq after it. */
+    readonly text: string;
+    /** The jq it is about, as the query writes it; `undefined` when it is about none. */
+    readonly code: string | undefined;
+}
+/** What a run knows of its plan as it goes: a split call's progress, and how many pieces it cut. */
+export interface PlanRun {
+    /** A split call's progress, while it goes. */
+    readonly progress?: SplitCallProgress | undefined;
+    /** How many pieces it cut, once e3 says. */
+    readonly pieces?: number | undefined;
+}
+/**
+ * How far a split run has got, in words — `3 of 12 pieces done`, `1 of 1
+ * merges done`.
+ *
+ * @param progress - its progress, as e3 reports it
+ * @param words - the words
+ * @returns the words
+ */
+export declare function planProgressWords(progress: SplitCallProgress, words: QueryWords): string;
+/**
+ * A plan's explanation in words: one line per sentence, each with the jq it
+ * is about.
+ *
+ * @param explanation - the plan's explanation (`plan.ts`)
+ * @param words - the words
+ * @param run - what the run knows of its plan: a split call's progress while
+ *   it goes, and how many pieces it cut once e3 says
+ * @returns the lines, in order
+ *
+ * @remarks
+ * - **The path**, first: a split call over a dataset and what it weighs, more
+ *   than one piece — or what the heaviest dataset cut with it weighs; or one
+ *   call — within one piece, a weight not known, a split call that could not
+ *   be made, or the reason the query runs as one unit, with the jq the reason
+ *   is about. A re-keyed join says so next, and its re-key stage with the join
+ *   key and what the re-keyed rows are estimated to weigh (#942).
+ * - **A split's stages**: what each piece runs; the data sources cut at the
+ *   same keys with it (#942); how their outputs combine — rows joined;
+ *   totals, each by its rule; grouped by a key, each group's totals combined
+ *   or its rows collected; the distinct rows; the first row of each key; a
+ *   reduce's updates by key, added or the last kept; the first rows of a sort
+ *   (#942); what runs once after them; the data sources every piece reads
+ *   whole; and the pieces — how far the run has got while it goes, then how
+ *   many and about what each weighs.
+ * - **The reads that prune**, last: a count from a dataset's index, a key
+ *   seek, a stream that stops.
+ */
+export declare function planWords(explanation: PlanExplanation, words: QueryWords, run?: PlanRun): PlanLine[];
+/**
+ * A plan's read-out, beside a run's: `One call`; `Split call`, with how far it
+ * has got while it goes — `Split call · 3 of 12 pieces done` — and how many
+ * pieces it cut once e3 says — `Split call · 12 pieces`; and a re-keyed join's
+ * two calls the same way — `Re-keyed join · 12 pieces`, the join call's
+ * pieces (#942).
+ *
+ * @param planned - the run's plan
+ * @param words - the words
+ * @param run - what the run knows of its plan
+ * @returns the read-out
+ */
+export declare function planBadge(planned: QueryPlan, words: QueryWords, run?: PlanRun): string;
+//# sourceMappingURL=words.d.ts.map

package/dist/query/model/words.d.ts.map

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

package/dist/query/one-shot.d.ts

@@ -0,0 +1,266 @@
+import { CheckJqResult, EastType, EastTypeValue, JqMultiplicity, JqNode, ValueTypeOf } from '@elaraai/east';
+import { ExecuteResult, OneShotRequest, RunnerValue } from '@elaraai/e3-types';
+import { QueryResultType, QueryRootEntryType } from '@elaraai/e3-ui/internal';
+/**
+ * A data source of a query's root, as the builder binds it: the root field a
+ * query reads it by, its dataset's path, and the dataset's type.
+ *
+ * @remarks
+ * `name` and `path` are a {@link QueryRootEntryType} value, what a saved query
+ * keeps of its root; `type` is the dataset's East type, as e3 lists it.
+ */
+export type QueryRootEntry = ValueTypeOf<typeof QueryRootEntryType> & {
+    /** The dataset's East type, as e3 lists it. */
+    type: EastTypeValue;
+};
+/**
+ * A query's root: the type every query of the builder is checked against, and
+ * the data sources it is made of.
+ *
+ * @property type - The root's type: a Struct of the data sources' types, in entry order
+ * @property entries - The data sources, in root order
+ */
+export interface QueryRoot {
+    /** The root's type: a Struct of the data sources' types, in entry order. */
+    readonly type: EastType;
+    /** The data sources, in root order. */
+    readonly entries: QueryRootEntry[];
+}
+/**
+ * The root a query's data sources make: the builder's `useQueryRoot` gives it
+ * from the data sources a page binds.
+ *
+ * @param entries - the data sources, in root order
+ * @returns the root: a Struct of the data sources' types, in entry order, and
+ *   the data sources
+ * @throws {Error} When a name is not a jq identifier, or is given twice,
+ *   naming it.
+ *
+ * @remarks
+ * The root is only a type. Its entries become the translation's parameters,
+ * one dataset each, because a lazy dataset put into a struct is read whole
+ * (`devdocs/QUERY.md` §15.6). A name is a jq identifier — a letter or `_`,
+ * then letters, digits and `_` — so `.name` reads it. A root of no data
+ * sources is the empty Struct, and a query that reads a data source of it is
+ * refused when it is checked.
+ *
+ * @example
+ * ```ts
+ * const root = queryRoot([
+ *     { name: "customers", path: [variant("field", "inputs"), variant("field", "customers")], type: toEastTypeValue(Customers) },
+ *     { name: "orders", path: [variant("field", "inputs"), variant("field", "orders")], type: toEastTypeValue(Orders) },
+ * ]);
+ * // root.type is StructType({ customers: Customers, orders: Orders })
+ *
+ * queryRoot([{ name: "order lines", path, type }]);
+ * // throws: queryRoot: "order lines" is not a jq identifier: …
+ * ```
+ */
+export declare function queryRoot(entries: readonly QueryRootEntry[]): QueryRoot;
+/**
+ * Options for {@link prepareQuery}: the call's limits, and its runner.
+ *
+ * @property maxOutputs - The most outputs a `many` query returns: 1 000 by default, at most 100 000
+ * @property maxBytes - The largest answer the call returns, in bytes: 1 MiB by default
+ * @property timeoutMs - The call's time limit, in milliseconds: the server's when omitted
+ * @property runner - The runner: east-c given no platform package, by default
+ */
+export interface QueryOptions {
+    /** The most outputs a `many` query returns: 1 000 by default, at most 100 000. */
+    readonly maxOutputs?: number;
+    /** The largest answer the call returns, in bytes: 1 MiB by default. */
+    readonly maxBytes?: number;
+    /**
+     * The call's time limit, in milliseconds. Omitted, the call names none and
+     * the server's applies: its default for a call that names none, under the
+     * longest a request to it may take (#1131).
+     */
+    readonly timeoutMs?: number;
+    /** The runner: east-c given no platform package by default, which any caller who may read the workspace may run. */
+    readonly runner?: RunnerValue;
+}
+/** What a run of a query answered: a {@link QueryResultType} value. */
+export type QueryResult = ValueTypeOf<typeof QueryResultType>;
+/**
+ * What the checker made of a program that checks: the program as written, the
+ * type of each output and how many there are, each present.
+ */
+export type CheckedProgram = CheckJqResult & {
+    /** The program as written. */
+    readonly program: JqNode;
+    /** The type of each output. */
+    readonly elementType: EastType;
+    /** How many outputs the program gives. */
+    readonly multiplicity: JqMultiplicity;
+};
+/**
+ * Whether a program checks: its program, the type of each output and how many
+ * there are are present exactly when no diagnostic is an error.
+ *
+ * @param checked - what `checkJq` made of the program
+ * @returns whether it checks
+ */
+export declare function programChecks(checked: CheckJqResult): checked is CheckedProgram;
+/**
+ * A query's one-shot call, ready to send, and what reading its answer needs.
+ *
+ * @property checked - What the checker made of the program: the program as written, the type of each output and how many there are, and the spans a runtime error is placed by
+ * @property entries - The data sources the query reads, one per argument of the call, in its order
+ * @property request - The call, which e3-api-client's `oneShotExecute` sends
+ * @property maxOutputs - The most outputs a `many` query returns
+ */
+export interface PreparedQuery {
+    /** What the checker made of the program: the program as written, the type of each output and how many there are, and the spans a runtime error is placed by. */
+    readonly checked: CheckedProgram;
+    /** The data sources the query reads, one per argument of the call, in its order: the order the query first reads them. */
+    readonly entries: QueryRootEntry[];
+    /** The call, which e3-api-client's `oneShotExecute` sends. */
+    readonly request: OneShotRequest;
+    /** The most outputs a `many` query returns; the call gives one more, which says the answer was cut short. */
+    readonly maxOutputs: number;
+}
+/**
+ * What reading a call's answer needs ({@link queryResultOf}): the checker's
+ * record of the query that ran — the type of each output, and how many there
+ * are — the data sources in the call's argument order, and its most outputs. A
+ * one-shot call's {@link PreparedQuery} is one; so is a split call's, which
+ * the planner gives (`plan.ts`).
+ */
+export type QueryReading = Pick<PreparedQuery, "checked" | "entries" | "maxOutputs">;
+/** A call's limits and runner, as its options set them: what a one-shot call and a split call both send. */
+export interface QueryLimits {
+    /** The most outputs a `many` query returns. */
+    readonly maxOutputs: number;
+    /** The call's limits: its largest answer as `maxResultBytes`, and its time limit when the options name one. */
+    readonly limits: OneShotRequest["limits"];
+    /** The runner: east-c given no platform package, unless the options name another. */
+    readonly runner: RunnerValue;
+}
+/**
+ * A call's limits and runner, from its options: its most outputs and its
+ * largest answer their defaults when the options give none, and no time limit
+ * unless the options name one, so the server's applies (#1131).
+ *
+ * @param options - the call's limits and its runner
+ * @returns the most outputs, the limits and the runner
+ * @throws {RangeError} When a limit is not a whole number of at least 1.
+ */
+export declare function queryLimits(options?: QueryOptions): QueryLimits;
+/**
+ * Prepares a query's one-shot call: checks the program once against the whole
+ * root, translates it, and builds the request.
+ *
+ * @param program - the query's jq text
+ * @param root - the root its data sources make ({@link queryRoot})
+ * @param options - the call's limits and its runner
+ * @returns the prepared call; or, for a program that does not check, the
+ *   `error` result a run of it gives
+ * @throws {RangeError} When a limit is not a whole number of at least 1.
+ * @throws {TranslationError} When the checked program holds something the
+ *   translator cannot express: a gap in the translation, never a mistake in
+ *   the query.
+ *
+ * @remarks
+ * - **One check.** The program is checked with
+ *   `checkJq(program, root.type, { root: true })`, once, against the whole
+ *   root, which is never narrowed to what the query reads (#1041): `keys` on
+ *   the root answers every name. A problem of error severity is an `error`
+ *   result holding the checker's diagnostics, lints included, and no input,
+ *   since nothing ran; reading the whole root is one.
+ * - **The translation.** `translateJq` translates it, a `many` query asked
+ *   for at most `maxOutputs + 1` outputs (#923). Its parameters are the
+ *   datasets it reads, in the order it first reads them.
+ * - **The request.** `bodyIr` is the translation as an East function, its IR
+ *   encoded with its source map, so a runtime error names its place in the
+ *   jq; `args` is one `dataset` argument per dataset read, in the
+ *   translation's order; `runner` is east-c given no platform package, unless
+ *   the options name another; `limits` holds `maxBytes` as `maxResultBytes`,
+ *   and `timeoutMs` when the options give one. A call that names no time limit
+ *   runs under the server's: its default for a call that names none, under
+ *   the longest a request to it may take (#1131).
+ * - **Platform-free.** A translation calls East's builtins only, so the body
+ *   holds no `Platform` node, and with the default runner any caller who may
+ *   read the workspace may run the call (#1031).
+ *
+ * @example
+ * ```ts
+ * const prepared = prepareQuery(".orders | map(.total) | add", root, { timeoutMs: 10_000 });
+ * if ("result" in prepared) return prepared.result;   // the checker's problems
+ * const result = await oneShotExecute(url, repo, workspace, prepared.prepared.request, { token });
+ * return queryResultOf(prepared.prepared, result);
+ * ```
+ */
+export declare function prepareQuery(program: string, root: QueryRoot, options?: QueryOptions): {
+    prepared: PreparedQuery;
+} | {
+    result: QueryResult;
+};
+/**
+ * Prepares a query's one-shot call from what the checker made of it: what
+ * {@link prepareQuery} does once it has checked the program, for a caller that
+ * has checked it already — the planner, which checks a query once to split it
+ * and to call it.
+ *
+ * @param checked - what `checkJq` made of the program, against `root.type`, as an e3 root
+ * @param root - the root
+ * @param options - the call's limits and its runner
+ * @returns the prepared call; or, for a program that does not check, the `error` result a run of it gives
+ * @throws {RangeError} When a limit is not a whole number of at least 1.
+ * @throws {TranslationError} When the checked program holds something the translator cannot express.
+ */
+export declare function prepareCheckedQuery(checked: CheckJqResult, root: QueryRoot, options?: QueryOptions): {
+    prepared: PreparedQuery;
+} | {
+    result: QueryResult;
+};
+/**
+ * The data source of a root a query reads by a name.
+ *
+ * @param root - the root
+ * @param name - the root field the translation, or the split, reads
+ * @param caller - what asks, for the error: `prepareQuery` by default
+ * @returns the data source
+ * @throws {Error} When the root has none of that name: its type was not made from its entries.
+ */
+export declare function entryNamed(root: QueryRoot, name: string | null, caller?: string): QueryRootEntry;
+/**
+ * What a query's call answered: a one-shot call's, or a split call's.
+ *
+ * @param prepared - the call, as {@link prepareQuery} prepared it; or a split
+ *   call's reading, as the planner gives it — both a {@link QueryReading}
+ * @param result - what e3-api-client's `oneShotExecute` returned for it, or a
+ *   split call's result (`splitCall`'s `result`)
+ * @returns the answer: how the run ended, and the datasets it read
+ * @throws {Error} When the call read a dataset other than the one the query
+ *   reads there: the result is not this call's.
+ *
+ * @remarks
+ * - `success` is `ok`, the value decoded with the translation's result type.
+ *   A `many` answer of more than `maxOutputs` outputs — the translation gives
+ *   one more — is `truncated`, its last output dropped. `result` is
+ *   self-describing beast2 of the answer kept, at the result type, and
+ *   `outputs` counts its outputs: one for a `one` query, none or one for
+ *   `maybe`.
+ * - `failed` for a platform function the runner could not find is
+ *   `needs_platform`, naming each: a function value in the data may call one
+ *   (`devdocs/QUERY.md` §9).
+ * - `failed` otherwise is an `error` of one `runtime` diagnostic: the
+ *   runner's message, at the jq node that raised it, placed by east's
+ *   `runtimeErrorAt` as `evaluateJq` places one (`devdocs/QUERY.md` §15.3).
+ *   A failure with no message says what the runner last said, or its exit
+ *   code.
+ * - `invalid` is an `error`: `no_value` for a dataset e3 found unassigned
+ *   ("orders has no value yet"), and `invalid` for anything else it refused.
+ * - `timed_out` and `too_large` are as e3 reported them.
+ *
+ * `inputs` names each dataset the run read, with the hash e3 pinned it at, in
+ * the call's argument order: empty when nothing ran.
+ *
+ * @example
+ * ```ts
+ * const result = queryResultOf(prepared, await oneShotExecute(url, repo, workspace, prepared.request, { token }));
+ * if (result.outcome.type === "ok") show(decodeBeast2(result.outcome.value.result), result.outcome.value.truncated);
+ * ```
+ */
+export declare function queryResultOf(prepared: QueryReading, result: ExecuteResult): QueryResult;
+//# sourceMappingURL=one-shot.d.ts.map

package/dist/query/one-shot.d.ts.map

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