nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/classes/assumption/assume.d.ts

@@ -0,0 +1,90 @@
+import { Expression } from '../expression/Expression';
+import { Assumption } from './Assumption';
+/** @internal */
+export declare function hasAssumptions(): boolean;
+/**
+ * Registers a numeric interval assumption in Nerdamer's global assumption state.
+ *
+ * @remarks
+ * A one-argument call parses a complete constraint such as `x >= 0`. The two-argument
+ * form associates a plain variable with either another complete constraint for that
+ * same variable or an existing {@link Assumption} instance. Built-in constants and the
+ * configured imaginary-unit symbol cannot receive real interval assumptions.
+ *
+ * Repeated assumptions for the same variable are intersected. If the intersection is
+ * empty, the new constraint is rejected and the previously registered assumption is
+ * left unchanged.
+ *
+ * Assumption state is process-wide. It is consulted by expression comparisons and by
+ * algorithms that rely on those comparisons, including positivity-sensitive
+ * simplifications. Call {@link clearAssumptions} when that state should no longer
+ * affect later work. Scoped assumption contexts are not simulated in 2.0 because a
+ * correct scoped design must be threaded through the parser and algorithms rather
+ * than wrapping only this registry.
+ *
+ * @param expr - Complete constraint in the supported assumption grammar.
+ * @returns The registered interval after intersection with any existing constraint.
+ * @throws Error
+ * Thrown when the constraint is malformed or its bound is not numeric.
+ * @throws UnexpectedInputError
+ * Thrown when a new constraint contradicts the existing assumption.
+ *
+ * @example
+ * ```ts
+ * assume('x >= 0');
+ * assume('x < 10');
+ * getAssumptionFor('x')?.toString(); // "[0, 10)"
+ * clearAssumptions();
+ * ```
+ */
+export declare function assume(expr: string): Assumption;
+/**
+ * Registers an assumption for a named variable.
+ *
+ * @param symbol - Plain variable name receiving the constraint.
+ * @param exprOrAssumption - Constraint for the same symbol or a prebuilt interval.
+ * @returns The registered interval after intersection with any existing constraint.
+ */
+export declare function assume(symbol: string, exprOrAssumption: string | Assumption): Assumption;
+/**
+ * Clears Nerdamer's process-wide assumption registry.
+ *
+ * This does not modify expressions that have already been constructed; it only
+ * changes the assumptions consulted by later comparison and simplification work.
+ */
+export declare function clearAssumptions(): void;
+/**
+ * Removes the registered assumption for one plain variable.
+ *
+ * @remarks
+ * Passing an expression that is not a plain variable, or a name with no registered
+ * assumption, is a no-op. Other assumptions are left unchanged.
+ *
+ * @param x - Plain variable expression or variable name to forget.
+ */
+export declare function forgetAssumptionFor(x: Expression | string): void;
+/**
+ * Returns the interval currently registered for a plain variable.
+ *
+ * @remarks
+ * `Assumption` instances are immutable, so the returned object can be inspected
+ * without exposing mutable registry state. Non-variable expressions have no direct
+ * assumption and return `undefined`.
+ *
+ * @param x - Plain variable expression or variable name.
+ * @returns The registered interval, or `undefined` when no assumption is available.
+ */
+export declare function getAssumptionFor(x: Expression | string): Assumption | undefined;
+/**
+ * Parser marker used by `assume(...)` so comparison operators register constraints
+ * instead of evaluating ordinary boolean relations.
+ *
+ * @internal
+ */
+export declare function assuming(x: Expression): Expression;
+/**
+ * Parser-facing compatibility function for `forget(variable)` and `forget(all)`.
+ *
+ * @internal
+ */
+export declare function forget(x: Expression): Expression;

