nerdamer 2.0.0-rc.1 → 2.0.0

package/README.md

@@ -1,243 +1,226 @@
 # Nerdamer
 
-Nerdamer is a symbolic math library for JavaScript and TypeScript. It can parse and manipulate algebraic expressions, solve equations, work with matrices and vectors, perform calculus, and evaluate expressions numerically.
+Nerdamer is a symbolic mathematics library and computer algebra system for JavaScript and TypeScript.
 
-Nerdamer 2.0 is a TypeScript rewrite of the library. Everyday usage remains familiar, while the parser, solvers, numeric handling, public types, and internal architecture have been substantially reworked.
+Nerdamer 2.0 is a TypeScript rewrite of Nerdamer. The familiar string-based API remains available, while the package also exposes typed modules for direct use of the symbolic engine, algebra, calculus, solving, structures, assumptions, parser APIs, and advanced algorithms.
 
-## Getting started with Nerdamer
+This branch prepares `2.0.0`.
 
-Nerdamer 2.0 is currently available as a release candidate under the npm `next` tag:
+## Install
 
 ```bash
-npm install nerdamer@next
+npm install nerdamer
 ```
 
-When Nerdamer 2.0 becomes the stable `latest` release, the normal `npm install nerdamer` command will install the 2.x line.
+Nerdamer 2.0 is published under npm's `latest` tag.
 
-### Need to stay on the 1.x line?
+## Quick start
 
