@elaraai/east 1.0.68 → 1.0.70

package/dist/src/expr/block.js

@@ -4,6 +4,7 @@
  */
 import {} from "../ast.js";
 import { ensure_source_map, get_current_source_map, get_location, get_location_id, printLocations } from "../location.js";
+import { bindingNameAt, parameterNames } from "../naming.js";
 import { FunctionType, isSubtype, NullType, printType, isTypeEqual, StringType, NeverType, VariantType, BooleanType, TypeUnion, IntegerType, StructType, ArrayType, AsyncFunctionType, assignTypeId } from "../types.js";
 import { typeMismatchError } from "../type_diff.js";
 import { AstSymbol, Expr, SourceMapSymbol, TypeSymbol } from "./expr.js";
@@ -28,6 +29,7 @@ import { isVariant } from "../containers/variant.js";
 import { RefExpr } from "./ref.js";
 import { AsyncFunctionExpr, createAsyncFunctionExpr } from "./asyncfunction.js";
 import { PatchType } from "../patch/index.js";
+import { applyTypeParameters, Builtins } from "../builtins.js";
 import { VectorExpr } from "./vector.js";
 import { MatrixExpr } from "./matrix.js";
 /** A factory function to help build `Expr` from AST.
@@ -141,11 +143,12 @@ export function from(value, type) {
         // pointer to user code (issue #204).
         return ensure_source_map(() => {
             const { inputs, output } = type;
-            const input_variables = inputs.map(i => ({
+            const input_variables = inputs.map((i, k) => ({
                 ast_type: "Variable",
                 type: i,
                 loc_id: get_location_id(),
                 mutable: false,
+                name: parameterNames(value)?.[k + 1],
             }));
             const $ = BlockBuilder(output);
             const input_exprs = input_variables.map(fromAst);
@@ -229,11 +232,12 @@ export function from(value, type) {
         }
         return ensure_source_map(() => {
             const { inputs, output } = type;
-            const input_variables = inputs.map(i => ({
+            const input_variables = inputs.map((i, k) => ({
                 ast_type: "Variable",
                 type: i,
                 loc_id: get_location_id(),
                 mutable: false,
+                name: parameterNames(value)?.[k + 1],
             }));
             const $ = BlockBuilder(output);
             const input_exprs = input_variables.map(fromAst);
@@ -327,11 +331,12 @@ export function from(value, type) {
 }
 export function func(input_types, output_type, body) {
     return ensure_source_map(() => {
-        const parameters = input_types.map(i => ({
+        const parameters = input_types.map((i, k) => ({
             ast_type: "Variable",
             type: i,
             loc_id: get_location_id(),
             mutable: false,
+            name: parameterNames(body)?.[k + 1],
         }));
         const $ = BlockBuilder(output_type ?? NeverType);
         let ret = body($, ...parameters.map(fromAst));
@@ -413,11 +418,12 @@ export function func(input_types, output_type, body) {
 }
 export function asyncFunction(input_types, output_type, body) {
     return ensure_source_map(() => {
-        const parameters = input_types.map(i => ({
+        const parameters = input_types.map((i, k) => ({
             ast_type: "Variable",
             type: i,
             loc_id: get_location_id(),
             mutable: false,
+            name: parameterNames(body)?.[k + 1],
         }));
         const $ = BlockBuilder(output_type ?? NeverType);
         let ret = body($, ...parameters.map(fromAst));
@@ -759,6 +765,7 @@ export function matchExpr(variant, handlers) {
             type: t,
             loc_id: get_location_id(),
             mutable: false,
+            name: parameterNames(handler)?.[1],
         };
         const ast = handler === undefined ? valueOrExprToAstTyped(null, NullType) : block($ => handler($, fromAst(data_variable)))[AstSymbol];
         out_type = TypeUnion(out_type, ast.type);
@@ -784,12 +791,14 @@ export function tryCatch(try_body, catch_body) {
         type: StringType,
         loc_id: get_location_id(),
         mutable: false,
+        name: parameterNames(catch_body)?.[1],
     };
     const stack_variable = {
         ast_type: "Variable",
         type: ArrayType(StructType({ filename: StringType, line: IntegerType, column: IntegerType })),
         loc_id: get_location_id(),
         mutable: false,
+        name: parameterNames(catch_body)?.[2],
     };
     if (typeof catch_body !== "function") {
         throw new Error(`tryCatch expected catch_body to be a function, got ${typeof catch_body}`);
@@ -926,6 +935,107 @@ export function is(left, right) {
         arguments: [Expr.ast(left), rightAst],
     });
 }
+/**
+ * Calls an East builtin by name — the raw spelling for a builtin the surface
+ * has no method for, and the form the codegen printers fall back to for one
+ * (`RAW_ONLY`). The python twin is `East.builtin`.
+ *
+ * @param name - The builtin's IR name, e.g. `"ArrayGetKeys"`
+ * @param typeParameters - Its type parameters, in declaration order
+ * @param args - Its arguments in IR order — expressions, values, or callbacks
+ * @param outputType - The type of the result
+ * @returns The `Builtin` expression, typed `outputType`
+ * @throws {Error} When `name` is not a builtin, or the type-parameter or
+ *   argument counts do not match its declaration
+ *
+ * @example
+ * ```ts
+ * const size = East.function([ArrayType(IntegerType)], IntegerType, ($, xs) => {
+ *   $.return(East.builtin("ArraySize", [IntegerType], [xs], IntegerType));
+ * });
+ * const compiled = East.compile(size, []);
+ * compiled([1n, 2n, 3n]);  // 3n
+ * ```
+ */
+export function builtin(name, typeParameters, args, outputType) {
+    const def = Builtins[name];
+    if (def === undefined) {
+        throw new Error(`Unknown builtin function '${name}'`);
+    }
+    if (def.type_parameters.length !== typeParameters.length) {
+        throw new Error(`Builtin function '${name}' expected ${def.type_parameters.length} type parameters, got ${typeParameters.length}`);
+    }
+    if (def.inputs.length !== args.length) {
+        throw new Error(`Builtin function '${name}' expected ${def.inputs.length} arguments, got ${args.length}`);
+    }
+    const typeMap = new Map(def.type_parameters.map((param, i) => [param, typeParameters[i]]));
+    const argAsts = args.map((arg, i) => {
+        const expected = applyTypeParameters(def.inputs[i], typeMap, [], []);
+        return valueOrExprToAstTyped(arg, expected);
+    });
+    return fromAst({
+        ast_type: "Builtin",
+        type: outputType,
+        loc_id: get_location_id(),
+        builtin: name,
+        type_parameters: typeParameters,
+        arguments: argAsts,
+    });
+}
+/**
+ * Widens a value to a declared supertype explicitly — an `As` node. The
+ * builder inserts the same node itself wherever a narrower value meets a
+ * wider declared type (a `$.const(x, T)`, a function argument), so this is
+ * the spelling for the other positions; the codegen printers spell every
+ * IR `As` with it. The python twin is `East.as_`.
+ *
+ * @param value - The value or expression to widen
+ * @param type - The wider type; the value's type must be a subtype of it
+ * @returns The value as an expression of `type`
+ * @throws {Error} When the value's type is not a subtype of `type`
+ *
+ * @example
+ * ```ts
+ * const Shape = VariantType({ circle: FloatType, square: FloatType });
+ * const widen = East.function([FloatType], Shape, ($, r) => {
+ *   $.return(East.as(East.value(variant("circle", r)), Shape));
+ * });
+ * const compiled = East.compile(widen, []);
+ * compiled(2.0);  // variant("circle", 2.0)
+ * ```
+ */
+export function as(value, type) {
+    const ast = valueOrExprToAstTyped(value, type);
+    return fromAst({
+        ast_type: "As",
+        type,
+        loc_id: get_location_id(),
+        value: ast,
+    });
+}
+/**
+ * Wraps a value or expression of a recursive type's node type in the
+ * recursive type — a `WrapRecursive` node; {@link RecursiveExpr.unwrap} is
+ * its inverse. The python twin is `East.wrap_recursive`.
+ *
+ * @param value - The value or expression of the wrapper's node type
+ * @param type - The recursive type to wrap it in
+ * @returns A `RecursiveExpr` of `type`
+ *
+ * @example
+ * ```ts
+ * const ListType = RecursiveType(self => VariantType({ nil: NullType, cons: StructType({ head: IntegerType, tail: self }) }));
+ * const singleton = East.function([IntegerType], ListType, ($, x) => {
+ *   const nil = $.const(East.wrapRecursive(variant("nil", null), ListType));
+ *   $.return(East.wrapRecursive(variant("cons", { head: x, tail: nil }), ListType));
+ * });
+ * const compiled = East.compile(singleton, []);
+ * compiled(1n);  // variant("cons", { head: 1n, tail: variant("nil", null) })
+ * ```
+ */
+export function wrapRecursive(value, type) {
+    return RecursiveExpr.wrap(value, type, fromAst);
+}
 /** Print a value as a string. */
 export function print(value) {
     const valueAst = Expr.ast(value);
@@ -1009,6 +1119,42 @@ export function invertPatch(patch, type) {
         arguments: [patchAst],
     });
 }
