@unly/conditions-matcher

Conditions-matcher

Compares a given context with a filter (a set of conditions) and resolves whether the context checks the filter. Strongly inspired by GraphQL filters.

Use cases are:

• Compare a given context with a set or conditions, to see if it matches those conditions
• We use it at Unly to resolve which financing solutions apply to a student, depending on that student's situation

The biggest strengths of this plugin are:

• Flexibility: You compose your own filter, by defining conditions within it that depends on your business logic.
  • You have access to a wide range of conditional operators (contains, endsWith, greaterThan, etc.).
  • You have access to the same logical operators as those available in GraphQL (AND, OR, NOT).
  • You can nest those operators within themselves, without limit.
• Robustness: There is an important test suite (unit tests) written to make sure to detect regressions and only ship well-tested and quality software. We also follow Semantic Versioning.

This package was developed after opening a StackOverflow question, we were disappointed not to find an existing implementation and therefore built our own.

• Getting started
  • Installation
  • Usage
    • Import in you project
    • Function prototype
    • Documentation
• Contributing
  • Working locally
  • Test
  • Versions
    • SemVer
    • Release a new version
  • Releasing and publishing
• License

Getting started

Installation

Using npm :

npm i @unly/conditions-matcher

Using yarn :

yarn add @unly/conditions-matcher

Usage

Import in you project

ES5

const contextMatcher = require("@unly/conditions-matcher");

ES6

import contextMatcher from "@unly/conditions-matcher";

See the examples for more details, clone the project to play around with those. Then please check the conditional operators documentation here

Function prototype

const result: boolean = contextMatcher(filter, context, options);

filter: Contains all the conditions that constitute the said filter. For a complete list of conditions and operators, see the documentation. Example :

const filter = {
  AND: [
    { "school_gpa__lessThan": 3 },
    { "school_name__contains": "business" },
    { "foo__eq": "bar" },
  ],
};

context: Is an object containing the data (context) to match against the filter, to know whether it passes the conditions or not. Example :

const context = {
  'school': {
      name: 'Awesome business school',
      gpa: 2.5
  },
};

options: Optional configuration object.

This example will return the following in result:

{
  status: true, // Means the check passed, the context therefore passes the filter's conditions
  ignoredConditions: [ // Contains conditions that were ignored due to a lack of data in `context`
    {
      status: null, // "null" because no check could be performed (lack of data)
      rule: 'foo__eq',
      conditionalOperator: 'eq',
      path: 'foo',
      valueInContext: undefined,
      reason: 'Error: path: foo is not defined in context' // Human friendly error message, easier to reason about
    }
  ],
}

Documentation

Options

See defaultOptions.

Option name	Default value	Description
strictMatch	false	This represents the behavior in case of non-existent context corresponds to the filter. Set to true if you want to return false in case of a value in the filter doesn't exist.

Contributing

We gladly accept PRs, but please open an issue first so we can discuss it beforehand.

Working locally

yarn start # Shortcut - Runs linter + build + tests in concurrent mode (watch mode)

OR run each process separately for finer control

yarn lint
yarn build
yarn test

Test

yarn test # Run all tests, interactive and watch mode
yarn test:once # Used for CI/CD
yarn test:coverage # Generate coverage report

Versions

SemVer

We use Semantic Versioning for this project: https://semver.org/. (vMAJOR.MINOR.PATCH: v1.0.1)

• Major version: Must be changed when Breaking Changes are made (public API isn't backward compatible).
  • A function has been renamed/removed from the public API
  • Something has changed that will cause the app to behave differently with the same configuration
• Minor version: Must be changed when a new feature is added or updated (without breaking change nor behavioral change)
• Patch version: Must be changed when any change is made that isn't either Major nor Minor. (Misc, doc, etc.)

Release a new version

Note: You should write the CHANGELOG.md doc before releasing the version. This way, it'll be included in the same commit as the built files and version update

Then, release a new version:

• yarn run release

This command will prompt you for the version to update to, create a git tag, build the files and commit/push everything automatically.

Don't forget we are using SemVer, please follow our SemVer rules.

Pro hint: use beta tag if you're in a work-in-progress (or unsure) to avoid releasing WIP versions that looks legit

Releasing and publishing

yarn releaseAndPublish # Shortcut - Will prompt for bump version, commit, create git tag, push commit/tag and publish to NPM

yarn release # Will prompt for bump version, commit, create git tag, push commit/tag
npm publish # Will publish to NPM

License

MIT