Concordance JavaScript Value Utility

Common errors

• ReferenceError: require is not defined in ES module scope

  cause 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

  cause 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

  cause 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`.

Warnings

• breaking Concordance 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.
• breaking Concordance 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.
• breaking Concordance 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.
• gotcha When 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.
• gotcha Concordance'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`.

Install

• npm install concordance npm
• yarn add concordance yarn
• pnpm add concordance pnpm

Imports

• compare
  wrong:

  const compare = require('concordance').compare

  correct:

  import { compare } from 'concordance'

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

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

  correct:

  import { format } from 'concordance'

  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.

Quickstart

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