@cortex-js/compute-engine 0.32.0 → 0.32.1

package/dist/types/compute-engine/boxed-expression/box.d.ts

@@ -0,0 +1,47 @@
+/* 0.32.1 */
+import { MathJsonSymbol } from '../../math-json/types';
+import { NumericValue } from '../numeric-value/types';
+/**
+ * Given a name and a set of arguments, return a boxed function expression.
+ *
+ * If available, preserve LaTeX and wikidata metadata in the boxed expression.
+ *
+ * Note that `boxFunction()` should only be called from `ce.function()`
+ */
+export declare function boxFunction(ce: ComputeEngine, name: MathJsonSymbol, ops: readonly SemiBoxedExpression[], options?: {
+    metadata?: Metadata;
+    canonical?: CanonicalOptions;
+    structural?: boolean;
+    scope?: Scope;
+}): BoxedExpression;
+/**
+ * Notes about the boxed form:
+ *
+ * [1] Expression with an operator of `Number`, `String`, `Symbol` and `Dictionary`
+ *      are converted to the corresponding atomic expression.
+ *
+ * [2] Expressions with an operator of `Complex` are converted to a (complex) number
+ *     or a `Add`/`Multiply` expression.
+ *
+ *     The precedence of `Complex` (for serialization) is sometimes the
+ *     precedence of `Add` (when re and im != 0), sometimes the precedence of
+ *    `Multiply` (when im or re === 0). Using a number or an explicit
+ *    `Add`/`Multiply` expression avoids this ambiguity.
+ *
+ * [3] An expression with a `Rational` operator is converted to a rational
+ *    number if possible, to a `Divide` otherwise.
+ *
+ * [4] A `Negate` function applied to a number literal is converted to a number.
+ *
+ *     Note that `Negate` is only distributed over addition. In practice, having
+ * `Negate` factored on multiply/divide is more useful to detect patterns.
+ *
+ * Note that this function should only be called from `ce.box()`
+ *
+ */
+export declare function box(ce: ComputeEngine, expr: null | undefined | NumericValue | SemiBoxedExpression, options?: {
+    canonical?: CanonicalOptions;
+    structural?: boolean;
+    scope?: Scope;
+}): BoxedExpression;
+export declare function semiCanonical(ce: ComputeEngine, xs: ReadonlyArray<SemiBoxedExpression>, scope?: Scope): ReadonlyArray<BoxedExpression>;

package/dist/types/compute-engine/boxed-expression/boxed-dictionary.d.ts

@@ -0,0 +1,44 @@
+/* 0.32.1 */
+import { _BoxedExpression } from './abstract-boxed-expression';
+import { BoxedType } from '../../common/type/boxed-type';
+import { DictionaryValue, Expression } from '../../math-json/types';
+/**
+ * BoxedDictionary
+ *
+ */
+export declare class BoxedDictionary extends _BoxedExpression implements DictionaryInterface {
+    [Symbol.toStringTag]: string;
+    private readonly _keyValues;
+    private _type;
+    /** The input to the constructor is either a ["Dictionary", ["KeyValuePair", ..., ...], ...] expression or a record of key-value pairs */
+    constructor(ce: ComputeEngine, keyValues: Record<string, DictionaryValue> | BoxedExpression, options?: {
+        metadata?: Metadata;
+        canonical?: boolean;
+    });
+    private _initFromRecord;
+    private _initFromExpression;
+    get json(): Expression;
+    toMathJson(options: Readonly<JsonSerializationOptions>): Expression;
+    get hash(): number;
+    get operator(): string;
+    get type(): BoxedType;
+    get isPure(): boolean;
+    get isCanonical(): boolean;
+    set isCanonical(_va: boolean);
+    get value(): BoxedExpression | undefined;
+    get complexity(): number;
+    get isCollection(): boolean;
+    get isIndexedCollection(): boolean;
+    get isLazyCollection(): boolean;
+    contains(_rhs: BoxedExpression): boolean | undefined;
+    get count(): number | undefined;
+    get isEmptyCollection(): boolean;
+    get isFiniteCollection(): boolean;
+    each(): Generator<BoxedExpression>;
+    get(key: string): BoxedExpression | undefined;
+    has(key: string): boolean;
+    get keys(): string[];
+    get entries(): [string, BoxedExpression][];
+    get values(): BoxedExpression[];
+    match(pattern: BoxedExpression, _options?: PatternMatchOptions): BoxedSubstitution | null;
+}

