@elaraai/east 1.0.83 → 1.0.85

package/dist/src/query/types.d.ts

@@ -0,0 +1,505 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The wire types of typed jq queries over East values.
+ *
+ * A query's text is parsed into a {@link JqType} tree, the program as
+ * written, each constant in it a typed East value. A query's types are never
+ * kept with it: they are what checking the program against the data it reads
+ * gives, and every place that needs them checks the program (#1138). In code,
+ * the `Query` builtin carries the program and a root's input names
+ * ({@link QueryCallType}) beside the query's translation, whose function type
+ * carries the types, and a runtime runs the translation (#1041), so no
+ * runtime reads query text.
+ *
+ * Struct fields are declared alphabetically, as `FunctionManifestType`'s are,
+ * and the python twins in `east/query/types.py` declare the same types, so a
+ * type encodes to the same bytes in either language. `devdocs/QUERY.md` is the
+ * normative account of what the values mean.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, BooleanType, FloatType, IntegerType, NullType, OptionType, RecursiveType, StringType, StructType, VariantType } from "../types.js";
+/**
+ * A constant a jq program writes, as the East value it is.
+ *
+ * @remarks
+ * - `boolean` — `true` or `false`.
+ * - `float` — a number written with a `.` or an exponent: `1001.0`, `1e2`.
+ * - `integer` — a number written as digits alone, `1001`: a 64-bit Integer.
+ * - `null` — `null`.
+ * - `string` — a string with no interpolation, `"C01"`.
+ *
+ * A literal is the constant as written. Where the checker reads it as
+ * another type — an Integer where a Float is, an ISO-8601 string where a
+ * DateTime is — the program still holds it as written, and its translation
+ * gives the value that type has (`devdocs/QUERY.md` §7).
+ */
+export declare const JqLiteralType: VariantType<{
+    readonly boolean: BooleanType;
+    readonly float: FloatType;
+    readonly integer: IntegerType;
+    readonly null: NullType;
+    readonly string: StringType;
+}>;
+/**
+ * A destructuring pattern, as `as`, `reduce` and `foreach` bind one.
+ *
+ * @remarks
+ * - `array` — `[$a, $b]`: each element pattern matches the element at its
+ *   index.
+ * - `object` — `{name: $n, $id}`: each entry reads the field named by `key`
+ *   and matches it against `value`; an entry with no `value` binds the
+ *   variable named `key` (`$id` reads `.id`). Keys are literal in this version.
+ * - `variable` — `$x`, named without its `$`.
+ *
+ * `?//` alternatives are a list of patterns on the binding that uses them
+ * (see {@link JqType}'s `bind` case).
+ */
+export declare const JqPatternType: RecursiveType<VariantType<{
+    readonly array: ArrayType<import("../types.js").RecursiveTypeMarker>;
+    readonly object: ArrayType<StructType<{
+        readonly key: StringType;
+        readonly value: OptionType<import("../types.js").RecursiveTypeMarker>;
+    }>>;
+    readonly variable: StringType;
+}>>;
+/**
+ * A jq program, as a tree.
+ *
+ * @remarks
+ * The parser keeps jq's sugar rather than desugaring it, so printing a parsed
+ * program gives back what was written: `.a.b` is two `field` nodes and `f?` is
+ * a `try` with no `catch`. Operators, builtin names and error codes are
+ * strings, so a new one never changes this type.
+ *
+ * - `alternative` — `left // right`.
+ * - `array` — `[f]`, or `[]` when there is no body.
+ * - `binary` — `left op right`, for `op` one of `+ - * / % == != < <= > >=
+ *   and or`.
+ * - `bind` — `source as $p ?// $q | body`: the first of `patterns` that
+ *   matches binds.
+ * - `break` — `break $name`, named without its `$`.
+ * - `call` — a builtin or a `def` by name, with its `;`-separated arguments.
+ * - `comma` — `left, right`.
+ * - `def` — `def name(params): body; rest`.
+ * - `descend` — `..`, every nested value in pre-order.
+ * - `field` — `target.name`, or `target.name?` when `optional`.
+ * - `foreach` — `foreach source as pattern (init; update; extract)`.
+ * - `format` — `@name`, or `@name "…"` applied to a string.
+ * - `identity` — `.`.
+ * - `if` — `if c then t elif … else e end`; `otherwise` is the `else`.
+ * - `index` — `target[index]`: an index on an array, a key on a dict,
+ *   decided by the target's type; `optional` is a trailing `?`.
+ * - `iterate` — `target[]`, or `target[]?` when `optional`.
+ * - `label` — `label $name | body`, named without its `$`.
+ * - `literal` — a constant, as the typed East value it is
+ *   ({@link JqLiteralType}): `1001` is an Integer, `1001.0` a Float.
+ * - `negate` — `-f`.
+ * - `object` — `{…}`: a key is a `name` (`{a: f}`, or `{a}` with no value),
+ *   a `variable` (`{$x}`, named without its `$`) or `computed` (`{(k): v}`).
+ * - `pipe` — `left | right`.
+ * - `reduce` — `reduce source as pattern (init; update)`.
+ * - `slice` — `target[from:to]`, either bound optional.
+ * - `string` — a string with interpolations, `"a\(f)b"`, as its parts.
+ * - `try` — `try body catch handler`; `f?` is `try f` with no `catch`.
+ * - `update` — `path op value`, for `op` one of `= |= += -= *= /= %= //=`.
+ * - `variable` — `$x`, named without its `$`.
+ */
+export declare const JqType: RecursiveType<VariantType<{
+    readonly alternative: StructType<{
+        readonly left: import("../types.js").RecursiveTypeMarker;
+        readonly right: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly array: OptionType<import("../types.js").RecursiveTypeMarker>;
+    readonly binary: StructType<{
+        readonly left: import("../types.js").RecursiveTypeMarker;
+        readonly op: StringType;
+        readonly right: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly bind: StructType<{
+        readonly body: import("../types.js").RecursiveTypeMarker;
+        readonly patterns: ArrayType<RecursiveType<VariantType<{
+            readonly array: ArrayType<import("../types.js").RecursiveTypeMarker>;
+            readonly object: ArrayType<StructType<{
+                readonly key: StringType;
+                readonly value: OptionType<import("../types.js").RecursiveTypeMarker>;
+            }>>;
+            readonly variable: StringType;
+        }>>>;
+        readonly source: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly break: StringType;
+    readonly call: StructType<{
+        readonly args: ArrayType<import("../types.js").RecursiveTypeMarker>;
+        readonly name: StringType;
+    }>;
+    readonly comma: StructType<{
+        readonly left: import("../types.js").RecursiveTypeMarker;
+        readonly right: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly def: StructType<{
+        readonly body: import("../types.js").RecursiveTypeMarker;
+        readonly name: StringType;
+        readonly params: ArrayType<StringType>;
+        readonly rest: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly descend: NullType;
+    readonly field: StructType<{
+        readonly name: StringType;
+        readonly optional: BooleanType;
+        readonly target: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly foreach: StructType<{
+        readonly extract: OptionType<import("../types.js").RecursiveTypeMarker>;
+        readonly init: import("../types.js").RecursiveTypeMarker;
+        readonly pattern: RecursiveType<VariantType<{
+            readonly array: ArrayType<import("../types.js").RecursiveTypeMarker>;
+            readonly object: ArrayType<StructType<{
+                readonly key: StringType;
+                readonly value: OptionType<import("../types.js").RecursiveTypeMarker>;
+            }>>;
+            readonly variable: StringType;
+        }>>;
+        readonly source: import("../types.js").RecursiveTypeMarker;
+        readonly update: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly format: StructType<{
+        readonly name: StringType;
+        readonly string: OptionType<import("../types.js").RecursiveTypeMarker>;
+    }>;
+    readonly identity: NullType;
+    readonly if: StructType<{
+        readonly branches: ArrayType<StructType<{
+            readonly condition: import("../types.js").RecursiveTypeMarker;
+            readonly then: import("../types.js").RecursiveTypeMarker;
+        }>>;
+        readonly otherwise: OptionType<import("../types.js").RecursiveTypeMarker>;
+    }>;
+    readonly index: StructType<{
+        readonly index: import("../types.js").RecursiveTypeMarker;
+        readonly optional: BooleanType;
+        readonly target: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly iterate: StructType<{
+        readonly optional: BooleanType;
+        readonly target: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly label: StructType<{
+        readonly body: import("../types.js").RecursiveTypeMarker;
+        readonly name: StringType;
+    }>;
+    readonly literal: VariantType<{
+        readonly boolean: BooleanType;
+        readonly float: FloatType;
+        readonly integer: IntegerType;
+        readonly null: NullType;
+        readonly string: StringType;
+    }>;
+    readonly negate: import("../types.js").RecursiveTypeMarker;
+    readonly object: ArrayType<StructType<{
+        readonly key: VariantType<{
+            readonly computed: import("../types.js").RecursiveTypeMarker;
+            readonly name: StringType;
+            readonly variable: StringType;
+        }>;
+        readonly value: OptionType<import("../types.js").RecursiveTypeMarker>;
+    }>>;
+    readonly pipe: StructType<{
+        readonly left: import("../types.js").RecursiveTypeMarker;
+        readonly right: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly reduce: StructType<{
+        readonly init: import("../types.js").RecursiveTypeMarker;
+        readonly pattern: RecursiveType<VariantType<{
+            readonly array: ArrayType<import("../types.js").RecursiveTypeMarker>;
+            readonly object: ArrayType<StructType<{
+                readonly key: StringType;
+                readonly value: OptionType<import("../types.js").RecursiveTypeMarker>;
+            }>>;
+            readonly variable: StringType;
+        }>>;
+        readonly source: import("../types.js").RecursiveTypeMarker;
+        readonly update: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly slice: StructType<{
+        readonly from: OptionType<import("../types.js").RecursiveTypeMarker>;
+        readonly optional: BooleanType;
+        readonly target: import("../types.js").RecursiveTypeMarker;
+        readonly to: OptionType<import("../types.js").RecursiveTypeMarker>;
+    }>;
+    readonly string: ArrayType<VariantType<{
+        readonly interpolate: import("../types.js").RecursiveTypeMarker;
+        readonly text: StringType;
+    }>>;
+    readonly try: StructType<{
+        readonly body: import("../types.js").RecursiveTypeMarker;
+        readonly catch: OptionType<import("../types.js").RecursiveTypeMarker>;
+    }>;
+    readonly update: StructType<{
+        readonly op: StringType;
+        readonly path: import("../types.js").RecursiveTypeMarker;
+        readonly value: import("../types.js").RecursiveTypeMarker;
+    }>;
+    readonly variable: StringType;
+}>>;
+/**
+ * How many outputs a query gives: `one` exactly, `maybe` none or one, or
+ * `many`.
+ *
+ * @remarks
+ * A checked query's result is its element type `T` for `one`, `Option<T>` for
+ * `maybe`, and `Array<T>` (the stream collected in order) for `many`. A
+ * runtime enforces the multiplicity: a `one` query that yields no output, or
+ * two, is a runtime error.
+ */
+export declare const QueryMultiplicityType: VariantType<{
+    readonly many: NullType;
+    readonly maybe: NullType;
+    readonly one: NullType;
+}>;
+/**
+ * A query as the `Query` builtin carries it in code (#1041): the program as
+ * written, and a root's input names.
+ *
+ * @remarks
+ * - `inputs` — the names of a root's fields, one per input of the
+ *   translation, in order; `none` for a query of one input.
+ * - `program` — the program as written ({@link JqType}).
+ *
+ * The builtin's type parameter, the translation's function type, carries the
+ * query's input and result types, so they are not held twice. A structural
+ * change is a new case that sorts after `v1` (a variant's cases are ordered
+ * by name, and inserting one before an existing case renumbers it), and
+ * readers accept every released version.
+ */
+export declare const QueryCallType: VariantType<{
+    readonly v1: StructType<{
+        readonly inputs: OptionType<ArrayType<StringType>>;
+        readonly program: RecursiveType<VariantType<{
+            readonly alternative: StructType<{
+                readonly left: import("../types.js").RecursiveTypeMarker;
+                readonly right: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly array: OptionType<import("../types.js").RecursiveTypeMarker>;
+            readonly binary: StructType<{
+                readonly left: import("../types.js").RecursiveTypeMarker;
+                readonly op: StringType;
+                readonly right: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly bind: StructType<{
+                readonly body: import("../types.js").RecursiveTypeMarker;
+                readonly patterns: ArrayType<RecursiveType<VariantType<{
+                    readonly array: ArrayType<import("../types.js").RecursiveTypeMarker>;
+                    readonly object: ArrayType<StructType<{
+                        readonly key: StringType;
+                        readonly value: OptionType<import("../types.js").RecursiveTypeMarker>;
+                    }>>;
+                    readonly variable: StringType;
+                }>>>;
+                readonly source: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly break: StringType;
+            readonly call: StructType<{
+                readonly args: ArrayType<import("../types.js").RecursiveTypeMarker>;
+                readonly name: StringType;
+            }>;
+            readonly comma: StructType<{
+                readonly left: import("../types.js").RecursiveTypeMarker;
+                readonly right: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly def: StructType<{
+                readonly body: import("../types.js").RecursiveTypeMarker;
+                readonly name: StringType;
+                readonly params: ArrayType<StringType>;
+                readonly rest: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly descend: NullType;
+            readonly field: StructType<{
+                readonly name: StringType;
+                readonly optional: BooleanType;
+                readonly target: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly foreach: StructType<{
+                readonly extract: OptionType<import("../types.js").RecursiveTypeMarker>;
+                readonly init: import("../types.js").RecursiveTypeMarker;
+                readonly pattern: RecursiveType<VariantType<{
+                    readonly array: ArrayType<import("../types.js").RecursiveTypeMarker>;
+                    readonly object: ArrayType<StructType<{
+                        readonly key: StringType;
+                        readonly value: OptionType<import("../types.js").RecursiveTypeMarker>;
+                    }>>;
+                    readonly variable: StringType;
+                }>>;
+                readonly source: import("../types.js").RecursiveTypeMarker;
+                readonly update: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly format: StructType<{
+                readonly name: StringType;
+                readonly string: OptionType<import("../types.js").RecursiveTypeMarker>;
+            }>;
+            readonly identity: NullType;
+            readonly if: StructType<{
+                readonly branches: ArrayType<StructType<{
+                    readonly condition: import("../types.js").RecursiveTypeMarker;
+                    readonly then: import("../types.js").RecursiveTypeMarker;
+                }>>;
+                readonly otherwise: OptionType<import("../types.js").RecursiveTypeMarker>;
+            }>;
+            readonly index: StructType<{
+                readonly index: import("../types.js").RecursiveTypeMarker;
+                readonly optional: BooleanType;
+                readonly target: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly iterate: StructType<{
+                readonly optional: BooleanType;
+                readonly target: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly label: StructType<{
+                readonly body: import("../types.js").RecursiveTypeMarker;
+                readonly name: StringType;
+            }>;
+            readonly literal: VariantType<{
+                readonly boolean: BooleanType;
+                readonly float: FloatType;
+                readonly integer: IntegerType;
+                readonly null: NullType;
+                readonly string: StringType;
+            }>;
+            readonly negate: import("../types.js").RecursiveTypeMarker;
+            readonly object: ArrayType<StructType<{
+                readonly key: VariantType<{
+                    readonly computed: import("../types.js").RecursiveTypeMarker;
+                    readonly name: StringType;
+                    readonly variable: StringType;
+                }>;
+                readonly value: OptionType<import("../types.js").RecursiveTypeMarker>;
+            }>>;
+            readonly pipe: StructType<{
+                readonly left: import("../types.js").RecursiveTypeMarker;
+                readonly right: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly reduce: StructType<{
+                readonly init: import("../types.js").RecursiveTypeMarker;
+                readonly pattern: RecursiveType<VariantType<{
+                    readonly array: ArrayType<import("../types.js").RecursiveTypeMarker>;
+                    readonly object: ArrayType<StructType<{
+                        readonly key: StringType;
+                        readonly value: OptionType<import("../types.js").RecursiveTypeMarker>;
+                    }>>;
+                    readonly variable: StringType;
+                }>>;
+                readonly source: import("../types.js").RecursiveTypeMarker;
+                readonly update: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly slice: StructType<{
+                readonly from: OptionType<import("../types.js").RecursiveTypeMarker>;
+                readonly optional: BooleanType;
+                readonly target: import("../types.js").RecursiveTypeMarker;
+                readonly to: OptionType<import("../types.js").RecursiveTypeMarker>;
+            }>;
+            readonly string: ArrayType<VariantType<{
+                readonly interpolate: import("../types.js").RecursiveTypeMarker;
+                readonly text: StringType;
+            }>>;
+            readonly try: StructType<{
+                readonly body: import("../types.js").RecursiveTypeMarker;
+                readonly catch: OptionType<import("../types.js").RecursiveTypeMarker>;
+            }>;
+            readonly update: StructType<{
+                readonly op: StringType;
+                readonly path: import("../types.js").RecursiveTypeMarker;
+                readonly value: import("../types.js").RecursiveTypeMarker;
+            }>;
+            readonly variable: StringType;
+        }>>;
+    }>;
+}>;
+/**
+ * A range of query text.
+ *
+ * @remarks
+ * Offsets and lengths count UTF-16 code units, the unit browsers and
+ * TypeScript index strings in; python converts from code points, so a program
+ * holding characters outside the Basic Multilingual Plane gets the same span
+ * in both front ends.
+ *
+ * - `column` — 1-based, in UTF-16 code units of its line.
+ * - `length` — in UTF-16 code units.
+ * - `line` — 1-based.
+ * - `offset` — 0-based, in UTF-16 code units of the whole text.
+ */
+export declare const QuerySpanType: StructType<{
+    readonly column: IntegerType;
+    readonly length: IntegerType;
+    readonly line: IntegerType;
+    readonly offset: IntegerType;
+}>;
+/**
+ * One text edit: replace `length` UTF-16 code units at `offset` with
+ * `insert`.
+ */
+export declare const QueryEditType: StructType<{
+    readonly insert: StringType;
+    readonly length: IntegerType;
+    readonly offset: IntegerType;
+}>;
+/**
+ * A one-click fix for a diagnostic: its `label` ("Use .demand") and the text
+ * `edits` that make it, applied together.
+ *
+ * @remarks
+ * A fix is text edits so every client applies it the same way. The edits of
+ * one fix do not overlap.
+ */
+export declare const QueryFixType: StructType<{
+    readonly edits: ArrayType<StructType<{
+        readonly insert: StringType;
+        readonly length: IntegerType;
+        readonly offset: IntegerType;
+    }>>;
+    readonly label: StringType;
+}>;
+/**
+ * A diagnostic from checking a query, or an error from evaluating one.
+ *
+ * @remarks
+ * - `code` — `syntax`, `unknown_field`, `unknown_case`, `unknown_function`,
+ *   `type_mismatch`, `not_iterable`, `not_indexable`, `arity`,
+ *   `ambiguous_output`, `cannot_infer`, `unsupported` or
+ *   `array_builtin_on_element`, or a lint (`duplicate_outputs`,
+ *   `duplicate_key`, `never_missing`, `long_range`); `devdocs/QUERY.md` §12
+ *   lists each message's template. An error a query raised as it ran is
+ *   `runtime` (§15).
+ * - `fixes` — one-click fixes, best first.
+ * - `message` — one sentence, the same wherever the checker runs.
+ * - `severity` — `error`, or `warning` for a lint.
+ * - `span` — the text it is about, when it is about some.
+ * - `suggestions` — replacement texts for the span, best first.
+ */
+export declare const QueryErrorType: StructType<{
+    readonly code: StringType;
+    readonly fixes: ArrayType<StructType<{
+        readonly edits: ArrayType<StructType<{
+            readonly insert: StringType;
+            readonly length: IntegerType;
+            readonly offset: IntegerType;
+        }>>;
+        readonly label: StringType;
+    }>>;
+    readonly message: StringType;
+    readonly severity: VariantType<{
+        readonly error: NullType;
+        readonly warning: NullType;
+    }>;
+    readonly span: OptionType<StructType<{
+        readonly column: IntegerType;
+        readonly length: IntegerType;
+        readonly line: IntegerType;
+        readonly offset: IntegerType;
+    }>>;
+    readonly suggestions: ArrayType<StringType>;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/query/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/query/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa;;;;;;EAMxB,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;;;;;;;GAIvB,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BhB,CAAC;AAEJ;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB;;;;EAAkE,CAAC;AAErG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKxB,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;;;;;EAKxB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;EAA+E,CAAC;AAE1G;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;;;;;;;EAAqE,CAAC;AAE/F;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;EAOzB,CAAC"}