@elaraai/east 0.0.1-beta.0

package/dist/src/expr/libs/set.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { FunctionType, type EastType, IntegerType, SetType } from "../../types.js";
+import { Expr } from "../expr.js";
+import type { SubtypeExprOrValue, ExprType } from "../types.js";
+/** Standard library functions for sets */
+declare const _default: {
+    /**
+     * Generates a set of a given size programmatically with a function from index to key.
+     *
+     * @typeParam K - The type of the set keys
+     * @param size - The number of elements to generate
+     * @param keyType - The East type of the set keys
+     * @param keyFn - A function that takes an index and returns the key at that index
+     * @param onConflict - Optional function `(key) => null` to handle duplicate keys by ignoring them
+     * @returns A set expression containing the programmatically generated keys
+     *
+     * @throws East runtime error if duplicate keys are produced and no onConflict is provided
+     *
+     * @remarks
+     * If the generator produces duplicate keys, an error will be thrown by default.
+     * To handle duplicates, provide an `onConflict` function that receives the duplicate key
+     * and returns `null` to ignore it.
+     *
+     * @example
+     * ```ts
+     * // Generate set with string keys
+     * const makeSet = East.function([], SetType(StringType), ($) => {
+     *   $.return(East.Set.generate(
+     *     3n,
+     *     StringType,
+     *     ($, i) => Expr.str`key${i}`
+     *   ));
+     * });
+     * const compiled = East.compile(makeSet.toIR(), []);
+     * compiled();  // Set(["key0", "key1", "key2"])
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Generate set with conflict resolution (ignore duplicates)
+     * const makeSetConflict = East.function([], SetType(IntegerType), ($) => {
+     *   $.return(East.Set.generate(
+     *     5n,
+     *     IntegerType,
+     *     ($, i) => i.remainder(3n),  // Creates duplicates: 0,1,2,0,1
+     *     ($, key) => null  // Ignore duplicates
+     *   ));
+     * });
+     * const compiled = East.compile(makeSetConflict.toIR(), []);
+     * compiled();  // Set([0n, 1n, 2n])
+     * ```
+     */
+    generate<K extends EastType>(size: Expr<IntegerType> | bigint, keyType: K, keyFn: SubtypeExprOrValue<FunctionType<[IntegerType], NoInfer<K>>>, onConflict?: SubtypeExprOrValue<FunctionType<[NoInfer<K>], NoInfer<K>>>): ExprType<SetType<K>>;
+};
+export default _default;
+//# sourceMappingURL=set.d.ts.map

package/dist/src/expr/libs/set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../../../src/expr/libs/set.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,WAAW,EAAY,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,EAAa,IAAI,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEhE,0CAA0C;;IAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;aACM,CAAC,SAAS,QAAQ,QAAQ,IAAI,CAAC,WAAW,CAAC,GAAG,MAAM,WAAW,CAAC,SAAS,kBAAkB,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,kBAAkB,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;;AA/C/O,wBA6DC"}

package/dist/src/expr/libs/set.js