package/dist/types/compute-engine/boxed-expression/boxed-function.d.ts

@@ -0,0 +1,136 @@
+/* 0.32.1 */
+import type { SimplifyOptions, ReplaceOptions, PatternMatchOptions, BoxedExpression, BoxedBaseDefinition, BoxedOperatorDefinition, BoxedRuleSet, BoxedSubstitution, CanonicalOptions, EvaluateOptions, ComputeEngine, Metadata, Rule, Sign, Substitution, Scope, BoxedValueDefinition } from '../global-types';
+import { Type } from '../../common/type/types';
+import { BoxedType } from '../../common/type/boxed-type';
+import { NumericValue } from '../numeric-value/types';
+import { _BoxedExpression } from './abstract-boxed-expression';
+/**
+ * A boxed function expression represent an expression composed of an operator
+ * (the name of the function) and a list of arguments. For example:
+ * `["Add", 1, 2]` is a function expression with the operator "Add" and two
+ * arguments 1 and 2.
+ *
+ * If canonical, it has a definition associated with it, based on the operator.
+ *
+ * The definition contains its signature and its evaluation handler.
+ *
+ */
+export declare class BoxedFunction extends _BoxedExpression {
+    private readonly _operator;
+    private readonly _ops;
+    private _def;
+    /** @todo: wrong. If the function is scoped (has its own lexical scope), the captured eval context. This includes the lexical scope for this expression
+     */
+    private _capturedContext;
+    /** If the operator is scoped, the local scope associated with
+     * the function expression
+     */
+    private _localScope;
+    private _isPure;
+    private _isStructural;
+    private _hash;
+    private _value;
+    private _valueN;
+    private _sgn;
+    private _type;
+    constructor(ce: ComputeEngine, operator: string, ops: ReadonlyArray<BoxedExpression>, options?: {
+        metadata?: Metadata;
+        canonical?: boolean;
+        structural?: boolean;
+        scope?: Scope;
+    });
+    get hash(): number;
+    /**
+     * For function expressions, `infer()` infers the result type of the function
+     * based on the provided type and inference mode.
+     */
+    infer(t: Type, inferenceMode?: 'narrow' | 'widen'): boolean;
+    bind(): void;
+    reset(): void;
+    get value(): BoxedExpression | undefined;
+    get isCanonical(): boolean;
+    get isPure(): boolean;
+    get isConstant(): boolean;
+    get constantValue(): number | boolean | string | object | undefined;
+    get json(): Expression;
+    get operator(): string;
+    get ops(): ReadonlyArray<BoxedExpression>;
+    get nops(): number;
+    get op1(): BoxedExpression;
+    get op2(): BoxedExpression;
+    get op3(): BoxedExpression;
+    get isScoped(): boolean;
+    get localScope(): Scope | undefined;
+    get isValid(): boolean;
+    /** Note: if the expression is not canonical, this will return a canonical
+     * version of the expression in the current lexical scope.
+     */
+    get canonical(): BoxedExpression;
+    get structural(): BoxedExpression;
+    get isStructural(): boolean;
+    toNumericValue(): [NumericValue, BoxedExpression];
+    /**
+     * Note: the result is bound to the current scope, not the scope of the
+     * original expression.
+     * <!-- This may or may not be desirable -->
+     */
+    subs(sub: Substitution, options?: {
+        canonical?: CanonicalOptions;
+    }): BoxedExpression;
+    replace(rules: BoxedRuleSet | Rule | Rule[], options?: Partial<ReplaceOptions>): BoxedExpression | null;
+    match(pattern: BoxedExpression, options?: PatternMatchOptions): BoxedSubstitution | null;
+    has(v: string | string[]): boolean;
+    get sgn(): Sign | undefined;
+    get isNaN(): boolean | undefined;
+    get isInfinity(): boolean | undefined;
+    get isFinite(): boolean | undefined;
+    get isOne(): boolean | undefined;
+    get isNegativeOne(): boolean | undefined;
+    get isPositive(): boolean | undefined;
+    get isNonNegative(): boolean | undefined;
+    get isNegative(): boolean | undefined;
+    get isNonPositive(): boolean | undefined;
+    get numerator(): BoxedExpression;
+    get denominator(): BoxedExpression;
+    get numeratorDenominator(): [BoxedExpression, BoxedExpression];
+    neg(): BoxedExpression;
+    inv(): BoxedExpression;
+    abs(): BoxedExpression;
+    add(rhs: number | BoxedExpression): BoxedExpression;
+    mul(rhs: NumericValue | number | BoxedExpression): BoxedExpression;
+    div(rhs: number | BoxedExpression): BoxedExpression;
+    pow(exp: number | BoxedExpression): BoxedExpression;
+    root(exp: number | BoxedExpression): BoxedExpression;
+    sqrt(): BoxedExpression;
+    ln(semiBase?: number | BoxedExpression): BoxedExpression;
+    get complexity(): number | undefined;
+    get baseDefinition(): BoxedBaseDefinition | undefined;
+    get operatorDefinition(): BoxedOperatorDefinition | undefined;
+    get valueDefinition(): BoxedValueDefinition | undefined;
+    get isNumber(): boolean | undefined;
+    get isInteger(): boolean | undefined;
+    get isRational(): boolean | undefined;
+    get isReal(): boolean | undefined;
+    get isFunctionExpression(): boolean;
+    /** The type of the value of the function */
+    get type(): BoxedType;
+    simplify(options?: Partial<SimplifyOptions>): BoxedExpression;
+    evaluate(options?: Partial<EvaluateOptions>): BoxedExpression;
+    evaluateAsync(options?: Partial<EvaluateOptions>): Promise<BoxedExpression>;
+    N(): BoxedExpression;
+    solve(vars?: Iterable<string> | string | BoxedExpression | Iterable<BoxedExpression>): null | ReadonlyArray<BoxedExpression>;
+    get isCollection(): boolean;
+    get isIndexedCollection(): boolean;
+    get isLazyCollection(): boolean;
+    contains(rhs: BoxedExpression): boolean | undefined;
+    get count(): number | undefined;
+    get isEmptyCollection(): boolean | undefined;
+    get isFiniteCollection(): boolean | undefined;
+    each(): Generator<BoxedExpression>;
+    at(index: number): BoxedExpression | undefined;
+    get(index: BoxedExpression | string): BoxedExpression | undefined;
+    indexWhere(predicate: (element: BoxedExpression) => boolean): number | undefined;
+    subsetOf(rhs: BoxedExpression, strict: boolean): boolean;
+    _computeValue(options?: Partial<EvaluateOptions>): () => BoxedExpression;
+    _computeValueAsync(options?: Partial<EvaluateOptions>): () => Promise<BoxedExpression>;
+}

