concordance

library0.1.3jsnpmunverified

Concordance is a robust JavaScript utility library designed for deep comparison, human-readable formatting, detailed diffing, and consistent serialization of any JavaScript value. Currently stable at version 5.0.4, it maintains an active release cadence with frequent patch releases addressing minor issues and less frequent major versions that introduce breaking changes or significant feature enhancements. A key differentiator is its consistent underlying algorithm applied across all core operations—comparison, formatting, and diffing—ensuring predictable behavior. It offers granular control over comparisons, notably treating `-0` as distinct from `0`, `NaN` as equal to `NaN`, and comparing functions, promises, and symbols strictly by identity. Formatting is optimized for legibility, including special handling for multi-line strings and control characters. Concordance also supports serialization for later comparison, with specific behavioral changes noted when a deserialized value is used as the 'actual' value in comparisons.

serialization testing

npm install concordance

github ↗package ↗

INSTALL

IMPORT

SIG · CONCORDANCE

concordance

serializationjavascriptv0.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

compare

✓ import { compare } from 'concordance'

✗ const compare = require('concordance').compare

Concordance v5+ is primarily designed for ES Modules. While CommonJS `require` might work in some setups, named ES imports are the recommended approach.

format

✓ import { format } from 'concordance'

✗ import concordance from 'concordance'; const formatted = concordance.format(value)

Concordance does not provide a default export; all primary utilities like `format` are exposed as named exports.

serialize

✓ import { serialize, deserialize } from 'concordance'

The `serialize` and `deserialize` functions are designed to be used in tandem for persisting and re-hydrating values, especially for later comparisons.

This quickstart demonstrates how to use `diff` to compare two complex JavaScript objects and `format` to render the differences in a human-readable way. It also includes an example highlighting Concordance's unique handling of `-0` versus `0`.

import { diff, format } from 'concordance'; interface User { id: number; name: string; email?: string; address: { street: string; city: string; zip: string; }; roles: string[]; createdAt: Date; lastLogin?: Date; preferences?: Map<string, any>; } const user1: User = { id: 1, name: 'Alice', email: 'alice@example.com', address: { street: '123 Main St', city: 'Anytown', zip: '12345' }, roles: ['admin', 'editor'], createdAt: new Date('2023-01-01T10:00:00Z'), preferences: new Map([['theme', 'dark'], ['notifications', true]]) }; const user2: User = { id: 1, name: 'Alicia', // Changed name // email missing address: { street: '123 Main Street', // Street name changed slightly city: 'Anytown', zip: '12345' }, roles: ['editor'], // Role removed createdAt: new Date('2023-01-01T10:00:00Z'), lastLogin: new Date('2024-04-18T15:30:00Z') // New field }; console.log("--- Diffing two user objects ---"); const userDiff = diff(user1, user2); console.log(format(userDiff)); const objA = { a: 1, b: { c: 2 } }; const objB = { a: 1, b: { c: 3, d: 4 } }; console.log("\n--- Diffing simple objects ---"); console.log(format(diff(objA, objB))); // Example of how -0 and 0 are handled distinctly console.log("\n--- Comparing -0 and 0 ---"); const negativeZeroDiff = diff(-0, 0); console.log(format(negativeZeroDiff)); // Will show a difference

Debug

Known issues

breakingConcordance v3.0.0 introduced a breaking change to how circular references are compared. Previously, all circular references were considered unequal. As of v3.0.0, if the *same* cycle is present in both the actual and expected values, they are considered equal; otherwise, they are unequal.

fix

Review existing comparison logic, especially for tests involving circular data structures, to ensure the new behavior aligns with expectations and update any assertions if needed.

affects: >=3.0.0

breakingConcordance v4.0.0 dropped support for Node.js 4. Users running Node.js environments older than version 6 must upgrade their Node.js runtime to use Concordance v4.x or later.

fix

Upgrade your Node.js environment to version 6 or higher to use Concordance v4.x, or Node.js 10 or higher for v5.x and beyond.

affects: >=4.0.0

breakingConcordance v5.0.0 and subsequent versions explicitly require Node.js 10 or higher. Running on older Node.js versions (e.g., Node.js 8) will result in errors.

fix

Ensure your Node.js environment is version 10 or higher. For continuous integration setups, verify and update the Node.js version specified in your `package.json` `engines` field and CI configuration.

affects: >=5.0.0

gotchaWhen comparing deserialized values, specific behaviors change compared to live JavaScript values. For example, `Argument` values can only be compared to other `Argument` values, `Function` values are compared by name, `Promise` values by their constructor and enumerable properties (not identity), and `Symbol` values by their string serialization.

fix

Always pass the deserialized value as the *actual* value to comparison and diffing methods. Be aware that comparisons involving deserialized values may not behave identically to comparisons between original, live JavaScript values for certain types.

affects: >=2.0.0

gotchaConcordance's comparison logic treats `-0` as distinct from `0`, and `NaN` as equal to `NaN`. This behavior deviates from standard JavaScript strict equality (`===`) for both `-0` and `NaN`.

fix

When performing comparisons or writing assertions, ensure your test expectations account for Concordance's specific handling of `-0` and `NaN`.

affects: >=2.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

Attempting to use CommonJS `require()` syntax (e.g., `const { compare } = require('concordance');`) in an ES module environment, such as a `.mjs` file or a project with `"type": "module"` in `package.json`.

fix

Switch to ES module import syntax: `import { compare } from 'concordance';`

TypeError: concordance.compare is not a function

This error typically occurs when trying to access `compare` as a property of a non-existent default import, or when `require('concordance')` does not return an object with `compare` as a direct property in a CommonJS context.

fix

Use named imports for ES Modules: `import { compare } from 'concordance';`. If in a CommonJS context, ensure correct destructuring: `const { compare } = require('concordance');`.

SyntaxError: Cannot use import statement outside a module

Using `import` syntax (e.g., `import { format } from 'concordance';`) in a CommonJS file, which is the default for `.js` files unless `"type": "module"` is set in `package.json` or the file has a `.mjs` extension.

fix

If your project is CommonJS, use `const { format } = require('concordance');`. If you intend to use ES Modules, ensure your `package.json` includes `"type": "module"` or rename your file to `.mjs`.

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/concordancejs/concordance ↗

packagehttps://www.npmjs.com/package/concordance ↗