@segment/signals-rule-engine

Backing library for signals-rule-engine

Public API Usage

Importing the Rules Engine

import { RulesEngine, type Rule, type SignalsRuntime } from "@segment/signals-rule-engine";

Defining a Rule

A rule consists of triggers and actions. Example:

const rules: Rule[] = [{
  triggers: [
    {
      ref: "current",
      subscription: {
        type: "fql";
        data: {
          contextualSignalType: { id: "network-request" },
          ir: ["match", "data.url", { value: "*order*" }],
        };
      };
    },
  ],
  actions: [
    {
      action: "send-event",
      mappings: {
        type: "track",
        event: "some-event",
        properties: {
          foo: {
            "@path": "$.current.data.body.foo",
          }
      },
    },
    { action: "reset" },
  ],
}]

Evaluating Signals

const signals: SignalsRuntime = {
  signalBuffer: [
    {
      type: "network-request",
      data: {
        url: "https://example.com/order/123",
        body: { foo: "bar" },
      },
    },
  ],
}

const result = 
  new RulesEngine(rules)
  .eval(signals);
  
console.log(result);

Output:

[
  ["track", { 
    type: "track", 
    event: "some-event", 
    properties: { foo: "bar" } 
  }],
  ["reset"]
]

Event Emitter

The Rules Engine includes an event emitter for monitoring rule evaluation and execution. You can use the on method to subscribe to specific events emitted during the evaluation process.

Available Events

• eval_rule_start: Emitted when the evaluation of a rule starts. Provides the rule being evaluated, the signal being processed, and the signal buffer.
• eval_trigger_match_result: Emitted for each trigger match result. Includes whether the match was successful, the trigger, the signal being processed, and the signal buffer.

Example Usage

import { RulesEngine, type Rule } from "@segment/signals-rule-engine";

const rules: Rule[] = [
  // ...existing rules...
];

const signalBuffer = [
  // ...existing signals...
];

const rulesEngine = new RulesEngine(rules);

rulesEngine.on("eval_rule_start", ({ rule, signal, signalBuffer }) => {
  console.log(`Evaluating rule:`, rule);
});

rulesEngine.on("eval_trigger_match_result", ({ match, trigger, signal, signalBuffer }) => {
  console.log(`Trigger match result:`, { match, trigger });
});

const result = rulesEngine.eval({ signalBuffer });

console.log(result);

Output:

Evaluating rule: { ref: "current" }
Trigger match result: { match: true, trigger: { ref: "current" } }
Trigger match result: { match: true, trigger: { ref: "other" } }
[
  ["track", { 
    type: "track", 
    event: "some-event", 
    properties: { foo: "bar" } 
  }],
  ["reset"]
]

The on method allows you to listen for other events as well, depending on your use case.

See the src/__tests__/integration.test.ts file for more advanced usage and test cases...