@unleash/yggdrasil
v0.1.0-beta.2
Published
Direct bindings to the Yggdrasil grammar for NodeJS
Downloads
3
Keywords
Readme
Wasm Engine
Introduction
This project is a simple WASM cross compilation of the Yggdrasil engine.
Currently, this only supports direct access to the Yggdrasil rule grammar, and is not a full implementation of the Unleash logic.
Please note that this is an experimental project and the API is subject to change rapidly as we iterate on the ideas here.
Usage
First, install the package:
$ yarn add @unleash/yggdrasil-engine
Then, you can use it in your code:
const yggdrasil = require("../pkg/wasm_engine.js");
const context = {
userId: "7",
};
const ruleEnabled = yggdrasil.evaluate("user_id > 6", context); //returns true
const ruleEnabled = yggdrasil.evaluate("user_id > 8", context); //returns false
const ruleEnabled = yggdrasil.evaluate("some rule that is nonsense", context); //raises an error
Rule fragments that are passed to the evaluate function must be valid Yggdrasil rules; rules that are invalid will raise an error. Valid rules will always result in a boolean value when evaluated.
Context properties
Currently the context is built to match the Unleash Context, so the special properties that are supported are:
| Property Name | Use in Unleash | | --- |--- | | environment | the environment the app is running in | | userId | an identifier for the current user | | sessionId | identifier for the current session | | remoteAddress | the app's IP address | | currentTime | the current time in ISO format | | properties | a key-value store of any data you want |
You don't have to use any of these if they have no meaning to you, using the properties object is the most flexible way to pass data into the engine but it does mean the rules you need to produce are slightly more verbose:
const context = {
properties: {
customProperty: "7",
},
};
const result = yggdrasil.evaluate('context["customProperty"] > 6', context); // matches the "customProperty" field on the context and returns true
Please note that you must pass a context object, even if it is empty. Failure to do so will result in an error being raised by the engine.
Development
This project uses wasm-bindgen to generate the Rust/JS bindings. To build the project, run:
$ wasm-pack build --target nodejs --scope public
Running tests can be done with:
$ wasm-pack test --node
There's also a set of integration tests in the e2e-tests
directory, which will ensure that the WASM module can be loaded and used in Node JS and that calls to the engine are correctly managed. These must be run within the e2e-tests directory:
$ cd e2e-tests
$ yarn jest