feat: implement serialization support for Parser (fixes #3509) (#3525)

Author: josdejong

docs/expressions/parsing.md

@@ -234,3 +234,31 @@ Some care is taken to mutate the same object that is passed into mathjs, so they
 For less reliance on this blacklist, scope can also be a `Map`, which allows mathjs expressions to define variables and functions of any name.
 
 For more, see [examples of custom scopes](../../examples/advanced/custom_scope_objects.js).
+
+## Serialization
+
+All mathjs data types can be serialized. A scope containing variables can therefore be safely serialized too. However, in the expression parser it is possible to define functions, like:
+
+```
+f(x) = x^2
+```
+
+Such a custom function cannot be serialized on its own, since it may be bound to other variables in the scope.
+
+A [`Parser`](#parser) can safely serialize all variables and functions evaluated via the expression parser:
+
+```js
+const parser = math.parser()
+
+// evaluate some expressions
+parser.evaluate('w = 2')
+parser.evaluate('f(x) = x^w')
+parser.evaluate('c = f(3)') // 9
+
+// serialize the parser with its state
+const str = JSON.stringify(parser)
+
+// deserialize the parser again
+const parser2 = JSON.parse(str, math.reviver)
+parser.evaluate('f(4)') // 16
+```

src/expression/Parser.js

@@ -1,4 +1,5 @@
 import { factory } from '../utils/factory.js'
+import { isFunction } from '../utils/is.js'
 import { createEmptyMap, toObject } from '../utils/map.js'
 
 const name = 'Parser'
@@ -157,5 +158,42 @@ export const createParserClass = /* #__PURE__ */ factory(name, dependencies, ({
     this.scope.clear()
   }
 
+  Parser.prototype.toJSON = function () {
+    const json = {
+      mathjs: 'Parser',
+      variables: {},
+      functions: {}
+    }
+
+    for (const [name, value] of this.scope) {
+      if (isFunction(value)) {
+        if (!isExpressionFunction(value)) {
+          throw new Error(`Cannot serialize external function ${name}`)
+        }
+
+        json.functions[name] = `${value.syntax} = ${value.expr}`
+      } else {
+        json.variables[name] = value
+      }
+    }
+
+    return json
+  }
+
+  Parser.fromJSON = function (json) {
+    const parser = new Parser()
+
+    Object.entries(json.variables).forEach(([name, value]) => parser.set(name, value))
+    Object.entries(json.functions).forEach(([_name, fn]) => parser.evaluate(fn))
+
+    return parser
+  }
+
   return Parser
 }, { isClass: true })
+
+function isExpressionFunction (value) {
+  return typeof value === 'function' &&
+    typeof value.syntax === 'string' &&
+    typeof value.expr === 'string'
+}

src/expression/node/FunctionAssignmentNode.js

@@ -97,7 +97,8 @@ export const createFunctionAssignmentNode = /* #__PURE__ */ factory(name, depend
       })
 
       // compile the function expression with the child args
-      const evalExpr = this.expr._compile(math, childArgNames)
+      const expr = this.expr
+      const evalExpr = expr._compile(math, childArgNames)
       const name = this.name
       const params = this.params
       const signature = join(this.types, ',')
@@ -116,6 +117,7 @@ export const createFunctionAssignmentNode = /* #__PURE__ */ factory(name, depend
         }
         const fn = typed(name, signatures)
         fn.syntax = syntax
+        fn.expr = expr.toString()
 
         scope.set(name, fn)
 

test/unit-tests/json/replacer.test.js

@@ -187,6 +187,36 @@ describe('replacer', function () {
     assert.deepStrictEqual(JSON.parse(JSON.stringify(node, replacer)), json)
   })
 
+  it('should stringify a Parser', function () {
+    const parser = new math.Parser()
+    parser.evaluate('a = 42')
+    parser.evaluate('w = bignumber(2)')
+    parser.evaluate('f(x) = w * x')
+    parser.evaluate('c = f(3)')
+
+    const json = {
+      mathjs: 'Parser',
+      variables: {
+        a: 42,
+        c: { mathjs: 'BigNumber', value: '6' },
+        w: { mathjs: 'BigNumber', value: '2' }
+      },
+      functions: {
+        f: 'f(x) = w * x'
+      }
+    }
+
+    assert.deepStrictEqual(JSON.parse(JSON.stringify(parser)), json)
+    assert.deepStrictEqual(JSON.parse(JSON.stringify(parser, replacer)), json)
+  })
+
+  it('should throw when stringifying a Parser containing external functions', function () {
+    const parser = new math.Parser()
+    parser.set('f', (x) => 2 * x)
+
+    assert.throws(() => JSON.stringify(parser), /Cannot serialize external function f/)
+  })
+
   it('should stringify Help', function () {
     const h = new math.Help({ name: 'foo', description: 'bar' })
     const json = '{"mathjs":"Help","name":"foo","description":"bar"}'

test/unit-tests/json/reviver.test.js

@@ -246,4 +246,25 @@ describe('reviver', function () {
     assert.strictEqual(node.type, 'OperatorNode')
     assert.strictEqual(node.toString(), '2 + sin(3 x)')
   })
+
+  it('should parse a stringified Parser', function () {
+    const json = JSON.stringify({
+      mathjs: 'Parser',
+      variables: {
+        a: 42,
+        c: { mathjs: 'BigNumber', value: '6' },
+        w: { mathjs: 'BigNumber', value: '2' }
+      },
+      functions: {
+        f: 'f(x) = w * x'
+      }
+    })
+
+    const parser = JSON.parse(json, reviver)
+
+    assert.deepStrictEqual(parser.get('a'), 42)
+    assert.deepStrictEqual(parser.get('c'), math.bignumber('6'))
+    assert.deepStrictEqual(parser.get('w'), math.bignumber('2'))
+    assert.deepStrictEqual(parser.evaluate('f(4)'), math.bignumber('8'))
+  })
 })