yarabey / node-object-hash

Node.js object hash library with properties/arrays sorting to provide constant hashes. It also provides a method that returns sorted object strings that can be used for object comparison without hashes.

node-object-hash

Tiny and fast node.js object hash library with properties/arrays sorting to provide constant hashes. It also provides a method that returns sorted object strings that can be used for object comparison without hashes. One of the fastest among other analogues (see benchmarks).

Hashes are built on top of node's crypto module (so for using in browser use something like browserify-crypto or some kind of crypto functions polyfills). Or you can use only objectSorter (source) for getting your objects' string representation and compare or pass them to your own hash function.

Installation

npm i node-object-hash -S

Features

• Supports object property sorting for constant hashes for objects with same properties, but different order.
• Supports ES6 (Weak)Maps and (Weak)Sets.
• Supports type coercion (see table below)
• Supports all hashes and encodings of crypto library
• Supports large objects and arrays
• Very fast comparing to other libs (see Benchmarks section)

Type map

This map displays what types will have identical string representation (e.g. new Set([1, 2, 3]) and [1, 2, 3] will have equal string representations and hashes.

Initial type	Mapped type
Array ([])	array
ArrayObject (new Array())
Int8Array
Uint8Array
Uint8ClampedArray
Int16Array
Uint16Array
Int32Array
Uint32Array
Float32Array
Float64Array
Buffer
Set
WeakSet
Map	array[array]
WeakMap
string ('')	string
String (new String())
boolean (true)	boolean
Boolean (new Boolean())
number (true)	number
Number (new Number())
Date	date
Symbol	symbol
undefined	undefined
null	null
function	function
Object ({})	object
Object (new Object())
other	unknown

Coercion map

Initial "type"	Coerced type	Example
boolean	string	true -> 1
number	string	'1' -> 1
string	string	'a' -> a
null	string (empty)	null ->
undefined	string (empty)	undefined ->

Changes

See changelog

API overview

Constructor require('node-object-hash')([options])

Returns preconfigured object with API

Parameters:

• options:object - object with hasher config options
• options.coerce:boolean - if true performs type coercion (default: true); e.g. hash(true) == hash('1') == hash(1), hash(false) == hash('0') == hash(0)
• options.sort:boolean - if true performs sorting on objects, arrays, etc. (default: true);
• options.alg:string - sets default hash algorithm (default: 'sha256'); can be overridden in hash method;
• options.enc:string - sets default hash encoding (default: 'hex'); can be overridden in hash method;

API methods

hash(object[, options])

Returns hash string.

• object:* object for calculating hash;
• options:object object with options;
• options.alg:string - hash algorithm (default: 'sha256');
• options.enc:string - hash encoding (default: 'hex');

sort(object)

Returns sorted string generated from object (can be used for object comparison)

• object:* - object for sorting;

Full API docs (separate page)

Modules

node-object-hash/objectSorter : objectToString

Object sorter module. It provides object sorter function constructor.

node-object-hash : apiConstructor

Node object hash module. It provides a methods that return object hash or sorted object string.

node-object-hash/objectSorter : objectToString

Object sorter module. It provides object sorter function constructor.

• node-object-hash/objectSorter : objectToString
  • ~_guessObjectType(obj) ⇒ string ℗
  • ~_guessType(obj) ⇒ string ℗
  • ~makeObjectSorter([options]) ⇒ objectToString ℗
    • ~objectToString(obj) ⇒ string ℗

node-object-hash/objectSorter~_guessObjectType(obj) ⇒ string ℗

Guesses object's type

Kind: inner method of node-object-hash/objectSorter
Returns: string - Object type
Access: private

Param	Type	Description
obj	Object	Object to guess type

Example

var a = [];
_guessObjectType(a) === 'array'; // true

node-object-hash/objectSorter~_guessType(obj) ⇒ string ℗

Guesses variable type

Kind: inner method of node-object-hash/objectSorter
Returns: string - Variable type
Access: private

Param	Type	Description
obj	*	Variable to guess type

Example

var a = '';
_guessType(a) === 'string'; // true

node-object-hash/objectSorter~makeObjectSorter([options]) ⇒ objectToString ℗

Creates object sorter function

Kind: inner method of node-object-hash/objectSorter
Returns: objectToString - Object sorting function
Access: private

Param	Type	Default	Description
[options]	Object		Sorter options
[options.coerce]	boolean	true	Performs type coercion
[options.sort]	boolean	true	Performs array, object, etc. sorting

Example

// with coercion
var sorter = makeObjectSorter({coerce: true, sort: false});
sorter(1) === "1"; // true
// with sort
var sorter = makeObjectSorter({coerce: false, sort: true});
sorter([2, 3, 1]) === [1, 2, 3]; // true

makeObjectSorter~objectToString(obj) ⇒ string ℗

Object sorting function

Kind: inner method of makeObjectSorter
Returns: string - Sorted string
Access: private

Param	Type	Description
obj	Object	Object to sort

node-object-hash : apiConstructor

Node object hash module. It provides a methods that return object hash or sorted object string.

• node-object-hash : apiConstructor
  • instance
    • .sort(obj) ⇒ string
    • .hash(obj, [opts]) ⇒ string
  • inner
    • ~apiConstructor([options]) ⇒ API
    • ~API : Object

node-object-hash.sort(obj) ⇒ string

Creates sorted string from given object

Kind: instance method of node-object-hash
Returns: string - Sorted object string
Access: public
See: objectToString

Param	Type	Description
obj	*	JS object to be sorted

Example

var apiConstructor = require('node-object-hash');
var sorter = apiConstructor({sort:true, coerce:true}).sort;

sort({b: {b: 1, d: 'x'}, c: 2, a: [3, 5, 1]});
// "{a:[1,3,5],b:{b:1,d:x},c:2}"

node-object-hash.hash(obj, [opts]) ⇒ string

Creates hash from given object

Kind: instance method of node-object-hash
Returns: string - Object hash value
Access: public

Param	Type	Default	Description
obj	*		JS object to hash
[opts]	Object		Options
[opts.alg]	string	"sha256"	Crypto algorithm to use
[opts.enc]	string	"hex"	Hash string encoding

Example

var apiConstructor = require('node-object-hash');
var hasher = apiConstructor({sort:true, coerce:true}).hash;

hash({b: {b: 1, d: 'x'}, c: 2, a: [3, 5, 1]});
// "4c18ce0dcb1696b329c8568d94a9830da810437d8c9e6cecf5d969780335a26b"

node-object-hash~apiConstructor([options]) ⇒ API

Generates node-object-hash API object

Kind: inner method of node-object-hash
Returns: API - Node object hash API instance

Param	Type	Default	Description
[options]	Object		Library options
[options.coerce]	boolean	true	Performs type coercion
[options.sort]	boolean	true	Performs array, object, etc. sorting
[options.alg]	string	"sha256"	Default crypto algorithm to use (can be overridden)
[options.enc]	string	"hex"	Hash string encoding (can be overridden)

Example

var apiConstructor = require('node-object-hash');
var hashSortCoerce = apiConstructor({sort:true, coerce:true});
// or
var hashSort = apiConstructor({sort:true, coerce:false});
// or
var hashCoerce = apiConstructor({sort:false, coerce:true});

var objects = {
   a: {
     a: [{c: 2, a: 1, b: {a: 3, c: 2, b: 0}}],
     b: [1, 'a', {}, null],
   },
   b: {
     b: ['a', 1, {}, undefined],
     a: [{c: '2', b: {b: false, c: 2, a: '3'}, a: true}]
   },
   c: ['4', true, 0, 2, 3]
};
hashSortCoerce.hash(objects.a) === hashSortCoerce.hash(objects.b);
// returns true

hashSortCoerce.sort(object.c);
// returns '[0,1,2,3,4]'

node-object-hash~API : Object

Node object hash API object

Kind: inner typedef of node-object-hash
Properties

Name	Type	Description
hash	function	Returns object hash string (see hash)
sort	function	Returns sorted object string (see sort)

Requirements

version >=1.0.0

• >=nodejs-0.10.0

version >=0.1.0 && <1.0.0

• >=nodejs-6.0.0
• >=nodejs-4.0.0 (requires to run node with --harmony flag)

browsers

• nodejs crypto module for browsers (e.g. browserify-crypto).

Example

var hasher = require('node-object-hash');

var hashSortCoerce = hasher({sort:true, coerce:true});
// or
// var hashSortCoerce = hasher();
// or
// var hashSort = hasher({sort:true, coerce:false});
// or
// var hashCoerce = hasher({sort:false, coerce:true});

var objects = {
    a: {
      a: [{c: 2, a: 1, b: {a: 3, c: 2, b: 0}}],
      b: [1, 'a', {}, null],
    },
    b: {
      b: ['a', 1, {}, undefined],
      a: [{c: '2', b: {b: false, c: 2, a: '3'}, a: true}]
    },
    c: ['4', true, 0, 2, 3]
};

hashSortCoerce.hash(objects.a) === hashSortCoerce.hash(objects.b);
// returns true

hashSortCoerce.sort(object.c);
// returns '[0,1,2,3,4]'

For more examples you can see tests file or try it out online at runkit

Benchmarks

Bench data - array of 100000 complex objects

Usage

• npm run bench to run custom benchmark
• npm run bench2 to run benchmark suite

Results

Custom benchmark (code)

Library	Time (ms)	Memory (Mb)
node-object-hash-0.2.1	5813.575	34
node-object-hash-1.0.X	2805.581	27
node-object-hash-1.1.X (node v7)	2555.583	27
node-object-hash-1.2.X (node v7)	2390.752	28
object-hash-1.1.5 (node v7)	28115.553	39
object-hash-1.1.4	534528.254	41
object-hash-1.1.3	ERROR	Out of heap memory
hash-object-0.1.7	9219.826	42

Benchmark suite module (code)

Library (node v7)	Perf (ops/s)
node-object-hash-0.2.1	540 ±1.34%
node-object-hash-1.1.X	844 ±2.51%
node-object-hash-1.2.X	1021 ±1.81%
object-hash-1.1.5	106 ±0.88%
hash-object-0.1.7	305 ±1.66%

Links

• object-hash - Slow, useful for browsers because it not uses node's crypto library
• hash-object - no ES6 types support

License

ISC