@elaraai/east 1.0.84 → 1.0.86

package/dist/src/query/types.js

@@ -0,0 +1,231 @@
+/**
+ * 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 const JqLiteralType = VariantType({
+    boolean: BooleanType,
+    float: FloatType,
+    integer: IntegerType,
+    null: NullType,
+    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 const JqPatternType = RecursiveType(pattern => VariantType({
+    array: ArrayType(pattern),
+    object: ArrayType(StructType({ key: StringType, value: OptionType(pattern) })),
+    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 const JqType = RecursiveType(jq => VariantType({
+    alternative: StructType({ left: jq, right: jq }),
+    array: OptionType(jq),
+    binary: StructType({ left: jq, op: StringType, right: jq }),
+    bind: StructType({ body: jq, patterns: ArrayType(JqPatternType), source: jq }),
+    break: StringType,
+    call: StructType({ args: ArrayType(jq), name: StringType }),
+    comma: StructType({ left: jq, right: jq }),
+    def: StructType({ body: jq, name: StringType, params: ArrayType(StringType), rest: jq }),
+    descend: NullType,
+    field: StructType({ name: StringType, optional: BooleanType, target: jq }),
+    foreach: StructType({ extract: OptionType(jq), init: jq, pattern: JqPatternType, source: jq, update: jq }),
+    format: StructType({ name: StringType, string: OptionType(jq) }),
+    identity: NullType,
+    if: StructType({ branches: ArrayType(StructType({ condition: jq, then: jq })), otherwise: OptionType(jq) }),
+    index: StructType({ index: jq, optional: BooleanType, target: jq }),
+    iterate: StructType({ optional: BooleanType, target: jq }),
+    label: StructType({ body: jq, name: StringType }),
+    literal: JqLiteralType,
+    negate: jq,
+    object: ArrayType(StructType({
+        key: VariantType({ computed: jq, name: StringType, variable: StringType }),
+        value: OptionType(jq),
+    })),
+    pipe: StructType({ left: jq, right: jq }),
+    reduce: StructType({ init: jq, pattern: JqPatternType, source: jq, update: jq }),
+    slice: StructType({ from: OptionType(jq), optional: BooleanType, target: jq, to: OptionType(jq) }),
+    string: ArrayType(VariantType({ interpolate: jq, text: StringType })),
+    try: StructType({ body: jq, catch: OptionType(jq) }),
+    update: StructType({ op: StringType, path: jq, value: jq }),
+    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 const QueryMultiplicityType = VariantType({ many: NullType, maybe: NullType, 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 const QueryCallType = VariantType({
+    v1: StructType({
+        inputs: OptionType(ArrayType(StringType)),
+        program: JqType,
+    }),
+});
+/**
+ * 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 const QuerySpanType = StructType({
+    column: IntegerType,
+    length: IntegerType,
+    line: IntegerType,
+    offset: IntegerType,
+});
+/**
+ * One text edit: replace `length` UTF-16 code units at `offset` with
+ * `insert`.
+ */
+export const QueryEditType = StructType({ insert: StringType, length: IntegerType, 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 const QueryFixType = StructType({ edits: ArrayType(QueryEditType), 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 const QueryErrorType = StructType({
+    code: StringType,
+    fixes: ArrayType(QueryFixType),
+    message: StringType,
+    severity: VariantType({ error: NullType, warning: NullType }),
+    span: OptionType(QuerySpanType),
+    suggestions: ArrayType(StringType),
+});
+//# sourceMappingURL=types.js.map

package/dist/src/query/types.js.map

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

package/dist/src/runner_exec.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Executing a unit of the runner protocol: {@link executeUnit}, the one
+ * TypeScript unit runner, over a {@link UnitIO}.
+ *
+ * A unit (`UnitType`) runs a program on its inputs, merges the parts of one
+ * output that earlier units wrote, or takes a delivered collection in, and
+ * names where its output and its result go. A program's output is written by
+ * its kind:
+ * - a value as one blob, or as a manifest directory when it is a collection;
+ * - an array through the Writer;
+ * - a set or a dict through the RunSorter, as sorted runs;
+ * - a fold by folding every emitted value into an accumulator.
+ *
+ * A delivery taken in is read a segment at a time from its file, and written
+ * through the Writer as a manifest directory (`intakeBeast2For`).
+ *
+ * Collections are written as manifest directories, which a store takes in by
+ * linking their files. The result (`UnitResultType`) records the outcome —
+ * `ok`, or the failure's message and source locations — with where the time
+ * went and the host's peak memory. east-c and east-py implement the same
+ * protocol, and the conformance corpus holds the three to the same output
+ * bytes and outcomes.
+ *
+ * The work reaches its files only through the UnitIO it is given, its
+ * platform functions only through the host's resolver, and the host's memory
+ * only through the gauges it is given, so the same code runs as east-node's
+ * `exec` over this machine's files and in a browser's Web Worker over an
+ * `InMemoryUnitIO` — east-c's shape (`east/unit.h`), where the unit machinery
+ * is library code and its CLI wires it to files.
+ */
+import { type EastTypeValue } from "./type_of_type.js";
+import type { PlatformFunction } from "./platform.js";
+import { type Beast2LazyStats } from "./serialization/beast2/index.js";
+import type { Unit, UnitResult } from "./runner_protocol.js";
+import { type UnitIO, type UnitInputReport } from "./runner_io.js";
+/** One input of a run unit, as a report names it. */
+export interface UnitRunInput {
+    /** The input's file, as the unit names it. */
+    readonly path: string;
+    /** The type the input is read as: its parameter's. */
+    readonly type: EastTypeValue;
+}
+/**
+ * What a host hears of a run unit's inputs as its work goes: the account a
+ * runner's `exec -v` prints, which reaches a task's log.
+ *
+ * @remarks
+ * The report says what happened and the host says it in its own words:
+ * east-node's prints the lines east-c and east-py print. A merge or intake
+ * unit reads no program inputs, and reports nothing.
+ */
+export interface UnitRunReport extends UnitInputReport {
+    /**
+     * The program is loaded and its signature fits the unit: it is about to run
+     * on `inputs`, none read yet.
+     *
+     * @param program - the program's file, as the unit names it
+     * @param inputs - the inputs, in parameter order
+     */
+    running(program: string, inputs: readonly UnitRunInput[]): void;
+    /**
+     * The program ran, and its output was written — or either failed: what
+     * reading lazy input `index` came to. Inputs decoded whole have no reads to
+     * account for.
+     *
+     * @param index - the input's position
+     * @param path - the input's file, as the unit names it
+     * @param stats - its segment decodes and fence probes, and whether an
+     *   operation the pager cannot serve read it whole
+     * @param bytesRead - the bytes its reads read from its files
+     */
+    lazyReads(index: number, path: string, stats: Beast2LazyStats, bytesRead: number): void;
+}
+/** What a host gives {@link executeUnit} besides the unit and its files. */
+export interface ExecuteUnitOptions {
+    /**
+     * Resolves the platform functions of one package the unit lists, as the
+     * runner names it. Asked once per package, in the unit's order, before the
+     * work begins; a package it cannot resolve fails the unit with its message.
+     *
+     * @param name - the package's name
+     * @returns its platform functions
+     */
+    platforms(name: string): readonly PlatformFunction[] | Promise<readonly PlatformFunction[]>;
+    /** The host's resident memory now, in bytes: what a lazily opened input
+     *  weighs a read of it whole by, and what the report says an input decoded
+     *  whole added. Without it, both come to 0. east-node's reads
+     *  `process.memoryUsage.rss()`. */
+    resident?: () => number;
+    /** The host's peak resident memory in bytes, read once the work is done:
+     *  the result's `peakBytes`. Without it the result says 0 — the host does
+     *  not measure memory, as a browser does not. */
+    peakBytes?: () => bigint;
+    /** The decoded weight, in bytes, each lazily opened input's pager keeps of
+     *  the segments its keyed and index reads decode (v5/SPEC.md, "The pager's
+     *  cache"): 256 MiB without it. east-node's reads it from
+     *  `EAST_PAGED_CACHE_BYTES`, as east-c's pager does. */
+    cacheBytes?: number;
+    /** Hears how a run unit reads its inputs: without it, nothing is reported
+     *  and nothing is measured for a report. */
+    report?: UnitRunReport;
+}
+/**
+ * Executes a unit: does its work over `io`, writes its output there, and says
+ * how it went.
+ *
+ * @param unit - the unit; the files it names are read and written through `io`
+ * @param io - the unit's files
+ * @param options - the host's platform resolver, its memory gauges, the
+ *   decoded weight a lazy input's pager keeps, and who hears how the inputs
+ *   are read
+ * @returns the result — a failure is its outcome, never a throw. The host
+ *   writes it where the unit's `result` says, if it keeps it
+ *
+ * @remarks
+ * The unit's thread grant caps the frame pool for the rest of the process: a
+ * grant of one frames every output inline. A unit whose host places its
+ * segments as they are read (`fetch`) has `io` asked for each segment of a
+ * staged manifest before it is read ({@link UnitIO.segment}).
+ *
+ * @example
+ * ```ts
+ * const io = new InMemoryUnitIO(files);  // the unit and every file it names
+ * const unit = decodeBeast2For(UnitType)(io.read("unit.beast2"));
+ * const result = await executeUnit(unit, io, { platforms: (name) => packages.get(name)! });
+ * if (result.outcome.type === "ok") io.files.get("output.beast2");  // the output
+ * ```
+ */
+export declare function executeUnit(unit: Unit, io: UnitIO, options: ExecuteUnitOptions): Promise<UnitResult>;
+//# sourceMappingURL=runner_exec.d.ts.map

package/dist/src/runner_exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner_exec.d.ts","sourceRoot":"","sources":["../../src/runner_exec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAuC,MAAM,mBAAmB,CAAC;AAM5F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAQL,KAAK,eAAe,EAGrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,IAAI,EAA2B,UAAU,EAAe,MAAM,sBAAsB,CAAC;AACnG,OAAO,EACL,KAAK,MAAM,EACX,KAAK,eAAe,EAMrB,MAAM,gBAAgB,CAAC;AAexB,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI,CAAC;IAChE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACzF;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,gBAAgB,EAAE,GAAG,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAC;IAC5F;;;uCAGmC;IACnC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB;;qDAEiD;IACjD,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IACzB;;;4DAGwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;gDAC4C;IAC5C,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CA4B1G"}