@johnhenry/math 0.0.0

package/src/Decimal.ts

@@ -0,0 +1,145 @@
+/**
+ * Decimal — an arbitrary-precision decimal number `digits × 10^exponent`,
+ * backed by `bigint`. Addition/subtraction/multiplication are exact (unlike
+ * `number`, which drifts on values like `0.1 + 0.2`); division is inherently
+ * approximate and rounds to a configurable number of significant digits — an
+ * honest limitation analogous to floats, just with configurable precision
+ * instead of a fixed 53 bits.
+ *
+ * Unlike {@link Rational}, no canonical/normalized form is maintained —
+ * equality and comparison work by aligning exponents rather than requiring
+ * reduced digits, which keeps arithmetic simple at the cost of `toString()`
+ * not collapsing trailing zeros introduced by intermediate computations.
+ */
+
+const digitCount = (n: bigint): number => (n < 0n ? -n : n).toString().length;
+
+/** Round `num / den` to the nearest integer (half away from zero), for any sign combination. */
+function divRound(num: bigint, den: bigint): bigint {
+  const q = num / den;
+  const r = num % den;
+  if (r === 0n) return q;
+  const doubledR = (r < 0n ? -r : r) * 2n;
+  const absDen = den < 0n ? -den : den;
+  if (doubledR >= absDen) {
+    const sameSign = num < 0n === den < 0n;
+    return sameSign ? q + 1n : q - 1n;
+  }
+  return q;
+}
+
+export class Decimal {
+  static readonly DEFAULT_PRECISION = 20;
+
+  readonly digits: bigint;
+  readonly exponent: number;
+
+  static readonly Zero = new Decimal(0n, 0);
+  static readonly One = new Decimal(1n, 0);
+
+  constructor(digits: bigint = 0n, exponent = 0) {
+    this.digits = digits;
+    this.exponent = exponent;
+  }
+
+  static fromString(value: string): Decimal {
+    const match = /^\s*([+-]?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?\s*$/.exec(value);
+    if (!match) throw new Error(`Invalid Decimal string: ${value}`);
+    const [, sign, intPart, fracPart = "", expPart] = match;
+    const digits = BigInt((sign === "-" ? "-" : "") + intPart + fracPart);
+    const exponent = -fracPart.length + (expPart ? Number(expPart) : 0);
+    return new Decimal(digits, exponent);
+  }
+
+  static from(value: Decimal | bigint | number | string): Decimal {
+    if (value instanceof Decimal) return value;
+    if (typeof value === "bigint") return new Decimal(value, 0);
+    if (typeof value === "number") {
+      if (!Number.isFinite(value)) throw new Error("Cannot make a Decimal from a non-finite number.");
+      return Decimal.fromString(value.toString());
+    }
+    return Decimal.fromString(value);
+  }
+
+  /** Rescale `a` and `b` to a shared exponent (the smaller of the two). */
+  private static align(a: Decimal, b: Decimal): { ad: bigint; bd: bigint; exponent: number } {
+    const exponent = Math.min(a.exponent, b.exponent);
+    const ad = a.digits * 10n ** BigInt(a.exponent - exponent);
+    const bd = b.digits * 10n ** BigInt(b.exponent - exponent);
+    return { ad, bd, exponent };
+  }
+
+  add(other: Decimal): Decimal {
+    const { ad, bd, exponent } = Decimal.align(this, other);
+    return new Decimal(ad + bd, exponent);
+  }
+
+  subtract(other: Decimal): Decimal {
+    const { ad, bd, exponent } = Decimal.align(this, other);
+    return new Decimal(ad - bd, exponent);
+  }
+
+  multiply(other: Decimal): Decimal {
+    return new Decimal(this.digits * other.digits, this.exponent + other.exponent);
+  }
+
+  /** Division is approximate: the result is rounded to `precision` significant digits. */
+  divide(other: Decimal, precision = Decimal.DEFAULT_PRECISION): Decimal {
+    if (other.digits === 0n) throw new Error("Division by zero Decimal.");
+    if (this.digits === 0n) return Decimal.Zero;
+    const shift = Math.max(0, precision - digitCount(this.digits) + digitCount(other.digits));
+    const scaledNumerator = this.digits * 10n ** BigInt(shift);
+    const quotient = divRound(scaledNumerator, other.digits);
+    return new Decimal(quotient, this.exponent - other.exponent - shift);
+  }
+
+  negate(): Decimal {
+    return new Decimal(-this.digits, this.exponent);
+  }
+
+  abs(): Decimal {
+    return this.digits < 0n ? this.negate() : this;
+  }
+
+  equals(other: Decimal): boolean {
+    const { ad, bd } = Decimal.align(this, other);
+    return ad === bd;
+  }
+
+  /** -1, 0 or 1 depending on ordering against `other`. */
+  compare(other: Decimal): number {
+    const { ad, bd } = Decimal.align(this, other);
+    return ad < bd ? -1 : ad > bd ? 1 : 0;
+  }
+
+  lessThan(other: Decimal): boolean {
+    return this.compare(other) < 0;
+  }
+
+  isZero(): boolean {
+    return this.digits === 0n;
+  }
+
+  toNumber(): number {
+    return Number(this.digits) * 10 ** this.exponent;
+  }
+
+  /**
+   * Renders in plain decimal notation. Trailing fractional zeros are trimmed
+   * for readability — this is purely presentational; no canonical form is
+   * maintained internally, so `digits`/`exponent` are untouched.
+   */
+  toString(): string {
+    if (this.digits === 0n) return "0";
+    const negative = this.digits < 0n;
+    let s = (negative ? -this.digits : this.digits).toString();
+    if (this.exponent >= 0) {
+      s = s + "0".repeat(this.exponent);
+    } else {
+      const pointPos = s.length + this.exponent;
+      s = pointPos <= 0 ? `0.${"0".repeat(-pointPos)}${s}` : `${s.slice(0, pointPos)}.${s.slice(pointPos)}`;
+      if (s.includes(".")) s = s.replace(/0+$/, "").replace(/\.$/, "");
+    }
+    return negative ? `-${s}` : s;
+  }
+}

package/src/Distributions.ts

@@ -0,0 +1,269 @@
+import { SpecialFunctions as SF } from "./SpecialFunctions.ts";
+
+/**
+ * Distributions — common probability distributions (continuous and discrete),
+ * each exposing `pdf`/`pmf`, `cdf`, `mean`, `variance` and a random `sample`,
+ * plus a small suite of {@link HypothesisTests}. CDFs use the exact incomplete
+ * gamma/beta functions from {@link SpecialFunctions} rather than numeric
+ * integration, so they are accurate in the tails.
+ *
+ * Every factory takes an optional trailing `rng: () => number` (default
+ * `Math.random`), threaded through to every nested distribution it samples
+ * from — pass a seeded generator to make `sample()` deterministic in tests.
+ */
+
+export interface ContinuousDistribution {
+  pdf(x: number): number;
+  cdf(x: number): number;
+  mean(): number;
+  variance(): number;
+  sample(): number;
+}
+
+export interface DiscreteDistribution {
+  pmf(k: number): number;
+  cdf(k: number): number;
+  mean(): number;
+  variance(): number;
+  sample(): number;
+}
+
+/** The inverse standard-normal CDF (Acklam's rational approximation). */
+function normInv(p: number): number {
+  if (p <= 0) return Number.NEGATIVE_INFINITY;
+  if (p >= 1) return Number.POSITIVE_INFINITY;
+  const a = [
+    -3.969683028665376e1, 2.209460984245205e2, -2.759285104469687e2, 1.38357751867269e2, -3.066479806614716e1,
+    2.506628277459239,
+  ];
+  const b = [
+    -5.447609879822406e1, 1.615858368580409e2, -1.556989798598866e2, 6.680131188771972e1, -1.328068155288572e1,
+  ];
+  const c = [
+    -7.784894002430293e-3, -3.223964580411365e-1, -2.400758277161838, -2.549732539343734, 4.374664141464968,
+    2.938163982698783,
+  ];
+  const d = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996, 3.754408661907416];
+  const plow = 0.02425;
+  const phigh = 1 - plow;
+  if (p < plow) {
+    const q = Math.sqrt(-2 * Math.log(p));
+    return (
+      (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+      ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
+    );
+  }
+  if (p <= phigh) {
+    const q = p - 0.5;
+    const r = q * q;
+    return (
+      ((((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q) /
+      (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1)
+    );
+  }
+  const q = Math.sqrt(-2 * Math.log(1 - p));
+  return (
+    -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+    ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
+  );
+}
+
+export class Distributions {
+  /** The inverse standard-normal CDF (quantile / probit function). */
+  static normalQuantile(p: number, mean = 0, sd = 1): number {
+    return mean + sd * normInv(p);
+  }
+
+  static normal(mean = 0, sd = 1, rng: () => number = Math.random): ContinuousDistribution {
+    return {
+      pdf: (x) => Math.exp(-0.5 * ((x - mean) / sd) ** 2) / (sd * Math.sqrt(2 * Math.PI)),
+      cdf: (x) => 0.5 * SF.erfc(-(x - mean) / (sd * Math.SQRT2)),
+      mean: () => mean,
+      variance: () => sd * sd,
+      sample: () => mean + sd * Math.sqrt(-2 * Math.log(1 - rng())) * Math.cos(2 * Math.PI * rng()),
+    };
+  }
+
+  static exponential(rate = 1, rng: () => number = Math.random): ContinuousDistribution {
+    return {
+      pdf: (x) => (x < 0 ? 0 : rate * Math.exp(-rate * x)),
+      cdf: (x) => (x < 0 ? 0 : 1 - Math.exp(-rate * x)),
+      mean: () => 1 / rate,
+      variance: () => 1 / (rate * rate),
+      sample: () => -Math.log(1 - rng()) / rate,
+    };
+  }
+
+  static uniform(a = 0, b = 1, rng: () => number = Math.random): ContinuousDistribution {
+    return {
+      pdf: (x) => (x >= a && x <= b ? 1 / (b - a) : 0),
+      cdf: (x) => (x < a ? 0 : x > b ? 1 : (x - a) / (b - a)),
+      mean: () => (a + b) / 2,
+      variance: () => (b - a) ** 2 / 12,
+      sample: () => a + rng() * (b - a),
+    };
+  }
+
+  static gamma(shape: number, scale = 1, rng: () => number = Math.random): ContinuousDistribution {
+    return {
+      pdf: (x) => (x <= 0 ? 0 : (x ** (shape - 1) * Math.exp(-x / scale)) / (SF.gamma(shape) * scale ** shape)),
+      cdf: (x) => (x <= 0 ? 0 : SF.regularizedGammaP(shape, x / scale)),
+      mean: () => shape * scale,
+      variance: () => shape * scale * scale,
+      sample: () => Distributions.sampleGamma(shape, rng) * scale,
+    };
+  }
+
+  static chiSquare(df: number, rng: () => number = Math.random): ContinuousDistribution {
+    const g = Distributions.gamma(df / 2, 2, rng);
+    return { ...g, mean: () => df, variance: () => 2 * df };
+  }
+
+  static studentT(df: number, rng: () => number = Math.random): ContinuousDistribution {
+    const c = SF.gamma((df + 1) / 2) / (Math.sqrt(df * Math.PI) * SF.gamma(df / 2));
+    return {
+      pdf: (x) => c * (1 + (x * x) / df) ** (-(df + 1) / 2),
+      cdf: (x) => {
+        const ib = SF.regularizedIncompleteBeta(df / (df + x * x), df / 2, 0.5);
+        return x >= 0 ? 1 - 0.5 * ib : 0.5 * ib;
+      },
+      mean: () => (df > 1 ? 0 : Number.NaN),
+      variance: () => (df > 2 ? df / (df - 2) : Number.POSITIVE_INFINITY),
+      sample: () => {
+        const z = Distributions.normal(0, 1, rng).sample();
+        const chi = Distributions.chiSquare(df, rng).sample();
+        return z / Math.sqrt(chi / df);
+      },
+    };
+  }
+
+  static binomial(n: number, p: number, rng: () => number = Math.random): DiscreteDistribution {
+    const logChoose = (k: number) => SF.lnGamma(n + 1) - SF.lnGamma(k + 1) - SF.lnGamma(n - k + 1);
+    const pmf = (k: number): number =>
+      k < 0 || k > n || !Number.isInteger(k) ? 0 : Math.exp(logChoose(k) + k * Math.log(p) + (n - k) * Math.log(1 - p));
+    return {
+      pmf,
+      cdf: (k) => {
+        // Reuse the single pmf closure above instead of rebuilding a whole new
+        // binomial distribution (and its logChoose closure) on every step.
+        let s = 0;
+        for (let i = 0; i <= Math.floor(k); i++) s += pmf(i);
+        return Math.min(1, s);
+      },
+      mean: () => n * p,
+      variance: () => n * p * (1 - p),
+      sample: () => {
+        let count = 0;
+        for (let i = 0; i < n; i++) if (rng() < p) count++;
+        return count;
+      },
+    };
+  }
+
+  static poisson(lambda: number, rng: () => number = Math.random): DiscreteDistribution {
+    return {
+      pmf: (k) => (k < 0 || !Number.isInteger(k) ? 0 : Math.exp(k * Math.log(lambda) - lambda - SF.lnGamma(k + 1))),
+      cdf: (k) => (k < 0 ? 0 : SF.regularizedGammaQ(Math.floor(k) + 1, lambda)),
+      mean: () => lambda,
+      variance: () => lambda,
+      sample: () => {
+        const L = Math.exp(-lambda);
+        let k = 0;
+        let prod = 1;
+        do {
+          k++;
+          prod *= rng();
+        } while (prod > L);
+        return k - 1;
+      },
+    };
+  }
+
+  /** Marsaglia-Tsang gamma sampler (shape ≥ 0). */
+  private static sampleGamma(shape: number, rng: () => number = Math.random): number {
+    if (shape < 1) return Distributions.sampleGamma(shape + 1, rng) * rng() ** (1 / shape);
+    const d = shape - 1 / 3;
+    const c = 1 / Math.sqrt(9 * d);
+    for (;;) {
+      let x: number;
+      let v: number;
+      do {
+        x = Distributions.normal(0, 1, rng).sample();
+        v = 1 + c * x;
+      } while (v <= 0);
+      v = v * v * v;
+      const u = rng();
+      if (u < 1 - 0.0331 * x ** 4) return d * v;
+      if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v))) return d * v;
+    }
+  }
+}
+
+export interface TestResult {
+  statistic: number;
+  df: number;
+  pValue: number;
+}
+
+export class HypothesisTests {
+  /** One-sample two-tailed Student t-test against a hypothesised mean `mu0`. */
+  static tTestOneSample(sample: number[], mu0 = 0): TestResult {
+    const n = sample.length;
+    const mean = sample.reduce((a, b) => a + b, 0) / n;
+    const variance = sample.reduce((acc, x) => acc + (x - mean) ** 2, 0) / (n - 1);
+    const se = Math.sqrt(variance / n);
+    const t = (mean - mu0) / se;
+    const df = n - 1;
+    const p = 2 * (1 - Distributions.studentT(df).cdf(Math.abs(t)));
+    return { statistic: t, df, pValue: p };
+  }
+
+  /** Welch's two-sample t-test (unequal variances). */
+  static tTestTwoSample(a: number[], b: number[]): TestResult {
+    const na = a.length;
+    const nb = b.length;
+    const ma = a.reduce((s, x) => s + x, 0) / na;
+    const mb = b.reduce((s, x) => s + x, 0) / nb;
+    const va = a.reduce((s, x) => s + (x - ma) ** 2, 0) / (na - 1);
+    const vb = b.reduce((s, x) => s + (x - mb) ** 2, 0) / (nb - 1);
+    const se = Math.sqrt(va / na + vb / nb);
+    const t = (ma - mb) / se;
+    const df = (va / na + vb / nb) ** 2 / ((va / na) ** 2 / (na - 1) + (vb / nb) ** 2 / (nb - 1));
+    const p = 2 * (1 - Distributions.studentT(df).cdf(Math.abs(t)));
+    return { statistic: t, df, pValue: p };
+  }
+
+  /** Pearson chi-square goodness-of-fit test. */
+  static chiSquareGoodnessOfFit(observed: number[], expected: number[]): TestResult {
+    const chi2 = observed.reduce((s, o, i) => s + (o - expected[i]) ** 2 / expected[i], 0);
+    const df = observed.length - 1;
+    const p = 1 - Distributions.chiSquare(df).cdf(chi2);
+    return { statistic: chi2, df, pValue: p };
+  }
+
+  /** Confidence interval for the mean of a sample at the given level (t-based). */
+  static confidenceIntervalMean(sample: number[], level = 0.95): [number, number] {
+    const n = sample.length;
+    const m = sample.reduce((a, b) => a + b, 0) / n;
+    const variance = sample.reduce((acc, x) => acc + (x - m) ** 2, 0) / (n - 1);
+    const se = Math.sqrt(variance / n);
+    const alpha = 1 - level;
+    const tCrit = tQuantile(1 - alpha / 2, n - 1);
+    return [m - tCrit * se, m + tCrit * se];
+  }
+}
+
+// -- small internal helpers -------------------------------------------------
+
+/** Quantile of Student-t via bisection on its CDF. */
+function tQuantile(p: number, df: number): number {
+  const dist = Distributions.studentT(df);
+  let lo = -100;
+  let hi = 100;
+  for (let i = 0; i < 200; i++) {
+    const mid = (lo + hi) / 2;
+    if (dist.cdf(mid) < p) lo = mid;
+    else hi = mid;
+  }
+  return (lo + hi) / 2;
+}

package/src/DualNumber.ts

@@ -0,0 +1,105 @@
+/**
+ * DualNumber — a number of the form `value + deriv·ε` where `ε² = 0`. Evaluating
+ * a function on a dual number carries its derivative along automatically (the
+ * `ε` component), giving exact forward-mode automatic differentiation — more
+ * accurate than the finite differences in {@link RealMath.differentiateN}.
+ *
+ * It is also a commutative ring (a valid {@link Structure}).
+ */
+export class DualNumber {
+  readonly value: number;
+  readonly deriv: number;
+
+  constructor(value = 0, deriv = 0) {
+    this.value = value;
+    this.deriv = deriv;
+  }
+
+  /** A constant (zero derivative). */
+  static constant(x: number): DualNumber {
+    return new DualNumber(x, 0);
+  }
+
+  /** An independent variable at `x` (unit derivative). */
+  static variable(x: number): DualNumber {
+    return new DualNumber(x, 1);
+  }
+
+  private static lift(x: DualNumber | number): DualNumber {
+    return x instanceof DualNumber ? x : new DualNumber(x, 0);
+  }
+
+  add(o: DualNumber | number): DualNumber {
+    const d = DualNumber.lift(o);
+    return new DualNumber(this.value + d.value, this.deriv + d.deriv);
+  }
+
+  subtract(o: DualNumber | number): DualNumber {
+    const d = DualNumber.lift(o);
+    return new DualNumber(this.value - d.value, this.deriv - d.deriv);
+  }
+
+  multiply(o: DualNumber | number): DualNumber {
+    const d = DualNumber.lift(o);
+    return new DualNumber(this.value * d.value, this.value * d.deriv + this.deriv * d.value);
+  }
+
+  divide(o: DualNumber | number): DualNumber {
+    const d = DualNumber.lift(o);
+    return new DualNumber(this.value / d.value, (this.deriv * d.value - this.value * d.deriv) / (d.value * d.value));
+  }
+
+  negate(): DualNumber {
+    return new DualNumber(-this.value, -this.deriv);
+  }
+
+  /** Raise to a constant power (chain rule). */
+  pow(n: number): DualNumber {
+    return new DualNumber(this.value ** n, n * this.value ** (n - 1) * this.deriv);
+  }
+
+  static sin(x: DualNumber): DualNumber {
+    return new DualNumber(Math.sin(x.value), Math.cos(x.value) * x.deriv);
+  }
+  static cos(x: DualNumber): DualNumber {
+    return new DualNumber(Math.cos(x.value), -Math.sin(x.value) * x.deriv);
+  }
+  static tan(x: DualNumber): DualNumber {
+    const c = Math.cos(x.value);
+    return new DualNumber(Math.tan(x.value), x.deriv / (c * c));
+  }
+  static exp(x: DualNumber): DualNumber {
+    const e = Math.exp(x.value);
+    return new DualNumber(e, e * x.deriv);
+  }
+  static log(x: DualNumber): DualNumber {
+    return new DualNumber(Math.log(x.value), x.deriv / x.value);
+  }
+  static sqrt(x: DualNumber): DualNumber {
+    const s = Math.sqrt(x.value);
+    return new DualNumber(s, x.deriv / (2 * s));
+  }
+
+  /** The derivative of `f` at `x`, evaluated exactly via dual numbers. */
+  static derivative(f: (x: DualNumber) => DualNumber, x: number): number {
+    return f(DualNumber.variable(x)).deriv;
+  }
+
+  /** The value and derivative of `f` at `x` together. */
+  static valueAndDerivative(f: (x: DualNumber) => DualNumber, x: number): { value: number; derivative: number } {
+    const r = f(DualNumber.variable(x));
+    return { value: r.value, derivative: r.deriv };
+  }
+
+  /** The gradient of a multivariate `f` at `point` (one dual seed per coordinate). */
+  static gradient(f: (xs: DualNumber[]) => DualNumber, point: number[]): number[] {
+    return point.map((_, i) => {
+      const seeded = point.map((v, j) => new DualNumber(v, i === j ? 1 : 0));
+      return f(seeded).deriv;
+    });
+  }
+
+  toString(): string {
+    return `${this.value} + ${this.deriv}ε`;
+  }
+}

package/src/Environment.ts

@@ -0,0 +1,127 @@
+/**
+ * Environment — a symbol table mapping string keys to values, with a separate
+ * pool of immutable bindings. Used by {@link StringEvaluator} and
+ * {@link Expression} to resolve variables and functions.
+ *
+ * Ported from Mallory's ActionScript `Enviornment` (the original class name was
+ * misspelled; corrected here). Deep-clone via Flash `ByteArray` serialisation is
+ * replaced with an ordinary entry copy — values are treated as immutable data.
+ */
+export class Environment {
+  private _items = new Map<string, unknown>();
+  private _immutableItems = new Map<string, unknown>();
+
+  /**
+   * Each consecutive pair of arguments `(key, value)` becomes an immutable
+   * binding. A trailing unpaired argument is ignored.
+   */
+  constructor(...rest: unknown[]) {
+    if (rest.length % 2 === 1) rest.pop();
+    for (let i = 0; i < rest.length; i += 2) {
+      if (typeof rest[i] === "string") this.assignImmutable(rest[i] as string, rest[i + 1]);
+    }
+  }
+
+  existKey(request: string): boolean {
+    return this._immutableItems.has(request) || this._items.has(request);
+  }
+
+  existImmutableKey(request: string): boolean {
+    return this._immutableItems.has(request);
+  }
+
+  existValue(request: unknown): boolean {
+    for (const v of this._immutableItems.values()) if (v === request) return true;
+    for (const v of this._items.values()) if (v === request) return true;
+    return false;
+  }
+
+  toString(showImmutable = true, showRest = true): string {
+    const result: string[] = [];
+    if (showImmutable) for (const [k, v] of this._immutableItems) result.push(`${k} : ${v}`);
+    if (showRest) for (const [k, v] of this._items) result.push(`${k} : ${v}`);
+    return `{${result.join(" ; ")}}`;
+  }
+
+  /** A copy of the environment (bindings are shared by reference). */
+  clone(): Environment {
+    const out = new Environment();
+    out._items = new Map(this._items);
+    out._immutableItems = new Map(this._immutableItems);
+    return out;
+  }
+
+  get size(): number {
+    return this._items.size + this._immutableItems.size;
+  }
+
+  get keys(): string[] {
+    return [...this._immutableItems.keys(), ...this._items.keys()];
+  }
+
+  get immutableKeys(): string[] {
+    return [...this._immutableItems.keys()];
+  }
+
+  get values(): unknown[] {
+    return [...this._immutableItems.values(), ...this._items.values()];
+  }
+
+  /** Bind `key` to `value`. Assigning `undefined` (or the key to itself) removes it. */
+  assign(key: string, value?: unknown): boolean {
+    if (value === undefined || (key as unknown) === value) return this.remove(key);
+    if (this.existImmutableKey(key)) return false;
+    this._items.set(key, value);
+    return true;
+  }
+
+  /** Bind `key` immutably. Fails if the key already exists in either pool. */
+  assignImmutable(key: string, value?: unknown): boolean {
+    if (value === undefined || (key as unknown) === value) return this.remove(key);
+    if (this.existKey(key)) return false;
+    this._immutableItems.set(key, value);
+    return true;
+  }
+
+  /** Bind `key` to `value` after first resolving `value` in this environment. */
+  assignDeep(key: string, value: string): boolean {
+    return this.assign(key, this.retrieveDeep(value));
+  }
+
+  assignImmutableDeep(key: string, value: string): boolean {
+    return this.assignImmutable(key, this.retrieveDeep(value));
+  }
+
+  /** Look up `key`; an unknown key resolves to itself (symbolic passthrough). */
+  retrieve(key: string): unknown {
+    if (!this.existKey(key)) return key;
+    if (this.existImmutableKey(key)) return this._immutableItems.get(key);
+    return this._items.get(key);
+  }
+
+  /** Follow chains of string references to the deepest concrete value. */
+  retrieveDeep(key: string): unknown {
+    let previous = this.retrieve(key);
+    // <= (not <): the initial `retrieve` above already consumes one lookup
+    // that isn't tied to a loop iteration, so even an empty environment
+    // (size 0) must still get one pass to notice `previous === key` and
+    // return the symbolic passthrough instead of falling through below.
+    for (let i = 0; i <= this.size; i++) {
+      if (previous === key) return key;
+      if (typeof previous !== "string" || previous === this.retrieve(previous)) return previous;
+      previous = this.retrieve(previous);
+    }
+    return undefined;
+  }
+
+  /** Remove a mutable binding (immutable ones cannot be removed). */
+  remove(key: string): boolean {
+    if (this.existImmutableKey(key)) return false;
+    return this._items.delete(key);
+  }
+
+  /** Remove an immutable binding (for debugging; normally you should not). */
+  removeImmutable(key: string): boolean {
+    return this._immutableItems.delete(key);
+  }
+}

package/src/Expression.ts

@@ -0,0 +1,48 @@
+import { Environment } from "./Environment.ts";
+import { StringEvaluator } from "./StringEvaluator.ts";
+
+/**
+ * Expression — a named formula over a list of independent variables, evaluated
+ * by substituting values and delegating to {@link StringEvaluator}. Ported from
+ * Mallory's ActionScript `Expression`. (The dead `mx.messaging` import is dropped.)
+ */
+export class Expression {
+  private readonly _representation: string;
+  private readonly _indeVars: string[];
+
+  constructor(representation: unknown = "", independentVariables: string[] | null = null) {
+    this._representation = String(representation);
+    this._indeVars = independentVariables ?? [];
+  }
+
+  indeVarString(): string {
+    return this._indeVars.join(",");
+  }
+
+  toString(expanded = true, name = "function"): string {
+    if (expanded) return `${name}(${this.indeVarString()})=${this._representation}`;
+    return this._representation;
+  }
+
+  /**
+   * Evaluate the expression. `values` are bound to the independent variables
+   * (in order); an outer `environment` supplies everything else.
+   */
+  evaluate(values: unknown = null, environment: Environment | null = null): unknown {
+    const args = Array.isArray(values) ? values : [values];
+
+    if (environment === null) {
+      const subEnvironment = new Environment();
+      for (let i = 0; i < this._indeVars.length; i++) {
+        subEnvironment.assign(this._indeVars[i] as string, args[i]);
+      }
+      return StringEvaluator.evaluate(this._representation, subEnvironment);
+    }
+
+    const subEnvironment = environment.clone();
+    for (let i = 0; i < this._indeVars.length; i++) {
+      subEnvironment.assign(this._indeVars[i] as string, args[i]);
+    }
+    return StringEvaluator.evaluate(StringEvaluator.evaluate(this._representation, subEnvironment), environment);
+  }
+}