Mangler.test() - DarthJDG/Mangler.js GitHub Wiki

Checks if the parameter passes a test.

Mangler.test(value, test)

Return true if value passes the test, false otherwise.

Many Mangler.js functions and methods use Mangler.test() internally to test a value agains a test expression. It mostly uses the MongoDB query language.

The following parameter types will be used in the specification below:

A <test> expression can be one of the following:

• Any simple value can be a test expression in itself and it's evaluated using the strict equality operator ===. For example Mangler.test(5, 5) returns true, while Mangler.test(5, '5') returns false.
• A regular expression, which evaluates to true if it matches the tested string. Mangler.test('hello', /^h/) returns true.
• An object literal with special properties. All properties are evaluated with an implied and logical relationship.
• An array is interpreted as an implied $all operator.
• A function is interpreted as an implied $where operator.

Here's a complete list of the valid properties of a test object:

• $gt, $gte, $lt, $lte, $eq and $ne are simple comparisons, corresponding to >, >=, <, <=, === and !== respectively. Use it as { $gt: <value> }
  • You can also use any comparison operator directly as a property name, e.g. '<'. Note that this is the only way to use the non-strict operators '==' and '!='. Use it as { '==': <value> }
• $or is true if any test expression in the passed array evaluates to true. { $or: [<test>, <test>, ...] }
• $all is true if the tested array contains all values passed. { $all: [<value>, <value>, ...] }
• $size is true if the tested array has matching length. { $size: <integer> }
• $elemMatch is true if any item in the tested array satisfies the test expression. { $elemMatch: <test> }
• $in is true if the tested array contains at least one passed value. If tested against a single value, it's true if value is in the passed array. { $in: [<value>, <value>, ...] }
• $not is the logical opposite of the passed test expression. { $not: <test> }
• $nin is shorthand for { $not: { $in: [<value>, <value>, ...] } }
• $nor is shorthand for { $not: { $or: [<test>, <test>, ...] } }
• $exists evaluates to the value passed if the tested value is not undefined. { $exists: true/false }
• $type checks the type with Mangler.compareType(). { $type: <value> }
• $mod is true if value % divisor === remainder. Use as { $mod: [divisor, remainder] }
• $where evaluates to the return value of the passed function, called with the tested value as parameter. { $where: <function> }
• $aggregate passes the current value to Mangler.aggregate() and checks the result against a test expression. { $aggregate: [aggregator, <test>] } or { $aggregate: [aggregator, options, <test>] }
• All other property names will be interpreted as either a named property on the tested object, or a path into the tested object. It will be evaluated using Mangler.getPath(), then tested. Use it as { property: <test> } or { 'path.to.value': <test> }

To see usage examples, see Searching and testing or have a look at the Mangler.js functions and methods that use test expressions as a main feature:

• Mangler.find()
• Mangler.findOne()
• Mangler.first()
• Mangler.last()
• .filter()
• .find()
• .findOne()
• .first()
• .last()