@elaraai/east 0.0.1-beta.0

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

@@ -0,0 +1,357 @@
+/**
+ * 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 } from "../types.js";
+import { Expr, type ToExpr } from "./expr.js";
+import type { IntegerExpr } from "./integer.js";
+/**
+ * Expression representing floating-point values and operations (IEEE 754 double-precision).
+ *
+ * FloatExpr provides arithmetic, trigonometric, and conversion operations for 64-bit floats.
+ * Automatically converts integer operands to float when needed. Supports special values: Infinity, -Infinity, NaN.
+ *
+ * @example
+ * ```ts
+ * // Basic arithmetic
+ * const calculate = East.function([FloatType, FloatType], FloatType, ($, x, y) => {
+ *   const sum = x.add(y);
+ *   const ratio = x.divide(y);
+ *   $.return(sum.multiply(ratio));
+ * });
+ *
+ * // Trigonometry
+ * const angle = East.function([FloatType], FloatType, ($, degrees) => {
+ *   const radians = degrees.multiply(Math.PI / 180);
+ *   $.return(radians.sin());
+ * });
+ *
+ * // Mixed with integers
+ * const mixed = East.function([IntegerType], FloatType, ($, x) => {
+ *   $.return(x.add(2.5));  // Integer auto-converts to float
+ * });
+ * ```
+ */
+export declare class FloatExpr extends Expr<FloatType> {
+    constructor(ast: AST, createExpr: ToExpr);
+    /**
+     * Negates a floating-point number (-x).
+     *
+     * @returns A FloatExpr representing the negated value
+     *
+     * @example
+     * ```ts
+     * const negateFloat = East.function([FloatType], FloatType, ($, x) => {
+     *   $.return(x.negate());
+     * });
+     * const compiled = East.compile(negateFloat.toIR(), []);
+     * compiled(3.14);    // -3.14
+     * compiled(-2.5);    // 2.5
+     * compiled(0.0);     // -0.0 (negative zero)
+     * ```
+     */
+    negate(): FloatExpr;
+    /**
+     * Adds two floating-point numbers or converts integer to float and adds (x + y).
+     *
+     * @param y - The float, number, IntegerExpr, or bigint to add
+     * @returns A FloatExpr representing the sum
+     *
+     * @remarks Automatically converts integer operands to float before addition.
+     *
+     * @example
+     * ```ts
+     * const addFloats = East.function([FloatType, FloatType], FloatType, ($, x, y) => {
+     *   $.return(x.add(y));
+     * });
+     * const compiled = East.compile(addFloats.toIR(), []);
+     * compiled(3.14, 2.86);  // 6.0
+     * compiled(1.5, -0.5);   // 1.0
+     *
+     * // Mixed with integers
+     * const addMixed = East.function([FloatType, IntegerType], FloatType, ($, x, y) => {
+     *   $.return(x.add(y));  // Integer auto-converts to float
+     * });
+     * compiled = East.compile(addMixed.toIR(), []);
+     * compiled(3.14, 2n);    // 5.14
+     * ```
+     */
+    add(y: FloatExpr | number | IntegerExpr | bigint): FloatExpr;
+    /**
+     * Subtracts two floating-point numbers or converts integer to float and subtracts (x - y).
+     *
+     * @param y - The float, number, IntegerExpr, or bigint to subtract
+     * @returns A FloatExpr representing the difference
+     *
+     * @remarks Automatically converts integer operands to float before subtraction.
+     *
+     * @example
+     * ```ts
+     * const subtractFloats = East.function([FloatType, FloatType], FloatType, ($, x, y) => {
+     *   $.return(x.subtract(y));
+     * });
+     * const compiled = East.compile(subtractFloats.toIR(), []);
+     * compiled(5.5, 2.3);    // 3.2
+     * compiled(1.0, 1.0);    // 0.0
+     * compiled(-2.5, 3.5);   // -6.0
+     * ```
+     */
+    subtract(y: FloatExpr | number | IntegerExpr | bigint): FloatExpr;
+    /**
+     * Multiplies two floating-point numbers or converts integer to float and multiplies (x * y).
+     *
+     * @param y - The float, number, IntegerExpr, or bigint to multiply
+     * @returns A FloatExpr representing the product
+     *
+     * @remarks Automatically converts integer operands to float before multiplication.
+     *
+     * @example
+     * ```ts
+     * const multiplyFloats = East.function([FloatType, FloatType], FloatType, ($, x, y) => {
+     *   $.return(x.multiply(y));
+     * });
+     * const compiled = East.compile(multiplyFloats.toIR(), []);
+     * compiled(3.0, 2.5);    // 7.5
+     * compiled(2.0, -1.5);   // -3.0
+     * compiled(0.5, 0.5);    // 0.25
+     * ```
+     */
+    multiply(y: FloatExpr | number | IntegerExpr | bigint): FloatExpr;
+    /**
+     * Divides two floating-point numbers or converts integer to float and divides (x / y).
+     *
+     * @param y - The float, number, IntegerExpr, or bigint divisor
+     * @returns A FloatExpr representing the quotient
+     *
+     * @remarks Division by zero returns Infinity, -Infinity, or NaN according to IEEE 754.
+     *          Automatically converts integer operands to float before division.
+     *
+     * @example
+     * ```ts
+     * const divideFloats = East.function([FloatType, FloatType], FloatType, ($, x, y) => {
+     *   $.return(x.divide(y));
+     * });
+     * const compiled = East.compile(divideFloats.toIR(), []);
+     * compiled(10.0, 2.0);   // 5.0
+     * compiled(1.0, 3.0);    // 0.3333333333333333
+     * compiled(5.0, 0.0);    // Infinity
+     * compiled(-5.0, 0.0);   // -Infinity
+     * compiled(0.0, 0.0);    // NaN
+     * ```
+     */
+    divide(y: FloatExpr | number | IntegerExpr | bigint): FloatExpr;
+    /**
+     * Computes floating-point remainder of division (x % y).
+     *
+     * @param y - The float, number, IntegerExpr, or bigint divisor
+     * @returns A FloatExpr representing the remainder
+     *
+     * @remarks Uses IEEE 754 remainder semantics. Automatically converts integer operands to float.
+     *
+     * @example
+     * ```ts
+     * const remainderFloats = East.function([FloatType, FloatType], FloatType, ($, x, y) => {
+     *   $.return(x.remainder(y));
+     * });
+     * const compiled = East.compile(remainderFloats.toIR(), []);
+     * compiled(7.5, 2.0);    // 1.5
+     * compiled(10.0, 3.0);   // 1.0
+     * compiled(-7.5, 2.0);   // -1.5
+     * ```
+     */
+    remainder(y: FloatExpr | number | IntegerExpr | bigint): FloatExpr;
+    /**
+     * Raises a floating-point number to a power (x ** y).
+     *
+     * @param y - The float, number, IntegerExpr, or bigint exponent
+     * @returns A FloatExpr representing x raised to the power of y
+     *
+     * @remarks Automatically converts integer operands to float before exponentiation.
+     *
+     * @example
+     * ```ts
+     * const powFloats = East.function([FloatType, FloatType], FloatType, ($, x, y) => {
+     *   $.return(x.pow(y));
+     * });
+     * const compiled = East.compile(powFloats.toIR(), []);
+     * compiled(2.0, 3.0);    // 8.0
+     * compiled(9.0, 0.5);    // 3.0 (square root)
+     * compiled(2.0, -1.0);   // 0.5
+     * compiled(-1.0, 0.5);   // NaN (square root of negative)
+     * ```
+     */
+    pow(y: FloatExpr | number | IntegerExpr | bigint): FloatExpr;
+    /**
+     * Computes the absolute value of a floating-point number (|x|).
+     *
+     * @returns A FloatExpr representing the absolute value
+     *
+     * @example
+     * ```ts
+     * const absFloat = East.function([FloatType], FloatType, ($, x) => {
+     *   $.return(x.abs());
+     * });
+     * const compiled = East.compile(absFloat.toIR(), []);
+     * compiled(3.14);     // 3.14
+     * compiled(-2.5);     // 2.5
+     * compiled(0.0);      // 0.0
+     * compiled(-0.0);     // 0.0
+     * ```
+     */
+    abs(): FloatExpr;
+    /**
+     * Computes the sign of a floating-point number.
+     *
+     * @returns A FloatExpr representing -1.0 for negative, 0.0 for zero, 1.0 for positive, or NaN for NaN
+     *
+     * @example
+     * ```ts
+     * const signFloat = East.function([FloatType], FloatType, ($, x) => {
+     *   $.return(x.sign());
+     * });
+     * const compiled = East.compile(signFloat.toIR(), []);
+     * compiled(3.14);     // 1.0
+     * compiled(-2.5);     // -1.0
+     * compiled(0.0);      // 0.0
+     * compiled(-0.0);     // -0.0
+     * ```
+     */
+    sign(): FloatExpr;
+    /**
+     * Computes the square root of a floating-point number (√x).
+     *
+     * @returns A FloatExpr representing the square root
+     *
+     * @remarks Returns NaN for negative numbers.
+     *
+     * @example
+     * ```ts
+     * const sqrtFloat = East.function([FloatType], FloatType, ($, x) => {
+     *   $.return(x.sqrt());
+     * });
+     * const compiled = East.compile(sqrtFloat.toIR(), []);
+     * compiled(9.0);      // 3.0
+     * compiled(2.0);      // 1.4142135623730951
+     * compiled(0.0);      // 0.0
+     * compiled(-1.0);     // NaN
+     * ```
+     */
+    sqrt(): FloatExpr;
+    /**
+     * Computes the exponential function (e^x).
+     *
+     * @returns A FloatExpr representing e raised to the power of x
+     *
+     * @example
+     * ```ts
+     * const expFloat = East.function([FloatType], FloatType, ($, x) => {
+     *   $.return(x.exp());
+     * });
+     * const compiled = East.compile(expFloat.toIR(), []);
+     * compiled(0.0);      // 1.0
+     * compiled(1.0);      // 2.718281828459045
+     * compiled(2.0);      // 7.38905609893065
+     * compiled(-1.0);     // 0.36787944117144233
+     * ```
+     */
+    exp(): FloatExpr;
+    /**
+     * Computes the natural logarithm (ln(x)).
+     *
+     * @returns A FloatExpr representing the natural logarithm of x
+     *
+     * @remarks Returns NaN for negative numbers, -Infinity for 0.
+     *
+     * @example
+     * ```ts
+     * const logFloat = East.function([FloatType], FloatType, ($, x) => {
+     *   $.return(x.log());
+     * });
+     * const compiled = East.compile(logFloat.toIR(), []);
+     * compiled(Math.E);   // 1.0
+     * compiled(1.0);      // 0.0
+     * compiled(10.0);     // 2.302585092994046
+     * compiled(0.0);      // -Infinity
+     * compiled(-1.0);     // NaN
+     * ```
+     */
+    log(): FloatExpr;
+    /**
+     * Computes the sine of a floating-point number (sin(x)).
+     *
+     * @returns A FloatExpr representing the sine of x (x in radians)
+     *
+     * @example
+     * ```ts
+     * const sinFloat = East.function([FloatType], FloatType, ($, x) => {
+     *   $.return(x.sin());
+     * });
+     * const compiled = East.compile(sinFloat.toIR(), []);
+     * compiled(0.0);              // 0.0
+     * compiled(Math.PI / 2);      // 1.0
+     * compiled(Math.PI);          // ~0.0 (very close to zero)
+     * compiled(Math.PI / 6);      // 0.5
+     * ```
+     */
+    sin(): FloatExpr;
+    /**
+     * Computes the cosine of a floating-point number (cos(x)).
+     *
+     * @returns A FloatExpr representing the cosine of x (x in radians)
+     *
+     * @example
+     * ```ts
+     * const cosFloat = East.function([FloatType], FloatType, ($, x) => {
+     *   $.return(x.cos());
+     * });
+     * const compiled = East.compile(cosFloat.toIR(), []);
+     * compiled(0.0);              // 1.0
+     * compiled(Math.PI / 2);      // ~0.0 (very close to zero)
+     * compiled(Math.PI);          // -1.0
+     * compiled(Math.PI / 3);      // 0.5
+     * ```
+     */
+    cos(): FloatExpr;
+    /**
+     * Computes the tangent of a floating-point number (tan(x)).
+     *
+     * @returns A FloatExpr representing the tangent of x (x in radians)
+     *
+     * @example
+     * ```ts
+     * const tanFloat = East.function([FloatType], FloatType, ($, x) => {
+     *   $.return(x.tan());
+     * });
+     * const compiled = East.compile(tanFloat.toIR(), []);
+     * compiled(0.0);              // 0.0
+     * compiled(Math.PI / 4);      // 1.0
+     * compiled(Math.PI / 6);      // 0.5773502691896257
+     * compiled(-Math.PI / 4);     // -1.0
+     * ```
+     */
+    tan(): FloatExpr;
+    /**
+     * Converts a floating-point number to an integer.
+     *
+     * @returns An IntegerExpr representing the converted value
+     *
+     * @throws East runtime error if the float is NaN, infinite, larger than 2^63-1, smaller than -2^63, or not an integer value
+     *
+     * @example
+     * ```ts
+     * const floatToInt = East.function([FloatType], IntegerType, ($, x) => {
+     *   $.return(x.toInteger());
+     * });
+     * const compiled = East.compile(floatToInt.toIR(), []);
+     * compiled(42.0);     // 42n
+     * compiled(-10.0);    // -10n
+     * compiled(0.0);      // 0n
+     * // compiled(3.14) would throw error (not an integer value)
+     * // compiled(NaN) would throw error
+     * // compiled(Infinity) would throw error
+     * ```
+     */
+    toInteger(): IntegerExpr;
+}
+//# sourceMappingURL=float.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"float.d.ts","sourceRoot":"","sources":["../../../src/expr/float.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAErC,OAAO,EAAE,SAAS,EAAuC,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAa,IAAI,EAAiB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAExE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SAAU,SAAQ,IAAI,CAAC,SAAS,CAAC;gBAChC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM;IAIxC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,IAAI,SAAS;IAWnB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS;IA8B5D;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS;IA8BjE;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS;IA8BjE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS;IA8B/D;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS;IA8BlE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS;IA8B5D;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,IAAI,SAAS;IAWhB;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,IAAI,SAAS;IAWjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,IAAI,SAAS;IAWjB;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,IAAI,SAAS;IAWhB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,IAAI,SAAS;IAWhB;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,IAAI,SAAS;IAWhB;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,IAAI,SAAS;IAWhB;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,IAAI,SAAS;IAWhB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,IAAI,WAAW;CAUzB"}