node-object-hash/README.hbs

# 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](#Benchmarks)).

Hashes are built on top of node's crypto module
(so for using in browser use something like [browserify-crypto](https://github.com/crypto-browserify/crypto-browserify) or some kind of crypto functions polyfills). Or you can use only `objectSorter` ([source](https://github.com/SkeLLLa/node-object-hash/blob/master/objectSorter.js)) for getting your objects' string representation and compare or pass them to your own hash function.

[![node](https://img.shields.io/node/v/node-object-hash.svg?maxAge=21600&style=flat-square)]()
[![NPM](https://img.shields.io/npm/v/node-object-hash.svg?maxAge=21600&style=flat-square)](https://npmjs.org/packages/node-object-hash)
[![NPM Downloads](https://img.shields.io/npm/dt/node-object-hash.svg?maxAge=21600&style=flat-square)](https://npmjs.org/packages/node-object-hash)
[![Build Status](https://img.shields.io/travis/SkeLLLa/node-object-hash.svg?maxAge=21600&branch=master&style=flat-square)](https://travis-ci.org/SkeLLLa/node-object-hash)
[![Known Vulnerabilities](https://snyk.io/test/github/SkeLLLa/node-object-hash/badge.svg?maxAge=21600&style=flat-square)](https://snyk.io/test/github/skellla/node-object-hash)
[![Code Climate](https://img.shields.io/codeclimate/github/SkeLLLa/node-object-hash.svg?maxAge=21600&style=flat-square)](https://codeclimate.com/github/SkeLLLa/node-object-hash/code)
[![Coverage](https://img.shields.io/codeclimate/coverage/github/SkeLLLa/node-object-hash.svg?maxAge=21600&style=flat-square)](https://codeclimate.com/github/SkeLLLa/node-object-hash/coverage)
[![Analytics](https://ga-beacon.appspot.com/UA-90571586-1/node-object-hash/readme?pixel&useReferer)](https://github.com/igrigorik/ga-beacon)

# 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](#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

{{>main}}

# 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](https://github.com/crypto-browserify/crypto-browserify)).

# Example
```js
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](https://github.com/SkeLLLa/node-object-hash/blob/master/test/hash2.js)
or try it out online at [runkit](https://runkit.com/skellla/node-object-hash-example)

# 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](bench/index.js))

| 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                 |
| 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](bench/bench.js))

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