@webnt-dev/object-match v1.0.7

Package allows for complex object matching: checking if you package matches template

Following code tests if provided user (1st parameter) matches template (2nd parameter). Test for user having account-manager role and is from Czech Republic or Slovak Republic.

import { objectMatch } from '@webnt-dev/object-match';
// function objectMatch(source: JSONObject, template: JSONObject): boolean
objectMatch(
  {
    id: 5,
    name: "Bronislav",
    roles: ['customer-care', 'account-manager'],
    address: {
      country: 'cz',
    },
  },
  {
    id: 5,
    roles: { $contains: 'account-manager' },
    address: {
      country: { $in: ['cz', 'sk'] },
    },
  },
) === true;

Function objectMatch traverses the object and matches it against the template property by property. If all template conditions match, function returns true.

Function supports direct matching (id in example above) or pattern matching using function - properties starting with $ in template (roles in example above).

Included template matching functions

Comparison functions

List of predefined comparison functions with simple examples.

Comparison functions can be nested, see complex example at the end.

$is (alias $eq)

function does generic matching (this function can be omitted / not used)

$not (alias $neq)

negation of template (see logical functions)

$gt

source is greater than template (numbers, strings)

objectMatch(
  {
    a: 5,
  },
  {
    a: { $gt: 4 },
  },
) === true;

$gte

source is greater or equal than value (numbers, strings)

objectMatch(
  {
    a: 5,
  },
  {
    a: { $gte: 4 },
  },
) === true;

$lt

source is less than value (numbers, strings)

objectMatch(
  {
    a: 5,
  },
  {
    a: { $lt: 6 },
  },
) === true;

$lte

source is less or equal than value (numbers, strings)

objectMatch(
  {
    a: 5,
  },
  {
    a: { $lte: 6 },
  },
) === true;

Array functions

$in

source (of any type) is in template array

objectMatch(
  {
    a: 1,
  },
  {
    a: { $in: [0, 1, 2] },
  },
) === true;

$contains

source array contains template value (of any type)

objectMatch(
  {
    a: [0, { o1: 1 }, 2],
  },
  {
    a: { $contains: { o1: 1 } },
  },
) === true;

$subsetOf

source array is subset of template array

objectMatch(
  {
    a: [0, 1, 2],
  },
  {
    a: { $subsetOf: [1, 0, 2, 3, 'a'] }
  },
) === true;

$supersetOf

template array is subset of source array

objectMatch(
  {
    a: [1, 0, 2, 3, 'a'],
  },
  {
    a: { $supersetOf: [0, 1, 2] }
  },
) === true;

$size

source array length (number)

objectMatch(
  {
    a: [1, 0, 2, 3, 'a'],
  },
  {
    a: { $size: 5 }
  },
) === true;

$intersection

there is non-empty intersection of source array and template array

objectMatch(
  {
    a: [0, 1, 2, 3, 'a'],
  },
  {
    a: { $intersection: [-1, 0] },
  },
) === true;

Object functions

$size

source object key number

objectMatch(
  {
    a: { x1: 1, x2: 2 },
  },
  {
    a: { $size: 2 },
  },
) === true;

$hasKey

source object has key

objectMatch(
  {
    a: { x1: 1, x2: 2 },
  },
  {
    a: { $hasKey: 'x1' },
  },
) === true;

Logical functions

$not

negation of template

objectMatch(
  {
    a: { x1: 1, x2: 2 },
  },
  {
    a: { $not: { $size: 3 } },
  },
) === true;

$and

all template array items must match against source

objectMatch(
  {
    a: 4,
  },
  {
    a: { $and: [{ $gt: 3 }, { $lt: 5 }] },
  },
) === true;

$or

at least one template item must match against source

objectMatch(
  {
    a: 4,
  },
  {
    a: { $or: [{ $gt: 3 }, { $lt: 4 }] },
  },
) === true;

$none

no template item must match against source

objectMatch(
  {
    a: 4,
  },
  {
    a: { $none: [{ $gt: 4 }, { $lt: 4 }] },
  },
) === true;

Full complex example

