@truecalc/core

WebAssembly-powered spreadsheet formula engine for JavaScript/TypeScript.

Install

npm install @truecalc/core

Usage

Node.js (CJS)

Works out of the box — no bundler configuration needed.

const { evaluate, validate, list_functions } = require('@truecalc/core');

const result = evaluate('SUM(A1, B1)', { A1: 100, B1: 200 });
// => { type: 'number', value: 300 }

Vite

Install the wasm plugin first:

npm install -D vite-plugin-wasm

Add it to vite.config.js:

import wasm from 'vite-plugin-wasm';

export default {
  plugins: [wasm()],
};

Then import and use normally:

import { evaluate } from '@truecalc/core';

const result = evaluate('IF(A1 > 0, "yes", "no")', { A1: 1 });
// => { type: 'text', value: 'yes' }

webpack 5

webpack 5 supports WebAssembly natively. Enable the experiment in webpack.config.js:

module.exports = {
  experiments: {
    asyncWebAssembly: true,
  },
};

API

evaluate(formula, variables)

Evaluates a formula with the given variable bindings.

evaluate('SUM(A1, B1)', { A1: 100, B1: 200 })
// => { type: 'number', value: 300 }

evaluate('CONCAT("Hello, ", name)', { name: 'world' })
// => { type: 'text', value: 'Hello, world' }

Return value shape:

type	Shape
number	{ type: 'number', value: 6 }
text	{ type: 'text', value: 'yes' }
boolean	{ type: 'boolean', value: true }
error	{ type: 'error', error: '#NAME?' }
empty	{ type: 'empty', value: null }

validate(formula)

Checks whether a formula is syntactically valid without evaluating it.

validate('SUM(A1, B1)')  // => { valid: true }
validate('SUM(A1,')      // => { valid: false, error: '...' }

list_functions()

Returns metadata for all built-in functions.

const fns = list_functions();