@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { FunctionType, IntegerType, NullType, SetType } from "../../types.js";
+import { AstSymbol, Expr } from "../expr.js";
+/** Standard library functions for sets */
+export default {
+    /**
+     * Generates a set of a given size programmatically with a function from index to key.
+     *
+     * @typeParam K - The type of the set keys
+     * @param size - The number of elements to generate
+     * @param keyType - The East type of the set keys
+     * @param keyFn - A function that takes an index and returns the key at that index
+     * @param onConflict - Optional function `(key) => null` to handle duplicate keys by ignoring them
+     * @returns A set expression containing the programmatically generated keys
+     *
+     * @throws East runtime error if duplicate keys are produced and no onConflict is provided
+     *
+     * @remarks
+     * If the generator produces duplicate keys, an error will be thrown by default.
+     * To handle duplicates, provide an `onConflict` function that receives the duplicate key
+     * and returns `null` to ignore it.
+     *
+     * @example
+     * ```ts
+     * // Generate set with string keys
+     * const makeSet = East.function([], SetType(StringType), ($) => {
+     *   $.return(East.Set.generate(
+     *     3n,
+     *     StringType,
+     *     ($, i) => Expr.str`key${i}`
+     *   ));
+     * });
+     * const compiled = East.compile(makeSet.toIR(), []);
+     * compiled();  // Set(["key0", "key1", "key2"])
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Generate set with conflict resolution (ignore duplicates)
+     * const makeSetConflict = East.function([], SetType(IntegerType), ($) => {
+     *   $.return(East.Set.generate(
+     *     5n,
+     *     IntegerType,
+     *     ($, i) => i.remainder(3n),  // Creates duplicates: 0,1,2,0,1
+     *     ($, key) => null  // Ignore duplicates
+     *   ));
+     * });
+     * const compiled = East.compile(makeSetConflict.toIR(), []);
+     * compiled();  // Set([0n, 1n, 2n])
+     * ```
+     */
+    generate(size, keyType, keyFn, onConflict) {
+        const length_expr = Expr.from(size, IntegerType);
+        const generator_expr = Expr.from(keyFn, FunctionType([IntegerType], keyType, []));
+        const on_conflict_expr = onConflict ? Expr.from(onConflict, FunctionType([keyType], NullType, [])) : Expr.function([keyType], NullType, ($, key) => $.error(Expr.str `Duplicate key ${key} in set`));
+        return Expr.fromAst({
+            ast_type: "Builtin",
+            type: SetType(keyType),
+            builtin: "SetGenerate",
+            type_parameters: [keyType],
+            arguments: [length_expr[AstSymbol], generator_expr[AstSymbol], on_conflict_expr[AstSymbol]],
+            location: length_expr[AstSymbol].location,
+        });
+    },
+};
+//# sourceMappingURL=set.js.map

package/dist/src/expr/libs/set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set.js","sourceRoot":"","sources":["../../../../src/expr/libs/set.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAiB,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAG7C,0CAA0C;AAC1C,eAAe;IACb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,QAAQ,CAAqB,IAAgC,EAAE,OAAU,EAAE,KAAkE,EAAE,UAAuE;QACpN,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACjD,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,KAAY,EAAE,YAAY,CAAC,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QACzF,MAAM,gBAAgB,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAiB,EAAE,YAAY,CAAC,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAA,iBAAiB,GAAG,SAAS,CAAC,CAAC,CAAC;QAE3M,OAAO,IAAI,CAAC,OAAO,CAAC;YAClB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC;YACtB,OAAO,EAAE,aAAa;YACtB,eAAe,EAAE,CAAC,OAAO,CAAC;YAC1B,SAAS,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;YAC3F,QAAQ,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC,QAAQ;SAC1C,CAAC,CAAC;IACL,CAAC;CACF,CAAA"}

