match-rules

    1.3.8 • Public • Published

    match-rules

    A tiny (1kB GZipped) zero dependency JavaScript utility that lets you write your conditional business logic in a declarative way (React like).

    It can be used with feature flags, complex conditions, conditional rendering, and the rest is your imagination.

    I wrote a detailed blog post, please do read it to understand the thought process in depth (5 mins tops).

    Install

    Build Status Build Status Coverage Status npm npm NPM npm DeepScan grade

    npm bundle size

    Through Yarn yarn add match-rules

    Through npm npm install match-rules --save

    Usage

    ES6

    import matchRules from "match-rules";

    ES5

    const matchRules = require("match-rules").default;

    TypeScript

    import matchRules from "match-rules";

    API

    // returns a boolean value.
    matchRules(
      sourceObject, // can be any object with data.
      RULES_OBJECT, // you can also pass multiple rules in an array [RULE_ONE, RULE_TWO],
      options // (optional)
    );
    
    const options = {
      operator: "and", // (optional, default: 'and') in case of multiple rules you can pass 'and' or 'or'. In case of 'or' your rules will be compared with 'or' operator. Default is 'and'
      debug: true, // (optional, default: false) when debug is true, it logs a trace object which will tell you which rule failed and with what values of source and rules object.
    };
    
    // NOTE: all the rules inside a single rule are concatenated by 'and' operator.

    Live Playground

    Live Example on Stackblitz

    Server Side

    This module can be used with Node as well.

    Example (Usecase)

    // rules object
    import matchRules from "match-rules";
    
    const SHOW_JOB_RULE = {
      hasVisa: true,
      profile: {
        country: "US",
        yearsOfExperience: (exp, sourceObject) => exp > 3,
      },
    };
    
    // source object
    const user = {
      username: "someName",
      hasVisa: true,
      profile: {
        country: "US",
        yearsOfExperience: 5,
        yearOfGraduation: 2011,
      },
    };
    
    // pass source and rules
    if (matchRules(user, SHOW_JOB_RULE)) {
      //... do something conditionally.
    }

    Features

    • Multiple rules support - you can pass multiple rules dealing with a common source object.

    • Graceful exit - returns false if the asked property in the rule doesn’t exist in the source object.

    • Debugging - when enabled logs a trace object for all the keys in the rule with a meaningful message of what went wrong.

    • Function support - you can pass custom functions in the rule for handling complex conditions.

    • Nested Rules - you can pass a rule no matter how deep your data source is.

    • Multiple operator support - you can pass or / and operators in case of multiple rules. Dillinger is a cloud-enabled, mobile-ready, offline-storage, AngularJS powered HTML5 Markdown editor.

    Why would you want to use it in your projects.

    • Reduces cognitive complexity.

    • Easy to maintain, declarative in nature.

    • Code is more readable, you can separate conditional logic in a rules.js file.

    • You do not have to write unit tests for those conditions individually, just take a snapshot at max.

    • Reduce code redundancy (you can compose and extend rules).

    • You do not have to traverse nested objects, just write your rules with the same structure.

    • Any conditional (complex) case can be handled using a function.

    • Easily manage your AB testing logic.

    Function Support:

    So far it is capable to handle any condition since you can write your own functions in the rule.

    when it encounters a function it passes the value (as the first parameter) and original source object (as the second parameter) from the source to that function matching the corresponding key of that level.

    Using a combination of key's value and original source object you can handle complex conditions.

    For example:

    const SHOW_ADS_RULES = {
      profile: {
        age: (value, sourceObject) =>
          value > 18 && value < 55 && sourceObject.admin === true,
      },
    };
    
    const source = {
      profile: {
        age: 20,
      },
      admin: true,
    };
    
    // so value of 20 (First param) and complete source object (Second Param) will be passed to that function.
    // NOTE: you should always return boolean value from the function you implement.

    Extending Rules (avoid redundancy)

    const SHOW_ADS_RULES = {
      onboarding: true,
      admin: false,
      profile: {
        country: "US",
        school: "MIT",
        age: (value) => value > 18 && value < 55,
      },
    };
    
    // show a different Ad if the country is India.
    const SHOW_ADS_RULES_INDIA = {
      ...SHOW_ADS_RULES,
      profile: {
        ...SHOW_ADS_RULES.profile,
        country: "India",
      },
    };

    More examples

    Ex 1. Feature Flags

    import matchRules from "match-rules";
    
    // this object can come from your app state
    const sourceObject = {
      enable_unique_feature: true,
      when_user_is_admin: true,
      age_more_than_18: 25,
    };
    
    // Rule
    const ENABLE_UNIQUE_FEATURE = {
      enable_unique_feature: true,
      when_user_is_admin: true,
      age_more_than_18: (value, sourceObject) => value > 18,
    };
    
    if (matchRules(sourceObject, ENABLE_UNIQUE_FEATURE)) {
      // render unique feature
    }

    Ex 2. Multiple Rules and functions implementation

    import matchRules from "match-rules";
    
    // this object can come from your app state
    const sourceObject = {
      enable_unique_feature: true,
      profile: {
        age: 18,
      },
    };
    
    // Rules
    const ENABLE_UNIQUE_FEATURE = {
      enable_unique_feature: true,
    };
    
    const ENABLE_UNIQUE_FEATURE_WITH_AGE_18YO = {
      profile: {
        age: (value, sourceObject) => value > 18,
      },
    };
    
    // by default multiple rules will be combined using AND operator
    if (
      matchRules(sourceObject, [
        ENABLE_UNIQUE_FEATURE,
        ENABLE_UNIQUE_FEATURE_WITH_AGE_18YO,
      ])
    ) {
      // render unique feature
    }

    Ex 3. Multiple Rules using OR operator

    import matchRules from "match-rules";
    
    // this object can come from your app state
    const sourceObject = {
      enable_unique_feature: true,
      profile: {
        age: 18,
        country: "US",
      },
    };
    
    // Rules
    const ENABLE_UNIQUE_FEATURE_FOR_US = {
      profile: {
        country: "US",
      },
    };
    
    const ENABLE_UNIQUE_FEATURE_FOR_INDIA = {
      profile: {
        country: "IN",
      },
    };
    
    // to combine rules using OR, (display feature if user is from US or INDIA)
    if (
      matchRules(
        sourceObject,
        [ENABLE_UNIQUE_FEATURE_FOR_US, ENABLE_UNIQUE_FEATURE_FOR_INDIA],
        { operator: "or" }
      )
    ) {
      // render unique feature
    }
    
    // you can pass as many rules you want

    Ex 4. using functions

    import matchRules from "match-rules";
    
    // this object can come from your app state
    const sourceObject = {
      enable_unique_feature: true,
      profile: {
        age: 18,
        country: "US",
      },
    };
    
    // Rules
    const ENABLE_UNIQUE_FEATURE_FOR_US_OR_INDIA = {
      profile: {
        country: (value, sourceObject) => value === "US" || value === "IN",
      },
    };
    
    // to combine rules using OR, (display feature if user is from US or INDIA)
    if (matchRules(sourceObject, ENABLE_UNIQUE_FEATURE_FOR_US_OR_INDIA)) {
      // render unique feature
    }
    
    // you can use functions to deal with complex scenarios

    Ex 5. Rule for deep source objects

    import matchRules from "match-rules";
    
    // this object can come from your app state
    const sourceObject = {
      enable_unique_feature: true,
      userData: {
        personalData: {
          profile: {
            age: 18,
            country: "US",
          },
        },
      },
    };
    
    // Rules
    const ENABLE_UNIQUE_FEATURE_FOR_US_OR_INDIA = {
      userData: {
        personalData: {
          profile: {
            country: (value, sourceObject) => value === "US" || value === "IN",
          },
        },
      },
    };
    
    // to combine rules using OR, (display feature if user is from US or INDIA)
    if (matchRules(sourceObject, ENABLE_UNIQUE_FEATURE_FOR_US_OR_INDIA)) {
      // render unique feature
    }
    // you can use functions to deal with complex scenarios

    Ex 6. Dynamic Rules | RULES as functions

    // example where you have to match the dynamically generated rule
    const dataFromServer = {
      user_id: 123, // created by user
      item_id: '87df83b',
      item_type: 'Post'
    }
    
    const userSource = {
      id: 123,
    }
    
    const DYNAMIC_USER_RULE = (itemCreatedByUserParam) => {
      return {
        id: itemCreatedByUserParam.user_id,
      }
    }
    
    if(matchRules(userSource, DYNAMIC_USER_RULE(dataFromServer)) {
     // show edit option to creator of this post
    }

    Debugging

    when enabled logs a trace object for all the keys in the rule with a meaningful message of what went right and wrong.

    matchRules(sourceObject, RULES, { debug: true })
    
    // sample trace object
    {
      "0": {
        "company": {
          "enable_feature": {
            "enable_feature_for_user": {
              "value": true,
              "message": "Value equated for the given rule, Rule data: true (type: boolean), Source data: true (type: boolean)"
            }
          },
          "enable_people_management": {
            "value": true,
            "message": "Value equated for the given rule, Rule data: true (type: boolean), Source data: true (type: boolean)"
          }
        },
        "company_admin": {
          "value": true,
          "message": "Value equated for the given rule, Rule data: true (type: boolean), Source data: true (type: boolean)"
        },
        "enable_special_feature": {
          "value": true,
          "message": "Value equated for the given rule, Rule data: false (type: boolean), Source data: false (type: boolean)"
        },
        "temp": {
          "value": false,
          "message": "Function was executed for the given rule with value: 3 (type: number)"
        }
      }
    }

    Development

    For development, please make the changes in the code and write appropriate unit test case. Feel free to send across a Pull Request if it doesn't fit your use-case.

    Zero dependency library

    match-rules does not have any dependency, it is just 1kB (GZipped) in size.

    Install

    npm i match-rules

    DownloadsWeekly Downloads

    2

    Version

    1.3.8

    License

    MIT

    Unpacked Size

    19.4 kB

    Total Files

    8

    Last publish

    Collaborators

    • naman03malhotra