@pie-framework/math-validation 1.4.2 → 2.0.0-next.20261110063142

package/LICENSE

@@ -0,0 +1,233 @@
+MIT License
+
+Copyright (c) 2026 PIE Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Portions of this software are ported from pie-elements
+(https://github.com/pie-framework/pie-elements), pie-lib
+(https://github.com/pie-framework/pie-lib) and math-validation
+(https://github.com/pie-framework/math-validation), distributed under this
+license:
+
+ISC License
+
+Copyright 2019 CoreSpring Inc
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The LaTeX parser and its conversion to mathjs (src/conversion/latex-to-ast.ts,
+src/conversion/ast-to-mathjs.ts, src/conversion/lexer.ts and
+src/conversion/flatten.ts, bundled into dist/index.js) are derived from release
+2.0.0-alpha26 of math-expressions (https://github.com/kisonecat/math-expressions),
+Copyright 2014-2017 by Jim Fowler <kisonecat@gmail.com> and Duane Nykamp
+<nykamp@umn.edu>, which is licensed under GPL-3.0 or Apache-2.0. They are used
+under the Apache License, Version 2.0, below, and have been changed for this
+package.
+
+                               Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -1,134 +1,65 @@
-# math-validation
+# @pie-framework/math-validation
 
-- an api
-- a large set of test data
-- aims to determine if two mathematical expressions are equal, either having the same form or not
-- have a public website where you can add some math and check if it works - also the link should be shareable
+Decides whether two LaTeX expressions are equal, literally or symbolically. The math-inline and math-templated controllers score responses with it.
 
+```ts
+import { latexEqual } from '@pie-framework/math-validation';
 
-## demo
-
-```shell
-yarn demo
-```
-
-Then go to `http://localhost:$PORT/demo`
-
-
-## Tests
-
-```shell
-yarn jest
-```
-
-Runs all the tests
-
-There is one test that runs fixture data located here: `src/fixtures/latex-equal/*.ts`. To filter the fixtures you run here you can use the `-t` flag:
-
-```shell
-yarn jest src/__tests__/latex-equal.spec.ts -t src/fixtures/latex-equal/7119.ts --reporters default
+latexEqual('\\frac{4}{6}', '\\frac{2}{3}', { mode: 'symbolic' }); // true
+latexEqual('a+7+b', '7+a+b', { mode: 'literal', literal: { ignoreOrder: true } }); // true
 ```
 
-
-## Next Steps
-
-* Check that api we expose will support what is needed.
-* Do triage on the test failures, add a note to failing test so we can build a picture of the work needed
-
-
-## Test failure triage
-
-| theme                      | notes                                                                  |
-|----------------------------|------------------------------------------------------------------------|
-| latex parsing              | seems like we aren't able to parse all the inputs in the test cases    |
-| math evaluation            | math.js is not seeing things as being equal - need more detail on that |
-| incomplete literal support | we haven't really set up literal options support yet                   |
-| incorrect test data        | sometimes the test data is not quite right                             |
-
-
-## Goals
-
-* we parse from latex -> ast -> mathjs
-* clean up symbolic evaluation (in progress)
-* avoid the use of string manipulation/regex (in progress)
-* more advanced literal validation (todo)
-* block input that is clearly too large/unrelated (eg: a user can type in gobbledy-gook - we should just abort if we see that)
-
-
-## Capabilities
-
-It can determine mathematical equivalence between: 
-
-- linear equations in one variable
-- linear equations in two variables
-- quadratic equations
-- 2-way inequalities in one or two variables
-- compound inequalities in one variable
-- trigonometric identities and functions
-- inverse trigonometric functions
-- similar notation for logarithms and based logarithms
-
-It can also handle degrees, radians and gradians
-
-
-### things that'd be great (but we may have to park until we have more time)
-
-* a faster latex parser
-* faster math evaluation
-
+The package is ES modules only. LaTeX is parsed into an AST (`src/conversion/latex-to-ast.ts`), converted to a mathjs expression tree (`src/conversion/ast-to-mathjs.ts`), and compared there. Both converters derive from the math-expressions library and are used under its Apache-2.0 license; `LICENSE` holds the terms.
 
 ## Modes
 
-There are 2 modes - literal and symbolic
-
-Literal: is at its most basic a tuned version of a string validation
-
-By default - ignores spaces and parentheses as long as they do not change the meaning of operations (ex. “a+7 +b” will validate against “  ((a)    + (7))+b ”)
-           - ignores leading zeros: “0.1” will validate against “.1”
-           - accepts commas for decimal marks. For example “1,000” will be equivalent with 1000
+**Literal** compares the form of the expressions. It ignores spaces and parentheses that do not change the meaning, so `a+7 +b` matches `((a) + (7))+b`, and it ignores leading zeros (`0.1` matches `.1`) and thousands separators (`1,000` matches `1000`). Three options under `literal` widen it:
 
-Literal Validation offers two configuration options that can be used to validate some variety of forms for an expression:
+- `allowTrailingZeros`: `4.5` matches `4.50000`.
+- `ignoreOrder`: the order of terms and factors stops mattering, so `a+7+b*c` matches `7+a+bc`, though not `ac+7+b`.
+- `compareNumbersByValue`: a single number matches only a single number of equal value. A number is an integer, decimal, fraction (`\frac{2}{3}` or `2/3`) or mixed number (`2\frac{1}{2}`), with at most one sign and optionally in parentheses. `4/6` matches `2/3` and `2.5` matches `2\frac{1}{2}`, but `3+3` does not match `6`: any operation, constant (`\pi`), unit or percentage makes a side a non-number. When neither side is a number, the literal comparison decides.
 
-Ignore trailing zeros option; allows the evaluation to accept zeros to the right of the decimal place “4.5” will validate against “4.50000000000000”
-Ignore order option; makes validation indifferent to the variables order, as long as it does not change operations meaning. In this case “a+7 +b*c” will validate against “7 + a+bc”, but not against “ac+7+b”; without it “a+7 +b” will not validate against “7 + a+b”
+**Symbolic** decides mathematical equivalence. It normalises both sides (distributing coefficients, combining like terms, sorting) and, where that is not enough, solves or samples them. It takes no options; the literal options do not apply to it. It handles:
 
-Symbolic: attempts to decide if expressions are mathematically equivalent or not
+- linear equations in one or two variables, and quadratic equations
+- two-way inequalities in one or two variables, and compound inequalities in one variable
+- trigonometric and inverse trigonometric functions and identities, with angles in radians or in degrees written `°` or `\degree`
+- the product, quotient and power rules for logarithms, and `\log` as `\log_{10}`
 
-By default, it offers all configurations presented for literal validation, exceeding it by quite a lot
-In order to check equivalence between 2 expressions, we have to reduce both expressions to the simplest one. Then distribute all coefficients, combine any like terms on each side of the expression, and arrange them in the same order. 
+## Demo
 
+```shell
+bun run demo
+```
 
-### Notes
+Serves a page that compares two expressions in either mode; the URL records the comparison, so it can be shared. `bun run build:demo` type-checks the page and writes it to `demo/dist`.
 
-* `@babel/runtime` is a devDependency if you ever need to link this repo to another package for testing
+## Tests
 
-## TODO
-* set up api that is compatible w/ ui component options
-* derivatives kind of work and kind of not - how to use?
+```shell
+bun run test
+```
 
-### CI
+`src/__tests__/latex-equal.test.ts` runs the fixtures under `src/fixtures/latex-equal/literal` and `src/fixtures/latex-equal/symbolic`, one suite per fixture file named by its path. Narrow a run with Vitest's `-t` filter:
 
-We use circleci - see .circleci/config.yml
+```shell
+bunx vitest run src/__tests__/latex-equal.test.ts -t src/fixtures/latex-equal/literal/PD-303.ts
+```
 
-### debugging tests
+To debug in VS Code, add an attach configuration to `launch.json`:
 
-#### vscode
-add the following to `configurations` array in launch.json
 ```json
-    {
-      "name": "Attach",
-      "port": 9229,
-      "request": "attach",
-      "skipFiles": [
-        "<node_internals>/**"
-      ],
-      "type": "pwa-node"
-    }
+{
+  "name": "Attach",
+  "port": 9229,
+  "request": "attach",
+  "skipFiles": ["<node_internals>/**"],
+  "type": "node"
+}
 ```
 
-```shell
-node --inspect-brk ./node_modules/.bin/jest --runInBand #and any other flags you want
-```
-The launch debug using 'Attach' command above.
+Start the tests with `bunx vitest run --inspect-brk --no-file-parallelism`, then run the Attach configuration.
+
+## Release
 
-[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
+The package builds, tests and releases with the rest of [pie-elements-ng](https://github.com/pie-framework/pie-elements-ng); see `docs/PUBLISHING.md` there.

package/dist/conversion/ast-to-mathjs.d.ts

@@ -0,0 +1,3 @@
+export declare class AstToMathJs {
+    convert(tree: any): any;
+}

package/dist/conversion/error.d.ts

@@ -0,0 +1,4 @@
+export declare class ParseError extends Error {
+    location?: number;
+    constructor(message: string, location?: number);
+}

package/dist/conversion/flatten.d.ts

@@ -0,0 +1 @@
+export declare function flatten(expr: any): any;

package/{lib → dist}/conversion/latex-to-ast.d.ts

@@ -1,22 +1,23 @@
-import { Token } from "./lexer";
+import { type Token } from './lexer.js';
 export declare const whitespace_rule = "\\s|\\\\,|\\\\!|\\\\ |\\\\>|\\\\;|\\\\:|\\\\quad\\b|\\\\qquad\\b";
 export declare const latex_rules: string[][];
-export declare type Opts = {
+export type Opts = {
     allowSimplifiedFunctionApplication: boolean;
     allowedLatexSymbols: string[];
     appliedFunctionSymbols: string[];
     functionSymbols: string[];
     parseLeibnizNotation: boolean;
     missingFactor: (token: Token, e: Error) => number | string;
-    unknownCommandBehavior: "error" | "passthrough";
+    unknownCommandBehavior: 'error' | 'passthrough';
+    /** Keep a mixed number such as `2\\frac{1}{2}` as `["mixed", 2, ["/", 1, 2]]` instead of a sum. */
+    keepMixedNumbers: boolean;
 };
 export declare const DEFAULT_OPTS: Opts;
 export declare class LatexToAst {
-    private unknownCommandBehavior;
     private lexer;
     private token;
     private opts;
-    constructor(opts?: Opts);
+    constructor(opts?: Partial<Opts>);
     advance(params?: any): void;
     return_state(): {
         lexer_state: {
@@ -26,8 +27,8 @@ export declare class LatexToAst {
         token: Token;
     };
     set_state(state: any): void;
-    convert(input: any, pars?: any): any;
-    statement_list(pars?: any): any[];
+    convert(input: string, pars?: any): any;
+    statement_list(pars?: any): any;
     statement(opts?: {
         parse_absolute_value?: boolean;
         inside_absolute_value?: number;
@@ -40,17 +41,17 @@ export declare class LatexToAst {
     term(params: any): any;
     factor(params: any): any;
     nonMinusFactor(params: any): any;
-    fraction({ inside_absolute_value, parse_absolute_value, allow_absolute_value_closing, unknownCommands, }: {
+    fraction({ parse_absolute_value, unknownCommands, }: {
         inside_absolute_value?: number;
         parse_absolute_value?: boolean;
         allow_absolute_value_closing?: boolean;
         unknownCommands?: string;
-    }): string | any[];
+    }): any;
     baseFactor({ inside_absolute_value, parse_absolute_value, allow_absolute_value_closing, unknownCommands, }?: {
-        inside_absolute_value?: number;
-        parse_absolute_value?: boolean;
-        allow_absolute_value_closing?: boolean;
-        unknownCommands?: string;
+        inside_absolute_value?: number | undefined;
+        parse_absolute_value?: boolean | undefined;
+        allow_absolute_value_closing?: boolean | undefined;
+        unknownCommands?: string | undefined;
     }): any;
     leibniz_notation(): string | false;
 }

package/{lib → dist}/conversion/lexer.d.ts

@@ -1,5 +1,5 @@
-export declare type TokenRule = [RegExp, string, string?];
-export declare type Token = {
+export type TokenRule = [RegExp, string, string?];
+export type Token = {
     token_type: string;
     token_text: string;
     original_text: string;
@@ -10,18 +10,18 @@ declare class lexer {
     private rules;
     private whitespace;
     constructor(rawRules: string[][], ws?: string);
-    set_input(input: any): void;
+    set_input(input: string): void;
     return_state(): {
         input: string;
         location: number;
     };
     set_state({ input, location }?: {
-        input?: any;
-        location?: number;
+        input?: null | undefined;
+        location?: number | undefined;
     }): void;
     advance({ remove_initial_space }?: {
-        remove_initial_space?: boolean;
+        remove_initial_space?: boolean | undefined;
     }): Token;
-    unput(string: any): void;
+    unput(string: string): void;
 }
 export default lexer;

package/dist/difference.d.ts

@@ -0,0 +1 @@
+export declare const differenceIsTooGreat: (a: unknown[], b: unknown[]) => boolean;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { latexEqual } from './latex-equal.js';
+export type { Latex, LiteralOpts, Mode, Opts } from './options.js';