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
• Vulnerability disclosure
• Contributors and maintainers
• [ABOUT UNLY]

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

Vulnerability disclosure

See our policy.

---

Contributors and maintainers

This project is being maintained by:

• [Unly] Ambroise Dhenain (Vadorequest) (active)
• [Contributor] Adrien Zemma (Adrien-Zemma) (active)

Thanks to our contributors:

• Hugo Martin (Demmonius)

---

[ABOUT UNLY]

Unly is a socially responsible company, fighting inequality and facilitating access to higher education. Unly is committed to making education more inclusive, through responsible funding for students. We provide technological solutions to help students find the necessary funding for their studies.

We proudly participate in many TechForGood initiatives. To support and learn more about our actions to make education accessible, visit :

• https://twitter.com/UnlyEd
• https://www.facebook.com/UnlyEd/
• https://www.linkedin.com/company/unly
• Interested to work with us?

Tech tips and tricks from our CTO on our Medium page!

#TECHFORGOOD #EDUCATIONFORALL