package/dist/src/expr/libs/string.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { type StructType, StringType, type IntegerType } from "../../types.js";
+import type { ArrayExpr } from "../array.js";
+import { Expr } from "../expr.js";
+import type { StringExpr } from "../string.js";
+/** Standard library for string values */
+declare const _default: {
+    /**
+     * Formats an error message and stack trace in a human-readable form.
+     *
+     * @param message - The error message to display
+     * @param stack - An array of stack frames, each containing `filename`, `line`, and `column`
+     * @returns A formatted error string with the message and stack trace
+     *
+     * @example
+     * ```ts
+     * const StackFrameType = StructType({ filename: StringType, line: IntegerType, column: IntegerType });
+     *
+     * const formatError = East.function([StringType, ArrayType(StackFrameType)], StringType, ($, msg, stack) => {
+     *   $.return(East.printError(msg, stack));
+     * });
+     * const compiled = East.compile(formatError.toIR(), []);
+     * const result = compiled("Division by zero", [
+     *   { filename: "app.ts", line: 42n, column: 10n },
+     *   { filename: "main.ts", line: 15n, column: 5n }
+     * ]);
+     * // Returns:
+     * // "Error: Division by zero
+     * //     [0] app.ts 42:10
+     * //     [1] main.ts 15:5"
+     * ```
+     */
+    printError(message: StringExpr, stack: ArrayExpr<StructType<{
+        filename: StringType;
+        line: IntegerType;
+        column: IntegerType;
+    }>>): StringExpr;
+    /**
+     * Creates a string containing East's canonical JSON representation of a value.
+     *
+     * @param value - The East value to serialize to JSON
+     * @returns A JSON string representation of the value
+     *
+     * @example
+     * ```ts
+     * const PersonType = StructType({ name: StringType, age: IntegerType });
+     *
+     * const toJson = East.function([PersonType], StringType, ($, person) => {
+     *   $.return(East.String.printJson(person));
+     * });
+     * const compiled = East.compile(toJson.toIR(), []);
+     * compiled({ name: "Alice", age: 30n });  // '{"name":"Alice","age":30}'
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Array to JSON
+     * const arrayToJson = East.function([ArrayType(IntegerType)], StringType, ($, arr) => {
+     *   $.return(East.String.printJson(arr));
+     * });
+     * const compiled = East.compile(arrayToJson.toIR(), []);
+     * compiled([1n, 2n, 3n]);  // '[1,2,3]'
+     * ```
+     */
+    printJson(value: Expr): StringExpr;
+};
+export default _default;
+//# sourceMappingURL=string.d.ts.map

package/dist/src/expr/libs/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../../../src/expr/libs/string.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,yCAAyC;;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;wBACiB,UAAU,SAAS,SAAS,CAAC,UAAU,CAAC;QAAE,QAAQ,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,WAAW,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC,GAAG,UAAU;IAI3I;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;qBACc,IAAI,GAAG,UAAU;;AAzDpC,wBAmEC"}

package/dist/src/expr/libs/string.js

@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { StringType } from "../../types.js";
+import { Expr } from "../expr.js";
+/** Standard library for string values */
+export default {
+    /**
+     * Formats an error message and stack trace in a human-readable form.
+     *
+     * @param message - The error message to display
+     * @param stack - An array of stack frames, each containing `filename`, `line`, and `column`
+     * @returns A formatted error string with the message and stack trace
+     *
+     * @example
+     * ```ts
+     * const StackFrameType = StructType({ filename: StringType, line: IntegerType, column: IntegerType });
+     *
+     * const formatError = East.function([StringType, ArrayType(StackFrameType)], StringType, ($, msg, stack) => {
+     *   $.return(East.printError(msg, stack));
+     * });
+     * const compiled = East.compile(formatError.toIR(), []);
+     * const result = compiled("Division by zero", [
+     *   { filename: "app.ts", line: 42n, column: 10n },
+     *   { filename: "main.ts", line: 15n, column: 5n }
+     * ]);
+     * // Returns:
+     * // "Error: Division by zero
+     * //     [0] app.ts 42:10
+     * //     [1] main.ts 15:5"
+     * ```
+     */
+    printError(message, stack) {
+        return Expr.str `Error: ${message}\n    ${stack.map((_$, { filename, line, column }, i) => Expr.str `[${i}] ${filename} ${line}:${column}`).stringJoin("\n    ")}`;
+    },
+    /**
+     * Creates a string containing East's canonical JSON representation of a value.
+     *
+     * @param value - The East value to serialize to JSON
+     * @returns A JSON string representation of the value
+     *
+     * @example
+     * ```ts
+     * const PersonType = StructType({ name: StringType, age: IntegerType });
+     *
+     * const toJson = East.function([PersonType], StringType, ($, person) => {
+     *   $.return(East.String.printJson(person));
+     * });
+     * const compiled = East.compile(toJson.toIR(), []);
+     * compiled({ name: "Alice", age: 30n });  // '{"name":"Alice","age":30}'
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Array to JSON
+     * const arrayToJson = East.function([ArrayType(IntegerType)], StringType, ($, arr) => {
+     *   $.return(East.String.printJson(arr));
+     * });
+     * const compiled = East.compile(arrayToJson.toIR(), []);
+     * compiled([1n, 2n, 3n]);  // '[1,2,3]'
+     * ```
+     */
+    printJson(value) {
+        return Expr.fromAst({
+            ast_type: "Builtin",
+            type: StringType,
+            builtin: "StringPrintJSON",
+            location: { filename: "stdlib", line: 1, column: 1 },
+            type_parameters: [Expr.type(value)],
+            arguments: [Expr.ast(value)],
+        });
+    }
+};
+//# sourceMappingURL=string.js.map

