Installation
Quick Take
Examples
- Compare Arrays
- Compare Plain Objects
- Compare Strings
opts.hungryForWhitespaceopts.useWildcardsopts.verboseWhenMismatches
Purpose
It compares data structures, especially, AST’s.
We use it to compare two parsed HTML/CSS trees or their branches, but you can compare anything, it will recursively traverse arrays too. For example, it powers ast-delete-object which also works on AST’s.
The default mode is similar to Tap asserts t.match and the option opts.matchStrictly is similar to t.sameStrict.
API — compare()
The main function compare() is imported like this:
It’s a function which takes three input arguments:
| Input argument | Type | Obligatory | Description |
|---|---|---|---|
bigObjType: Array or Plain object or String Obligatory: yes | |||
bigObj | Array or Plain object or String | yes | Superset, larger thing. |
smallObjType: Array or Plain object or String Obligatory: yes | |||
smallObj | Array or Plain object or String | yes | A set of the above, smaller thing. |
optsType: Plain object Obligatory: no | |||
opts | Plain object | no | An Optional Options Object. |
- If everything from
smallObjmatches everything withinbigObj, this library returnstrue. - Otherwise, if there’s a mismatch or something wrong with input args, it returns
false.
None of the input arguments will be mutated by this program, we have unit tests to prove that.
The optional options object has the following shape:
| Key | Type | Obligatory | Default | Description |
|---|---|---|---|---|
hungryForWhitespaceType: Boolean Obligatory: no Default: false | ||||
hungryForWhitespace | Boolean | no | false | Any chunk of whitespace (tabs, spaces, line breaks and so on) will match any other chunk of white space. |
matchStrictlyType: Boolean Obligatory: no Default: false | ||||
matchStrictly | Boolean | no | false | When you want to match like ===. |
verboseWhenMismatchesType: Boolean Obligatory: no Default: false | ||||
verboseWhenMismatches | Boolean | no | false | When set to true, instead of false the output will be a string with a message explaining what didn’t match. It’s for cases when it’s important to report what didn’t match. |
useWildcardsType: Boolean Obligatory: no Default: false | ||||
useWildcards | Boolean | no | false | If off by default, but you can enable wildcards within object value strings. |
The function returns a boolean:
A positive answer is always boolean true.
A negative answer is either:
- a boolean
false(on default setting, ifopts.verboseWhenMismatchesisfalse) OR - a string, explaining what didn’t match (if
opts.verboseWhenMismatchesistrue)
API — defaults
You can import defaults:
It's a plain object:
The main function calculates the options to be used by merging the options you passed with these defaults.
API — version
You can import version:
opts.verboseWhenMismatches
Sometimes you just want a yes/no answer is something a subset or equal to something. But sometimes, the whole point of comparison is to inform the user exactly what is mismatching. In the latter cases, set opts.verboseWhenMismatches to true. When there is no match, instead of Boolean false the main function will return a string with an explanatory message.
If you use this setting, you have to anticipate Boolean true OR something else (Boolean false or string) coming out from this library.
Differences from _.isMatch
Partial comparisons will match empty array and empty object source values against any array or object value, respectively.
_.isMatch positively
matches empty arrays to everything. This is bad when you are comparing parsed HTML/CSS
trees. This library doesn’t do this. An empty array will not be reported as equal
to a non-empty array.
// in this library:
var res = compare(["a", "b", "c"], []);
// now, res === false