Trivial Rules

A simple NodeJS rules engine to create RegisterItem JSON from events. This library is not responsible for saving the RegisterItems, only producing them.

Installation

npm install trivial-rules

Usage

Generating an application from a manifest file

// Import the Generator class
import { Generator } from 'trivial-rules'

// CommonJS is also supported
// const { Generator } = require('trivial-rules')

// Definte a valid manifest JSON
const manifestJSON = {
  "app_id": "a1",
  "manifest_version": 3,
  "definitions": [],
  "rules": [
    {
      "name": "Order Shipped",
      "conditions": "initialPayload.event_name == 'order.shipped'",
      "outputs": [
        [
          {
            "from": "3.01",
            "to": "amount"
          },
          {
            "from": "`Order shipped for ${initialPayload.name}`",
            "to": "description"
          }
        ]
      ],
      "enabled": true
    }
  ]
}

// Create a new generator instance and run the main function
const destinationPath = './output'
const generator = new Generator(manifestJSON, destinationPath)
await generator.main()

// Files will be written to the destination folder
// ./output/rules.js
// ./output/manifest.json
// ./output/definitions.js

Applying rules to an event

// The Rules class will be written to the destination folder, you can now import and apply with

import { Rules } from './output/rules.js'

// CommonJS:
// const Rules = require(`./output/rules.js`)

const event = { event_name: 'order.shipped' }
const out = await Rules.apply(event)
// The result is an Promise that resolves to an Array of objects the Rules logic produced.
// Example:
[
  {
    amount: 3.01,
    description: 'Order Shipped',
  }
]

Handling Errors

If an error is encountered applying rules, none of the rules will be applied and the error will be returned. This is to ensure that the rules are applied in consistently. This way, if an event fails, it can more predictable be re-played, with confidence that the rules for the event have not been partialy applied.

As such, it is the event processor's responsibility to handle the error and decide how to proceed.

Running Tests

Tests are provided via vitest. To run the tests, simply run:

npm run test

Publishing

This package is written in ESM and is converted to CJS using Rollup. This will recreate index.cjs.

Publishing steps:

1. Run Rollup

npx rollup -c

2. Bump the verson number in package.json.

3. Update the changelog to describe the changes.

4. Commit the changes, create a PR, and merge to main.

5. Finally, publish to npm from main:

npm publish