package/output/core/classes/assumption/assume.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasAssumptions = hasAssumptions;
+exports.assume = assume;
+exports.clearAssumptions = clearAssumptions;
+exports.forgetAssumptionFor = forgetAssumptionFor;
+exports.getAssumptionFor = getAssumptionFor;
+exports.assuming = assuming;
+exports.forget = forget;
+const errors_1 = require("../../errors");
+const Settings_1 = require("../../Settings");
+const Expression_1 = require("../expression/Expression");
+const constants_1 = require("../parser/constants");
+const Assumption_1 = require("./Assumption");
+// Assumptions remain process-wide compatibility state in 2.0. A useful scoped
+// context would have to be threaded through parser, comparison, and simplification
+// calls; wrapping this Map without doing that would only create the appearance of
+// isolation. Keep the state explicit here until that larger API can be designed.
+const ASSUMPTIONS = new Map();
+/** @internal */
+function hasAssumptions() {
+    return ASSUMPTIONS.size !== 0;
+}
+function setAssumption(symbol, assumption) {
+    if (Expression_1.Expression.RESERVED.includes(symbol) ||
+        Settings_1.RESTRICTED.includes(symbol) ||
+        symbol === Expression_1.Expression.imaginary) {
+        throw new errors_1.UnexpectedInputError((0, errors_1.message)('plainVariableExpected', { input: symbol }));
+    }
+    const prev = ASSUMPTIONS.get(symbol);
+    let retval = assumption;
+    if (prev) {
+        const intersection = prev.intersect(assumption);
+        if (!intersection) {
+            throw new errors_1.UnexpectedInputError((0, errors_1.message)('inconsistentAssumptions'));
+        }
+        retval = intersection;
+    }
+    ASSUMPTIONS.set(symbol, retval);
+    return retval;
+}
+function assume(a, b) {
+    let retval;
+    if (arguments.length === 1) {
+        const parsed = Assumption_1.Assumption.parse(a);
+        retval = setAssumption(parsed.symbol, parsed.assumption);
+    }
+    else {
+        const symbol = String(a);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(symbol)) {
+            throw new errors_1.UnexpectedInputError((0, errors_1.message)('plainVariableExpected', { input: symbol }));
+        }
+        if (typeof b === 'string') {
+            const parsed = Assumption_1.Assumption.parse(b);
+            if (parsed.symbol !== symbol) {
+                throw new errors_1.UnexpectedInputError((0, errors_1.message)('wrongInput', { expected: symbol, received: parsed.symbol }));
+            }
+            retval = setAssumption(symbol, parsed.assumption);
+        }
+        else if (Assumption_1.Assumption.isAssumption(b)) {
+            retval = setAssumption(symbol, b);
+        }
+        else {
+            throw new errors_1.UnexpectedInputError((0, errors_1.message)('wrongInput', {
+                expected: 'string or Assumption',
+                received: typeof b,
+            }));
+        }
+    }
+    return retval;
+}
+/**
+ * Clears Nerdamer's process-wide assumption registry.
+ *
+ * This does not modify expressions that have already been constructed; it only
+ * changes the assumptions consulted by later comparison and simplification work.
+ */
+function clearAssumptions() {
+    ASSUMPTIONS.clear();
+}
+/**
+ * Removes the registered assumption for one plain variable.
+ *
+ * @remarks
+ * Passing an expression that is not a plain variable, or a name with no registered
+ * assumption, is a no-op. Other assumptions are left unchanged.
+ *
+ * @param x - Plain variable expression or variable name to forget.
+ */
+function forgetAssumptionFor(x) {
+    let symbol;
+    if (Expression_1.Expression.isExpression(x) && x.isPlainVariable()) {
+        symbol = x.value;
+    }
+    else if (typeof x === 'string') {
+        symbol = x;
+    }
+    if (symbol !== undefined) {
+        ASSUMPTIONS.delete(symbol);
+    }
+}
+/**
+ * Returns the interval currently registered for a plain variable.
+ *
+ * @remarks
+ * `Assumption` instances are immutable, so the returned object can be inspected
+ * without exposing mutable registry state. Non-variable expressions have no direct
+ * assumption and return `undefined`.
+ *
+ * @param x - Plain variable expression or variable name.
+ * @returns The registered interval, or `undefined` when no assumption is available.
+ */
+function getAssumptionFor(x) {
+    let symbol;
+    if (Expression_1.Expression.isExpression(x) && x.isPlainVariable()) {
+        symbol = x.value;
+    }
+    else if (typeof x === 'string') {
+        symbol = x;
+    }
+    return symbol === undefined ? undefined : ASSUMPTIONS.get(symbol);
+}
+/**
+ * Parser marker used by `assume(...)` so comparison operators register constraints
+ * instead of evaluating ordinary boolean relations.
+ *
+ * @internal
+ */
+function assuming(x) {
+    return x;
+}
+/**
+ * Parser-facing compatibility function for `forget(variable)` and `forget(all)`.
+ *
+ * @internal
+ */
+function forget(x) {
+    if (x.eq(constants_1.ALL_SYMBOL)) {
+        clearAssumptions();
+    }
+    else {
+        forgetAssumptionFor(x);
+    }
+    return x;
+}

package/output/core/classes/collection/Collection.d.ts

