kibana/packages/kbn-tinymath/README.md

kbn-tinymath

kbn-tinymath is a tiny arithmetic and function evaluator for simple numbers and arrays. Named properties can be accessed from an optional scope parameter. It's available as an expression function called math in Canvas, and the grammar/AST structure is available for use by Kibana plugins that want to use math.

See Function Documentation for details on built-in functions available in Tinymath.

const { evaluate } = require('@kbn/tinymath');

// Simple math
evaluate('10 + 20'); // 30
evaluate('round(3.141592)') // 3

// Named properties
evaluate('foo + 20', {foo: 5}); // 25

// Arrays
evaluate('bar + 20', {bar: [1, 2, 3]}); // [21, 22, 23]
evaluate('bar + baz', {bar: [1, 2, 3], baz: [4, 5, 6]}); // [5, 7, 9]
evaluate('multiply(bar, baz) / 10', {bar: [1, 2, 3], baz: [4, 5, 6]}); // [0.4, 1, 1.8]

Adding Functions

Functions can be injected, and built in function overwritten, via the 3rd argument to evaluate:

const { evaluate } = require('@kbn/tinymath');

evaluate('plustwo(foo)', {foo: 5}, {
    plustwo: function(a) {
        return a + 2;
    }
}); // 7

Parsing

You can get to the parsed AST by importing parse

const { parse } = require('@kbn/tinymath');

parse('1 + random()')
/*
{
   "name": "add",
   "args": [
      1,
      {
         "name": "random",
         "args": []
      }
   ]
}
*/

Notes

• Floating point operations have the normal Javascript limitations

Building kbn-tinymath

This package is rebuilt when running yarn kbn bootstrap, but can also be build directly using yarn build from the packages/kbn-tinymath directory.

Running tests

To test @kbn/tinymath from Kibana, run node scripts/jest --config packages/kbn-tinymath/jest.config.js from the top level of Kibana.

To test grammar changes it is required to run a build task before the test suite.