package/dist/types/compute-engine/boxed-expression/boxed-number.d.ts

@@ -0,0 +1,103 @@
+/* 0.32.1 */
+import { Decimal } from 'decimal.js';
+import type { Expression, MathJsonNumberObject } from '../../math-json';
+import type { Rational, SmallInteger } from '../numerics/types';
+import { ExactNumericValueData, NumericValue, NumericValueData } from '../numeric-value/types';
+import { _BoxedExpression } from './abstract-boxed-expression';
+import { BoxedType } from '../../common/type/boxed-type';
+import type { BoxedRuleSet, BoxedSubstitution, CanonicalOptions, EvaluateOptions, ComputeEngine, Metadata, Rule, Sign, Substitution, BoxedExpression, PatternMatchOptions, ReplaceOptions, SimplifyOptions } from '../global-types';
+/**
+ * BoxedNumber
+ *
+ */
+export declare class BoxedNumber extends _BoxedExpression {
+    protected readonly _value: SmallInteger | NumericValue;
+    private _hash;
+    /**
+     * By the time the constructor is called, the `value` should have been
+     * screened for cases where it's a well-known value (0, NaN, +Infinity,
+     * etc...) or non-normal (complex number with im = 0, rational with
+     * denom = 1, etc...).
+     *
+     * This is done in `ce.number()`. In general, use `ce.number()` rather
+     * than calling this constructor directly.
+     *
+     * We may store as a machine number if a Decimal is passed that is in machine
+     * range
+     */
+    constructor(ce: ComputeEngine, value: SmallInteger | NumericValueData | ExactNumericValueData | NumericValue, options?: {
+        metadata?: Metadata;
+    });
+    get hash(): number;
+    get json(): Expression;
+    get operator(): string;
+    get isPure(): boolean;
+    get isCanonical(): boolean;
+    set isCanonical(val: boolean);
+    get complexity(): number;
+    /**
+     *
+     * Return a JavaScript number when possible (most cases); else return a
+     * string representation of the number (ComplexInfinity and complex numbers
+     * for example).
+     *
+     * When a JavaScript number is returned, it may have fewer digits than the
+     * original number, but it will be a close approximation.
+     *
+     * @returns {number | string} The value of the number.
+     */
+    valueOf(): number | string;
+    get numericValue(): number | NumericValue;
+    get isNumberLiteral(): boolean;
+    get re(): number;
+    get im(): number;
+    get bignumRe(): Decimal | undefined;
+    get bignumIm(): Decimal | undefined;
+    neg(): BoxedExpression;
+    inv(): BoxedExpression;
+    abs(): BoxedExpression;
+    add(rhs: number | BoxedExpression): BoxedExpression;
+    mul(rhs: NumericValue | number | BoxedExpression): BoxedExpression;
+    div(rhs: number | BoxedExpression): BoxedExpression;
+    pow(exp: number | BoxedExpression): BoxedExpression;
+    root(exp: number | BoxedExpression): BoxedExpression;
+    sqrt(): BoxedExpression;
+    ln(semiBase?: number | BoxedExpression): BoxedExpression;
+    get value(): BoxedExpression;
+    get type(): BoxedType;
+    get sgn(): Sign | undefined;
+    get numerator(): BoxedExpression;
+    get denominator(): BoxedExpression;
+    get numeratorDenominator(): [BoxedExpression, BoxedExpression];
+    subs(sub: Substitution, options?: {
+        canonical?: CanonicalOptions;
+    }): BoxedExpression;
+    replace(rules: BoxedRuleSet | Rule | Rule[], options?: Partial<ReplaceOptions>): BoxedExpression | null;
+    match(pattern: BoxedExpression, options?: PatternMatchOptions): BoxedSubstitution | null;
+    /** x > 0, same as `isGreater(0)` */
+    get isPositive(): boolean | undefined;
+    /** x >= 0, same as `isGreaterEqual(0)` */
+    get isNonNegative(): boolean | undefined;
+    /** x < 0, same as `isLess(0)` */
+    get isNegative(): boolean | undefined;
+    /** x <= 0, same as `isLessEqual(0)` */
+    get isNonPositive(): boolean | undefined;
+    get isOdd(): boolean | undefined;
+    get isEven(): boolean | undefined;
+    get isInfinity(): boolean;
+    get isNaN(): boolean;
+    get isFinite(): boolean;
+    get isNumber(): true;
+    get isInteger(): boolean;
+    get isRational(): boolean;
+    get isReal(): boolean;
+    is(other: BoxedExpression | number | bigint | boolean): boolean;
+    get canonical(): BoxedExpression;
+    get isStructural(): boolean;
+    get structural(): BoxedExpression;
+    toNumericValue(): [NumericValue, BoxedExpression];
+    simplify(options?: Partial<SimplifyOptions>): BoxedExpression;
+    evaluate(options?: Partial<EvaluateOptions>): BoxedExpression;
+    N(): BoxedExpression;
+}
+export declare function canonicalNumber(ce: ComputeEngine, value: number | bigint | string | Decimal | Complex | Rational | NumericValue | MathJsonNumberObject): number | NumericValue;