@@ -0,0 +1,107 @@
+import { StructuredEntity } from '../../common/classes/StructuredEntity';
+import { COLLECTION } from '../parser/constants';
+import type { ParserEntity } from '../../types';
+/**
+ * An ordered heterogeneous collection of parser entities.
+ *
+ * @remarks
+ * The constructor retains the supplied array and its element references.
+ * {@link getElements} likewise exposes the live backing array. Use {@link copy}
+ * for an independent collection; it copies every contained parser entity.
+ *
+ * {@link each} and indexed assignment mutate the collection. A callback passed
+ * to `each` may return a replacement value or return nothing to leave the
+ * current value unchanged. Use {@link forEach} for observation-only iteration.
+ * Evaluation and expansion operate on a deep copy. Equality and relational
+ * predicates compare corresponding elements and return false for a non-Collection
+ * or length mismatch; these component-wise predicates do not define a
+ * lexicographic ordering for heterogeneous values.
+ */
+export declare class Collection extends StructuredEntity<Collection> {
+    /** Runtime type discriminator for collections. */
+    dataType: typeof COLLECTION;
+    /** Live array containing the collection's values. */
+    elements: ParserEntity[];
+    /** Indicates that parser operations may be applied to each element. */
+    isEnumerable: boolean;
+    /** Precision metadata when the collection carries an approximate result. */
+    precision?: number | undefined;
+    /**
+     * Creates a Collection, retaining `elements` when it is supplied.
+     * @param elements - Initial backing array.
+     */
+    constructor(elements?: ParserEntity[]);
+    /**
+     * Returns whether a value is a Collection.
+     * @param obj - Value to test.
+     */
+    static isCollection(obj: unknown): obj is Collection;
+    /**
+     * Returns the element at the given index.
+     * @param indices A single-element array [i]
+     */
+    __get__(indices: number[]): ParserEntity;
+    /**
+     * Sets the element at the given index.
+     * @param indices A single-element array [i]
+     * @param value The value to set
+     */
+    __set__(indices: number[], value: ParserEntity): void;
+    /** Returns the stored entity reference at a zero-based index, or `undefined` when absent. */
+    at(index: number): ParserEntity | undefined;
+    /** Copies the collection and every contained entity. */
+    copy(): Collection;
+    /** Returns the number of values in the collection. */
+    count(): number;
+    /** Returns the collection length as a one-dimensional shape. */
+    dimensions(): number[];
+    /**
+     * Visits or replaces values in ascending index order.
+     *
+     * Returning a ParserEntity replaces the current value. Returning `void` leaves
+     * that value unchanged, so callers can inspect a collection without a dummy return.
+     * Use {@link forEach} when no transformation is intended.
+     *
+     * @param callback - Function receiving each value and index.
+     */
+    each(callback: (a: ParserEntity, b: number) => ParserEntity | void): this;
+    /**
+     * Tests whether another Collection has equal values in the same order.
+     * @param x - Value to compare.
+     */
+    eq(x: ParserEntity): boolean;
+    /** Evaluates a copied collection, leaving this one unchanged. */
+    evaluate(): Collection;
+    /** Expands every value in a copied collection. */
+    expand(): Collection;
+    /** Visits stored entity references without changing the collection. */
+    forEach(callback: (value: ParserEntity, index: number) => void): void;
+    /** Returns the live backing array; mutations to it affect this Collection. */
+    getElements(): ParserEntity[];
+    /**
+     * Tests whether every value is greater than its corresponding value.
+     * @param x - Value to compare.
+     */
+    gt(x: ParserEntity): boolean;
+    /**
+     * Tests component-wise greater-than-or-equal comparison.
+     * @param x - Value to compare.
+     */
+    gte(x: ParserEntity): boolean;
+    /**
+     * Tests whether every value is less than its corresponding value.
+     * @param x - Value to compare.
+     */
+    lt(x: ParserEntity): boolean;
+    /**
+     * Tests component-wise less-than-or-equal comparison.
+     * @param x - Value to compare.
+     */
+    lte(x: ParserEntity): boolean;
+    /** Iterates over the stored entity references in insertion order. */
+    [Symbol.iterator](): Iterator<ParserEntity>;
+    /** Returns the collection in Nerdamer notation. */
+    text(): string;
+    /** Returns a new array containing the stored entity references in insertion order. */
+    toArray(): ParserEntity[];
+}