+/**
+ * The brand every declaration handle carries — a registered symbol, so a
+ * handle built by any copy of `@elaraai/east` in the process is recognised.
+ */
+export const PLATFORM_DECLARATION = Symbol.for("elaraai.east.platformDeclaration");
+/**
+ * Whether `value` is a platform declaration handle — what `East.platform`,
+ * `East.asyncPlatform`, `East.genericPlatform` and `East.asyncGenericPlatform`
+ * return.
+ *
+ * @param value - Anything
+ * @returns True for a declaration handle, whose identity fields are then typed
+ *
+ * @example
+ * ```ts
+ * const log = East.platform("log", [StringType], NullType);
+ * isPlatformDeclaration(log);   // true
+ * log.name;                     // "log"
+ * ```
+ */
+export function isPlatformDeclaration(value) {
+    return typeof value === "function" && value[PLATFORM_DECLARATION] === true;
+}
+/** Stamps a handle with its identity: the brand, and the declaration fields as own properties. */
+function brandDeclaration(fn, declaration) {
+    Object.defineProperty(fn, PLATFORM_DECLARATION, { value: true });
+    // a function's `name` is configurable: the handle's is the platform function's, not `fn`
+    Object.defineProperty(fn, "name", { value: declaration.name, configurable: true });
+    Object.defineProperty(fn, "inputs", { value: declaration.inputs, enumerable: true });
+    Object.defineProperty(fn, "output", { value: declaration.output, enumerable: true });
+    Object.defineProperty(fn, "async", { value: declaration.async, enumerable: true });
+    Object.defineProperty(fn, "optional", { value: declaration.optional, enumerable: true });
+    if (declaration.typeParameters !== undefined) {
+        Object.defineProperty(fn, "typeParameters", { value: declaration.typeParameters, enumerable: true });
+    }
+}
 /** Create a callable helper to invoke a synchronous platform function.
  *
  * Platform functions provide access to external capabilities (logging, I/O, database access, etc.)
@@ -1110,6 +1256,7 @@ export function platform(name, input_types, output_type, options = {}) {
             };
         }
     };
+    brandDeclaration(fn, { name, inputs: input_types, output: output_type, async: false, optional: isOptional });
     return fn;
 }
 /** Create a callable helper to invoke an asynchronous platform function.
@@ -1203,6 +1350,7 @@ export function asyncPlatform(name, input_types, output_type, options = {}) {
             };
         }
     };
+    brandDeclaration(fn, { name, inputs: input_types, output: output_type, async: true, optional: isOptional });
     return fn;
 }
 // Runtime type substitution function
@@ -1410,6 +1558,7 @@ export function genericPlatform(name, typeParams, inputs, output, options = {})
             fn: factory,
         };
     };
+    brandDeclaration(fn, { name, inputs, output, async: false, optional: isOptional, typeParameters: typeParams });
     return fn;
 }
 /** Create a callable helper to invoke an asynchronous generic (polymorphic) platform function.
@@ -1548,6 +1697,7 @@ export function asyncGenericPlatform(name, typeParams, inputs, output, options =
             fn: factory,
         };
     };
+    brandDeclaration(fn, { name, inputs, output, async: true, optional: isOptional, typeParameters: typeParams });
     return fn;
 }
 export const BlockBuilder = (return_type) => {
@@ -1584,6 +1734,7 @@ export const BlockBuilder = (return_type) => {
             type: type ?? ast.type,
             loc_id: get_location_id(),
             mutable: false,
+            name: bindingNameAt(get_location()) ?? undefined,
         };
         statements.push({
             ast_type: "Let",
@@ -1613,6 +1764,7 @@ export const BlockBuilder = (return_type) => {
             type: type ?? ast.type,
             loc_id: get_location_id(),
             mutable: true,
+            name: bindingNameAt(get_location()) ?? undefined,
         };
         statements.push({
             ast_type: "Let",
@@ -1764,6 +1916,7 @@ export const BlockBuilder = (return_type) => {
                 type: t,
                 loc_id: get_location_id(),
                 mutable: false,
+                name: parameterNames(f)?.[1],
             };
             if (f === undefined) {
                 cases_out[k] = { variable: data_variable, body: { ast_type: "Value", type: NullType, loc_id: get_location_id(), value: null } };
@@ -1874,6 +2027,7 @@ export const BlockBuilder = (return_type) => {
                 type: Expr.type(collection).value,
                 loc_id: get_location_id(),
                 mutable: false,
+                name: parameterNames(body)?.[1],
             };
             const value = fromAst(value_variable);
             const key_variable = {
@@ -1881,6 +2035,7 @@ export const BlockBuilder = (return_type) => {
                 type: IntegerType,
                 loc_id: get_location_id(),
                 mutable: false,
+                name: parameterNames(body)?.[2],
             };
             const key = fromAst(key_variable);
             const label = { loc_id: get_location_id() };
@@ -1930,6 +2085,7 @@ export const BlockBuilder = (return_type) => {
                 type: Expr.type(collection).key,
                 loc_id: get_location_id(),
                 mutable: false,
+                name: parameterNames(body)?.[1],
             };
             const key = fromAst(key_variable);
             const label = { loc_id: get_location_id() };
@@ -1978,6 +2134,7 @@ export const BlockBuilder = (return_type) => {
                 type: Expr.type(collection).value,
                 loc_id: get_location_id(),
                 mutable: false,
+                name: parameterNames(body)?.[1],
             };
             const value = fromAst(value_variable);
             const key_variable = {
@@ -1985,6 +2142,7 @@ export const BlockBuilder = (return_type) => {
                 type: Expr.type(collection).key,
                 loc_id: get_location_id(),
                 mutable: false,
+                name: parameterNames(body)?.[2],
             };
             const key = fromAst(key_variable);
             const label = { loc_id: get_location_id() };
@@ -2207,6 +2365,12 @@ class TryCatchExpr extends NullExpr {
         }
         this.catchCalled = true;
         const $ = BlockBuilder(this.return_type);
+        // the handler names the catch variables (#639): `($, message, stack) => …`
+        const names = parameterNames(body);
+        if (names?.[1] !== undefined)
+            this.message_variable.name = names[1];
+        if (names?.[2] !== undefined)
+            this.stack_variable.name = names[2];
         const ret = body($, fromAst(this.message_variable), fromAst(this.stack_variable));
         const stmts = $.statements;
         if (ret !== undefined) {