package/dist/src/expr/libs/string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.js","sourceRoot":"","sources":["../../../../src/expr/libs/string.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAmB,UAAU,EAAoB,MAAM,gBAAgB,CAAC;AAE/E,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGlC,yCAAyC;AACzC,eAAe;IACb;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,UAAU,CAAC,OAAmB,EAAE,KAA8F;QAC5H,OAAO,IAAI,CAAC,GAAG,CAAA,UAAU,OAAO,SAAS,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAA,IAAI,CAAC,KAAK,QAAQ,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;IACnK,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,SAAS,CAAC,KAAW;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC;YAClB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,iBAAiB;YAC1B,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;YACpD,eAAe,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnC,SAAS,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;SAC7B,CAAC,CAAA;IACJ,CAAC;CACF,CAAA"}

package/dist/src/expr/never.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import type { AST } from "../ast.js";
+import { NeverType } from "../types.js";
+import { Expr, type ToExpr } from "./expr.js";
+/**
+ * Expression representing the Never type (bottom type).
+ * Used for error expressions and unreachable code paths.
+ */
+export declare class NeverExpr extends Expr<NeverType> {
+    constructor(ast: AST, createExpr: ToExpr);
+}
+//# sourceMappingURL=never.d.ts.map

package/dist/src/expr/never.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"never.d.ts","sourceRoot":"","sources":["../../../src/expr/never.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAE9C;;;GAGG;AACH,qBAAa,SAAU,SAAQ,IAAI,CAAC,SAAS,CAAC;gBAChC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM;CAGzC"}

package/dist/src/expr/never.js

@@ -0,0 +1,12 @@
+import { NeverType } from "../types.js";
+import { Expr } from "./expr.js";
+/**
+ * Expression representing the Never type (bottom type).
+ * Used for error expressions and unreachable code paths.
+ */
+export class NeverExpr extends Expr {
+    constructor(ast, createExpr) {
+        super(NeverType, ast, createExpr);
+    }
+}
+//# sourceMappingURL=never.js.map

