diff.js/README.md

Object diff

XXX Intro

• Object diff
  • Motivation
  • General
    • Diff
      • Diff class API
      • Diff object API
      • Options
    • Deep compare
    • Patterns
    • Patterns (EXPERIMENTAL)
    • JSON compatibility
  • Extending Diff
  • The Diff format
    • Flat
    • Tree
  • Contacts, feedback and contributions
  • License

Motivation

XXX goals

XXX alternatives

General

Install the package:

$ npm install --save object-diff

Load the module:

var diff = require('object-diff')

This module supports both requirejs and node's require(..).

Diff

Create a diff object:

var diff = new Diff(A, B)

Diff class API

.cmp(A, B) -> bool

.clone(<title>)

.fromJSON(json) -> diff

Diff object API

.patch(X) -> X'

.unpatch(X') -> X

.check(X) -> bool

.json() -> JSON

Options

{
	// if true return a tree diff format...
	tree_diff: false | true,

	// if true, NONE change items will not be removed from the diff...
	keep_none: false | true,

	// Minimum length of a string for it to be treated as Text...
	//
	// If this is set to a negative number Text diffing is disabled.
	//
	// NOTE: a string must also contain at least one \n to be text 
	//		diffed...
	min_text_length: 1000 | -1,

	// If true, disable attribute diff for non Object's...
	//
	// XXX should be more granular...
	no_attributes: false | true,

	// Plaeholders to be used in the diff..
	//
	// Set these if the default values conflict with your data...
	//
	// XXX remove these from options in favor of auto conflict 
	//		detection and hashing...
	NONE: null | { .. },
	EMPTY: null | { .. },
}

Deep compare

cmp(A, B)

Diff.cmp(A, B)

Patterns

XXX General description...

ANY - matches anything

NOT(A) - match anything but A

OR(A[, .. ]) - match if one of the arguments matches

AND(A[, .. ]) - matches of all of the arguments match

XXX examples...

Patterns (EXPERIMENTAL)

NUMBER(min, max)

IN(A)

AT(A, K)

OF(A, N)

JSON compatibility

var json = diff.json()

var diff2 = Diff.fromJSON(json)

Note that the output of .json() may not be JSON compatible if the input objects are not json compatible. The reasoning here is simple: object-diff is a diffing module and not a serializer.

The simple way to put this is: if the inputs are JSON-compatible the output of .json() is going to also be JSON-compatible.

The big picture is a bit more complicated, Diff(..) and friends support allot more than simply JSON, this would include any types, attributes on all objects and loops/recursive structures.

.fromJSON(..) does not care about JSON compatibility and will be happy with any output of .json().

Extending Diff

Create a new diff handler:

var ExtendedDiff = diff.Diff.clone()

Add new type handler:

ExtendedDiff.types.set(SomeType, {
	priority: null,

	handle: function(obj, diff, A, B, options){
		// ...
	},
	walk: function(diff, func, path){
		// ...
	},
	patch: function(target, key, change, root, options){
		// ...
	},
	reverse: function(change){
		// ...
	},
})

Add new synthetic type handler:

ExtendedDiff.types.set(SomeType, {
	priority: null,

	check: function(obj, options){
		// ...
	},

	// ...
})

Remove an existing type handler:

ExtendedDiff.types.delete('Text')

The source code is a good example for this as the base Diff(..) is built using this API, but note that we are registirng types on the Types object rather that on the Diff itself, there is no functional difference other than how the main code is structured internally.

The Diff format

Flat

This is the main and default format used to store diff information.

[]

Tree

This format is used internally but may be useful for introspection.

Contacts, feedback and contributions

XXX github, email, ...

License

BSD 3-Clause License

Copyright (c) 2018, Alex A. Naanou, All rights reserved.