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. 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 (e.g. 1 and "1" will be the same)
  • rules:
    • numbers and strings represented without quotes;
    • boolean values converted to numbers;
• Supports all hashes and encodings of crypto library
• Supports large objects and arrays
• Very fast comparing to other libs (see Benchmarks section)

Changes

v0.x.x -> v1.0.0

• Sorting mechanism rewritten form ES6 Maps to simple arrays (add <=node-4.0.0 support)
• Performance optimization (~2 times faster than 0.x.x)
• API changes:
  • Now module returns 'constructor' function, where you can set default parameters: var objectHash = require('node-object-hash')(options);

In case if you still need an old 0.x.x version it's available in hash.js file.

v1.0.X -> v1.1.X

Mainly all changes affected codestyle and documentation to provide better experience using this library. There are no changes that should affect functionality.

• Renamed sortObject function to sort (old one is still present in code for backward compatibility).
• Performed some refactoring for better codestyle and documentation.
• Old version (0.X.X) moved to subfolder (./v0).
• Advanced API reference added: [link](#Full API docs).

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

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

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

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

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

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

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

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

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

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)

Benchmark suite module (code)

    node-object-hash x 844 ops/sec ±2.51% (82 runs sampled)
    node-object-hash-v0 x 540 ops/sec ±1.34% (82 runs sampled)
    hash-object x 310 ops/sec ±0.88% (81 runs sampled)
    object-hash x 107 ops/sec ±1.66% (72 runs sampled)

Links

• https://www.npmjs.com/package/object-hash (Slow, useful for browsers because it not uses node's crypto library)
• https://www.npmjs.com/package/hash-object (no ES6 types support)

License

ISC