README.md

Objectron

Compare an object to a generic model to test equality and extract matches

This module provides you with the means to define a tester object containing a set of match rules that will be used against a payload object. The match() method within the module will return whether the payload object has satisfied all the rules and will return the set of matches.

Demo

The best way to really understand this module is to play with some examples. Go through some of our usage examples and test them in our interactive demo page:

Installation

Windows, macOS, Linux -- requires node v10.13.x or above

$ npm install --save @menadevs/objectron

Run tests (optional)

$ npm test

Use cases

1. You can use this module as a basic JSON schema validator
2. Can also be used in unit testing for broader assertions
3. Can be used to extract values from a complex API response. We are actively using it in the maintenance of our community slack bot (https://github.com/mena-devs/bosta)
4. Can be used at the core of a JSON linter

Check our FAQs for more insights

Usage examples

Keep in mind that the tester object can be a subset of the payload. You don't have to write explicit rules for all the properties of the payload object.

1. Simple match (Success)

The tester object will match with the payload provided

const match = require('@menadevs/objectron');

const payload = {
  'type': 'message',
  'text': 'text',
}

const tester = {
  'type': 'message',
  'text': 'text',
}

const result = match(payload, tester);

console.log(result)

# Output
> {
    match: true,
    total: 2,
    matches: { type: 'message', text: 'text' },
    groups: {}
  }

2. Simple match (Fail)

The tester object will not match with the payload provided

const match = require('@menadevs/objectron');

const payload = {
  'type': 'message',
  'text': 'text',
}

const tester = {
  'another_key': 'different value',
}

const result = match(payload, tester);

console.log(result)

# Output
> { 
    match: false, 
    total: 0, 
    matches: {}, 
    groups: {} 
  }

3. Simple match with RegEx (Success)

You can use regular expressions to build generic tester objects

const match = require('@menadevs/objectron');

const payload = {
  'type': 'message',
  'text': 'invite Smith',
}

const tester = {
  'type': 'message',
  'text': /invite (\S+)/,
}

const result = match(payload, tester);

console.log(result)

# Output
> {
    match: true,
    total: 2,
    matches: { type: 'message', text: 'invite Smith' },
    groups: {}
}

4. Match with RegEx and named groups (Success)

You can use regular expression named groups to capture matches separately

const match = require('@menadevs/objectron');

const payload = {
  'type': 'message',
  'text': 'invite (Smith) (john@example.com) (CompanyX) (Engineer)',
}

const tester = {
  'type': 'message',
  'text': /invite \((?<name>\S+)\) \((?<email>\S+)\) \((?<company>\S+)\) \((?<role>\S+)\)/,
}

const result = match(payload, tester);

console.log(result)

# Output
> {
    match: true,
    total: 2,
    matches: {
      type: 'message',
      text: 'invite (Smith) (john@example.com) (CompanyX) (Engineer)'
    },
    groups: {
      name: 'Smith',
      email: 'john@example.com',
      company: 'CompanyX',
      role: 'Engineer'
    }
}

5. Match with nested Objects, Arrays and RegExp (Success)

You can create complex tester objects with an indefinite nesting depth

const match = require('@menadevs/objectron');

const payload = {
    'type': 'message',
    'level1': [
        {
            'level2': [
                {
                    'text': 'invite (Smith) (john@example.com) (CompanyX) (Engineer)'
                }
            ]
        },
        {
            'text': 'secondary object'
        }
    ]
}

const tester = {
  'level1': [
      {
          'level2': [
              {
                  'text': /invite \((?<name>\S+)\) \((?<email>\S+)\) \((?<company>\S+)\) \((?<role>\S+)\)/,
              }
          ]
      }
  ]
}

const result = match(payload, tester);

console.dir(result, {depth: null});

# Output
> {
    match: true,
    total: 1,
    matches: {
      level1: [
        {
          level2: [
            {
              text: 'invite (Smith) (john@example.com) (CompanyX) (Engineer)'
            }
          ]
        }
      ]
    },
    groups: {
      name: 'Smith',
      email: 'john@example.com',
      company: 'CompanyX',
      role: 'Engineer'
    }
  }

6. Match with closures (Success)

You can use closures for testing

const match = require('@menadevs/objectron');

const payload = {
  'type': 'message',
  'text': 'text',
  'int': 1,
  'bool': true,
  'float': 1.1,
  'items': [1, 1, 1, 1],
}

const tester = {
  'type': (val) => val === 'message',
  'text': (val) => val.length == 4,
  'int': (val) => val + 1 == 2,
  'bool': (val) => !!!!!!!!val,
  'float': (val) => val - 1.1 == 0,
  'items': (val) => val.length == 4,
}

const result = match(payload, tester);

console.dir(result, {depth: null});

# Output
> {
    match: true,
    total: 0,
    matches: { type: {}, text: {}, int: {}, bool: {}, float: {}, items: {} },
    groups: {}
}

7. Using closures as wildcard (Success)

You can utilize closures to return an entire sub-object or sub-array from specific keys in a payload. This can be useful in cases where you want to return all values under a key without the need for further matching.

const match = require('@menadevs/objectron');

const payload = {
  request: {
    status: 200,
    headers: [
      {
        "name": "User-Agent",
        "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3)"
      },
      {
        "name": "Referer",
        "value": "https://www.somethingabcxyz.kfc/"
      }
    ]
  }
}

const tester = {
  request: {
    status: 200,
    headers: (val) => val
  }
};

const result = match(payload, tester);

# Output
> {
    match: true,
    total: 2,
    matches: {
      request: {
        status: 200,
        headers: [
          {
            "name": "User-Agent",
            "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3)"
          },
          {
            "name": "Referer",
            "value": "https://www.somethingabcxyz.kfc/"
          }
        ]
      }
    },
    groups: {}
}

FAQs

1. What's the difference between Objectron and any other Schema Validator?

Objectron has a simple interface, it's a very small module (~60 LOCs), and most importantly it allows the extraction of the data that matches the rules not merely validating it.

2. Has this been used in production?

No, but we're planning to use it.

3. Why did you build this?

Why not? :)

4. I have a great idea for a new feature!

Fantastic, we'd love to hear more about it. Please create an issue and we will look into it as soon as we're able to.

5. I have a question not in this list

Please create an issue and we will look into it as soon as we're able to.

Meta

• @Link-
• @aymanfarhat
• @omaraboumrad

Contributing

This project does not require a Contributor License Agreement.

Release Process

Release checklist and process is documented in Release.md