@elaraai/east 0.0.1-beta.0

package/dist/src/expr/index.js

@@ -0,0 +1,423 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+// Re-export all types
+export * from './types.js';
+// Re-export abstract base and concrete classes
+import { Expr } from './expr.js';
+export { Expr } from './expr.js';
+// Import factory implementation
+import { from, equal, notEqual, less, lessEqual, print, is, greaterEqual, greater, func, str, platform } from './block.js';
+export { BlockBuilder } from './block.js';
+// import type { FunctionExpr } from './function.js';
+// Import standard libraries
+import IntegerLib from './libs/integer.js';
+import FloatLib from './libs/float.js';
+import DateTimeLib from './libs/datetime.js';
+import StringLib from './libs/string.js';
+import BlobLib from './libs/blob.js';
+import ArrayLib from './libs/array.js';
+import SetLib from './libs/set.js';
+import DictLib from './libs/dict.js';
+// /** Compile an East function to executable JavaScript.
+//  *
+//  * This is a convenience wrapper around `fn.toIR().compile(platform)`.
+//  *
+//  * @param fn - The East function to compile
+//  * @param platform - Object mapping platform function names to their JavaScript implementations
+//  * @returns Compiled JavaScript function that can be called with the specified input types
+//  *
+//  * @example
+//  * ```ts
+//  * const add = East.function([IntegerType, IntegerType], IntegerType, ($, a, b) => a.add(b));
+//  * const compiled = East.compile(add, {});
+//  * const result = compiled(5n, 3n); // 8n
+//  * ```
+//  */
+// function compile<I extends any[], O extends any>(
+//   fn: FunctionExpr<I, O>,
+//   platform: Record<string, (...args: any[]) => any>
+// ): any {
+//   return fn.toIR().compile(platform);
+// }
+/**
+ * Standard entry point for constructing East expressions.
+ *
+ * @example
+ * ```ts
+ * // Create expressions from values
+ * East.value(3.14).add(2)
+ *
+ * // String interpolation
+ * East.str`Hello, ${name}!`
+ *
+ * // Comparisons
+ * East.equal(x, y)
+ * East.less(x, y)
+ *
+ * // Create functions
+ * East.function([IntegerType], IntegerType, ($, x) => $.return(x.add(1n)))
+ *
+ * // Standard library
+ * East.Integer.printCommaSeperated(1234567890n)
+ * East.Array.range(0n, 10n)
+ * ```
+ */
+export const East = {
+    // Expr factories
+    /**
+     * Creates an East expression from a JavaScript value.
+     * Type is inferred from the value, or can be explicitly specified.
+     *
+     * @param value - The JavaScript value to convert to an East expression
+     * @param type - Optional explicit type specification
+     * @returns An East expression wrapping the value
+     *
+     * @example
+     * ```ts
+     * East.value(42n)                    // IntegerExpr
+     * East.value(3.14)                   // FloatExpr
+     * East.value("hello")                // StringExpr
+     * East.value([1n, 2n, 3n])           // ArrayExpr<IntegerType>
+     * East.value(new Map([[1n, "a"]]))   // DictExpr<IntegerType, StringType>
+     * ```
+     */
+    value: from,
+    /**
+     * Creates a string expression with interpolation support.
+     * Allows embedding East expressions inside template literals.
+     *
+     * @returns A StringExpr with the interpolated values
+     *
+     * @example
+     * ```ts
+     * East.str`Hello, ${name}!`
+     * East.str`Total: ${count} items`
+     * East.str`Result: ${x.add(y)}`
+     * ```
+     */
+    str,
+    /**
+     * Creates an East function with typed inputs and output.
+     * Functions can be nested, serialized to IR, and compiled to JavaScript.
+     *
+     * @param inputs - Array of East types for function parameters
+     * @param output - East type for function return value
+     * @param body - Function body using block builder and parameters
+     * @returns A FunctionExpr that can be compiled or serialized
+     *
+     * @example
+     * ```ts
+     * const add = East.function(
+     *   [IntegerType, IntegerType],
+     *   IntegerType,
+     *   ($, a, b) => $.return(a.add(b))
+     * );
+     *
+     * const fibonacci = East.function([IntegerType], IntegerType, ($, n) => {
+     *   $.if(East.lessEqual(n, 1n), $ => $.return(n));
+     *   $.return(fibonacci(n.subtract(1n)).add(fibonacci(n.subtract(2n))));
+     * });
+     * ```
+     */
+    function: func,
+    /**
+     * Defines a platform function that can be called from East code.
+     * Platform functions allow East code to interact with the external environment.
+     *
+     * @param name - The name of the platform function
+     * @param inputs - Array of East types for the function parameters
+     * @param output - East type for the function return value
+     * @returns A callable platform function helper
+     *
+     * @example
+     * ```ts
+     * const log = East.platform("log", [StringType], NullType);
+     * const readFile = East.platform("readFile", [StringType], StringType);
+     *
+     * const myFunction = East.function([StringType], NullType, ($, msg) => {
+     *   $(log(East.str`Message: ${msg}`));
+     *   $.return(null);
+     * });
+     *
+     * const platform = [
+     *   log.implement(console.log),
+     *   readFile.implement(fs.readFileSync),
+     * ];
+     * ```
+     */
+    platform,
+    // compile,
+    // block,
+    // error,
+    // tryCatch,
+    // match: matchExpr,
+    // builtins
+    /**
+     * Converts any East expression to its string representation.
+     * Uses the East serialization format (not JSON).
+     *
+     * @param expr - The expression to convert to a string
+     * @returns A StringExpr containing the string representation
+     *
+     * @example
+     * ```ts
+     * East.print(42n)                    // "42"
+     * East.print(3.14)                   // "3.14"
+     * East.print([1n, 2n, 3n])           // "[1, 2, 3]"
+     * East.print({a: 1n, b: true})       // "(a=1, b=true)"
+     * ```
+     */
+    print,
+    /**
+     * Deep equality comparison between two expressions.
+     * Compares values recursively, including nested structures.
+     *
+     * @param a - First expression to compare
+     * @param b - Second expression to compare
+     * @returns BooleanExpr that is true if values are deeply equal
+     *
+     * @example
+     * ```ts
+     * East.equal(42n, 42n)                     // true
+     * East.equal([1n, 2n], [1n, 2n])           // true
+     * East.equal({a: 1n}, {a: 1n})             // true
+     * East.equal(x, y)                         // compare two expressions
+     * ```
+     */
+    equal,
+    /**
+     * Deep inequality comparison between two expressions.
+     * Returns true if values are not deeply equal.
+     *
+     * @param a - First expression to compare
+     * @param b - Second expression to compare
+     * @returns BooleanExpr that is true if values are not equal
+     *
+     * @example
+     * ```ts
+     * East.notEqual(42n, 43n)                  // true
+     * East.notEqual([1n, 2n], [1n, 3n])        // true
+     * ```
+     */
+    notEqual,
+    /**
+     * Less-than comparison using East's total ordering.
+     * All East types have a defined total ordering, even complex structures.
+     *
+     * @param a - First expression to compare
+     * @param b - Second expression to compare
+     * @returns BooleanExpr that is true if a < b
+     *
+     * @example
+     * ```ts
+     * East.less(1n, 2n)                        // true
+     * East.less(3.14, 2.0)                     // false
+     * East.less("apple", "banana")             // true
+     * ```
+     */
+    less,
+    /**
+     * Less-than-or-equal comparison using East's total ordering.
+     *
+     * @param a - First expression to compare
+     * @param b - Second expression to compare
+     * @returns BooleanExpr that is true if a <= b
+     *
+     * @example
+     * ```ts
+     * East.lessEqual(1n, 1n)                   // true
+     * East.lessEqual(2n, 1n)                   // false
+     * ```
+     */
+    lessEqual,
+    /**
+     * Greater-than comparison using East's total ordering.
+     *
+     * @param a - First expression to compare
+     * @param b - Second expression to compare
+     * @returns BooleanExpr that is true if a > b
+     *
+     * @example
+     * ```ts
+     * East.greater(2n, 1n)                     // true
+     * East.greater("banana", "apple")          // true
+     * ```
+     */
+    greater,
+    /**
+     * Greater-than-or-equal comparison using East's total ordering.
+     *
+     * @param a - First expression to compare
+     * @param b - Second expression to compare
+     * @returns BooleanExpr that is true if a >= b
+     *
+     * @example
+     * ```ts
+     * East.greaterEqual(2n, 2n)                // true
+     * East.greaterEqual(1n, 2n)                // false
+     * ```
+     */
+    greaterEqual,
+    /**
+     * Reference equality comparison for mutable types (Array, Set, Dict).
+     * Checks if two expressions reference the same object in memory.
+     *
+     * @param a - First expression to compare
+     * @param b - Second expression to compare
+     * @returns BooleanExpr that is true if they reference the same object
+     *
+     * @example
+     * ```ts
+     * const arr = $.let(East.value([1n, 2n]));
+     * East.is(arr, arr)                        // true (same reference)
+     * East.is([1n, 2n], [1n, 2n])              // false (different objects)
+     * ```
+     */
+    is,
+    // Root stdlib
+    /**
+     * Returns the minimum of two values using East's total ordering.
+     *
+     * @param a - First value
+     * @param b - Second value
+     * @returns The smaller of the two values
+     *
+     * @example
+     * ```ts
+     * East.min(5n, 3n)                         // 3n
+     * East.min(3.14, 2.71)                     // 2.71
+     * ```
+     */
+    min: Expr.min,
+    /**
+     * Returns the maximum of two values using East's total ordering.
+     *
+     * @param a - First value
+     * @param b - Second value
+     * @returns The larger of the two values
+     *
+     * @example
+     * ```ts
+     * East.max(5n, 3n)                         // 5n
+     * East.max(3.14, 2.71)                     // 3.14
+     * ```
+     */
+    max: Expr.max,
+    /**
+     * Clamps a value between minimum and maximum bounds.
+     *
+     * @param value - The value to clamp
+     * @param min - The minimum bound
+     * @param max - The maximum bound
+     * @returns The clamped value
+     *
+     * @example
+     * ```ts
+     * East.clamp(5n, 0n, 10n)                  // 5n
+     * East.clamp(-5n, 0n, 10n)                 // 0n
+     * East.clamp(15n, 0n, 10n)                 // 10n
+     * ```
+     */
+    clamp: Expr.clamp,
+    // Type stdlibs
+    /**
+     * Standard library functions for Integer operations.
+     * Provides formatting, rounding, and utility functions for integers.
+     *
+     * @example
+     * ```ts
+     * East.Integer.printCommaSeperated(1234567n)   // "1,234,567"
+     * East.Integer.printCompact(1500000n)          // "1.5M"
+     * East.Integer.printOrdinal(42n)               // "42nd"
+     * East.Integer.roundNearest(47n, 10n)          // 50n
+     * ```
+     */
+    Integer: IntegerLib,
+    /**
+     * Standard library functions for Float operations.
+     * Provides rounding, formatting, and comparison functions for floating-point numbers.
+     *
+     * @example
+     * ```ts
+     * East.Float.roundToDecimals(3.14159, 2n)      // 3.14
+     * East.Float.printCurrency(1234.56)            // "$1234.56"
+     * East.Float.printPercentage(0.452, 1n)        // "45.2%"
+     * East.Float.approxEqual(0.1, 0.10001, 0.001)  // true
+     * ```
+     */
+    Float: FloatLib,
+    /**
+     * Standard library functions for DateTime operations.
+     * Provides construction, parsing, and rounding functions for date/time values.
+     *
+     * @example
+     * ```ts
+     * East.DateTime.fromEpochMilliseconds(1640000000000n)
+     * East.DateTime.fromComponents(2025n, 1n, 15n, 10n, 30n)
+     * East.DateTime.roundDownDay(date, 1n)
+     * East.DateTime.parseFormatted("%Y-%m-%d", "2025-01-15")
+     * ```
+     */
+    DateTime: DateTimeLib,
+    /**
+     * Standard library functions for String operations.
+     * Provides error formatting utilities.
+     *
+     * @example
+     * ```ts
+     * East.String.printError(errorMsg, stackTrace)
+     * ```
+     */
+    String: StringLib,
+    /**
+     * Standard library functions for Blob operations.
+     * Provides binary encoding utilities.
+     *
+     * @example
+     * ```ts
+     * East.Blob.encodeBeast(myValue, 'v2')         // Encode to BEAST format
+     * ```
+     */
+    Blob: BlobLib,
+    /**
+     * Standard library functions for Array operations.
+     * Provides generation utilities for creating arrays.
+     *
+     * @example
+     * ```ts
+     * East.Array.range(0n, 10n, 2n)                // [0n, 2n, 4n, 6n, 8n]
+     * East.Array.linspace(0.0, 1.0, 11n)           // [0.0, 0.1, ..., 1.0]
+     * East.Array.generate(5n, IntegerType, ($, i) => i.multiply(i))
+     * ```
+     */
+    Array: ArrayLib,
+    /**
+     * Standard library functions for Set operations.
+     * Provides generation utilities for creating sets.
+     *
+     * @example
+     * ```ts
+     * East.Set.generate(5n, IntegerType, ($, i) => i.multiply(2n))
+     * ```
+     */
+    Set: SetLib,
+    /**
+     * Standard library functions for Dict operations.
+     * Provides generation utilities for creating dictionaries.
+     *
+     * @example
+     * ```ts
+     * East.Dict.generate(
+     *   5n,
+     *   IntegerType,
+     *   IntegerType,
+     *   ($, i) => i,
+     *   ($, i) => i.multiply(10n)
+     * )
+     * ```
+     */
+    Dict: DictLib,
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/expr/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,sBAAsB;AACtB,cAAc,YAAY,CAAC;AAE3B,+CAA+C;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,gCAAgC;AAChC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3H,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,qDAAqD;AAGrD,4BAA4B;AAC5B,OAAO,UAAU,MAAM,mBAAmB,CAAC;AAC3C,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AACvC,OAAO,WAAW,MAAM,oBAAoB,CAAC;AAC7C,OAAO,SAAS,MAAM,kBAAkB,CAAC;AACzC,OAAO,OAAO,MAAM,gBAAgB,CAAC;AACrC,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AACvC,OAAO,MAAM,MAAM,eAAe,CAAC;AACnC,OAAO,OAAO,MAAM,gBAAgB,CAAC;AAMrC,yDAAyD;AACzD,KAAK;AACL,yEAAyE;AACzE,KAAK;AACL,8CAA8C;AAC9C,kGAAkG;AAClG,6FAA6F;AAC7F,KAAK;AACL,cAAc;AACd,WAAW;AACX,gGAAgG;AAChG,6CAA6C;AAC7C,4CAA4C;AAC5C,SAAS;AACT,MAAM;AACN,oDAAoD;AACpD,4BAA4B;AAC5B,sDAAsD;AACtD,WAAW;AACX,wCAAwC;AACxC,IAAI;AAEJ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,iBAAiB;IAEjB;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,EAAE,IAAI;IAEX;;;;;;;;;;;;OAYG;IACH,GAAG;IAEH;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,EAAE,IAAI;IAEd;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ;IACR,WAAW;IACX,SAAS;IACT,SAAS;IACT,YAAY;IACZ,oBAAoB;IAEpB,WAAW;IAEX;;;;;;;;;;;;;;OAcG;IACH,KAAK;IAEL;;;;;;;;;;;;;;;OAeG;IACH,KAAK;IAEL;;;;;;;;;;;;;OAaG;IACH,QAAQ;IAER;;;;;;;;;;;;;;OAcG;IACH,IAAI;IAEJ;;;;;;;;;;;;OAYG;IACH,SAAS;IAET;;;;;;;;;;;;OAYG;IACH,OAAO;IAEP;;;;;;;;;;;;OAYG;IACH,YAAY;IAEZ;;;;;;;;;;;;;;OAcG;IACH,EAAE;IAEF,cAAc;IAEd;;;;;;;;;;;;OAYG;IACH,GAAG,EAAE,IAAI,CAAC,GAAG;IAEb;;;;;;;;;;;;OAYG;IACH,GAAG,EAAE,IAAI,CAAC,GAAG;IAEb;;;;;;;;;;;;;;OAcG;IACH,KAAK,EAAE,IAAI,CAAC,KAAK;IAEjB,eAAe;IAEf;;;;;;;;;;;OAWG;IACH,OAAO,EAAE,UAAU;IAEnB;;;;;;;;;;;OAWG;IACH,KAAK,EAAE,QAAQ;IAEf;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,WAAW;IAErB;;;;;;;;OAQG;IACH,MAAM,EAAE,SAAS;IAEjB;;;;;;;;OAQG;IACH,IAAI,EAAE,OAAO;IAEb;;;;;;;;;;OAUG;IACH,KAAK,EAAE,QAAQ;IAEf;;;;;;;;OAQG;IACH,GAAG,EAAE,MAAM;IAEX;;;;;;;;;;;;;;OAcG;IACH,IAAI,EAAE,OAAO;CACd,CAAC"}

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

@@ -0,0 +1,256 @@
+/**
+ * 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 { FloatType, IntegerType } from "../types.js";
+import { Expr, type ToExpr } from "./expr.js";
+import type { FloatExpr } from "./float.js";
+/**
+ * Expression representing integer values and operations.
+ *
+ * IntegerExpr provides arithmetic, comparison, and conversion operations for 64-bit signed integers.
+ * Operations automatically promote to FloatExpr when mixed with float operands.
+ *
+ * @example
+ * ```ts
+ * // Basic arithmetic
+ * const calculate = East.function([IntegerType, IntegerType], IntegerType, ($, a, b) => {
+ *   const sum = a.add(b);
+ *   const product = a.multiply(b);
+ *   const power = a.pow(2n);
+ *   $.return(sum.add(product).add(power));
+ * });
+ *
+ * // Integer division and remainder
+ * const divMod = East.function([IntegerType, IntegerType], StructType({quot: IntegerType, rem: IntegerType}), ($, x, y) => {
+ *   $.return({quot: x.divide(y), rem: x.remainder(y)});
+ * });
+ *
+ * // Type promotion with floats
+ * const mixed = East.function([IntegerType], FloatType, ($, x) => {
+ *   $.return(x.add(2.5));  // Returns FloatExpr
+ * });
+ * ```
+ */
+export declare class IntegerExpr extends Expr<IntegerType> {
+    constructor(ast: AST, createExpr: ToExpr);
+    /**
+     * Negates an integer value (-x).
+     *
+     * @returns The negated integer
+     *
+     * @example
+     * ```ts
+     * const negate = East.function([IntegerType], IntegerType, ($, x) => {
+     *   $.return(x.negate());
+     * });
+     * const compiled = East.compile(negate.toIR(), []);
+     * compiled(5n);   // -5n
+     * compiled(-3n);  // 3n
+     * ```
+     */
+    negate(): IntegerExpr;
+    /**
+     * Adds two integers or promotes to float if adding a float.
+     *
+     * @param y - The integer or float to add
+     * @returns IntegerExpr if both operands are integers, FloatExpr if either is a float
+     *
+     * @example
+     * ```ts
+     * const addIntegers = East.function([IntegerType, IntegerType], IntegerType, ($, x, y) => {
+     *   $.return(x.add(y));
+     * });
+     * const compiled = East.compile(addIntegers.toIR(), []);
+     * compiled(3n, 4n);  // 7n
+     *
+     * // Adding with float promotes to float
+     * const addFloat = East.function([IntegerType], FloatType, ($, x) => {
+     *   $.return(x.add(2.5));
+     * });
+     * ```
+     */
+    add(y: Expr<IntegerType> | bigint): IntegerExpr;
+    add(y: Expr<FloatType> | number): FloatExpr;
+    /**
+     * Subtracts two integers or promotes to float if subtracting a float.
+     *
+     * @param y - The integer or float to subtract
+     * @returns IntegerExpr if both operands are integers, FloatExpr if either is a float
+     *
+     * @example
+     * ```ts
+     * const subtractIntegers = East.function([IntegerType, IntegerType], IntegerType, ($, x, y) => {
+     *   $.return(x.subtract(y));
+     * });
+     * const compiled = East.compile(subtractIntegers.toIR(), []);
+     * compiled(10n, 3n);  // 7n
+     * compiled(5n, 8n);   // -3n
+     * ```
+     */
+    subtract(y: Expr<IntegerType> | bigint): IntegerExpr;
+    subtract(y: Expr<FloatType> | number): FloatExpr;
+    /**
+     * Multiplies two integers or promotes to float if multiplying by a float.
+     *
+     * @param y - The integer or float to multiply by
+     * @returns IntegerExpr if both operands are integers, FloatExpr if either is a float
+     *
+     * @example
+     * ```ts
+     * const multiplyIntegers = East.function([IntegerType, IntegerType], IntegerType, ($, x, y) => {
+     *   $.return(x.multiply(y));
+     * });
+     * const compiled = East.compile(multiplyIntegers.toIR(), []);
+     * compiled(6n, 7n);   // 42n
+     * compiled(-3n, 4n);  // -12n
+     * ```
+     */
+    multiply(y: Expr<IntegerType> | bigint): IntegerExpr;
+    multiply(y: Expr<FloatType> | number): FloatExpr;
+    /**
+     * Divides two integers (floor division) or promotes to float if dividing by a float.
+     *
+     * @param y - The integer or float divisor
+     * @returns IntegerExpr (floor division) if both are integers, FloatExpr if either is a float
+     *
+     * @remarks Integer division by zero returns 0 (does not throw error).
+     *          When dividing by a float, uses normal floating point division.
+     *
+     * @example
+     * ```ts
+     * const divideIntegers = East.function([IntegerType, IntegerType], IntegerType, ($, x, y) => {
+     *   $.return(x.divide(y));
+     * });
+     * const compiled = East.compile(divideIntegers.toIR(), []);
+     * compiled(10n, 3n);  // 3n (floor division)
+     * compiled(10n, 2n);  // 5n
+     * compiled(10n, 0n);  // 0n (division by zero returns 0)
+     * compiled(-10n, 3n); // -4n (floor towards negative infinity)
+     * ```
+     */
+    divide(y: Expr<IntegerType> | bigint): IntegerExpr;
+    divide(y: Expr<FloatType> | number): FloatExpr;
+    /**
+     * Computes the remainder of integer division or promotes to float.
+     *
+     * @param y - The integer or float divisor
+     * @returns IntegerExpr if both are integers, FloatExpr if either is a float
+     *
+     * @remarks Integer remainder by zero returns 0 (does not throw error).
+     *          Result has the same sign as the divisor (floor division semantics).
+     *
+     * @example
+     * ```ts
+     * const getRemainder = East.function([IntegerType, IntegerType], IntegerType, ($, x, y) => {
+     *   $.return(x.remainder(y));
+     * });
+     * const compiled = East.compile(getRemainder.toIR(), []);
+     * compiled(10n, 3n);   // 1n (10 = 3*3 + 1)
+     * compiled(10n, 4n);   // 2n
+     * compiled(-10n, 3n);  // 2n (floor division: -10 = 3*(-4) + 2)
+     * compiled(10n, 0n);   // 0n (remainder by zero returns 0)
+     * ```
+     */
+    remainder(y: Expr<IntegerType> | bigint): IntegerExpr;
+    remainder(y: Expr<FloatType> | number): FloatExpr;
+    /**
+     * Raises an integer to a power or promotes to float.
+     *
+     * @param y - The integer or float exponent
+     * @returns IntegerExpr if both are integers, FloatExpr if either is a float
+     *
+     * @remarks Integer exponentiation with negative exponent returns 0.
+     *          When using a float exponent, uses floating point exponentiation.
+     *
+     * @example
+     * ```ts
+     * const power = East.function([IntegerType, IntegerType], IntegerType, ($, base, exp) => {
+     *   $.return(base.pow(exp));
+     * });
+     * const compiled = East.compile(power.toIR(), []);
+     * compiled(2n, 3n);    // 8n (2^3)
+     * compiled(5n, 2n);    // 25n
+     * compiled(10n, 0n);   // 1n (anything^0 = 1)
+     * compiled(2n, -1n);   // 0n (negative exponent returns 0 for integers)
+     * ```
+     */
+    pow(y: Expr<IntegerType> | bigint): IntegerExpr;
+    pow(y: Expr<FloatType> | number): FloatExpr;
+    /**
+     * Returns the absolute value of an integer.
+     *
+     * @returns The absolute value (always non-negative)
+     *
+     * @example
+     * ```ts
+     * const absoluteValue = East.function([IntegerType], IntegerType, ($, x) => {
+     *   $.return(x.abs());
+     * });
+     * const compiled = East.compile(absoluteValue.toIR(), []);
+     * compiled(5n);    // 5n
+     * compiled(-5n);   // 5n
+     * compiled(0n);    // 0n
+     * ```
+     */
+    abs(): IntegerExpr;
+    /**
+     * Returns the sign of an integer (-1 for negative, 0 for zero, 1 for positive).
+     *
+     * @returns -1n, 0n, or 1n depending on the sign of the integer
+     *
+     * @example
+     * ```ts
+     * const getSign = East.function([IntegerType], IntegerType, ($, x) => {
+     *   $.return(x.sign());
+     * });
+     * const compiled = East.compile(getSign.toIR(), []);
+     * compiled(42n);   // 1n
+     * compiled(-17n);  // -1n
+     * compiled(0n);    // 0n
+     * ```
+     */
+    sign(): IntegerExpr;
+    /**
+     * Computes the integer logarithm with a specified base (floor of log).
+     *
+     * @param base - The base for the logarithm
+     * @returns The floor of log_base(x)
+     *
+     * @remarks Returns 0 if x <= 0 or base <= 1.
+     *
+     * @example
+     * ```ts
+     * const logarithm = East.function([IntegerType, IntegerType], IntegerType, ($, x, base) => {
+     *   $.return(x.log(base));
+     * });
+     * const compiled = East.compile(logarithm.toIR(), []);
+     * compiled(1000n, 10n);  // 3n (10^3 = 1000)
+     * compiled(8n, 2n);      // 3n (2^3 = 8)
+     * compiled(100n, 10n);   // 2n (10^2 = 100)
+     * compiled(7n, 2n);      // 2n (floor of log_2(7) ≈ 2.8)
+     * ```
+     */
+    log(base: Expr<IntegerType> | bigint): IntegerExpr;
+    /**
+     * Converts an integer to a floating-point number.
+     *
+     * @returns The integer as a FloatExpr
+     *
+     * @remarks May lose precision for very large integers (beyond 2^53).
+     *
+     * @example
+     * ```ts
+     * const convertToFloat = East.function([IntegerType], FloatType, ($, x) => {
+     *   $.return(x.toFloat());
+     * });
+     * const compiled = East.compile(convertToFloat.toIR(), []);
+     * compiled(42n);    // 42.0
+     * compiled(-17n);   // -17.0
+     * compiled(0n);     // 0.0
+     * ```
+     */
+    toFloat(): FloatExpr;
+}
+//# sourceMappingURL=integer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"integer.d.ts","sourceRoot":"","sources":["../../../src/expr/integer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAErC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAe,MAAM,aAAa,CAAC;AAClE,OAAO,EAAa,IAAI,EAAiB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAExE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,WAAY,SAAQ,IAAI,CAAC,WAAW,CAAC;gBACpC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM;IAIxC;;;;;;;;;;;;;;OAcG;IACH,MAAM,IAAI,WAAW;IAWrB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,WAAW;IAC/C,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS;IAwB3C;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,WAAW;IACpD,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS;IAwBhD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,WAAW;IACpD,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS;IAwBhD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,WAAW;IAClD,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS;IAwB9C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,WAAW;IACrD,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS;IAwBjD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,WAAW;IAC/C,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS;IAwB3C;;;;;;;;;;;;;;;OAeG;IACH,GAAG,IAAI,WAAW;IAWlB;;;;;;;;;;;;;;;OAeG;IACH,IAAI,IAAI,WAAW;IAWnB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,WAAW;IAYlD;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,IAAI,SAAS;CAUrB"}