package/output/core/classes/collection/Collection.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Collection = void 0;
+const StructuredEntity_1 = require("../../common/classes/StructuredEntity");
+const common_1 = require("../../common/common");
+const constants_1 = require("../parser/constants");
+/**
+ * An ordered heterogeneous collection of parser entities.
+ *
+ * @remarks
+ * The constructor retains the supplied array and its element references.
+ * {@link getElements} likewise exposes the live backing array. Use {@link copy}
+ * for an independent collection; it copies every contained parser entity.
+ *
+ * {@link each} and indexed assignment mutate the collection. A callback passed
+ * to `each` may return a replacement value or return nothing to leave the
+ * current value unchanged. Use {@link forEach} for observation-only iteration.
+ * Evaluation and expansion operate on a deep copy. Equality and relational
+ * predicates compare corresponding elements and return false for a non-Collection
+ * or length mismatch; these component-wise predicates do not define a
+ * lexicographic ordering for heterogeneous values.
+ */
+class Collection extends StructuredEntity_1.StructuredEntity {
+    /** Runtime type discriminator for collections. */
+    dataType = constants_1.COLLECTION;
+    /** Live array containing the collection's values. */
+    elements = [];
+    /** Indicates that parser operations may be applied to each element. */
+    isEnumerable = true;
+    /** Precision metadata when the collection carries an approximate result. */
+    precision;
+    /**
+     * Creates a Collection, retaining `elements` when it is supplied.
+     * @param elements - Initial backing array.
+     */
+    constructor(elements) {
+        super();
+        if (elements) {
+            this.elements = elements;
+        }
+        else {
+            this.elements = [];
+        }
+    }
+    /**
+     * Returns whether a value is a Collection.
+     * @param obj - Value to test.
+     */
+    static isCollection(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, constants_1.COLLECTION);
+    }
+    /**
+     * Returns the element at the given index.
+     * @param indices A single-element array [i]
+     */
+    __get__(indices) {
+        const index = indices[0];
+        if (index < 0 || index >= this.elements.length) {
+            throw new RangeError(`Index ${index} out of bounds for Collection of length ${this.elements.length}`);
+        }
+        return this.elements[index];
+    }
+    /**
+     * Sets the element at the given index.
+     * @param indices A single-element array [i]
+     * @param value The value to set
+     */
+    __set__(indices, value) {
+        const index = indices[0];
+        if (index < 0 || index >= this.elements.length) {
+            throw new RangeError(`Index ${index} out of bounds for Collection of length ${this.elements.length}`);
+        }
+        this.elements[index] = value;
+    }
+    /** Returns the stored entity reference at a zero-based index, or `undefined` when absent. */
+    at(index) {
+        return this.elements[index];
+    }
+    /** Copies the collection and every contained entity. */
+    copy() {
+        const copy = new Collection();
+        this.each((e, i) => {
+            copy.elements[i] = e.copy();
+            return e;
+        });
+        return copy;
+    }
+    /** Returns the number of values in the collection. */
+    count() {
+        return this.elements.length;
+    }
+    /** Returns the collection length as a one-dimensional shape. */
+    dimensions() {
+        return [this.elements.length];
+    }
+    /**
+     * Visits or replaces values in ascending index order.
+     *
+     * Returning a ParserEntity replaces the current value. Returning `void` leaves
+     * that value unchanged, so callers can inspect a collection without a dummy return.
+     * Use {@link forEach} when no transformation is intended.
+     *
+     * @param callback - Function receiving each value and index.
+     */
+    each(callback) {
+        for (let i = 0; i < this.elements.length; i++) {
+            const current = this.elements[i];
+            const result = callback(current, i);
+            if (result !== undefined) {
+                this.elements[i] = result;
+            }
+        }
+        return this;
+    }
+    /**
+     * Tests whether another Collection has equal values in the same order.
+     * @param x - Value to compare.
+     */
+    eq(x) {
+        if (!Collection.isCollection(x) || x.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            const a = this.elements[i];
+            const b = x.elements[i];
+            if (!a.eq(b)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Evaluates a copied collection, leaving this one unchanged. */
+    evaluate() {
+        const copy = this.copy();
+        copy.each(e => e.evaluate());
+        return copy;
+    }
+    /** Expands every value in a copied collection. */
+    expand() {
+        const copy = this.copy();
+        copy.each(e => e.expand());
+        return copy;
+    }
+    /** Visits stored entity references without changing the collection. */
+    forEach(callback) {
+        for (let i = 0; i < this.elements.length; i++) {
+            callback(this.elements[i], i);
+        }
+    }
+    /** Returns the live backing array; mutations to it affect this Collection. */
+    getElements() {
+        return this.elements;
+    }
+    /**
+     * Tests whether every value is greater than its corresponding value.
+     * @param x - Value to compare.
+     */
+    gt(x) {
+        if (!Collection.isCollection(x) || x.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            const a = this.elements[i];
+            const b = x.elements[i];
+            if (!a.gt(b)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Tests component-wise greater-than-or-equal comparison.
+     * @param x - Value to compare.
+     */
+    gte(x) {
+        if (!Collection.isCollection(x) || x.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            if (!this.elements[i].gte(x.elements[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Tests whether every value is less than its corresponding value.
+     * @param x - Value to compare.
+     */
+    lt(x) {
+        if (!Collection.isCollection(x) || x.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            const a = this.elements[i];
+            const b = x.elements[i];
+            if (!a.lt(b)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Tests component-wise less-than-or-equal comparison.
+     * @param x - Value to compare.
+     */
+    lte(x) {
+        if (!Collection.isCollection(x) || x.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            if (!this.elements[i].lte(x.elements[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Iterates over the stored entity references in insertion order. */
+    [Symbol.iterator]() {
+        return this.elements[Symbol.iterator]();
+    }
+    /** Returns the collection in Nerdamer notation. */
+    text() {
+        return `(${this.elements.map(e => e.text()).join(', ')})`;
+    }
+    /** Returns a new array containing the stored entity references in insertion order. */
+    toArray() {
+        return [...this.elements];
+    }
+}
+exports.Collection = Collection;

package/output/core/classes/complex/Complex.d.ts

@@ -0,0 +1,99 @@
+import Decimal from 'decimal.js';
+/**
+ * Represents a numerical complex value backed by `decimal.js` components.
+ *
+ * @remarks
+ * This class is a numerical helper used by algorithms such as polynomial root solving. It is
+ * distinct from Nerdamer's symbolic complex expressions: it does not parse expressions, carry
+ * symbolic structure, or implement branch-sensitive transcendental functions. Component
+ * arithmetic follows the active global `decimal.js` precision.
+ *
+ * Arithmetic methods return new `Complex` objects rather than modifying the receiver. The
+ * {@link Complex.re} and {@link Complex.im} fields are public, however, so callers can reassign
+ * components directly.
+ */
+export declare class Complex {
+    /** Imaginary component. */
+    im: Decimal;
+    /** Real component. */
+    re: Decimal;
+    /**
+     * Creates a numerical complex value.
+     *
+     * @remarks
+     * Existing Decimal components are retained by reference; numeric inputs are converted to
+     * new Decimal values. `decimal.js` arithmetic itself returns new Decimal objects.
+     *
+     * @param re - Real component.
+     * @param im - Imaginary component; defaults to zero.
+     */
+    constructor(re: Decimal | number, im?: Decimal | number);
+    /**
+     * Creates a numerical complex value from Decimal or native-number components.
+     *
+     * @param re - Real component.
+     * @param im - Imaginary component; defaults to zero.
+     * @returns A new `Complex` value.
+     */
+    static create(re: Decimal | number, im?: Decimal | number): Complex;
+    /**
+     * Computes the modulus `sqrt(re^2 + im^2)`.
+     *
+     * @returns A new Decimal containing the nonnegative magnitude.
+     */
+    abs(): Decimal;
+    /**
+     * Adds another complex value component-wise.
+     *
+     * @param other - Complex value to add.
+     * @returns A new complex sum.
+     */
+    add(other: Complex): Complex;
+    /**
+     * Returns the complex conjugate `re - im*i`.
+     *
+     * @returns A new complex value with the imaginary component negated.
+     */
+    conjugate(): Complex;
+    /**
+     * Divides this complex value by another using the standard rectangular formula.
+     *
+     * @remarks
+     * Division rejects an exactly zero squared modulus. No numerical tolerance is applied at
+     * this arithmetic layer; iterative algorithms are responsible for choosing any tolerance
+     * appropriate to their convergence logic.
+     *
+     * @param other - Complex divisor.
+     * @returns A new complex quotient.
+     * @throws {@link core!DivisionByZeroError}
+     * Thrown when both components of `other` are exactly zero at the current Decimal value.
+     */
+    div(other: Complex): Complex;
+    /**
+     * Multiplies two rectangular complex values.
+     *
+     * @param other - Complex factor.
+     * @returns A new complex product.
+     */
+    mul(other: Complex): Complex;
+    /**
+     * Returns the additive inverse of this complex value.
+     *
+     * @returns A new complex value with both components negated.
+     */
+    neg(): Complex;
+    /**
+     * Multiplies both complex components by a real scalar.
+     *
+     * @param s - Decimal or native-number scale factor.
+     * @returns A new scaled complex value.
+     */
+    scale(s: Decimal | number): Complex;
+    /**
+     * Subtracts another complex value component-wise.
+     *
+     * @param other - Complex value to subtract.
+     * @returns A new complex difference.
+     */
+    sub(other: Complex): Complex;
+}