@elaraai/east 1.0.83 → 1.0.85

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

@@ -0,0 +1,345 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { type EastType } from "../../types.js";
+/**
+ * How many outputs a filter gives: at least `lo`, at most `hi`, where a `hi`
+ * of 2 stands for any number more than one.
+ *
+ * @internal
+ */
+export interface Mult {
+    /** 1 when the filter always gives at least one output. */
+    readonly lo: 0 | 1;
+    /** 0 for none, 1 for at most one, 2 for any number. */
+    readonly hi: 0 | 1 | 2;
+}
+/** Exactly one output. @internal */
+export declare const ONE: Mult;
+/** None or one output. @internal */
+export declare const MAYBE: Mult;
+/** No output: `empty`, `error`, `break`. @internal */
+export declare const ZERO: Mult;
+/** Any number of outputs. @internal */
+export declare const MANY: Mult;
+/** At least one output, possibly more. @internal */
+export declare const SOME: Mult;
+/**
+ * The multiplicity of `a | b`: each output of `a` feeds `b`.
+ *
+ * @remarks
+ * Not `then`: a module that exports a `then` is a thenable, and a promise
+ * resolved with its namespace calls that `then` and waits on it forever — as
+ * vitest's module runner resolves every module it loads.
+ *
+ * @internal
+ */
+export declare function piped(a: Mult, b: Mult): Mult;
+/**
+ * The multiplicity of `a, b`: the outputs of `a`, then those of `b`.
+ *
+ * @internal
+ */
+export declare function also(a: Mult, b: Mult): Mult;
+/**
+ * The multiplicity of a choice between two filters: `if`, `//`, `try`.
+ *
+ * @internal
+ */
+export declare function either(a: Mult, b: Mult): Mult;
+/**
+ * The multiplicity a checked query records.
+ *
+ * @internal
+ */
+export declare function wireMultiplicity(m: Mult): "one" | "maybe" | "many";
+/**
+ * What narrowing has proved about a value, following its type's structure.
+ *
+ * @remarks
+ * - `cases` — a variant holds one of these cases; `payload` is what is known
+ *   about the payload when there is only one.
+ * - `fields` — facts about some fields of a struct.
+ * - `elements` — facts about every element of an array, set or vector.
+ * - `values` — facts about every value of a dict.
+ * - `present` — an option holds a value.
+ *
+ * @internal
+ */
+export type Facts = {
+    readonly kind: "cases";
+    readonly cases: ReadonlySet<string>;
+    readonly payload: Facts | undefined;
+} | {
+    readonly kind: "fields";
+    readonly fields: ReadonlyMap<string, Facts>;
+} | {
+    readonly kind: "elements";
+    readonly element: Facts;
+} | {
+    readonly kind: "values";
+    readonly value: Facts;
+} | {
+    readonly kind: "present";
+    readonly payload: Facts | undefined;
+};
+/**
+ * An output of an East type, with what narrowing has proved about it.
+ *
+ * @internal
+ */
+export interface TypeShape {
+    readonly kind: "type";
+    readonly type: EastType;
+    readonly facts: Facts | undefined;
+}
+/**
+ * One member of a union: an output of one of several types, and the variant
+ * case it was read from when it is a payload.
+ *
+ * @internal
+ */
+export interface Member {
+    readonly shape: TypeShape;
+    readonly case: string | undefined;
+}
+/**
+ * The outputs of a filter as the checker knows them.
+ *
+ * @remarks
+ * - `type` — every output has this East type.
+ * - `union` — outputs have different types, one member per type (`..`, `.[]`
+ *   over a struct, the payload of an un-narrowed variant). A union must unify
+ *   into one type before it is collected or output.
+ * - `error` — a diagnostic was reported here; everything built on it is
+ *   unchecked, so one mistake reports one problem.
+ *
+ * @internal
+ */
+export type Shape = TypeShape | {
+    readonly kind: "union";
+    readonly members: readonly Member[];
+} | {
+    readonly kind: "error";
+};
+/** The shape after a reported problem. @internal */
+export declare const ERROR: Shape;
+/**
+ * The shape of outputs of one type.
+ *
+ * @internal
+ */
+export declare function typed(type: EastType, facts?: Facts): TypeShape;
+/**
+ * A union of members, flattened, with members of the same type and case
+ * merged; a single member is its own shape.
+ *
+ * @internal
+ */
+export declare function union(members: readonly Member[]): Shape;
+/**
+ * The members of a shape: one for a `type` shape.
+ *
+ * @internal
+ */
+export declare function membersOf(shape: Shape): readonly Member[];
+/**
+ * A type with its recursive wrapper and references read through: what a
+ * value of it is made of.
+ *
+ * @internal
+ */
+export declare function unwrap(type: EastType): EastType;
+/**
+ * The payload of an option that jq sees as `null` or the value: East JSON's
+ * flat options (`jsonFlatOptionPayload`).
+ *
+ * @param type - a type
+ * @returns the `some` payload's type, or `undefined` when the type is not a
+ *   flat option (jq then sees it as `{type, value}`)
+ *
+ * @internal
+ */
+export declare function nullablePayload(type: EastType): EastType | undefined;
+/**
+ * Whether jq sees values of a type as `null`: Null, or a flat option.
+ *
+ * @internal
+ */
+export declare function canBeNull(type: EastType): boolean;
+/**
+ * The type jq's `T` or `null` becomes: `Option<T>`, or `T` itself when it can
+ * already be `null`.
+ *
+ * @returns the type, or `undefined` when no type holds both: `T` is an option
+ *   jq sees as `{type, value}`, and wrapping it again would too
+ *
+ * @internal
+ */
+export declare function orNull(type: EastType): EastType | undefined;
+/**
+ * The one type two outputs can share, as jq's typed outputs unify.
+ *
+ * @param a - one output's type
+ * @param b - another's
+ * @returns their common type, or `undefined` when they have none
+ *
+ * @remarks
+ * - Equal types unify to themselves, and `Never` (no value) to the other.
+ * - A reference is read through, as jq sees its value: `Ref<T>` and `U`
+ *   unify as `T` and `U` do.
+ * - A recursive type and its node unify to the recursive type; another
+ *   recursive type only with `null`, or an option of it.
+ * - Integer and Float unify to Float.
+ * - `null` and `T` unify to `Option<T>`; `Option<T>` and `U` to
+ *   `Option<T ⊔ U>`.
+ * - Arrays, sets, dicts and vectors unify element-wise; `Array<Never>` (an
+ *   empty `[]`) takes the other's element type.
+ * - Structs with the same field names unify field by field, in the first's
+ *   field order; `Struct{}` (an empty `{}`) unifies with any dict.
+ * - Variants unify case by case, taking every case of both.
+ *
+ * @internal
+ */
+export declare function unify(a: EastType, b: EastType): EastType | undefined;
+/**
+ * The types `..` and `recurse` give on values of some types: each type, then
+ * the types of the values inside it, depth first, each once. Inside a value
+ * are an option's value, the elements of an array, set or vector, a matrix's
+ * rows, a dict's values, a struct's fields, and a variant's case name and
+ * payloads (jq's `{type, value}`).
+ *
+ * @param types - the input's types
+ * @returns the types, in the order the walk first meets them
+ *
+ * @internal
+ */
+export declare function descendTypes(types: readonly EastType[]): EastType[];
+/**
+ * The one type a shape's outputs share.
+ *
+ * @param shape - a shape
+ * @returns the type, `Never` for no outputs, or `undefined` when the members
+ *   have no common type (or the shape is an error)
+ *
+ * @internal
+ */
+export declare function unifyShape(shape: Shape): EastType | undefined;
+/**
+ * Prints a type for a diagnostic, as jq's users read one: `Integer`,
+ * `Option<Float>`, `Array<String>`, `Dict<String, Float>`,
+ * `Struct{id: Integer, total: Float}`, `Variant{cancelled, pending, shipped}`.
+ *
+ * @param type - the type
+ * @param depth - how many levels of structs to spell out
+ * @returns its text
+ *
+ * @remarks
+ * A struct deeper than `depth` prints as `Struct{…}`, and one with more than
+ * six fields lists six and `…`. A recursive type prints its node, and a
+ * reference back into it as `…`.
+ *
+ * @internal
+ */
+export declare function describeType(type: EastType, depth?: number): string;
+/**
+ * What a condition proves when it is true: that a variant at a field path
+ * from `.` holds one of some cases (`.status.type == "shipped"`), or that
+ * the value at the path has one of some jq types (`type == "number"`).
+ *
+ * @internal
+ */
+export type Proof = {
+    readonly kind: "case";
+    readonly path: readonly string[];
+    readonly cases: readonly string[];
+} | {
+    readonly kind: "type";
+    readonly path: readonly string[];
+    readonly types: readonly string[];
+};
+/**
+ * The names jq's `type` gives, and East's additions for its own types.
+ *
+ * @internal
+ */
+export declare const JQ_TYPE_NAMES: readonly string[];
+/**
+ * The names `type` can give for values of a type: an option's `null` and its
+ * payload's.
+ *
+ * @internal
+ */
+export declare function jqTypeNames(type: EastType): string[];
+/**
+ * Narrows a shape to the outputs whose jq type is one of some names: what
+ * `select(type == "object")` keeps.
+ *
+ * @internal
+ */
+export declare function narrowTypes(shape: Shape, types: readonly string[]): Shape;
+/**
+ * What the checker knows about a filter's outputs.
+ *
+ * @remarks
+ * - `shape` and `mult` — the outputs' types and how many there are.
+ * - `access` — the field names from the filter's input to its output, when
+ *   the filter only reads fields (`.a.b`, `.a | .b`).
+ * - `caseOf` — the output is `.P.type` of a variant at path `P`, with the cases
+ *   it can hold.
+ * - `proves` — what the output being true proves about the input.
+ * - `partial` — the output is an option only because some cases of a variant
+ *   lack the field read, so narrowing would make it exact: the case that has
+ *   it, the field, and the path of the node that read it.
+ * - `stream` — the output is an element of the stream the `[]` at this path
+ *   makes.
+ * - `typeOf` — the output is the jq type name of the value at this field
+ *   path from the input.
+ *
+ * @internal
+ */
+export interface Result {
+    readonly shape: Shape;
+    readonly mult: Mult;
+    readonly access?: readonly string[] | undefined;
+    readonly caseOf?: {
+        readonly path: readonly string[];
+        readonly variant: EastType;
+        readonly cases: readonly string[];
+    } | undefined;
+    readonly proves?: readonly Proof[] | undefined;
+    readonly partial?: {
+        readonly caseName: string;
+        readonly leaf: string;
+        readonly at: string;
+    } | undefined;
+    readonly stream?: string | undefined;
+    readonly typeOf?: readonly string[] | undefined;
+}
+/**
+ * Narrows a shape: the variant at `path` holds only `cases`.
+ *
+ * @param shape - the shape of `.`
+ * @param path - the field names from `.` to the variant
+ * @param cases - the cases it holds
+ * @returns the shape with the fact added, or the shape unchanged when the
+ *   path does not lead to a variant
+ *
+ * @internal
+ */
+export declare function refine(shape: Shape, path: readonly string[], cases: readonly string[]): Shape;
+/**
+ * The cases a variant can hold, given what is known about it.
+ *
+ * @internal
+ */
+export declare function casesOf(type: EastType, facts: Facts | undefined): string[];
+/**
+ * Whether values of a type can be sorted and compared by East's total order:
+ * every data type (no functions).
+ *
+ * @internal
+ */
+export declare function isOrdered(type: EastType): boolean;
+//# sourceMappingURL=shapes.d.ts.map

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

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