nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/classes/dictionary/Dictionary.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Dictionary = void 0;
+const StructuredEntity_1 = require("../../common/classes/StructuredEntity");
+const common_1 = require("../../common/common");
+const errors_1 = require("../../errors");
+const constants_1 = require("../parser/constants");
+/**
+ * A key-value container where keys are strings (variable names) and values
+ * are any ParserEntity. Supports element-wise arithmetic operations.
+ *
+ * @remarks
+ * The optional constructor Map is retained rather than copied. {@link set} and
+ * {@link merge} also retain value references, while {@link copy} copies every
+ * stored parser entity. Arrays returned by {@link keys}, {@link values}, and
+ * {@link entries} are new arrays, but their values still refer to the stored
+ * entities.
+ *
+ * Iteration and text output preserve Map insertion order. Replacing an existing
+ * key does not move it. {@link each} can replace values in place; returning
+ * nothing from its callback leaves a value unchanged. Use {@link forEach} for
+ * observation-only traversal. Evaluation and expansion return deep copies.
+ * Dictionaries support structural equality by key and value but define no
+ * greater-than or less-than ordering.
+ *
+ * Syntax: {x => 1, y => 2, z => x+3}
+ * Access: d[x] → 1, d[y] → 2
+ * Assign: d[y]: 10
+ */
+class Dictionary extends StructuredEntity_1.StructuredEntity {
+    /**
+     * Internal storage. The ordered map preserves insertion order for
+     * deterministic iteration and text output.
+     */
+    _entries = new Map();
+    dataType = constants_1.DICTIONARY;
+    isEnumerable = true;
+    precision;
+    /** Creates a Dictionary, retaining the supplied Map when present. */
+    constructor(entries) {
+        super();
+        if (entries) {
+            this._entries = entries;
+        }
+    }
+    static isDictionary(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, constants_1.DICTIONARY);
+    }
+    /**
+     * Returns the element for the given string key.
+     * Used by the parser for bracket indexing: d[x] → d.getter('x')
+     */
+    __get__(indices) {
+        const key = typeof indices === 'string' ? indices : String(indices[0]);
+        const value = this._entries.get(key);
+        if (value === undefined) {
+            throw new errors_1.UnexpectedDataType(`Key "${key}" not found in Dictionary. Available keys: ${this.keys().join(', ')}`);
+        }
+        return value;
+    }
+    /**
+     * Sets the element for the given string key.
+     * Used by the parser for bracket assignment: d[x]: 5
+     */
+    __set__(indices, value) {
+        const key = typeof indices === 'string' ? indices : String(indices[0]);
+        this._entries.set(key, value);
+    }
+    /** Copies the Dictionary, including every stored value. */
+    copy() {
+        const entries = new Map();
+        for (const [key, value] of this._entries) {
+            entries.set(key, value.copy());
+        }
+        return new Dictionary(entries);
+    }
+    /** Number of entries. */
+    count() {
+        return this._entries.size;
+    }
+    /** Removes a key-value pair. */
+    delete(key) {
+        return this._entries.delete(key);
+    }
+    dimensions() {
+        return [this._entries.size];
+    }
+    /**
+     * Visits or replaces entries in insertion order.
+     *
+     * Returning a ParserEntity replaces the current value. Returning `void` leaves
+     * that value unchanged, so callers can inspect a Dictionary without a dummy return.
+     * The callback receives the value and string key.
+     */
+    each(callback) {
+        for (const [key, value] of this._entries) {
+            const result = callback(value, key);
+            if (result !== undefined) {
+                this._entries.set(key, result);
+            }
+        }
+        return this;
+    }
+    /**
+     * Satisfies the StructuredEntity abstract property.
+     * Returns the values as an array for compatibility with element-wise operations.
+     */
+    get elements() {
+        return [...this._entries.values()];
+    }
+    set elements(values) {
+        // When StructuredEntity.binaryOp calls copy().each(...), the each method
+        // mutates values in place via the keys, so this setter is mainly for
+        // structural compatibility. Rebuild from existing keys.
+        const keys = [...this._entries.keys()];
+        this._entries.clear();
+        for (let i = 0; i < keys.length && i < values.length; i++) {
+            this._entries.set(keys[i], values[i]);
+        }
+    }
+    /**
+     * Returns all entries in insertion order as a new pair array.
+     * Stored value objects are not copied.
+     */
+    entries() {
+        return [...this._entries.entries()];
+    }
+    eq(other) {
+        if (!Dictionary.isDictionary(other)) {
+            return false;
+        }
+        if (this._entries.size !== other._entries.size) {
+            return false;
+        }
+        for (const [key, value] of this._entries) {
+            const otherValue = other._entries.get(key);
+            if (!otherValue || !value.eq(otherValue)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Evaluates a copied Dictionary, leaving this one unchanged. */
+    evaluate() {
+        return this.copy().each(e => e.evaluate());
+    }
+    expand() {
+        const copy = this.copy();
+        copy.each(e => e.expand());
+        return copy;
+    }
+    /** Visits stored value references without changing the Dictionary. */
+    forEach(callback) {
+        for (const [key, value] of this._entries) {
+            callback(value, key);
+        }
+    }
+    /** Gets the stored value reference by key, or `undefined` when absent. */
+    get(key) {
+        return this._entries.get(key);
+    }
+    gt(_other) {
+        return false;
+    }
+    gte(other) {
+        return this.eq(other);
+    }
+    /** Checks if a key exists. */
+    has(key) {
+        return this._entries.has(key);
+    }
+    /** Returns all keys. */
+    keys() {
+        return [...this._entries.keys()];
+    }
+    lt(_other) {
+        return false;
+    }
+    lte(other) {
+        return this.eq(other);
+    }
+    /**
+     * Merges another Dictionary into this one. Existing keys are overwritten and
+     * incoming value references are retained.
+     */
+    merge(other) {
+        for (const [key, value] of other._entries) {
+            this._entries.set(key, value);
+        }
+        return this;
+    }
+    /** Sets a key-value pair by reference and returns this Dictionary. */
+    set(key, value) {
+        this._entries.set(key, value);
+        return this;
+    }
+    /** Iterates over `[key, value]` pairs in insertion order. */
+    [Symbol.iterator]() {
+        return this._entries[Symbol.iterator]();
+    }
+    text() {
+        const pairs = [];
+        for (const [key, value] of this._entries) {
+            pairs.push(`${key} => ${value.text()}`);
+        }
+        return `{${pairs.join(', ')}}`;
+    }
+    /** Returns stored value references in insertion order in a new array. */
+    values() {
+        return [...this._entries.values()];
+    }
+}
+exports.Dictionary = Dictionary;

package/output/core/classes/equation/Equation.d.ts

@@ -0,0 +1,256 @@
+import { Expression } from '../expression/Expression';
+import { EQUATION } from '../parser/constants';
+import type { ExpressionInput, ParserEntity } from '../../types';
+/**
+ * Represents a symbolic equality between two expression sides.
+ *
+ * @remarks
+ * An `Equation` stores its left- and right-hand sides as public {@link Expression}
+ * references. The constructor does not copy those expressions, so mutating a supplied
+ * expression later, or mutating {@link Equation.LHS} or {@link Equation.RHS} directly,
+ * changes the equation. Use {@link Equation.copy} when an independent equation is needed.
+ *
+ * Arithmetic methods apply an operation to both sides, but that does not by itself prove
+ * that the transformed equation has exactly the same solution set. For example, multiplying
+ * or dividing by an expression whose value may be zero requires additional domain reasoning.
+ * Solver-facing code should account for those mathematical conditions.
+ *
+ * Absolute value is not supported as an equation rewrite because applying it
+ * independently to both sides can change the solution set. {@link Equation.abs} remains only
+ * as a compatibility member of the general parser-entity surface and always throws. Callers
+ * performing a non-equivalent transformation can use {@link Equation.each} explicitly.
+ *
+ * Equation comparisons reduce each equation to its residual `LHS - RHS` and then use the
+ * corresponding {@link Expression} comparison. They compare those residual expressions;
+ * they do not establish logical or solution-set equivalence between arbitrary equations.
+ *
+ * @example
+ * ```ts
+ * const equation = new Equation(Expression.create('x + 1'), Expression.create(3));
+ * equation.text(); // "1+x=3"
+ * equation.toLHS().text(); // "-2+x=0"
+ * ```
+ */
+export declare class Equation {
+    /** Parser entity tag used to identify equation values. */
+    dataType: typeof EQUATION;
+    /** Indicates that equations are not elementwise enumerable parser aggregates. */
+    isEnumerable: boolean;
+    /** Mutable left-hand side expression stored by this equation. */
+    LHS: Expression;
+    /**
+     * Optional parser-entity precision metadata.
+     *
+     * `Equation` itself does not currently use this value when performing equation
+     * operations or formatting its sides.
+     */
+    precision?: number | undefined;
+    /** Mutable right-hand side expression stored by this equation. */
+    RHS: Expression;
+    /**
+     * Creates an equation from two expression objects.
+     *
+     * @remarks
+     * The supplied expressions are stored by reference rather than copied. This preserves
+     * object identity but also means subsequent mutation of either expression is visible
+     * through the equation.
+     *
+     * @param lhs - Expression to store on the left-hand side.
+     * @param rhs - Expression to store on the right-hand side.
+     */
+    constructor(lhs: Expression, rhs: Expression);
+    /**
+     * Tests whether a value carries Nerdamer's equation parser-entity tag.
+     *
+     * @remarks
+     * This is a tag-based type guard rather than an `instanceof` check. It therefore
+     * recognizes compatible equation objects by their `dataType` value.
+     *
+     * @param obj - Value to inspect.
+     * @returns `true` when the value is tagged as an equation.
+     */
+    static isEquation(obj: unknown): obj is Equation;
+    /**
+     * Rejects absolute value as an equation transformation.
+     *
+     * @remarks
+     * Replacing `a = b` with `|a| = |b|` is not generally solution-set preserving. This
+     * method remains on `Equation` so the general {@link ParserEntity} surface can retain
+     * its historical `abs()` member without reintroducing the unsafe transformation.
+     *
+     * Use {@link Equation.each} explicitly to transform
+     * each side and accepts responsibility for the changed equation semantics.
+     *
+     * @throws {@link core!UnsupportedOperationError} Always; absolute value is not a supported
+     * equation operation.
+     * @deprecated Absolute value is not supported for equations.
+     */
+    abs(): Equation;
+    /**
+     * Legacy alias for {@link Equation.plus}.
+     *
+     * @param x - Value to add to both sides.
+     * @returns A new equation; the current equation is not modified.
+     */
+    add(x: ExpressionInput): Equation;
+    /**
+     * Creates an independent copy of this equation and both expression sides.
+     *
+     * @returns A new equation whose left- and right-hand expressions are deep copies.
+     */
+    copy(): Equation;
+    /**
+     * Divides both sides by the same nonzero number.
+     *
+     * A symbolic divisor is rejected because Nerdamer cannot assume that it is nonzero for
+     * every solution of the equation.
+     *
+     * @param x - Nonzero numeric value by which both sides are divided.
+     * @returns A new equation; the current equation is not modified.
+     * @throws {@link core!UnsupportedOperationError} If `x` is zero or is not numeric.
+     */
+    div(x: ExpressionInput): Equation;
+    /**
+     * Applies a callback to the two equation sides and rebuilds the equation from its results.
+     *
+     * @remarks
+     * The callback receives the stored left- and right-hand {@link Expression} references
+     * directly, with indices `0` and `1` respectively. Returned expressions are stored by
+     * reference in a new equation. The callback can therefore mutate the original equation
+     * if it mutates either argument before returning.
+     *
+     * Both callback results must be expressions. Other parser entities are rejected after
+     * the callback has run.
+     *
+     * @param fn - Transformation applied to the left and right sides.
+     * @returns A new equation containing the callback results.
+     * @throws {@link core!UnexpectedDataType}
+     * Thrown when either callback result is not an {@link Expression}.
+     */
+    each(fn: (e: ParserEntity, i?: number | string) => ParserEntity): Equation;
+    /**
+     * Compares this equation with another equation by comparing their residual expressions.
+     *
+     * @remarks
+     * Each equation is copied and rewritten as `LHS - RHS = 0`, then the two residual
+     * expressions are compared with {@link Expression.eq}. Equations with the same
+     * solution set are not necessarily equal by this method; for example, scaling an
+     * equation by a nonzero constant changes its residual expression.
+     *
+     * @param eq - Parser entity to compare with this equation.
+     * @returns `true` when `eq` is an equation and the two residual expressions compare equal.
+     */
+    eq(eq: ParserEntity): boolean;
+    /**
+     * Numerically re-evaluates both equation sides.
+     *
+     * @returns A new equation containing evaluated copies of the two sides.
+     */
+    evaluate(): Equation;
+    /**
+     * Expands both sides of a copied equation.
+     *
+     * @returns A new equation containing the expanded left- and right-hand sides.
+     */
+    expand(): Equation;
+    /**
+     * Orders this equation against another equation by comparing their residual expressions.
+     *
+     * @remarks
+     * Both equations are rewritten as `LHS - RHS = 0`, and the resulting expressions are
+     * compared with {@link Expression.gt}. This is an ordering of residual expressions,
+     * not a statement that one equation or solution set is logically greater than another.
+     *
+     * @param eq - Parser entity to compare with this equation.
+     * @returns `true` when `eq` is an equation and this residual compares greater.
+     */
+    gt(eq: ParserEntity): boolean;
+    /**
+     * Residual-expression comparison corresponding to `>=`.
+     *
+     * @param x - Parser entity to compare with this equation.
+     * @returns `true` when {@link Equation.gt} or {@link Equation.eq} succeeds.
+     */
+    gte(x: ParserEntity): boolean;
+    /**
+     * Orders this equation against another equation by comparing their residual expressions.
+     *
+     * @remarks
+     * Both equations are rewritten as `LHS - RHS = 0`, and the resulting expressions are
+     * compared with {@link Expression.lt}. This is an ordering of residual expressions,
+     * not a statement that one equation or solution set is logically less than another.
+     *
+     * @param eq - Parser entity to compare with this equation.
+     * @returns `true` when `eq` is an equation and this residual compares less.
+     */
+    lt(eq: ParserEntity): boolean;
+    /**
+     * Residual-expression comparison corresponding to `<=`.
+     *
+     * @param x - Parser entity to compare with this equation.
+     * @returns `true` when {@link Equation.lt} or {@link Equation.eq} succeeds.
+     */
+    lte(x: ParserEntity): boolean;
+    /**
+     * Subtracts the same value from both sides.
+     *
+     * @param x - Value to subtract from the left- and right-hand sides.
+     * @returns A new equation; the current equation is not modified.
+     */
+    minus(x: ExpressionInput): Equation;
+    /**
+     * Legacy alias for {@link Equation.times}.
+     *
+     * @param x - Nonzero numeric value by which both sides are multiplied.
+     * @returns This equation after mutation.
+     */
+    multiply(x: ExpressionInput): Equation;
+    /**
+     * Adds the same value to both sides.
+     *
+     * @param x - Value to add to the left- and right-hand sides.
+     * @returns A new equation; the current equation is not modified.
+     */
+    plus(x: ExpressionInput): Equation;
+    /**
+     * Legacy alias for {@link Equation.minus}.
+     *
+     * @param x - Value to subtract from both sides.
+     * @returns A new equation; the current equation is not modified.
+     */
+    subtract(x: ExpressionInput): Equation;
+    /**
+     * Returns the canonical text form `LHS=RHS`.
+     *
+     * @returns The two side representations joined by `=`.
+     */
+    text(): string;
+    /**
+     * Multiplies both sides by the same nonzero number.
+     *
+     * A symbolic multiplier is rejected because it may be zero for some solutions and add
+     * solutions that were not present in the original equation.
+     *
+     * @param x - Nonzero numeric value by which both sides are multiplied.
+     * @returns This equation after mutation.
+     * @throws {@link core!UnsupportedOperationError} If `x` is zero or is not numeric.
+     */
+    times(x: ExpressionInput): Equation;
+    /**
+     * Rewrites this equation as an equivalent residual form with zero on the right.
+     *
+     * @remarks
+     * The equation and both sides are copied before `RHS` is subtracted from `LHS`, so the
+     * current equation is not modified. The result has the form `LHS - RHS = 0` and is used
+     * by solver preparation and the equation comparison methods.
+     *
+     * @returns A new equation with the residual expression on the left and zero on the right.
+     */
+    toLHS(): Equation;
+    /**
+     * Returns the same canonical equation text as {@link Equation.text}.
+     *
+     * @returns The equation text representation.
+     */
+    toString(): string;
+}