objectMatch(
  {
    a: 5, // Properties compare
    b: 'X',
    c: false,
    d: ['1', { e1: 'test' }],

    e: { e1: 4 }, // $eq/$is compare
    f: 5,

    g: { g1: 4 }, // $neq/$not compare
    h: 5,

    i: { i1: 4 }, // $gt/$gte/$lt/$lte compare
    j: 5,
    k: 5,
    l: 5,

    m: 1, // $in compare
    n: [1],
    o: { o1: 1 },
    p: 1,

    q: [0, 1, 2], // $contains compare
    r: [0, { o1: 1 }, 2],

    s: [0, 1, 2], // $subsetOf compare

    t: [0, 1, 2, 3, 'a'], // $supersetOf compare

    u: [0, 1, 2, 3, 'a'], // $size compare (array)
    v: [0, 1, 2, 3, 'a'],

    w: [0, 1, 2, 3, 'a'], // $intersection compare

    x: { x1: 1, x2: 2 }, // $size compare (object)

    y: 4, // $and compare

    z: 4, // $or compare

    A: 4, // $none compare

    B: ['1', '2', 3, 7], // $hasKey compare
    C: {
      C1: 'f',
    },

  },
  {
    a: 5, // Properties compare

    e: { $eq: { e1: 4 } }, // $eq/$is compare
    f: { $is: 5 },

    g: { $neq: { g1: 5 } }, // $neq/$not compare
    h: { $not: 4 },

    i: { i1: { $gt: 3 } }, // $gt/$gte/$lt/$lte compare
    j: { $gte: 5 },
    k: { $lt: 6 },
    l: { $not: { $lte: 4 } },

    m: { $in: [0, 1, 2] }, // $in compare
    n: { $in: [0, [1], 2] },
    o: { $in: [0, { o1: 1 }, 2] },
    p: { $not: { $in: [{ $lt: 0 }] } },

    q: { $not: { $contains: 5 } }, // $contains compare
    r: { $contains: 2 },

    s: { $subsetOf: [1, { $lt: 1 }, 2, 3, 'a'] }, // $subsetOf compare

    t: { $supersetOf: [1, { $lt: 1 }, 2] }, // $supersetOf compare

    u: { $size: 5 }, // $size compare (array)
    v: { $size: { $not: { $gt: 6 } } },

    w: { $intersection: [-1, { $lte: 0 }] }, // $intersection compare

    x: { $size: 2, x1: 1 }, // $size compare (object)

    y: { $and: [{ $gt: 3 }, { $lt: 5 }] }, // $and compare

    z: { $or: [{ $gt: 3 }, { $lt: 4 }] }, // $or compare

    A: { $none: [{ $gt: 4 }, { $lt: 4 }] }, // $none compare

    $hasKey: 'B', // $hasKey compare
    $not: { $hasKey: 'D' },
    C: {
      $hasKey: 'C1',
      $not: { $hasKey: 'C2' },
    },

  },
) === true

Support for additional template matching functions

Package exports patternFunctions object with definitions of all template matching functions so those can be override or new one can be created

import {
  objectMatch,
  patternFunctions,
  JSONData,
  Optional
} from from '@webnt-dev/object-match';

/**
 * Function validates, if number is odd
 *
 * Function must accept 2 generic JSON types, any type validation must be done within function.
 * Function must return `undefined` if matching does not apply or `template` input variable
 * if it does.
 *
 * For example below:
 * `value` = 4
 * `template` = false
 *
 * @param {JSONData} value - value to test
 * @param {JSONData} template - template value to test `value` against
 *
 * @returns {undefined|JSONData} `undefined` if matching does not apply or `template` input variable if it does
 *
 */
patternFunctions.$odd = (value: JSONData, template: JSONData): Optional<JSONData> => {
  if (typeof template !== 'boolean') {
    throw Error('$odd template must be boolean');
  }
  if (typeof value !== 'number') {
    return undefined;
  }

  return (value % 2 === 1) === template ? template : undefined;
};

objectMatch(
  {
    a: 4,
  },
  {
    a: { $odd: false },
  },
) === true;

Package exports valueIntersection function that can be used run recursive matching of 2 values of any types if additional template matching functions needs to traverse complex structures.

Changelog

Any missing version means mostly documentation fixes.

version 1.0.6

2023-05-14

@ additions to documentation

version 1.0.4

2023-05-13

+ initial version