ast-compare^4.2.5

No 3rd party dependencies. All dependencies and devDependencies, checked recursively, are Codsen packages.

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• Compare Arrays
• Compare Plain Objects
• Compare Strings
• opts.arrayOrder
• opts.hungryForWhitespace
• opts.matchStrictly
• opts.useWildcards
• opts.verboseWhenMismatches
• Report deterministic work and elapsed time
• Report comparison progress
• Match each unordered array element only once
• Compare nested arrays without regard to order
• Match object keys using wildcards

Purpose

It checks whether one nested value is equal to, or a subset of, another. It is especially useful for comparing abstract syntax trees (ASTs).

We use it to compare parsed HTML and CSS trees or individual branches. It recursively traverses objects and arrays, and it powers ast-delete-object.

The default subset mode is similar to node-tap’s t.match. Set opts.matchStrictly to true when both structures must contain the same number of entries.

compare()

The main function compare() is imported like this:

The function takes two values and an optional options object:

• A match returns true.
• A mismatch returns false by default. With verboseWhenMismatches: true, it returns a string that describes the mismatch and its path.
• Missing arguments and invalid options throw a TypeError or RangeError with a stable throw identifier.

The function does not mutate either input.

The options object has the following shape:

The exported defaults object is a frozen, read-only snapshot. Attempting to modify it cannot change later comparisons.

Array matching

With the default arrayOrder: "ordered", pattern items must appear in the first array in the same order, but other items can occur between them. With arrayOrder: "any", every pattern item must match a different item in the first array; repeated or ambiguous items are matched one-to-one.

matchStrictly: true additionally requires equal array lengths and equal object key counts. Wildcard keys and values keep their normal meaning in strict mode.

Whitespace matching

With hungryForWhitespace: true, any two recursively empty values match, even when their container shapes differ. Empty values are:

• strings containing only whitespace;
• arrays whose entries are all empty; and
• plain objects whose values are all empty.

Numbers, booleans, null, undefined, and sparse array holes are meaningful; they are not whitespace. A whitespace-only pattern does not match meaningful content merely because it appears inside an array or object.

Wildcard matching

With useWildcards: true, * matches zero or more characters, including line breaks. Escape it as \* to match a literal asterisk. A leading ! negates the whole pattern. Matching is case-sensitive and anchored to the complete string.

Wildcard object keys are fallbacks: an exact own key takes precedence when it exists. Each wildcard key must consume a different key in the first object, and the corresponding values must recursively match as well.

Progress and completion reports

reportProgressFunc receives the configured start value, monotonic intermediate percentages, and the configured end value. Use reportProgressFuncFrom and reportProgressFuncTo to compose this work into a wider progress range.

reportCompletionFunc receives these statistics:

Exceptions thrown by either reporting callback are ignored and do not change the comparison result.

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.

version

You can import version:

Types

This package is written in TypeScript and exports the following types:

import type {
  AnyObject,
  BooleanOpts,
  ComparableValue,
  CompletionStats,
  JsonArray,
  JsonObject,
  JsonValue,
  Opts,
  VerboseOpts,
} from "ast-compare";

opts.verboseWhenMismatches

Use verboseWhenMismatches: true when you need to explain why a pattern did not match. Every mismatch returns a string containing the failing path, the reason, and correctly labelled first and second values. A successful comparison still returns true.

The VerboseOpts overload exposes this as true | string; it does not return false.

Differences from _.isMatch

Partial comparisons will match empty array and empty object source values against any array or object value, respectively.

Lodash isMatch documentation

_.isMatch matches an empty array pattern to every array. That is often undesirable when comparing parsed HTML or CSS trees. This library does not match an empty array pattern to a non-empty array unless hungryForWhitespace is enabled and both values are recursively whitespace-empty.

const result = compare(["a", "b", "c"], []);
// result === false

Permalink to changelogChangelog