package/dist/types/compute-engine/boxed-expression/boxed-operator-definition.d.ts

@@ -0,0 +1,53 @@
+/* 0.32.1 */
+import { BoxedType } from '../../common/type/boxed-type';
+import type { OperatorDefinition, BoxedExpression, BoxedOperatorDefinition, CollectionHandlers, CompiledExpression, EvaluateOptions, ComputeEngine, Sign } from '../global-types';
+export declare class _BoxedOperatorDefinition implements BoxedOperatorDefinition {
+    engine: ComputeEngine;
+    name: string;
+    description?: string | string[];
+    url?: string;
+    wikidata?: string;
+    broadcastable: boolean;
+    associative: boolean;
+    commutative: boolean;
+    commutativeOrder: ((a: BoxedExpression, b: BoxedExpression) => number) | undefined;
+    idempotent: boolean;
+    involution: boolean;
+    pure: boolean;
+    complexity: number;
+    lazy: boolean;
+    scoped: boolean;
+    signature: BoxedType;
+    inferredSignature: boolean;
+    type?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => BoxedType | Type | TypeString | undefined;
+    sgn?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => Sign | undefined;
+    eq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
+    neq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
+    even?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => boolean | undefined;
+    canonical?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => BoxedExpression | null;
+    evaluate?: (ops: ReadonlyArray<BoxedExpression>, options: Partial<EvaluateOptions> & {
+        engine: ComputeEngine;
+    }) => BoxedExpression | undefined;
+    evaluateAsync?: (ops: ReadonlyArray<BoxedExpression>, options?: Partial<EvaluateOptions> & {
+        engine?: ComputeEngine;
+    }) => Promise<BoxedExpression | undefined>;
+    evalDimension?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => BoxedExpression;
+    compile?: (expr: BoxedExpression) => CompiledExpression;
+    collection?: CollectionHandlers;
+    constructor(ce: ComputeEngine, name: string, def: OperatorDefinition);
+    /** For debugging */
+    toJSON(): any;
+    infer(sig: Type): void;
+    update(def: OperatorDefinition): void;
+    onConfigurationChange(): void;
+}