package/dist/src/expr/never.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"never.js","sourceRoot":"","sources":["../../../src/expr/never.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,IAAI,EAAe,MAAM,WAAW,CAAC;AAE9C;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,IAAe;IAC5C,YAAY,GAAQ,EAAE,UAAkB;QACtC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/src/expr/null.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import type { AST } from "../ast.js";
+import { NullType } from "../types.js";
+import { Expr, type ToExpr } from "./expr.js";
+/**
+* Expression representing the Null type (unit/void type).
+* Used for null values and statement expressions.
+*/
+export declare class NullExpr extends Expr<NullType> {
+    constructor(ast: AST, createExpr: ToExpr);
+}
+//# sourceMappingURL=null.d.ts.map

package/dist/src/expr/null.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"null.d.ts","sourceRoot":"","sources":["../../../src/expr/null.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAE9C;;;EAGE;AACF,qBAAa,QAAS,SAAQ,IAAI,CAAC,QAAQ,CAAC;gBAC9B,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM;CAGzC"}

package/dist/src/expr/null.js

@@ -0,0 +1,12 @@
+import { NullType } from "../types.js";
+import { Expr } from "./expr.js";
+/**
+* Expression representing the Null type (unit/void type).
+* Used for null values and statement expressions.
+*/
+export class NullExpr extends Expr {
+    constructor(ast, createExpr) {
+        super(NullType, ast, createExpr);
+    }
+}
+//# sourceMappingURL=null.js.map

package/dist/src/expr/null.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"null.js","sourceRoot":"","sources":["../../../src/expr/null.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,IAAI,EAAe,MAAM,WAAW,CAAC;AAE9C;;;EAGE;AACF,MAAM,OAAO,QAAS,SAAQ,IAAc;IAC1C,YAAY,GAAQ,EAAE,UAAkB;QACtC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/src/expr/ref.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import type { AST } from "../ast.js";
+import { FunctionType, NullType, RefType } from "../types.js";
+import { Expr, type ToExpr } from "./expr.js";
+import type { ExprType, SubtypeExprOrValue } from "./types.js";
+/**
+ * Expression representing reference cells (mutable containers) in East.
+ *
+ * RefExpr provides a reference cell type that can be shared across closures and modified.
+ * Unlike variables declared with `$.let()`, references can be captured and modified from
+ * within nested functions, making them useful for shared mutable state.
+ *
+ * @example
+ * ```ts
+ * // Creating and getting a reference value
+ * const getRefValue = East.function([], IntegerType, ($) => {
+ *   const counter = $.let(East.value(ref(42n)));
+ *   $.return(counter.get());
+ * });
+ * const compiled = East.compile(getRefValue.toIR(), []);
+ * compiled();  // 42n
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Updating a reference value
+ * const updateRef = East.function([IntegerType], IntegerType, ($, newValue) => {
+ *   const counter = $.let(East.value(ref(0n)));
+ *   $(counter.update(newValue));
+ *   $.return(counter.get());
+ * });
+ * const compiled = East.compile(updateRef.toIR(), []);
+ * compiled(100n);  // 100n
+ * ```
+ */
+export declare class RefExpr<T extends any> extends Expr<RefType<T>> {
+    private value_type;
+    constructor(value_type: T, ast: AST, createExpr: ToExpr);
+    /**
+     * Gets the current value stored in the reference cell.
+     *
+     * @returns An expression of the value type stored in the reference
+     *
+     * @example
+     * ```ts
+     * const getRefValue = East.function([], IntegerType, ($) => {
+     *   const counter = $.let(East.value(ref(42n)));
+     *   $.return(counter.get());
+     * });
+     * const compiled = East.compile(getRefValue.toIR(), []);
+     * compiled();  // 42n
+     * ```
+     */
+    get(): ExprType<T>;
+    /**
+     * Replaces the value in the reference cell with a new value.
+     *
+     * @param value - The new value to store in the reference cell
+     * @returns A NullExpr (used for side effects)
+     *
+     * @example
+     * ```ts
+     * const updateRef = East.function([IntegerType], IntegerType, ($, newValue) => {
+     *   const counter = $.let(East.value(ref(0n)));
+     *   $(counter.update(newValue));
+     *   $.return(counter.get());
+     * });
+     * const compiled = East.compile(updateRef.toIR(), []);
+     * compiled(100n);  // 100n
+     * ```
+     *
+     * @see {@link merge} for modifying the value based on its current value.
+     */
+    update(value: ExprType<T>): Expr<NullType>;
+    /**
+     * Modifies the reference value by merging it with a new value using a function.
+     *
+     * This is useful for patterns where you want to update a reference based on its current value,
+     * e.g. incrementing a number, appending to a string, updating fields in a struct, or pushing to an array.
+     *
+     * @param value - The new value to merge with the current value
+     * @param updateFn - Function that takes (current, new) and returns the merged value
+     * @returns A NullExpr (used for side effects)
+     *
+     * @example
+     * ```ts
+     * const incrementRef = East.function([IntegerType], IntegerType, ($, delta) => {
+     *   const counter = $.let(East.value(ref(10n)));
+     *   $(counter.merge(delta, ($, current, newVal) => current.add(newVal)));
+     *   $.return(counter.get());
+     * });
+     * const compiled = East.compile(incrementRef.toIR(), []);
+     * compiled(5n);  // 15n
+     * ```
+     *
+     * @see {@link update} for simply replacing the value.
+     */
+    merge<T2>(value: Expr<T2>, updateFn: SubtypeExprOrValue<FunctionType<[T, NoInfer<T2>], T>>): ExprType<NullType>;
+}
+//# sourceMappingURL=ref.d.ts.map

package/dist/src/expr/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../../src/expr/ref.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAErC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAiB,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAa,IAAI,EAA6B,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,OAAO,CAAC,CAAC,SAAS,GAAG,CAAE,SAAQ,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9C,OAAO,CAAC,UAAU;gBAAV,UAAU,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM;IAI/D;;;;;;;;;;;;;;OAcG;IACH,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC;IAWlB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;IAW1C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC;CAehH"}

package/dist/src/expr/ref.js

@@ -0,0 +1,131 @@
+import { get_location } from "../location.js";
+import { FunctionType, NullType, RefType } from "../types.js";
+import { AstSymbol, Expr, FactorySymbol, TypeSymbol } from "./expr.js";
+/**
+ * Expression representing reference cells (mutable containers) in East.
+ *
+ * RefExpr provides a reference cell type that can be shared across closures and modified.
+ * Unlike variables declared with `$.let()`, references can be captured and modified from
+ * within nested functions, making them useful for shared mutable state.
+ *
+ * @example
+ * ```ts
+ * // Creating and getting a reference value
+ * const getRefValue = East.function([], IntegerType, ($) => {
+ *   const counter = $.let(East.value(ref(42n)));
+ *   $.return(counter.get());
+ * });
+ * const compiled = East.compile(getRefValue.toIR(), []);
+ * compiled();  // 42n
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Updating a reference value
+ * const updateRef = East.function([IntegerType], IntegerType, ($, newValue) => {
+ *   const counter = $.let(East.value(ref(0n)));
+ *   $(counter.update(newValue));
+ *   $.return(counter.get());
+ * });
+ * const compiled = East.compile(updateRef.toIR(), []);
+ * compiled(100n);  // 100n
+ * ```
+ */
+export class RefExpr extends Expr {
+    value_type;
+    constructor(value_type, ast, createExpr) {
+        super(RefType(value_type), ast, createExpr);
+        this.value_type = value_type;
+    }
+    /**
+     * Gets the current value stored in the reference cell.
+     *
+     * @returns An expression of the value type stored in the reference
+     *
+     * @example
+     * ```ts
+     * const getRefValue = East.function([], IntegerType, ($) => {
+     *   const counter = $.let(East.value(ref(42n)));
+     *   $.return(counter.get());
+     * });
+     * const compiled = East.compile(getRefValue.toIR(), []);
+     * compiled();  // 42n
+     * ```
+     */
+    get() {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: this.value_type,
+            location: get_location(2),
+            builtin: "RefGet",
+            type_parameters: [this.value_type],
+            arguments: [Expr.ast(this)],
+        });
+    }
+    /**
+     * Replaces the value in the reference cell with a new value.
+     *
+     * @param value - The new value to store in the reference cell
+     * @returns A NullExpr (used for side effects)
+     *
+     * @example
+     * ```ts
+     * const updateRef = East.function([IntegerType], IntegerType, ($, newValue) => {
+     *   const counter = $.let(East.value(ref(0n)));
+     *   $(counter.update(newValue));
+     *   $.return(counter.get());
+     * });
+     * const compiled = East.compile(updateRef.toIR(), []);
+     * compiled(100n);  // 100n
+     * ```
+     *
+     * @see {@link merge} for modifying the value based on its current value.
+     */
+    update(value) {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: NullType,
+            location: get_location(2),
+            builtin: "RefUpdate",
+            type_parameters: [this.value_type],
+            arguments: [Expr.ast(this), Expr.ast(value)],
+        });
+    }
+    /**
+     * Modifies the reference value by merging it with a new value using a function.
+     *
+     * This is useful for patterns where you want to update a reference based on its current value,
+     * e.g. incrementing a number, appending to a string, updating fields in a struct, or pushing to an array.
+     *
+     * @param value - The new value to merge with the current value
+     * @param updateFn - Function that takes (current, new) and returns the merged value
+     * @returns A NullExpr (used for side effects)
+     *
+     * @example
+     * ```ts
+     * const incrementRef = East.function([IntegerType], IntegerType, ($, delta) => {
+     *   const counter = $.let(East.value(ref(10n)));
+     *   $(counter.merge(delta, ($, current, newVal) => current.add(newVal)));
+     *   $.return(counter.get());
+     * });
+     * const compiled = East.compile(incrementRef.toIR(), []);
+     * compiled(5n);  // 15n
+     * ```
+     *
+     * @see {@link update} for simply replacing the value.
+     */
+    merge(value, updateFn) {
+        const location = get_location(2);
+        const value2Type = value[TypeSymbol];
+        const updateFnExpr = Expr.from(updateFn, FunctionType([value2Type, this.value_type], this.value_type, null));
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: NullType,
+            location,
+            builtin: "RefMerge",
+            type_parameters: [this.value_type, value2Type],
+            arguments: [this[AstSymbol], value[AstSymbol], updateFnExpr[AstSymbol]],
+        });
+    }
+}
+//# sourceMappingURL=ref.js.map

