@clipboard-health/rules-engine 0.0.0

package/README.md

@@ -0,0 +1,100 @@
+# @clipboard-health/rules-engine
+
+A pure functional rules engine with two rule runners:
+
+- `firstMatch`: Runs the first rule that matches the criteria
+- `all`: Runs all the rules that matches the criteria
+
+## Table of Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Local development commands](#local-development-commands)
+
+## Install
+
+```bash
+npm install @clipboard-health/rules-engine
+```
+
+## Usage
+
+```ts
+// ./examples/rules.ts
+
+import {
+  all,
+  appendOutput,
+  firstMatch,
+  type Rule,
+  type RuleContext,
+} from "@clipboard-health/rules-engine";
+
+interface Input {
+  number1: number;
+  number2: number;
+}
+
+interface Output {
+  result: number;
+}
+
+const exampleContext: RuleContext<Input, Output> = {
+  input: {
+    number1: 2,
+    number2: 5,
+  },
+  output: [],
+};
+
+const addNumbersIfPositiveRule: Rule<Input, Output> = {
+  runIf: (input) => input.number1 > 0 && input.number2 > 0,
+  run: (context) => {
+    const { number1, number2 } = context.input;
+    const sum = number1 + number2;
+    return appendOutput(context, { result: sum });
+  },
+};
+
+const multiplyNumbersIfPositiveRule: Rule<Input, Output> = {
+  runIf: (input) => input.number1 > 0 && input.number2 > 0,
+  run: (context) => {
+    const { number1, number2 } = context.input;
+    const sum = number1 * number2;
+    return appendOutput(context, { result: sum });
+  },
+};
+
+const divideNumbersIfNegative: Rule<Input, Output> = {
+  runIf: (input) => input.number1 < 0 && input.number2 < 0,
+  run: (context) => {
+    const { number1, number2 } = context.input;
+    const sum = number1 * number2;
+    return appendOutput(context, { result: sum });
+  },
+};
+
+// Using all() applies all the rules to the context
+const allResult = all(
+  addNumbersIfPositiveRule,
+  divideNumbersIfNegative,
+  multiplyNumbersIfPositiveRule,
+).run(exampleContext);
+
+console.log(allResult.output);
+// => [{ result: 7 }, { result: 10 }]
+
+// Using firstMatch() applies the first the rules to the context
+const firstMatchResult = firstMatch(
+  divideNumbersIfNegative,
+  addNumbersIfPositiveRule,
+  multiplyNumbersIfPositiveRule,
+).run(exampleContext);
+
+console.log(firstMatchResult.output);
+// => [{ result: 7 }]
+```
+
+## Local development commands
+
+See [`package.json`](./package.json) `scripts` for a list of commands.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@clipboard-health/rules-engine",
+  "description": "A pure functional rules engine.",
+  "version": "0.0.0",
+  "bugs": "https://github.com/clipboardhealth/core-utils/issues",
+  "dependencies": {
+    "tslib": "2.6.3",
+    "type-fest": "4.25.0"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clipboardhealth/core-utils.git",
+    "directory": "packages/rules-engine"
+  },
+  "scripts": {
+    "embed": "embedme README.md"
+  },
+  "type": "commonjs",
+  "typings": "./src/index.d.ts",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./lib/appendOutput";
+export * from "./lib/rule";
+export * from "./lib/runners";

package/src/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/appendOutput"), exports);
+tslib_1.__exportStar(require("./lib/rule"), exports);
+tslib_1.__exportStar(require("./lib/runners"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/rules-engine/src/index.ts"],"names":[],"mappings":";;;AAAA,6DAAmC;AACnC,qDAA2B;AAC3B,wDAA8B"}

package/src/lib/appendOutput.d.ts

@@ -0,0 +1,6 @@
+import { type ReadonlyDeep } from "type-fest";
+import { type RuleContext } from "./rule";
+/**
+ * Rule output is immutable, do not modify existing items, only append using this function.
+ */
+export declare function appendOutput<TInput, TOutput>(context: RuleContext<TInput, TOutput>, output: ReadonlyDeep<TOutput>): RuleContext<TInput, TOutput>;

package/src/lib/appendOutput.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendOutput = appendOutput;
+/**
+ * Rule output is immutable, do not modify existing items, only append using this function.
+ */
+function appendOutput(context, output) {
+    return {
+        input: context.input,
+        output: [...context.output, output],
+    };
+}
+//# sourceMappingURL=appendOutput.js.map

package/src/lib/appendOutput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appendOutput.js","sourceRoot":"","sources":["../../../../../packages/rules-engine/src/lib/appendOutput.ts"],"names":[],"mappings":";;AAOA,oCAQC;AAXD;;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"}

package/src/lib/rule.d.ts

@@ -0,0 +1,29 @@
+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<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 appended to by previous rules by the time `run` is called.
+     */
+    runIf: (input: ReadonlyDeep<TInput>) => boolean;
+    /**
+     * A pure function that runs rule logic and returns a new context by appending to the output
+     * array.
+     *
+     * @see {@link appendOutput}
+     */
+    run: (context: TContext) => TContext;
+}

package/src/lib/rule.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=rule.js.map

package/src/lib/rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule.js","sourceRoot":"","sources":["../../../../../packages/rules-engine/src/lib/rule.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,7 @@
+import { type Rule, type RuleContext } from "../rule";
+/**
+ * Run all rules that return true for `runIf`.
+ *
+ * @param rules The rules to run.
+ */
+export declare function all<TInput, TOutput, TContext extends RuleContext<TInput, TOutput>>(...rules: Array<Rule<TInput, TOutput, TContext>>): Rule<TInput, TOutput, TContext>;

package/src/lib/runners/all.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.all = all;
+/**
+ * Run all rules that return true for `runIf`.
+ *
+ * @param rules The rules to run.
+ */
+function all(...rules) {
+    return {
+        runIf: (input) => rules.some((rule) => rule.runIf(input)),
+        run: (context) => rules
+            .filter((rule) => rule.runIf(context.input))
+            .reduce((previousContext, rule) => rule.run(previousContext), context),
+    };
+}
+//# sourceMappingURL=all.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"all.js","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/all.ts"],"names":[],"mappings":";;AAOA,kBAUC;AAfD;;;;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"}

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

@@ -0,0 +1,7 @@
+import { type Rule, type RuleContext } from "../rule";
+/**
+ * Run the first rule that returns true for `runIf`.
+ *
+ * @param rules The rules to run.
+ */
+export declare function firstMatch<TInput, TOutput, TContext extends RuleContext<TInput, TOutput>>(...rules: Array<Rule<TInput, TOutput, TContext>>): Rule<TInput, TOutput, TContext>;

package/src/lib/runners/firstMatch.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.firstMatch = firstMatch;
+/**
+ * Run the first rule that returns true for `runIf`.
+ *
+ * @param rules The rules to run.
+ */
+function firstMatch(...rules) {
+    return {
+        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;
+        },
+    };
+}
+//# sourceMappingURL=firstMatch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"firstMatch.js","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/firstMatch.ts"],"names":[],"mappings":";;AAOA,gCAUC;AAfD;;;;GAIG;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"}

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

@@ -0,0 +1,2 @@
+export * from "./all";
+export * from "./firstMatch";

package/src/lib/runners/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./all"), exports);
+tslib_1.__exportStar(require("./firstMatch"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/rules-engine/src/lib/runners/index.ts"],"names":[],"mappings":";;;AAAA,gDAAsB;AACtB,uDAA6B"}