package/dist/types/compute-engine/boxed-expression/boxed-patterns.d.ts

@@ -0,0 +1,107 @@
+/* 0.32.1 */
+ * # Pattern Matching Wildcards
+ *
+ * Patterns can contain wildcards that match parts of expressions. There are
+ * three types of wildcards:
+ *
+ * ## Universal Wildcard (`_` or `_name`)
+ * Matches exactly **one** expression element.
+ *
+ * - `_` - Anonymous wildcard (matches one element, not captured)
+ * - `_a`, `_x`, `_foo` - Named wildcard (matches one element, captured in substitution)
+ *
+ * **Examples:**
+ * - Pattern `['Add', '_a', 1]` matches `['Add', 'x', 1]` with `{_a: 'x'}`
+ * - Pattern `['Add', '_', '_']` matches any binary Add expression
+ *
+ * ## Sequence Wildcard (`__` or `__name`)
+ * Matches **one or more** expression elements.
+ *
+ * - `__` - Anonymous sequence (matches 1+ elements, not captured)
+ * - `__a`, `__args` - Named sequence (matches 1+ elements, captured as array)
+ *
+ * **Examples:**
+ * - Pattern `['Add', '__a']` matches `['Add', 1, 2, 3]` with `{__a: [1, 2, 3]}`
+ * - Pattern `['f', '__args']` captures all arguments of function f
+ *
+ * ## Optional Sequence Wildcard (`___` or `___name`)
+ * Matches **zero or more** expression elements.
+ *
+ * - `___` - Anonymous optional sequence (matches 0+ elements, not captured)
+ * - `___a`, `___rest` - Named optional sequence (matches 0+ elements, captured)
+ *
+ * **Examples:**
+ * - Pattern `['Add', 1, '___rest']` matches `['Add', 1]` with `{___rest: []}`
+ * - Pattern `['Add', 1, '___rest']` matches `['Add', 1, 2, 3]` with `{___rest: [2, 3]}`
+ *
+ * ## Validation Rules
+ *
+ * Consecutive multi-element wildcards (`__` or `___`) are **invalid** because
+ * there's no way to determine where one ends and the next begins:
+ *
+ * - **Invalid:** `['Add', '__a', '__b']` - How to split elements between `__a` and `__b`?
+ * - **Invalid:** `['Add', '___a', '___b']` - Same ambiguity
+ * - **Invalid:** `['Add', '__a', '___b']` - Same ambiguity
+ *
+ * However, multi-element wildcards followed by universal wildcards are **valid**
+ * because the single-element wildcard provides an anchor point:
+ *
+ * - **Valid:** `['Add', '__a', '_b']` - `_b` matches last element, `__a` gets the rest
+ * - **Valid:** `['Add', '___a', '_b', '___c']` - `_b` anchors the middle
+ *
+ * Use `validatePattern()` to check patterns for these invalid combinations.
+ *
+ * @module boxed-patterns
+ */
+import type { BoxedSymbol } from './boxed-symbol';
+import type { BoxedExpression } from '../global-types';
+/**
+ * Check if an expression is a wildcard (universal, sequence, or optional sequence).
+ *
+ * @param expr - The expression to check
+ * @returns `true` if the expression is any type of wildcard
+ */
+export declare function isWildcard(expr: BoxedExpression): expr is BoxedSymbol;
+/**
+ * Get the string representation of a wildcard expression.
+ *
+ * Returns the wildcard symbol including its name (if any):
+ * - `'_'` for anonymous universal wildcard
+ * - `'_a'` for named universal wildcard
+ * - `'__'` for anonymous sequence wildcard
+ * - `'__args'` for named sequence wildcard
+ * - `'___'` for anonymous optional sequence wildcard
+ * - `'___rest'` for named optional sequence wildcard
+ *
+ * @param expr - The expression to get the wildcard name from
+ * @returns The wildcard string, or `null` if not a wildcard
+ */
+export declare function wildcardName(expr: BoxedExpression): string | null;
+/**
+ * Determine the type of wildcard.
+ *
+ * @param expr - A BoxedExpression or wildcard symbol string
+ * @returns
+ * - `'Wildcard'` - Universal wildcard (`_` or `_name`), matches exactly one element
+ * - `'Sequence'` - Sequence wildcard (`__` or `__name`), matches one or more elements
+ * - `'OptionalSequence'` - Optional sequence (`___` or `___name`), matches zero or more elements
+ * - `null` - Not a wildcard
+ */
+export declare function wildcardType(expr: BoxedExpression | string): 'Wildcard' | 'Sequence' | 'OptionalSequence' | null;
+/**
+ * Validate a pattern for invalid wildcard combinations.
+ *
+ * Throws an error if the pattern contains consecutive multi-element wildcards:
+ * - Sequence (`__`) followed by Sequence (`__`) or OptionalSequence (`___`)
+ * - OptionalSequence (`___`) followed by Sequence (`__`) or OptionalSequence (`___`)
+ *
+ * These patterns are ambiguous because there's no delimiter to determine where
+ * one sequence ends and the next begins.
+ *
+ * Sequence or OptionalSequence followed by universal Wildcard (`_`) is allowed
+ * because the single-element wildcard provides an anchor point.
+ *
+ * @param pattern - The pattern to validate
+ * @throws Error if the pattern contains invalid wildcard combinations
+ */
+export declare function validatePattern(pattern: BoxedExpression): void;

package/dist/types/compute-engine/boxed-expression/boxed-string.d.ts

@@ -0,0 +1,27 @@
+/* 0.32.1 */
+import { _BoxedExpression } from './abstract-boxed-expression';
+import { BoxedType } from '../../common/type/boxed-type';
+/**
+ * BoxedString
+ *
+ */
+export declare class BoxedString extends _BoxedExpression {
+    [Symbol.toStringTag]: string;
+    private readonly _string;
+    private _utf8Buffer?;
+    private _unicodeScalarValues?;
+    constructor(ce: ComputeEngine, expr: string, metadata?: Metadata);
+    get json(): string;
+    get hash(): number;
+    get operator(): string;
+    get isPure(): boolean;
+    get isCanonical(): boolean;
+    set isCanonical(_va: boolean);
+    get value(): BoxedExpression;
+    get type(): BoxedType;
+    get complexity(): number;
+    get string(): string;
+    get buffer(): Uint8Array;
+    get unicodeScalars(): number[];
+    match(pattern: BoxedExpression, _options?: PatternMatchOptions): BoxedSubstitution | null;
+}