package/dist/src/expr/ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.js","sourceRoot":"","sources":["../../../src/expr/ref.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAiB,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,UAAU,EAAe,MAAM,WAAW,CAAC;AAGpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,OAAuB,SAAQ,IAAgB;IACtC;IAApB,YAAoB,UAAa,EAAE,GAAQ,EAAE,UAAkB;QAC7D,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;QAD1B,eAAU,GAAV,UAAU,CAAG;IAEjC,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,GAAG;QACD,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC;YACzB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,IAAI,CAAC,UAAsB;YACjC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;YACzB,OAAO,EAAE,QAAQ;YACjB,eAAe,EAAE,CAAC,IAAI,CAAC,UAAsB,CAAC;YAC9C,SAAS,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;SAC5B,CAAgB,CAAC;IACpB,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,KAAkB;QACvB,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC;YACzB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;YACzB,OAAO,EAAE,WAAW;YACpB,eAAe,EAAE,CAAC,IAAI,CAAC,UAAsB,CAAC;YAC9C,SAAS,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;SAC7C,CAAmB,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAK,KAAe,EAAE,QAA+D;QACxF,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;QAErC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,QAAe,EAAE,YAAY,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;QAEpH,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC;YACzB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,QAAQ;YACd,QAAQ;YACR,OAAO,EAAE,UAAU;YACnB,eAAe,EAAE,CAAC,IAAI,CAAC,UAAsB,EAAE,UAAsB,CAAC;YACtE,SAAS,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;SACxE,CAAuB,CAAC;IAC3B,CAAC;CACF"}

package/dist/src/expr/regex_validation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+interface ValidationResult {
+    isValid: boolean;
+    warnings: string[];
+    errors: string[];
+}
+export declare function validateCrossPlatformCompatible(regex: RegExp): ValidationResult;
+export declare function runCompatibilityTests(): void;
+export declare const RECOMMENDED_PATTERNS: {
+    email: RegExp;
+    phoneUS: RegExp;
+    uuid: RegExp;
+    ipv4: RegExp;
+    url: RegExp;
+    identifier: RegExp;
+    number: RegExp;
+    whitespace: RegExp;
+    word: RegExp;
+    lineBreak: RegExp;
+};
+export {};
+//# sourceMappingURL=regex_validation.d.ts.map

package/dist/src/expr/regex_validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex_validation.d.ts","sourceRoot":"","sources":["../../../src/expr/regex_validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,UAAU,gBAAgB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAkB/E;AAqED,wBAAgB,qBAAqB,IAAI,IAAI,CAyC5C;AAGD,eAAO,MAAM,oBAAoB;;;;;;;;;;;CAWhC,CAAC"}