@clipboard-health/rules-engine 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [0.1.1](https://github.com/ClipboardHealth/cbh-core/compare/rules-engine-0.1.0...rules-engine-0.1.1) (2023-12-22)
+
 ## 0.1.0 (2023-12-20)
 
 

package/README.md

@@ -2,8 +2,8 @@
 
 Exposes a functional rules-engine with 2 engines:
 
-- firstMatch: Runs the first rule that matches the criteria
-- all: Runs all the rules that matches the criteria
+- `firstMatch`: Runs the first rule that matches the criteria
+- `all`: Runs all the rules that matches the criteria
 
 ## Table of Contents
 
@@ -22,7 +22,13 @@ npm install @clipboard-health/rules-engine
 ```ts
 // ./examples/rules.ts
 
-import { all, firstMatch, type Rule, type RuleContext } from "@clipboard-health/rules-engine";
+import {
+  all,
+  appendOutput,
+  firstMatch,
+  type Rule,
+  type RuleContext,
+} from "@clipboard-health/rules-engine";
 
 interface Input {
   number1: number;
@@ -33,9 +39,7 @@ interface Output {
   result: number;
 }
 
-interface ExampleRuleContext extends RuleContext<Input, Output> {}
-
-const exampleContext: ExampleRuleContext = {
+const exampleContext: RuleContext<Input, Output> = {
   input: {
     number1: 2,
     number2: 5,
@@ -43,33 +47,30 @@ const exampleContext: ExampleRuleContext = {
   output: [],
 };
 
-const addNumbersIfPositiveRule: Rule<ExampleRuleContext> = {
-  runIf: (context) => context.input.number1 > 0 && context.input.number2 > 0,
+const addNumbersIfPositiveRule: Rule<Input, Output> = {
+  runIf: (input) => input.number1 > 0 && input.number2 > 0,
   run: (context) => {
     const { number1, number2 } = context.input;
     const sum = number1 + number2;
-    context.output.push({ result: sum });
-    return context;
+    return appendOutput(context, { result: sum });
   },
 };
 
-const multiplyNumbersIfPositiveRule: Rule<ExampleRuleContext> = {
-  runIf: (context) => context.input.number1 > 0 && context.input.number2 > 0,
+const multiplyNumbersIfPositiveRule: Rule<Input, Output> = {
+  runIf: (input) => input.number1 > 0 && input.number2 > 0,
   run: (context) => {
     const { number1, number2 } = context.input;
     const sum = number1 * number2;
-    context.output.push({ result: sum });
-    return context;
+    return appendOutput(context, { result: sum });
   },
 };
 
-const divideNumbersIfNegative: Rule<ExampleRuleContext> = {
-  runIf: (context) => context.input.number1 < 0 && context.input.number2 < 0,
+const divideNumbersIfNegative: Rule<Input, Output> = {
+  runIf: (input) => input.number1 < 0 && input.number2 < 0,
   run: (context) => {
     const { number1, number2 } = context.input;
     const sum = number1 * number2;
-    context.output.push({ result: sum });
-    return context;
+    return appendOutput(context, { result: sum });
   },
 };
 
@@ -80,7 +81,6 @@ const allResult = all(
   multiplyNumbersIfPositiveRule,
 ).run(exampleContext);
 
-// eslint-disable-next-line no-console
 console.log(allResult.output); // AllResult.output = [{ result: 7 }, { result: 10 }]
 
 // Using firstMatch() applies the first the rules to the context
@@ -90,7 +90,6 @@ const firstMatchResult = firstMatch(
   multiplyNumbersIfPositiveRule,
 ).run(exampleContext);
 
-// eslint-disable-next-line no-console
 console.log(firstMatchResult.output); // [{ result: 7 }]
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/rules-engine",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "./src/index.js",
   "scripts": {
     "build": "nx build rules-engine",
@@ -8,5 +8,8 @@
     "lint": "nx lint rules-engine",
     "test": "nx test rules-engine"
   },
+  "dependencies": {
+    "type-fest": "4.8.3"
+  },
   "type": "commonjs"
 }

package/src/lib/append-output.d.ts

@@ -1,3 +1,7 @@
+import { type ReadonlyDeep } from "type-fest";
 import { type RuleContext } from "./rule";
-export declare function appendOutput<TInput, TOutput>(context: RuleContext<TInput, TOutput>, output: TOutput): RuleContext<TInput, TOutput>;
+/**
+ * Rule output is immutable, do not modify existing items, only append.
+ */
+export declare function appendOutput<TInput, TOutput>(context: RuleContext<TInput, TOutput>, output: ReadonlyDeep<TOutput>): RuleContext<TInput, TOutput>;
 //# sourceMappingURL=append-output.d.ts.map

package/src/lib/append-output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"append-output.d.ts","sourceRoot":"","sources":["../../../../../packages/rules-engine/src/lib/append-output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAC1C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,MAAM,EAAE,OAAO,GACd,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAK9B"}
+{"version":3,"file":"append-output.d.ts","sourceRoot":"","sources":["../../../../../packages/rules-engine/src/lib/append-output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAC1C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,GAC5B,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAK9B"}

package/src/lib/append-output.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.appendOutput = void 0;
+/**
+ * Rule output is immutable, do not modify existing items, only append.
+ */
 function appendOutput(context, output) {
     return {
         input: context.input,

package/src/lib/append-output.js.map

@@ -1 +1 @@
-{"version":3,"file":"append-output.js","sourceRoot":"","sources":["../../../../../packages/rules-engine/src/lib/append-output.ts"],"names":[],"mappings":";;;AAEA,SAAgB,YAAY,CAC1B,OAAqC,EACrC,MAAe;IAEf,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC;KACpC,CAAC;AACJ,CAAC;AARD,oCAQC"}
+{"version":3,"file":"append-output.js","sourceRoot":"","sources":["../../../../../packages/rules-engine/src/lib/append-output.ts"],"names":[],"mappings":";;;AAIA;;GAEG;AACH,SAAgB,YAAY,CAC1B,OAAqC,EACrC,MAA6B;IAE7B,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC;KACpC,CAAC;AACJ,CAAC;AARD,oCAQC"}

package/src/lib/rule.d.ts

@@ -1,9 +1,29 @@
-export interface RuleContext<TInput = unknown, TOutput = unknown> {
-    input: TInput;
-    output: TOutput[];
+import { type ReadonlyDeep } from "type-fest";
+export interface RuleContext<TInput, TOutput> {
+    /**
+     * Input is immutable, rules must not modify it.
+     */
+    input: ReadonlyDeep<TInput>;
+    /**
+     * Output is immutable, do not modify existing items, only append.
+     *
+     * @see {@link appendOutput}
+     */
+    output: ReadonlyArray<ReadonlyDeep<TOutput>>;
 }
-export interface Rule<TContext extends RuleContext> {
-    runIf: (context: TContext) => boolean;
+export interface Rule<TInput, TOutput, TContext extends RuleContext<TInput, TOutput> = RuleContext<TInput, TOutput>> {
+    /**
+     * Returns whether the rule should run or not.
+     *
+     * Only the `input` and not the full `context` is passed to `runIf`. This prevents rules from
+     * relying on `output`, which may be modified by previous rules by the time `run` is called.
+     */
+    runIf: (input: ReadonlyDeep<TInput>) => boolean;
+    /**
+     * Runs the actual rule and returns a new context by appending to the output array.
+     *
+     * @see {@link appendOutput}
+     */
     run: (context: TContext) => TContext;
 }
 //# sourceMappingURL=rule.d.ts.map

package/src/lib/rule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule.d.ts","sourceRoot":"","sources":["../../../../../packages/rules-engine/src/lib/rule.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,IAAI,CAAC,QAAQ,SAAS,WAAW;IAChD,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC;IACtC,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,QAAQ,CAAC;CACtC"}
+{"version":3,"file":"rule.d.ts","sourceRoot":"","sources":["../../../../../packages/rules-engine/src/lib/rule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,MAAM,WAAW,WAAW,CAAC,MAAM,EAAE,OAAO;IAC1C;;OAEG;IACH,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAE5B;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,IAAI,CACnB,MAAM,EACN,OAAO,EACP,QAAQ,SAAS,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC;IAE5E;;;;;OAKG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC;IAEhD;;;;OAIG;IACH,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,QAAQ,CAAC;CACtC"}

package/src/lib/runners/all.d.ts

@@ -1,9 +1,8 @@
-import { type Rule, type RuleContext } from "../..";
+import { type Rule, type RuleContext } from "../rule";
 /**
- * Runs all the rules that return true for `runIf`.
+ * Runs all rules that return true for `runIf`.
  *
  * @param rules The rules to run.
- * @returns Rule<TContext>
  */
-export declare function all<TContext extends RuleContext>(...rules: Array<Rule<TContext>>): Rule<TContext>;
+export declare function all<TInput, TOutput, TContext extends RuleContext<TInput, TOutput>>(...rules: Array<Rule<TInput, TOutput, TContext>>): Rule<TInput, TOutput, TContext>;
 //# sourceMappingURL=all.d.ts.map

package/src/lib/runners/all.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"all.d.ts","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/all.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,QAAQ,SAAS,WAAW,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAejG"}
+{"version":3,"file":"all.d.ts","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/all.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,SAAS,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAChF,GAAG,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,GAC/C,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAQjC"}

package/src/lib/runners/all.js

@@ -2,24 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.all = void 0;
 /**
- * Runs all the rules that return true for `runIf`.
+ * Runs all rules that return true for `runIf`.
  *
  * @param rules The rules to run.
- * @returns Rule<TContext>
  */
 function all(...rules) {
     return {
-        runIf: function (context) {
-            return rules.some((rule) => rule.runIf(context));
-        },
-        run: function (context) {
-            return rules.reduce((previousContext, rule) => {
-                if (rule.runIf(context)) {
-                    return rule.run(previousContext);
-                }
-                return previousContext;
-            }, context);
-        },
+        runIf: (input) => rules.some((rule) => rule.runIf(input)),
+        run: (context) => rules
+            .filter((rule) => rule.runIf(context.input))
+            .reduce((previousContext, rule) => rule.run(previousContext), context),
     };
 }
 exports.all = all;

package/src/lib/runners/all.js.map

@@ -1 +1 @@
-{"version":3,"file":"all.js","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/all.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,SAAgB,GAAG,CAA+B,GAAG,KAA4B;IAC/E,OAAO;QACL,KAAK,EAAE,UAAU,OAAO;YACtB,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACnD,CAAC;QACD,GAAG,EAAE,UAAU,OAAO;YACpB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,eAAe,EAAE,IAAI,EAAE,EAAE;gBAC5C,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE;oBACvB,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;iBAClC;gBAED,OAAO,eAAe,CAAC;YACzB,CAAC,EAAE,OAAO,CAAC,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC;AAfD,kBAeC"}
+{"version":3,"file":"all.js","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/all.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACH,SAAgB,GAAG,CACjB,GAAG,KAA6C;IAEhD,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzD,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CACf,KAAK;aACF,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;aAC3C,MAAM,CAAC,CAAC,eAAe,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3E,CAAC;AACJ,CAAC;AAVD,kBAUC"}

package/src/lib/runners/first-match.d.ts

@@ -1,9 +1,9 @@
-import { type Rule, type RuleContext } from "../..";
+import { type Rule, type RuleContext } from "../rule";
 /**
- * Runs the first rule that returns true for `runIf`.
+ * Run the first rule that returns true for `runIf`.
  *
  * @param rules The rules to run.
  * @returns A rule that runs the first rule that matches the context.
  */
-export declare function firstMatch<TContext extends RuleContext>(...rules: Array<Rule<TContext>>): Rule<TContext>;
+export declare function firstMatch<TInput, TOutput, TContext extends RuleContext<TInput, TOutput>>(...rules: Array<Rule<TInput, TOutput, TContext>>): Rule<TInput, TOutput, TContext>;
 //# sourceMappingURL=first-match.d.ts.map

package/src/lib/runners/first-match.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"first-match.d.ts","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/first-match.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,SAAS,WAAW,EACrD,GAAG,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAC9B,IAAI,CAAC,QAAQ,CAAC,CAWhB"}
+{"version":3,"file":"first-match.d.ts","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/first-match.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,SAAS,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACvF,GAAG,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,GAC/C,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAQjC"}

package/src/lib/runners/first-match.js

@@ -2,18 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.firstMatch = void 0;
 /**
- * Runs the first rule that returns true for `runIf`.
+ * Run the first rule that returns true for `runIf`.
  *
  * @param rules The rules to run.
  * @returns A rule that runs the first rule that matches the context.
  */
 function firstMatch(...rules) {
     return {
-        runIf: function (context) {
-            return rules.some((rule) => rule.runIf(context));
-        },
-        run: function (context) {
-            const rule = rules.find((rule) => rule.runIf(context));
+        runIf: (input) => rules.some((rule) => rule.runIf(input)),
+        run: (context) => {
+            const rule = rules.find((rule) => rule.runIf(context.input));
             return rule ? rule.run(context) : context;
         },
     };

package/src/lib/runners/first-match.js.map

@@ -1 +1 @@
-{"version":3,"file":"first-match.js","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/first-match.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,SAAgB,UAAU,CACxB,GAAG,KAA4B;IAE/B,OAAO;QACL,KAAK,EAAE,UAAU,OAAO;YACtB,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACnD,CAAC;QACD,GAAG,EAAE,UAAU,OAAO;YACpB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAEvD,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC;AAbD,gCAaC"}
+{"version":3,"file":"first-match.js","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/first-match.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,SAAgB,UAAU,CACxB,GAAG,KAA6C;IAEhD,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzD,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE;YACf,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YAC7D,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC;AAVD,gCAUC"}