-Nerdamer 2.0 contains substantial API and behavior changes. If an existing application cannot migrate to 2.0 yet, use [Nerdamer-Prime](https://github.com/together-science/nerdamer-prime), a separately maintained continuation of the earlier Nerdamer codebase:
+```javascript
+const nerdamer = require('nerdamer');
 
-```bash
-npm install nerdamer-prime
+const expression = nerdamer('x^2+2*(cos(x)+x*x)');
+console.log(expression.text());
+// 2*cos(x)+3*x^2
+```
+
+TypeScript:
+
+```typescript
+import nerdamer from 'nerdamer';
+
+const expression = nerdamer('(x+1)^3').expand();
+console.log(expression.text({ sort: true }));
+// x^3+3*x^2+3*x+1
 ```
 
-Nerdamer-Prime is maintained separately from Nerdamer 2.0 and is the appropriate option for projects that need to remain closer to the 1.x API and package structure.
+TypeScript projects compiling to CommonJS should enable `esModuleInterop`.
 
-In Node.js, require the package and start working with expressions:
+## Full package and parser package
+
+The normal `nerdamer` entry point assembles the complete CAS. It registers the parser/core and math functions together with algebra, calculus, and solving.
 
 ```javascript
 const nerdamer = require('nerdamer');
 
-const e = nerdamer('x^2+2*(cos(x)+x*x)');
-console.log(e.text());
-// 2*cos(x)+3*x^2
+nerdamer.factor('x^2-1').text();
+nerdamer.diff('x^3', 'x').text();
+nerdamer.solve('x^2-4', 'x').text();
 ```
 
-TypeScript and ESM users can use the default import:
+Nerdamer 2.0 also has a separate parser entry point. It contains the symbolic parser, scripting, assumptions, structures, complex and polynomial operations, and general math functions without loading the higher-level algebra, calculus, and solver domains.
 
 ```typescript
-import nerdamer from 'nerdamer';
+import { Parser } from 'nerdamer/parser';
 
-console.log(nerdamer('expand((x+1)^3)').text());
+const expression = Parser.parse('sqrt(x^2+1)');
+console.log(expression.text());
 ```
 
-TypeScript projects that compile to CommonJS should enable `esModuleInterop`.
-
-### Browser use
+This separation is also reflected in the browser builds:
 
-The complete browser bundle is included in the package at `dist/bundle.js`. A standalone parser bundle is also available at `dist/parser.js`.
+- `dist/bundle.js` — complete Nerdamer package;
+- `dist/parser.js` — parser-focused browser bundle.
 
 ```html
 <script src="./node_modules/nerdamer/dist/bundle.js"></script>
 <script>
-    const e = nerdamer('x^2+2*x+1');
-    console.log(e.text());
+    console.log(nerdamer('factor(x^2-1)').text());
 </script>
 ```
 
-## Everything is included
+The parser bundle exposes `nerdamerParser` rather than the complete `nerdamer` API.
 
-Nerdamer 1.x was split into the core plus add-ons such as `Algebra.js`, `Calculus.js`, `Solve.js`, and `Extra.js`. Nerdamer 2.0 includes the commonly used algebra, calculus, solving, matrix, vector, and special-function features in the main package. Additional add-on imports are no longer required.
+## Package entry points
 
-```javascript
-const nerdamer = require('nerdamer');
+The npm package exports the complete callable API plus typed module entry points:
 
-console.log(nerdamer.factor('x^2-1').text());
-console.log(nerdamer.diff('x^3', 'x').text());
-console.log(nerdamer.solve('x^2-4', 'x').text());
+```typescript
+import nerdamer from 'nerdamer';
+import { Expression, Rational, type TextOptions } from 'nerdamer/core';
+import { Polynomial, gcd, lcm, partfrac } from 'nerdamer/algebra';
+import { diff, integrate, limit } from 'nerdamer/calculus';
+import { solve, PolynomialSolver } from 'nerdamer/solve';
+import { Matrix, Vector, ValuesSet } from 'nerdamer/structures';
+import { assume, clearAssumptions } from 'nerdamer/assumptions';
+import { Parser } from 'nerdamer/parser';
 ```
 
-## Expressions and substitutions
+Additional supported entry points are `nerdamer/advanced` and `nerdamer/debug`.
 
-As in earlier versions, calling `nerdamer(...)` parses an expression and returns a Nerdamer value.
+## Parser results
+
+`nerdamer(...)` returns the Nerdamer entity represented by the input. Scalar symbolic input normally returns an `Expression`; equations and structured notation can return `Equation`, `Vector`, `Matrix`, `Collection`, `ValuesSet`, or `Dictionary`.
 
 ```javascript
-const e = nerdamer('x^2+2*(cos(x)+x*x)', { x: 6 });
-console.log(e.text());
+const scalar = nerdamer('x^2+1');
+const equation = nerdamer('x^2=1');
+const vector = nerdamer('[x, y, 3]');
 ```
 
-Only substitution is performed by the values object. To numerically evaluate the result, call `evaluate()`:
+This is intentional. Nerdamer 2.0 does not wrap every parser result in a compatibility `Expression` object.
+
+## Substitution and evaluation
+
+Values supplied to `nerdamer(...)` are substitutions. They do not imply numerical evaluation.
 
 ```javascript
-const e = nerdamer('x^2+2*(cos(x)+x*x)', { x: 6 }).evaluate();
-console.log(e.text());
+const substituted = nerdamer('x^2+cos(x)', { x: 6 });
+const evaluated = substituted.evaluate();
 ```
 
-Values can themselves be expressions:
+Values can themselves be symbolic expressions:
 
 ```javascript
-const e = nerdamer('x^2+2*(cos(x)+x*x)', { x: 'x^2+1' });
-console.log(e.text());
+nerdamer('x^2+1', { x: 'y+1' }).text();
 ```
 
-Parser results are always represented by Nerdamer-native values. A scalar expression returns an `Expression`; equations, vectors, matrices, sets, collections, dictionaries, and other supported structured inputs return the corresponding Nerdamer type rather than a JavaScript-native result shape.
-
-## Text output and term ordering
+## Text and TeX output
 
-`text()` returns Nerdamer's normal symbolic representation. For example, a polynomial
-may place the constant term first:
+`text()` returns Nerdamer notation. Term ordering can be requested per call:
 
 ```javascript
-const e = nerdamer('x^2+2*x+1');
+const expression = nerdamer('x^2+2*x+1');
 
-e.text();
+expression.text();
 // 1+2*x+x^2
+
+expression.text({ sort: true });
+// x^2+2*x+1
 ```
 
-Use the per-call `sort` option when conventional display order is preferred:
+The full package also supplies `toText()` and TeX conversion:
 
 ```javascript
-e.text({ sort: true });
-// x^2+2*x+1
-
-nerdamer('(x+1)^2').expand().text({ sort: true });
-// x^2+2*x+1
+expression.toText();
+expression.toTeX();
+nerdamer.convertToTeX('sqrt(x^2+1)');
+nerdamer.convertFromLaTeX('\\frac{x^2+1}{2}');
 ```
 
-Sorting affects only the returned string. It does not modify the expression or change the
-process-wide `SORT_TERMS` setting. TypeScript users can import `TextOptions` from
-`nerdamer` or `nerdamer/core`.
+`convertToLaTeX()` remains as a deprecated compatibility alias.
 
-The full package also provides the chainable converter-based form:
+Scientific formatting can be requested through `text()` without changing the underlying expression:
 
 ```javascript
-e.toText();
-// x^2+2*x+1
+nerdamer('1200').text({ scientific: 4 });
+// 1.200e3
 ```
 
-Use `text({ sort: true })` when you want Nerdamer text syntax with explicit per-call
-ordering control. Use `toText()` when you simply want the conventional formatted-text
-representation.
-
 ## Algebra
 
-Nerdamer can expand, factor, simplify, compute polynomial GCDs, and perform related symbolic algebra operations.
-
 ```javascript
-nerdamer('expand((x+1)^4)').text();
+nerdamer.expand('(x+1)^4').text();
 nerdamer.factor('x^4-1').text();
 nerdamer.simplify('sin(x)^2+cos(x)^2').text();
 nerdamer.gcd('x^2-1', 'x^2-2*x+1').text();
-
-const completed = nerdamer.completeSquare('x^2+6*x+1');
-completed.expression.text({ sort: true });
-
-const [substituted, substitutions] = nerdamer.uSub(
-    'cos(x)^2+cos(x)+1',
-    'cos(x)'
-);
-nerdamer.uUnSub(substituted, substitutions);
+nerdamer.partfrac('1/(x^2-1)', 'x').text();
 ```
 
-## Solving equations
+The 2.0 algebra implementation includes the rewritten polynomial GCD/factorization path, partial fractions, polynomial solving support, and direct polynomial APIs.
 
-Use `solve` for a single equation:
+Prime factorization has two explicit forms:
 
 ```javascript
-const roots = nerdamer.solve('x^2-1', 'x');
-console.log(roots.text());
+nerdamer.pfactor(100).text();
+// [2,2,5,5]
 
-roots.each(root => {
-    console.log(root.text());
-});
-```
-
-Single-variable solving returns a `SolutionSet`. System solving returns Nerdamer structures rather than the compatibility-only arrays used by older releases.
-
-```javascript
-const solutions = nerdamer.solveSystem(
-    ['x+y=3', 'x-y=1'],
-    ['x', 'y']
-);
-
-console.log(solutions.text());
+nerdamer.pfactord(100).text();
+// {2=>2,5=>2}
 ```
 
 ## Calculus
 
-Differentiation, integration, limits, sums, products, and transforms are available without loading a separate add-on.
-
 ```javascript
 nerdamer.diff('x^3+sin(x)', 'x').text();
 nerdamer.integrate('x^2', 'x').text();
 nerdamer.limit('sin(x)/x', 'x', '0').text();
+nerdamer.laplace('t', 't', 's').text();
 ```
 
-You can also use calculus functions inside expression strings:
+The same functions can be used in Nerdamer notation:
 
 ```javascript
-nerdamer('diff(x^2+2*(cos(x)+x*x),x)').text();
+nerdamer('diff(x^3,x)').text();
 ```
 
-## Matrices and vectors
+## Solving
 
-Matrices and vectors are supported directly by the parser and are also available as public TypeScript classes.
+Single-variable solving returns a `SolutionSet`:
 
 ```javascript
-const m = nerdamer('matrix([1,2],[3,4])');
-console.log(m.text());
-
-const v = nerdamer('vector(1,2,3)');
-console.log(v.text());
-
-const basis = nerdamer.nullspace(nerdamer('matrix([1,2,3],[2,4,6])'));
-console.log(basis.text());
+const roots = nerdamer.solve('x^2-1', 'x');
+console.log(roots.text());
 ```
 
-## Runtime functions and constants
-
-Custom symbolic functions can be defined with Nerdamer syntax:
+System solving returns Nerdamer structures rather than legacy JavaScript arrays:
 
 ```javascript
-nerdamer('hyp(a,b):=sqrt(a^2+b^2)');
-console.log(nerdamer('hyp(3,4)').evaluate().text());
+const solutions = nerdamer.solveSystem(
+    ['x+y=3', 'x-y=1'],
+    ['x', 'y']
+);
+
+console.log(solutions.text());
 ```
 
-Or use the public function API:
+The legacy `solveeqs` name is retained as the compatibility alias for system solving. `solveEquations` is not part of the 2.0 public API.
 
-```javascript
-nerdamer.setFunction('line', ['x', 'm', 'b'], 'm*x+b');
-console.log(nerdamer('line(2,3,4)').text());
-```
+## Matrices, vectors, sets, and dictionaries
 
-Constants can be registered as well:
+Structured values are first-class parser entities:
 
 ```javascript
-nerdamer.setConstant('g', 9.81);
-console.log(nerdamer('100*g').text());
+nerdamer('matrix([1,2],[3,4])').text();
+nerdamer('[1,x,3]').text();
+nerdamer('{1,2,x}').text();
 ```
 
-## Nerdamer scripting
+The corresponding TypeScript classes are exported from `nerdamer/structures`.
 
-Nerdamer includes a small symbolic scripting language in addition to ordinary expression notation. It supports user-defined functions, assignments, local bindings, conditionals, loops, blocks, logical operations, `return`, `break`, `continue`, and error-handling helpers.
-
-```javascript
-const result = nerdamer('let(x,4,if(x>3,x^2,0))');
-console.log(result.text());
-```
+## Scripting
 
-Multiple statements use semicolons as statement separators:
+Nerdamer notation includes a symbolic scripting layer with assignments, user functions, local bindings, conditionals, loops, blocks, logical operations, `return`, `break`, `continue`, and error-handling helpers.
 
 ```javascript
 const result = nerdamer(`
@@ -248,160 +231,116 @@ const result = nerdamer(`
 console.log(result.text());
 ```
 
-## Build a JavaScript function
-
-An expression can be compiled to a JavaScript function:
-
-```javascript
-const f = nerdamer('x^2+5').buildFunction();
-console.log(f(9));
-// 86
-```
-
-You can specify the parameter order explicitly:
-
-```javascript
-const f = nerdamer('z+x^2+y').buildFunction(['y', 'x', 'z']);
-console.log(f(9, 2, 1));
-// 14
-```
-
-The chained `buildFunction()` method is available on values returned by `nerdamer(...)` so this form remains convenient in TypeScript. Only scalar `Expression` results can be compiled. If the input parses to an `Equation`, `Vector`, `Matrix`, set, or another structured result, calling `buildFunction()` throws `UnexpectedDataType` rather than compiling the contained values independently.
-
-`buildFunction()` uses dynamic JavaScript function construction. Applications with a Content Security Policy that forbids dynamic code generation should use Nerdamer's ordinary symbolic and numeric evaluation APIs instead.
-
-## TeX
+Control-flow operations that intentionally produce no mathematical value use an internal null signal. That signal is distinct from legitimate values such as an empty vector and is not exposed as a normal parser entity.
 
-Convert Nerdamer expressions to TeX math markup with `toTeX()` or `convertToTeX()`:
+## Runtime functions, constants, and settings
 
 ```javascript
-const e = nerdamer('x^2+2*x+1');
-console.log(e.toTeX());
-
-console.log(nerdamer.convertToTeX('sqrt(x^2+1)'));
+nerdamer.setFunction('line', ['x', 'm', 'b'], 'm*x+b');
+nerdamer.setConstant('g', 9.81);
+nerdamer.setVar('a', 5);
 ```
 
-The legacy `convertToLaTeX()` name remains available as a deprecated compatibility alias.
-
-Nerdamer can also parse supported LaTeX expressions:
+Settings remain shared by the package instance:
 
 ```javascript
-const e = nerdamer.convertFromLaTeX('\\frac{x^2+1}{2}');
-console.log(e.text());
-```
-
-## Direct TypeScript imports
-
-The callable `nerdamer` API remains available, but Nerdamer 2.0 also exposes public classes and functions through package subpaths:
-
-```typescript
-import { Expression, Rational, type TextOptions } from 'nerdamer/core';
-import {
-    Polynomial,
-    completeSquare,
-    gcd,
-    isPrime,
-    lcm,
-    polyFactors,
-    uSub,
-    uUnSub,
-} from 'nerdamer/algebra';
-import { diff, integrate, limit } from 'nerdamer/calculus';
-import { solve, PolynomialSolver } from 'nerdamer/solve';
-import { Matrix, Vector, ValuesSet, nullspace } from 'nerdamer/structures';
+nerdamer.set('LANGUAGE', 'spa');
+nerdamer.set('LANGUAGE', 'eng');
 ```
 
-Additional entry points are available for assumptions, selected parser APIs, advanced algorithms, and debugging tools.
+Built-in error messages are available in English, Spanish, French, German, Portuguese, Italian, and Dutch.
 
 ## Assumptions
 
-Nerdamer can register numeric interval assumptions for symbols. Assumptions are process-wide and are used by symbolic comparisons and simplifications that depend on sign or range information.
-
 ```typescript
 import nerdamer from 'nerdamer';
 import { assume, clearAssumptions } from 'nerdamer/assumptions';
 
 assume('x > 0');
-
 console.log(nerdamer('sqrt(x^2)').text());
 // x
-
 clearAssumptions();
 ```
 
-Repeated assumptions for the same symbol are intersected. Contradictory assumptions are rejected instead of silently replacing the existing range.
+Repeated assumptions for a symbol are intersected. Contradictory assumptions are rejected.
 
-## Localized error messages
+## Building JavaScript functions
 
-Nerdamer includes localized built-in error messages for English, Spanish, French, German, Portuguese, Italian, and Dutch. Select the language through the shared parser settings:
+Scalar expressions can be compiled to native JavaScript-number functions:
 
 ```javascript
-nerdamer.set('LANGUAGE', 'spa');
-
-// Restore English when needed.
-nerdamer.set('LANGUAGE', 'eng');
+const f = nerdamer('x^2+5').buildFunction();
+console.log(f(9));
+// 86
 ```
 
-The language codes are `eng`, `spa`, `fra`, `deu`, `por`, `ita`, and `nld`.
+`buildFunction()` uses dynamic JavaScript function construction. Applications whose Content Security Policy blocks dynamic code generation should use Nerdamer's symbolic or numeric evaluation APIs instead. Structured parser results cannot be compiled as scalar functions.
 
-## Numeric precision
+## Numeric behavior
 
-Nerdamer keeps exact rational and integer arithmetic where possible. Decimal arithmetic uses Decimal.js and large integers use native `BigInt`.
+Nerdamer preserves exact integer and rational arithmetic where possible. Large integers use native `BigInt`; decimal arithmetic uses Decimal.js. Complex arithmetic is represented by Nerdamer's numeric types rather than JavaScript's native `Number` alone.
 
 ```javascript
 nerdamer('0.1+0.2').text();
 nerdamer('sqrt(2)').evaluate().text();
 ```
 
-## What changed in 2.0
-
-Nerdamer 2.0 keeps the familiar expression-oriented API, but it is a new implementation rather than a continuation of the 1.x source tree. Important changes include:
-
-- the old add-on loading system is gone;
-- TypeScript declarations ship with the package;
-- Nerdamer no longer keeps a global history of every parsed expression;
-- parser-facing APIs consistently return Nerdamer-native values instead of mixing Nerdamer types with JavaScript-native result shapes;
-- solver result types are explicit public structures;
-- lower-level 1.x extension hooks such as `getCore()` and `register()` are not exposed in the same way;
-- decimal, complex-number, parser, solver, assumptions, and set handling have been substantially revised.
-
-If an existing project cannot move to Nerdamer 2.0 yet, use [Nerdamer-Prime](https://github.com/together-science/nerdamer-prime), which continues the earlier Nerdamer line under the `nerdamer-prime` npm package.
-
-For the current documentation, examples, and migration information, visit [nerdamer.com](https://nerdamer.com/).
-
-## Documentation and playground
+## Building from source
 
-- Website: [nerdamer.com](https://nerdamer.com/)
-- Documentation: [nerdamer.com/docs](https://nerdamer.com/docs/)
-- Playground: [nerdamer.com/playground](https://nerdamer.com/playground/)
-
-## Development
-
-Run the type checker:
+Install dependencies and run the normal checks:
 
 ```bash
+npm install
 npm run typecheck
+npm test
 ```
 
-Run the tests:
+Build the complete package:
 
 ```bash
-npm test
+npm run build
 ```
 
-Build the complete package:
+Build the parser-only browser bundle:
 
 ```bash
-npm run build
+npm run build:parser
 ```
 
-Validate the npm package as an installed consumer:
+Browser bundles include English by default. Additional error-message catalogs can be selected with a comma-separated language list:
 
 ```bash
-npm run validate:package
+npx webpack --mode=production --env target=full --env language=spa,fra
 ```
 
-The publish hook runs tests, builds the package and parser bundle, generates parser documentation data, and validates the packed npm artifact before publication.
+The supported codes are `eng`, `spa`, `fra`, `deu`, `por`, `ita`, and `nld`. English is always available. The first selected non-English language becomes active when the bundle loads; the remaining selected catalogs are available for runtime switching. Duplicate codes are ignored. Use `--env language=all` to include every translated catalog. `all` cannot be combined with individual language codes.
+
+Before publishing, the package runs type checking, tests, coverage, both browser builds, parser documentation generation, TypeDoc validation, and packed-package validation through `prepublishOnly`.
+
+## Migrating from Nerdamer 1.x
+
+Nerdamer 2.0 keeps much of the familiar expression-oriented API, but it is a new implementation. Important migration areas include:
+
+- the old `Algebra`, `Calculus`, `Solve`, and `Extra` side-effect imports are replaced by the complete package and supported module entry points;
+- the third and fourth arguments to `nerdamer(...)` are gone;
+- global parsed-expression history is gone;
+- parser results can be structured Nerdamer entities instead of always being wrapped in a compatibility `Expression`;
+- system-solving results use `Vector`/`Dictionary` structures;
+- lower-level 1.x extension hooks such as `getCore()` and `register()` are not restored;
+- several compatibility functions were restored explicitly rather than by exposing every parser function on the root object;
+- internal numeric, parser, solver, polynomial, assumptions, set, and scripting implementations have changed substantially.
+
+See [BREAKING_CHANGES.md](BREAKING_CHANGES.md) and [Moving from Nerdamer 1.x to 2.0](docs/MIGRATING_FROM_1X.md) before upgrading an existing application.
+
+## Documentation
+
+- Website: https://nerdamer.com/
+- Documentation: https://nerdamer.com/documentation
+- Migration guide: `docs/MIGRATING_FROM_1X.md`
+- 2.0 release notes: `docs/RELEASE_NOTES_2.md`
+- Parser conventions: `docs/PARSER_CONVENTIONS.md`
+- Source repository: https://github.com/jiggzson/nerdamer
+- Issues: https://github.com/jiggzson/nerdamer/issues
 
 ## License