arch: cleanup round, with more helper functions, removing unnecessary checks/guards

Author: arnog

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ### Features
 
+- **`numericValue()` convenience helper**: New standalone function that combines
+  the `isNumber()` guard with `.numericValue` access. Returns the numeric value
+  if the expression is a number literal, or `undefined` otherwise. Useful for
+  safely extracting numeric values without verbose ternary patterns:
+
+  ```ts
+  import { numericValue } from '@cortex-js/compute-engine';
+
+  // Before
+  const val = isNumber(expr) ? expr.numericValue : undefined;
+
+  // After
+  const val = numericValue(expr);
+  ```
+
 - **Stochastic equality check for expressions with unknowns**: `expr.isEqual()`
   now uses a stochastic fallback when symbolic methods (expand + simplify) can't
   prove equality. Both expressions are evaluated at 50 sample points (9
@@ -414,9 +429,9 @@ now only accessible after narrowing with a type guard.
 
 | Removed from `Expression`             | Access via                                |
 | :------------------------------------ | :---------------------------------------- |
-| `.symbol`                             | `isSymbol(expr)` then `expr.symbol`       |
+| `.symbol`                             | `isSymbol(expr)` or `isSymbol(expr, 'Pi')` then `expr.symbol` |
 | `.string`                             | `isString(expr)` then `expr.string`       |
-| `.ops`, `.nops`, `.op1`/`.op2`/`.op3` | `isFunction(expr)` then `expr.ops` etc.   |
+| `.ops`, `.nops`, `.op1`/`.op2`/`.op3` | `isFunction(expr)` or `isFunction(expr, 'Add')` then `expr.ops` etc. |
 | `.numericValue`, `.isNumberLiteral`   | `isNumber(expr)` then `expr.numericValue` |
 | `.tensor`                             | `isTensor(expr)` then `expr.tensor`       |
 
@@ -428,8 +443,16 @@ if (expr.symbol !== null) console.log(expr.symbol);
 import { isSymbol, sym } from '@cortex-js/compute-engine';
 
 if (isSymbol(expr)) console.log(expr.symbol);
+// isSymbol() accepts an optional symbol name:
+if (isSymbol(expr, 'Pi')) { /* expr is the Pi symbol */ }
 // or use the convenience helper:
 if (sym(expr) === 'Pi') { /* ... */ }
+
+// isFunction() accepts an optional operator name:
+if (isFunction(expr, 'Add')) {
+  // expr is narrowed to a function AND has operator 'Add'
+  console.log(expr.ops);
+}
 ```
 
 Properties that remain on `Expression`: `.operator`, `.re`/`.im`, `.shape`, all

MIGRATION_GUIDE_0.50.0.md

@@ -74,11 +74,11 @@ base interface. They are now only accessible after narrowing with a type guard.
 
 | Property                | Access via                                          |
 | :---------------------- | :-------------------------------------------------- |
-| `.symbol`               | `isSymbol(expr)` then `expr.symbol`                 |
+| `.symbol`               | `isSymbol(expr)` or `isSymbol(expr, 'Pi')` then `expr.symbol` |
 | `.string`               | `isString(expr)` then `expr.string`                 |
-| `.ops`                  | `isFunction(expr)` then `expr.ops`                  |
-| `.nops`                 | `isFunction(expr)` then `expr.nops`                 |
-| `.op1`/`.op2`/`.op3`    | `isFunction(expr)` then `expr.op1` etc.             |
+| `.ops`                  | `isFunction(expr)` or `isFunction(expr, 'Add')` then `expr.ops`  |
+| `.nops`                 | `isFunction(expr)` or `isFunction(expr, 'Add')` then `expr.nops` |
+| `.op1`/`.op2`/`.op3`    | `isFunction(expr)` or `isFunction(expr, 'Add')` then `expr.op1` etc. |
 | `.isFunctionExpression` | `isFunction(expr)` then `expr.isFunctionExpression` |
 | `.numericValue`         | `isNumber(expr)` then `expr.numericValue`           |
 | `.isNumberLiteral`      | `isNumber(expr)` then `expr.isNumberLiteral`        |
@@ -99,7 +99,7 @@ if (expr.numericValue !== null) {
 ### After
 
 ```ts
-import { isSymbol, isNumber, sym } from '@cortex-js/compute-engine';
+import { isSymbol, isNumber, sym, numericValue } from '@cortex-js/compute-engine';
 
 if (isSymbol(expr)) {
   // expr.symbol is `string` — guaranteed non-undefined
@@ -111,10 +111,12 @@ if (isNumber(expr)) {
   console.log(expr.numericValue);
 }
 
-// Convenience helper for symbol checks
+// Convenience helpers
 if (sym(expr) === 'Pi') {
   console.log('This is Pi');
 }
+
+const val = numericValue(expr);  // number | NumericValue | undefined
 ```
 
 See Section 6 for the full list of type guards and role interfaces.
@@ -316,12 +318,23 @@ if (isSymbol(expr)) {
   console.log(expr.symbol);
 }
 
+// Pass a symbol name to narrow and check the name in one step:
+if (isSymbol(expr, 'Pi')) {
+  // expr is a symbol with name "Pi"
+}
+
 if (isFunction(expr)) {
   // expr.ops is `ReadonlyArray<Expression>` (not undefined)
   // expr.isFunctionExpression is `true`
   console.log(expr.ops, expr.nops, expr.op1);
 }
 
+// Pass an operator name to narrow and check the operator in one step:
+if (isFunction(expr, 'Add')) {
+  // expr is a function expression with operator "Add"
+  console.log(expr.op1, expr.op2);
+}
+
 if (isString(expr)) {
   // expr.string is `string` (not undefined)
   console.log(expr.string);
@@ -344,7 +357,7 @@ if (isIndexedCollection(expr)) {
 }
 ```
 
-### Convenience Helper: `sym()`
+### Convenience Helpers: `sym()` and `numericValue()`
 
 For quick symbol name checks, use the `sym()` helper:
 
@@ -361,13 +374,25 @@ if (sym(expr) === 'Pi') { /* ... */ }
 const name = sym(expr);  // string | undefined
 ```
 
+For safe numeric value extraction, use the `numericValue()` helper:
+
+```ts
+import { numericValue } from '@cortex-js/compute-engine';
+
+// Instead of:
+const val = isNumber(expr) ? expr.numericValue : undefined;
+
+// You can write:
+const val = numericValue(expr);  // number | NumericValue | undefined
+```
+
 ### Role Interfaces
 
 | Guard                 | Narrows to                                |
 | :-------------------- | :---------------------------------------- |
 | `isNumber`            | `Expression & NumberLiteralInterface`     |
-| `isSymbol`            | `Expression & SymbolInterface`            |
-| `isFunction`          | `Expression & FunctionInterface`          |
+| `isSymbol`            | `Expression & SymbolInterface` (optional second arg: symbol name) |
+| `isFunction`          | `Expression & FunctionInterface` (optional second arg: operator name) |
 | `isString`            | `Expression & StringInterface`            |
 | `isTensor`            | `Expression & TensorInterface`            |
 | `isDictionary`        | `Expression & DictionaryInterface`        |

src/compute-engine.ts

@@ -69,6 +69,7 @@ export {
   isDictionary,
   isCollection,
   isIndexedCollection,
+  numericValue,
   isBoxedExpression,
   isBoxedNumber,
   isBoxedSymbol,

src/compute-engine/assume.ts

@@ -100,8 +100,8 @@ function assumeEquality(proposition: Expression): AssumeResult {
   const unknowns = proposition.unknowns;
   if (unknowns.length === 0) {
     const val = proposition.evaluate();
-    if (isSymbol(val) && val.symbol === 'True') return 'tautology';
-    if (isSymbol(val) && val.symbol === 'False') return 'contradiction';
+    if (isSymbol(val, 'True')) return 'tautology';
+    if (isSymbol(val, 'False')) return 'contradiction';
     console.log(proposition.canonical.evaluate());
     return 'not-a-predicate';
   }
@@ -254,8 +254,8 @@ function assumeInequality(proposition: Expression): AssumeResult {
   // Case 2
   const result = ce.box([op === '<' ? 'Less' : 'LessEqual', p, 0]).evaluate();
 
-  if (isSymbol(result) && result.symbol === 'True') return 'tautology';
-  if (isSymbol(result) && result.symbol === 'False') return 'contradiction';
+  if (isSymbol(result, 'True')) return 'tautology';
+  if (isSymbol(result, 'False')) return 'contradiction';
 
   const unknowns = result.unknowns;
   if (unknowns.length === 0) return 'not-a-predicate';
@@ -274,7 +274,7 @@ function assumeInequality(proposition: Expression): AssumeResult {
     const originalOp = proposition.operator;
     const propOp1 = proposition.op1;
     const propOp2 = proposition.op2;
-    const isSymbolOnLeft = isSymbol(propOp1) && propOp1.symbol === symbol;
+    const isSymbolOnLeft = isSymbol(propOp1, symbol);
     const otherSide = isSymbolOnLeft ? propOp2 : propOp1;
 
     // Only do bounds checking for simple comparisons like "x > k" where k is numeric
@@ -486,8 +486,8 @@ function assumeElement(proposition: Expression): AssumeResult {
 
   // Case 4
   const val = proposition.evaluate();
-  if (isSymbol(val) && val.symbol === 'True') return 'tautology';
-  if (isSymbol(val) && val.symbol === 'False') return 'contradiction';
+  if (isSymbol(val, 'True')) return 'tautology';
+  if (isSymbol(val, 'False')) return 'contradiction';
   return 'not-a-predicate';
 }
 
@@ -550,36 +550,31 @@ export function getSignFromAssumptions(
     // Case 1: Direct symbol comparison
     // x < 0 means x is negative
     // x <= 0 means x is non-positive
-    if (isSymbol(lhs) && lhs.symbol === symbol) {
+    if (isSymbol(lhs, symbol)) {
       if (op === 'Less') return 'negative';
       if (op === 'LessEqual') return 'non-positive';
     }
 
     // Case 2: Negated symbol comparison
     // -x < 0 means x > 0 (positive)
     // -x <= 0 means x >= 0 (non-negative)
-    if (
-      isFunction(lhs) &&
-      lhs.operator === 'Negate' &&
-      isSymbol(lhs.op1) &&
-      lhs.op1.symbol === symbol
-    ) {
+    if (isFunction(lhs, 'Negate') && isSymbol(lhs.op1, symbol)) {
       if (op === 'Less') return 'positive';
       if (op === 'LessEqual') return 'non-negative';
     }
 
     // Case 3: Symbol with subtraction from constant
     // a - x < 0 means x > a, so if a >= 0, x is positive
     // x - a < 0 means x < a, so if a <= 0, x is negative
-    if (isFunction(lhs) && lhs.operator === 'Subtract') {
+    if (isFunction(lhs, 'Subtract')) {
       const [a, b] = lhs.ops;
       if (a && b) {
         // a - x < 0 => x > a
-        if (isSymbol(b) && b.symbol === symbol && a.isNonNegative === true) {
+        if (isSymbol(b, symbol) && a.isNonNegative === true) {
           if (op === 'Less') return 'positive';
         }
         // x - a < 0 => x < a
-        if (isSymbol(a) && a.symbol === symbol && b.isNonPositive === true) {
+        if (isSymbol(a, symbol) && b.isNonPositive === true) {
           if (op === 'Less') return 'negative';
         }
       }
@@ -588,10 +583,10 @@ export function getSignFromAssumptions(
     // Case 4: Addition form (canonical form of subtraction)
     // x + (-a) < 0 means x < a, so if a <= 0, x is negative
     // -x + a < 0 means -x < -a means x > a, so if a >= 0, x is positive
-    if (isFunction(lhs) && lhs.operator === 'Add') {
+    if (isFunction(lhs, 'Add')) {
       for (const term of lhs.ops) {
         // Direct symbol in sum: check if other terms give us bounds
-        if (isSymbol(term) && term.symbol === symbol) {
+        if (isSymbol(term, symbol)) {
           // x + ... < 0, check if other terms are all non-negative
           // That would mean x < -(sum of others), so x < non-positive = negative
           const otherTerms = lhs.ops.filter((t) => t !== term);
@@ -604,12 +599,7 @@ export function getSignFromAssumptions(
           }
         }
         // Negated symbol in sum: -x + ... < 0
-        if (
-          isFunction(term) &&
-          term.operator === 'Negate' &&
-          isSymbol(term.op1) &&
-          term.op1.symbol === symbol
-        ) {
+        if (isFunction(term, 'Negate') && isSymbol(term.op1, symbol)) {
           // -x + ... < 0 means x > ...
           const otherTerms = lhs.ops.filter((t) => t !== term);
           if (

src/compute-engine/boxed-expression/abstract-boxed-expression.ts

@@ -480,9 +480,8 @@ export abstract class _BoxedExpression implements Expression {
 
     if (typeof other === 'boolean') {
       const val = this.value;
-      if (other === true) return isSymbol(val) ? val.symbol === 'True' : false;
-      if (other === false)
-        return isSymbol(val) ? val.symbol === 'False' : false;
+      if (other === true) return isSymbol(val, 'True');
+      if (other === false) return isSymbol(val, 'False');
       return false;
     }
 

src/compute-engine/boxed-expression/arithmetic-add.ts

@@ -103,7 +103,7 @@ export function canonicalAdd(
         if (isNumber(op)) {
           // Skip pure imaginary terms (already summed above)
           const facExpr = getImaginaryFactor(op);
-          if (facExpr !== undefined && isNumber(facExpr)) {
+          if (isNumber(facExpr)) {
             const f = facExpr.numericValue;
             const im = typeof f === 'number' ? f : f.re;
             if (im !== 0 && typeof im === 'number') continue;
@@ -292,7 +292,7 @@ export class Terms {
         this.terms = [{ term: ce.ComplexInfinity, coef: [] }];
         return;
       }
-      if (term.isNaN || (isSymbol(term) && term.symbol === 'Undefined')) {
+      if (term.isNaN || isSymbol(term, 'Undefined')) {
         this.terms = [{ term: ce.NaN, coef: [] }];
         return;
       }
@@ -337,15 +337,15 @@ export class Terms {
       return;
     }
 
-    if (isFunction(term) && term.operator === 'Add') {
+    if (isFunction(term, 'Add')) {
       for (const x of term.ops) {
         const [c, t] = x.toNumericValue();
         this._add(coef.mul(c), t);
       }
       return;
     }
 
-    if (isFunction(term) && term.operator === 'Negate') {
+    if (isFunction(term, 'Negate')) {
       this._add(coef.neg(), term.op1);
       return;
     }