@elaraai/east 0.0.1-beta.25 → 0.0.1-beta.27

package/dist/src/expr/block.js

@@ -23,8 +23,10 @@ import { RecursiveExpr } from "./recursive.js";
 import { createFunctionExpr, FunctionExpr } from "./function.js";
 import { valueOrExprToAst, valueOrExprToAstTyped } from "./ast.js";
 import { toEastTypeValue } from "../type_of_type.js";
+import { isVariant } from "../containers/variant.js";
 import { RefExpr } from "./ref.js";
 import { AsyncFunctionExpr, createAsyncFunctionExpr } from "./asyncfunction.js";
+import { PatchType } from "../patch/index.js";
 /** A factory function to help build `Expr` from AST.
  * We inject this into each concrete `Expr` type so they can create new expressions recursively, without having circular dependencies between JavaScript modules.
  */
@@ -833,6 +835,37 @@ export function greaterEqual(left, right) {
         arguments: [Expr.ast(left), rightAst],
     });
 }
+// ============================================================================
+// Aliases for standalone comparison functions
+// ============================================================================
+/** Alias for {@link equal} */
+export const equals = equal;
+/** Alias for {@link equal} */
+export const eq = equal;
+/** Alias for {@link notEqual} */
+export const notEquals = notEqual;
+/** Alias for {@link notEqual} */
+export const ne = notEqual;
+/** Alias for {@link less} */
+export const lessThan = less;
+/** Alias for {@link less} */
+export const lt = less;
+/** Alias for {@link lessEqual} */
+export const lessThanOrEqual = lessEqual;
+/** Alias for {@link lessEqual} */
+export const lte = lessEqual;
+/** Alias for {@link lessEqual} */
+export const le = lessEqual;
+/** Alias for {@link greater} */
+export const greaterThan = greater;
+/** Alias for {@link greater} */
+export const gt = greater;
+/** Alias for {@link greaterEqual} */
+export const greaterThanOrEqual = greaterEqual;
+/** Alias for {@link greaterEqual} */
+export const gte = greaterEqual;
+/** Alias for {@link greaterEqual} */
+export const ge = greaterEqual;
 /** Test if the first value is the same object the second.
  * For mutable collections, such as arrays, this means that they are the same object in memory.
  * For immutable data types, such as integers and strings, this is equivalent to equality.
@@ -860,6 +893,77 @@ export function print(value) {
         arguments: [valueAst],
     });
 }
+// ============================================================================
+// Patch Operations
+// ============================================================================
+/** Compute the difference between two values of the same type.
+ * Returns a patch that, when applied to `before`, produces `after`.
+ */
+export function diff(before, after) {
+    const beforeAst = Expr.ast(before);
+    const afterAst = Expr.ast(after);
+    const valueType = beforeAst.type;
+    const patchType = PatchType(valueType);
+    return fromAst({
+        ast_type: "Builtin",
+        type: patchType,
+        location: get_location(2),
+        builtin: "Diff",
+        type_parameters: [valueType, patchType],
+        arguments: [beforeAst, afterAst],
+    });
+}
+/** Apply a patch to a value, producing the modified value.
+ * @throws East runtime error if the patch conflicts with the value (e.g., deleting a non-existent key)
+ */
+export function applyPatch(value, patch) {
+    const valueAst = Expr.ast(value);
+    const patchAst = Expr.ast(patch);
+    const valueType = valueAst.type;
+    const patchType = patchAst.type;
+    return fromAst({
+        ast_type: "Builtin",
+        type: valueType,
+        location: get_location(2),
+        builtin: "ApplyPatch",
+        type_parameters: [valueType, patchType],
+        arguments: [valueAst, patchAst],
+    });
+}
+/** Compose two patches into a single patch.
+ * The result is a patch that has the same effect as applying `first` then `second`.
+ * @throws East runtime error if the patches are incompatible (second expects different intermediate state)
+ */
+export function composePatch(first, second, type) {
+    const firstAst = Expr.ast(first);
+    const secondAst = Expr.ast(second);
+    const valueType = type;
+    const patchType = PatchType(valueType);
+    return fromAst({
+        ast_type: "Builtin",
+        type: patchType,
+        location: get_location(2),
+        builtin: "ComposePatch",
+        type_parameters: [valueType, patchType],
+        arguments: [firstAst, secondAst],
+    });
+}
+/** Invert a patch, producing a patch that undoes the original.
+ * Applying the inverted patch to the "after" value produces the "before" value.
+ */
+export function invertPatch(patch, type) {
+    const patchAst = Expr.ast(patch);
+    const valueType = type;
+    const patchType = PatchType(valueType);
+    return fromAst({
+        ast_type: "Builtin",
+        type: patchType,
+        location: get_location(2),
+        builtin: "InvertPatch",
+        type_parameters: [valueType, patchType],
+        arguments: [patchAst],
+    });
+}
 /** Create a callable helper to invoke a synchronous platform function.
  *
  * Platform functions provide access to external capabilities (logging, I/O, database access, etc.)
@@ -921,6 +1025,7 @@ export function platform(name, input_types, output_type) {
             type: output_type,
             location: get_location(2),
             name: name,
+            type_parameters: [],
             arguments: argAsts,
             async: false,
         });
@@ -1010,6 +1115,7 @@ export function asyncPlatform(name, input_types, output_type) {
             type: output_type,
             location: get_location(2),
             name: name,
+            type_parameters: [],
             arguments: argAsts,
             async: true,
         });
@@ -1039,6 +1145,347 @@ export function asyncPlatform(name, input_types, output_type) {
     };
     return fn;
 }
+// Runtime type substitution function
+function applyTypeArgs(typeArgs, t) {
+    if (typeof t === 'string') {
+        const ret = typeArgs[t];
+        if (ret === undefined) {
+            throw new Error(`Unexpected type argument ${t}`);
+        }
+        return ret;
+    }
+    else if (t.type === "Ref") {
+        return { type: "Ref", value: applyTypeArgs(typeArgs, t.value) };
+    }
+    else if (t.type === "Array") {
+        return { type: "Array", value: applyTypeArgs(typeArgs, t.value) };
+    }
+    else if (t.type === "Set") {
+        return { type: "Set", key: applyTypeArgs(typeArgs, t.key) };
+    }
+    else if (t.type === "Dict") {
+        return { type: "Dict", key: applyTypeArgs(typeArgs, t.key), value: applyTypeArgs(typeArgs, t.value) };
+    }
+    else if (t.type === "Struct") {
+        const newFields = {};
+        for (const k in t.fields) {
+            newFields[k] = applyTypeArgs(typeArgs, t.fields[k]);
+        }
+        return { type: "Struct", fields: newFields };
+    }
+    else if (t.type === "Variant") {
+        const newCases = {};
+        for (const k in t.cases) {
+            newCases[k] = applyTypeArgs(typeArgs, t.cases[k]);
+        }
+        return { type: "Variant", cases: newCases };
+    }
+    else if (t.type === "Function") {
+        const newInputs = t.inputs.map((inputType) => applyTypeArgs(typeArgs, inputType));
+        const newOutput = applyTypeArgs(typeArgs, t.output);
+        return { type: "Function", inputs: newInputs, output: newOutput };
+    }
+    else if (t.type === "Recursive") {
+        if (t.node === undefined) {
+            // RecursiveTypeMarker (self-reference) - leave alone
+            return t;
+        }
+        return { type: "Recursive", node: applyTypeArgs(typeArgs, t.node) };
+    }
+    else {
+        return t;
+    }
+}
+/** Create a callable helper to invoke a generic (polymorphic) platform function.
+ *
+ * Generic platform functions allow you to define platform functions with type parameters,
+ * similar to how builtins work. The type parameters are passed at call time and flow
+ * through to the implementation.
+ *
+ * @param name - The name of the platform function
+ * @param typeParams - Array of type parameter names (e.g., `["T", "U"]`)
+ * @param inputs - Array of input types, can contain string placeholders like `"T"`
+ * @param output - Output type, can be a string placeholder like `"T"`
+ * @returns A callable function that creates Platform AST nodes when invoked
+ *
+ * @example
+ * ```ts
+ * // Define a generic log function
+ * const log = East.genericPlatform(
+ *   "log",
+ *   ["T"],
+ *   ["T"],      // Input is type parameter T
+ *   NullType
+ * );
+ *
+ * // Use it in East code - type args as array, then value args
+ * const myFunction = East.function([StringType], NullType, ($, s) => {
+ *   $(log([StringType], s));
+ * });
+ *
+ * // Implementation receives type params as a factory
+ * const platform = [
+ *   log.implement((T) => (value) => {
+ *     console.log(printFor(T)(value));
+ *     return null;
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Define a generic map function with 2 type parameters
+ * const map = East.genericPlatform(
+ *   "map",
+ *   ["T", "U"],
+ *   ["T", FunctionType(["T"], "U")],  // String placeholders in nested types
+ *   "U"
+ * );
+ *
+ * // Call with type args array, then value arguments
+ * map([StringType, IntegerType], myString, myMapperFn)
+ * ```
+ */
+export function genericPlatform(name, typeParams, inputs, output) {
+    const numTypeParams = typeParams.length;
+    const fn = (type_args, ...valueArgs) => {
+        // Validate type args array
+        if (!Array.isArray(type_args)) {
+            throw new Error(`Generic platform function '${name}' expects type arguments as an array, ` +
+                `got ${typeof type_args}`);
+        }
+        // Validate type args count
+        if (type_args.length !== numTypeParams) {
+            throw new Error(`Generic platform function '${name}' expects ${numTypeParams} type parameters, ` +
+                `got ${type_args.length}`);
+        }
+        // Validate type args are EastTypes
+        for (let i = 0; i < numTypeParams; i++) {
+            const typeArg = type_args[i];
+            if (!typeArg || typeof typeArg !== 'object' || !('type' in typeArg)) {
+                throw new Error(`Generic platform function '${name}' expects type parameter ${i + 1} ` +
+                    `(${typeParams[i]}) to be an EastType`);
+            }
+        }
+        // Build type argument map
+        const typeArgMap = {};
+        typeParams.forEach((param, idx) => {
+            typeArgMap[param] = type_args[idx];
+        });
+        // Apply type substitution to get concrete input/output types
+        const inputTypes = inputs.map(t => applyTypeArgs(typeArgMap, t));
+        const outputType = applyTypeArgs(typeArgMap, output);
+        // Validate value args count
+        if (valueArgs.length !== inputTypes.length) {
+            throw new Error(`Generic platform function '${name}' expects ${inputTypes.length} ` +
+                `value arguments, got ${valueArgs.length}`);
+        }
+        // Convert value args to AST with type validation and implicit casts
+        const argAsts = valueArgs.map((arg, index) => {
+            const expectedType = inputTypes[index];
+            let ast = valueOrExprToAstTyped(arg, expectedType);
+            if (ast.type.type === "Never") {
+                throw new Error(`Generic platform function ${name} argument ${index + 1} expected type ${printType(expectedType)}, got Never type`);
+            }
+            if (!isTypeEqual(ast.type, expectedType)) {
+                if (!isSubtype(ast.type, expectedType)) {
+                    throw new Error(`Generic platform function ${name} argument ${index + 1} expected type ${printType(expectedType)}, got ${printType(ast.type)}`);
+                }
+                // Insert implicit cast
+                ast = {
+                    ast_type: "As",
+                    type: expectedType,
+                    location: get_location(2),
+                    value: ast,
+                };
+            }
+            return ast;
+        });
+        // Create PlatformAST with type_parameters
+        return fromAst({
+            ast_type: "Platform",
+            type: outputType,
+            location: get_location(2),
+            name: name,
+            type_parameters: type_args,
+            arguments: argAsts,
+            async: false,
+        });
+    };
+    fn.implement = (factory) => {
+        return {
+            name,
+            type_parameters: [...typeParams],
+            inputs: [], // Computed at call time via inputsFn
+            output: toEastTypeValue(NullType), // Placeholder
+            inputsFn: (...tps) => {
+                const typeArgMap = {};
+                typeParams.forEach((param, idx) => {
+                    typeArgMap[param] = tps[idx];
+                });
+                return inputs.map(t => {
+                    if (typeof t === 'string')
+                        return typeArgMap[t];
+                    let result = applyTypeArgs(typeArgMap, t);
+                    if (!isVariant(result))
+                        result = toEastTypeValue(result);
+                    return result;
+                });
+            },
+            outputsFn: (...tps) => {
+                const typeArgMap = {};
+                typeParams.forEach((param, idx) => {
+                    typeArgMap[param] = tps[idx];
+                });
+                if (typeof output === 'string')
+                    return typeArgMap[output];
+                let result = applyTypeArgs(typeArgMap, output);
+                if (!isVariant(result))
+                    result = toEastTypeValue(result);
+                return result;
+            },
+            type: 'sync',
+            fn: factory,
+        };
+    };
+    return fn;
+}
+/** Create a callable helper to invoke an asynchronous generic (polymorphic) platform function.
+ *
+ * This is the async variant of `genericPlatform`. The implementation factory should return
+ * an async function.
+ *
+ * @param name - The name of the platform function
+ * @param typeParams - Array of type parameter names (e.g., `["T", "U"]`)
+ * @param inputs - Array of input types, can contain string placeholders like `"T"`
+ * @param output - Output type, can be a string placeholder like `"T"`
+ * @returns A callable function that creates Platform AST nodes when invoked
+ *
+ * @see {@link genericPlatform} for synchronous generic platform functions
+ *
+ * @example
+ * ```ts
+ * // Define an async generic fetch function
+ * const fetchAs = East.asyncGenericPlatform(
+ *   "fetchAs",
+ *   ["T"],
+ *   [StringType],  // URL input
+ *   "T"            // Returns parsed value of type T
+ * );
+ *
+ * // Implementation receives type params and returns async function
+ * const platform = [
+ *   fetchAs.implement((T) => async (url) => {
+ *     const response = await fetch(url);
+ *     return parseFor(T)(await response.text());
+ *   }),
+ * ];
+ * ```
+ */
+export function asyncGenericPlatform(name, typeParams, inputs, output) {
+    const numTypeParams = typeParams.length;
+    const fn = (type_args, ...valueArgs) => {
+        // Validate type args array
+        if (!Array.isArray(type_args)) {
+            throw new Error(`Generic platform function '${name}' expects type arguments as an array, ` +
+                `got ${typeof type_args}`);
+        }
+        // Validate type args count
+        if (type_args.length !== numTypeParams) {
+            throw new Error(`Generic platform function '${name}' expects ${numTypeParams} type parameters, ` +
+                `got ${type_args.length}`);
+        }
+        // Validate type args are EastTypes
+        for (let i = 0; i < numTypeParams; i++) {
+            const typeArg = type_args[i];
+            if (!typeArg || typeof typeArg !== 'object' || !('type' in typeArg)) {
+                throw new Error(`Generic platform function '${name}' expects type parameter ${i + 1} ` +
+                    `(${typeParams[i]}) to be an EastType`);
+            }
+        }
+        // Build type argument map
+        const typeArgMap = {};
+        typeParams.forEach((param, idx) => {
+            typeArgMap[param] = type_args[idx];
+        });
+        // Apply type substitution to get concrete input/output types
+        const inputTypes = inputs.map(t => applyTypeArgs(typeArgMap, t));
+        const outputType = applyTypeArgs(typeArgMap, output);
+        // Validate value args count
+        if (valueArgs.length !== inputTypes.length) {
+            throw new Error(`Generic platform function '${name}' expects ${inputTypes.length} ` +
+                `value arguments, got ${valueArgs.length}`);
+        }
+        // Convert value args to AST with type validation and implicit casts
+        const argAsts = valueArgs.map((arg, index) => {
+            const expectedType = inputTypes[index];
+            let ast = valueOrExprToAstTyped(arg, expectedType);
+            if (ast.type.type === "Never") {
+                throw new Error(`Generic platform function ${name} argument ${index + 1} expected type ${printType(expectedType)}, got Never type`);
+            }
+            if (!isTypeEqual(ast.type, expectedType)) {
+                if (!isSubtype(ast.type, expectedType)) {
+                    throw new Error(`Generic platform function ${name} argument ${index + 1} expected type ${printType(expectedType)}, got ${printType(ast.type)}`);
+                }
+                // Insert implicit cast
+                ast = {
+                    ast_type: "As",
+                    type: expectedType,
+                    location: get_location(2),
+                    value: ast,
+                };
+            }
+            return ast;
+        });
+        // Create PlatformAST with type_parameters and async: true
+        return fromAst({
+            ast_type: "Platform",
+            type: outputType,
+            location: get_location(2),
+            name: name,
+            type_parameters: type_args,
+            arguments: argAsts,
+            async: true,
+        });
+    };
+    fn.implement = (factory) => {
+        return {
+            name,
+            type_parameters: [...typeParams],
+            inputs: [], // Computed at call time via inputsFn
+            output: toEastTypeValue(NullType), // Placeholder
+            inputsFn: (...tps) => {
+                const typeArgMap = {};
+                typeParams.forEach((param, idx) => {
+                    typeArgMap[param] = tps[idx];
+                });
+                return inputs.map(t => {
+                    if (typeof t === 'string')
+                        return typeArgMap[t];
+                    let result = applyTypeArgs(typeArgMap, t);
+                    if (!isVariant(result))
+                        result = toEastTypeValue(result);
+                    return result;
+                });
+            },
+            outputsFn: (...tps) => {
+                const typeArgMap = {};
+                typeParams.forEach((param, idx) => {
+                    typeArgMap[param] = tps[idx];
+                });
+                if (typeof output === 'string')
+                    return typeArgMap[output];
+                let result = applyTypeArgs(typeArgMap, output);
+                if (!isVariant(result))
+                    result = toEastTypeValue(result);
+                return result;
+            },
+            type: 'async',
+            fn: factory,
+        };
+    };
+    return fn;
+}
 export const BlockBuilder = (return_type) => {
     const statements = [];
     const $ = ((expr) => {
@@ -1757,6 +2204,26 @@ Object.assign(Expr, {
     greater,
     greaterEqual,
     is,
-    match: matchExpr
+    match: matchExpr,
+    // Comparison aliases
+    equals,
+    eq,
+    notEquals,
+    ne,
+    lessThan,
+    lt,
+    lessThanOrEqual,
+    lte,
+    le,
+    greaterThan,
+    gt,
+    greaterThanOrEqual,
+    gte,
+    ge,
+    // Patch operations
+    diff,
+    applyPatch,
+    composePatch,
+    invertPatch,
 });
 //# sourceMappingURL=block.js.map