tmatch Deep Object Matching

5.0.0 · active · verified Wed Apr 22

tmatch is a utility module designed to facilitate deep and flexible object matching, primarily used by the `t.match()` method in the `tap` test framework. Currently at version 5.0.0, it provides a comprehensive algorithm for comparing a target value against a pattern, supporting various data types including objects, arrays, regular expressions, dates, buffers, and constructor functions. Its matching logic goes beyond shallow equality, handling nested structures and specific type-based comparisons. For instance, it can match strings against regular expressions, check if an object is an `instanceof` a given constructor, or assert the absence of a property using `{propertyName: null}`. While its release cadence is tied to `tap`, it is generally stable. Key differentiators include its detailed, multi-step matching algorithm that accounts for many edge cases and its utility in robust assertion scenarios, offering a more nuanced comparison than standard deep equality checks.

Common errors

```
TypeError: tmatch is not a function
```
cause Attempting to import `tmatch` as a named export (`import { tmatch } from 'tmatch'`) or destructure it from a CommonJS `require` call.

fix Use a default import for ESM (`import tmatch from 'tmatch';`) or assign the direct module export for CommonJS (`const tmatch = require('tmatch');`).
```
My pattern `{foo: undefined}` isn't matching objects without `foo`!
```
cause `tmatch` explicitly differentiates between an `undefined` value and a missing property. Using `undefined` in a pattern matches an existing property whose value is `undefined`.

fix To assert that a property `foo` is completely absent from the target object, set its value in the pattern to `null`: `{ foo: null }`. `tmatch` resolves missing keys to `undefined` during comparison, allowing `null` to effectively act as a 'does not exist' assertion.

Warnings

gotcha Using `undefined` in a pattern property will match an existing property explicitly set to `undefined`, not a missing property. To assert that a property is *absent* from the target object, use `null` in the pattern instead.
Fix: If your intention is to ensure a property is missing, set its value in the pattern to `null` (e.g., `{ foo: null }`). If you want to match a property that exists and is `undefined`, use `{ foo: undefined }`.
gotcha When a pattern value is a `Function` constructor (e.g., `String`, `Array`, `Buffer`), `tmatch` checks if the corresponding object value is an `instanceof` that constructor. This differs from value-based comparison.
Fix: Be aware that patterns like `{ myValue: String }` will check `object.myValue instanceof String`, which is true for `new String('hi')` but false for `'hi'` (a string primitive). If you intend to match primitive types, specify the primitive value directly or use a `RegExp` for strings.
gotcha The algorithm's first step performs a loose equality check (`==`). This means `null` will match `undefined`, and some type coercions may occur before deeper comparison logic is applied. This can lead to unexpected matches if not accounted for.
Fix: If strict equality is desired for non-object types or `null`/`undefined`, ensure the pattern and object values are explicitly identical, or use a custom matching function if `tmatch`'s specific loose equality behavior is not suitable.
gotcha String patterns are matched as substrings (step 6: 'return true if the string occurs within the object'). If you need more complex string matching (e.g., starts with, ends with), a `RegExp` pattern is required.
Fix: For patterns requiring anything beyond simple substring presence, use a regular expression. For example, to match a string starting with 'prefix', use `{ myString: /^prefix/ }` instead of `{ myString: 'prefix' }`.

Install

npm install tmatch npm
yarn add tmatch yarn
pnpm add tmatch pnpm

Imports

tmatch
wrong:
```
import { tmatch } from 'tmatch';
```
correct:
```
import tmatch from 'tmatch';
```
tmatch is exported as the default function for ESM consumers.
tmatch
wrong:
```
const { tmatch } = require('tmatch');
```
correct:
```
const tmatch = require('tmatch');
```
For CommonJS, the module's export is the tmatch function directly.

Quickstart

Demonstrates `tmatch` for deep object comparison, including regex matching and asserting property absence with `null`.

const tmatch = require('tmatch');

// Simulate an HTTP response object
const mockResponse = {
  statusCode: 200,
  headers: {
    'content-type': 'application/json',
    server: 'express/4.17.1'
  },
  body: {
    message: 'Hello, world!'
  }
};

const expectedPattern = {
  statusCode: 200,
  headers: {
    server: /express/, // Matches any server header containing 'express'
    'content-type': 'application/json' // Exact string match
  },
  // 'body' property is not in pattern, so it's ignored during matching
};

if (tmatch(mockResponse, expectedPattern)) {
  console.log('Response matches the expected pattern!');
} else {
  console.error('Response DOES NOT match the expected pattern.');
  console.error('Actual:', JSON.stringify(mockResponse, null, 2));
  console.error('Pattern:', JSON.stringify(expectedPattern, null, 2));
}

// Example of asserting a property's absence using null
const negativePattern = {
  headers: {
    'x-powered-by': null // Ensures 'x-powered-by' property is absent
  }
};

const responseWithXPoweredBy = {
  statusCode: 200,
  headers: {
    'x-powered-by': 'Express',
    server: 'express/4.17.1'
  }
};

if (!tmatch(responseWithXPoweredBy, negativePattern)) {
  console.log("Response does not have 'x-powered-by' header as expected (correct behavior for negative pattern).");
} else {
  console.error("Response HAS 'x-powered-by' header, but pattern expected it absent.");
}

view raw JSON →