DOCSEARCHbyAlgolia
Submit Docs

microdiff

repository·master·Indexed 26 days ago

https://github.com/asyncbanana/microdiff

A lightweight (<1kb), high-performance deep object and array comparison library with zero dependencies and full TypeScript support. It provides a diff() function that returns an array of change objects (CREATE, REMOVE, or CHANGE) describing the differences between two inputs, with optional support for circular references via the cyclesFix configuration.

Tokens
1K
Snippets
5
Records
8
Agent score
37%

What's inside microdiff

  3. Use the diff() function

    master

    Import diff and pass two objects (or arrays) to it. The function returns an array of change objects describing the differences between the two inputs.

    import diff from "microdiff";

const obj1 = {
	originalProperty: true,
};
const obj2 = {
	originalProperty: true,
	newProperty: "new",
};

console.log(diff(obj1, obj2));
// [{type: "CREATE", path: ["newProperty"], value: "new"}]

  4. Disable cycle support with cyclesFix

    master

    By default, Microdiff supports cyclical references. If you are certain your objects do not contain cycles (e.g., objects parsed from JSON), you can improve performance by setting the cyclesFix option to false.

    diff(obj1, obj2, { cyclesFix: false });

  5. Configure cycle detection with cyclesFix

    master

    The diff() function accepts an options object to control how circular references are handled.

    • cyclesFix (boolean): When true (default), the function tracks visited objects in a stack to prevent infinite recursion during deep comparison of circular structures. If set to false, the function may enter an infinite loop if circular references are present.

  6. Understand the diff output format

    master

    The diff() function returns an array of objects. Each object represents a change and contains the following properties:

    • type: One of CREATE, REMOVE, or CHANGE.
    • path: An array of keys (strings for Objects, numbers for Arrays) representing the path to the changed property.
    • value: Present in CREATE and CHANGE types; contains the new value.
    • oldValue: Present in CHANGE and REMOVE types; contains the previous value.

  7. Compute object or array differences with diff()

    master

    The diff() function compares two objects or arrays and returns an array of Difference objects describing the changes. It supports deep comparison of nested structures and handles circular references if cyclesFix is enabled.

    Parameters:

    • obj: The original object or array (Record<string, any> | any[]).
    • newObj: The new object or array to compare against the original (Record<string, any> | any[]).
    • options (optional): Configuration object. Defaults to { cyclesFix: true }.
    • _stack (internal): Used for recursion and cycle detection.

    Returns: An array of Difference objects representing CREATE, REMOVE, or CHANGE operations.

  8. Understand the Difference type structure

    master

    The Difference type is a union of three specific interfaces that describe what changed between two objects. Each interface includes a path array representing the location of the change (using strings for object keys and numbers for array indices).

    TypeInterfaceDescription
    CREATEDifferenceCreateA new key or index was added. Contains path and value.
    REMOVEDifferenceRemoveAn existing key or index was deleted. Contains path and oldValue.
    CHANGEDifferenceChangeAn existing value was modified. Contains path, oldValue, and value.

    Note on path: The path is an array of (string | number)[].

    export interface DifferenceCreate {
	type: "CREATE";
	path: (string | number)[];
	value: any;
}

export interface DifferenceRemove {
	type: "REMOVE";
	path: (string | number)[];
	oldValue: any;
}

export interface DifferenceChange {
	type: "CHANGE";
	path: (string | number)[];
	value: any;
	oldValue: any;
}