node-object-hash - npm Package Compare versions

Comparing version 1.0.3 to 1.1.0

objectSorter.js

@@ -1,4 +0,1 @@
-/**
- * Created on 8/22/16.
- */
 'use strict';
@@ -8,6 +5,12 @@
  * Guesses object's type
- * @param {Object} obj Object
- * @returns {string}
+ * @memberOf module:node-object-hash/objectSorter
+ * @inner
+ * @private
+ * @param {Object} obj Object to guess type
+ * @returns {string} Object type
+ * @example
+ * var a = [];
+ * _guessObjectType(a) === 'array'; // true
  */
-function guessObjectType(obj) {
+function _guessObjectType(obj) {
   var hasMapSet = typeof Map !== 'undefined';
@@ -35,9 +38,15 @@
  * Guesses variable type
- * @param {*} obj
- * @returns {string}
+ * @memberOf module:node-object-hash/objectSorter
+ * @inner
+ * @private
+ * @param {*} obj Variable to guess type
+ * @returns {string} Variable type
+ * @example
+ * var a = '';
+ * _guessType(a) === 'string'; // true
  */
-function guessType(obj) {
+function _guessType(obj) {
   var type = typeof obj;
 
-  return type !== 'object' ? type : guessObjectType(obj);
+  return type !== 'object' ? type : _guessObjectType(obj);
 }
@@ -47,8 +56,19 @@
  * Creates object sorter function
+ * @memberOf module:node-object-hash/objectSorter
+ * @inner
+ * @private
  * @param {Object} [options] Sorter options
- * @param {boolean} [options.coerce="true"] Performs type coercion (e.g sorter(1) === ("1"))
+ * @param {boolean} [options.coerce="true"] Performs type coercion
  * @param {boolean} [options.sort="true"] Performs array, object, etc. sorting
- * @returns {string} Sorted object string
+ * @returns {module:node-object-hash/objectSorter~makeObjectSorter~objectToString}
+ * Object sorting function
+ * @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
  */
-function objectSorter(options) {
+function makeObjectSorter(options) {
   options = options || {};
@@ -112,3 +132,3 @@ var coerce = typeof options.coerce === 'undefined' ? true : options.coerce,
       item = obj[i];
-      itemType = guessType(item);
+      itemType = _guessType(item);
       result.push(self[itemType](item));
@@ -142,3 +162,3 @@ }
       value = obj[key];
-      valueType = guessType(value);
+      valueType = _guessType(value);
       objArray.push(key + ':' + self[valueType](value));
@@ -159,4 +179,4 @@ }
       item = [
-        self[guessType(key)](key),
-        self[guessType(value)](value)
+        self[_guessType(key)](key),
+        self[_guessType(value)](value)
       ];
@@ -169,9 +189,21 @@ arr[i] = item;
 
-  function obj2string(obj) {
-    return self[guessType(obj)](obj);
+  /**
+   * Object sorting function
+   * @private
+   * @param {Object} obj Object to sort
+   * @returns {string} Sorted string
+   */
+  function objectToString(obj) {
+    return self[_guessType(obj)](obj);
   }
 
-  return obj2string;
+  return objectToString;
 }
 
-module.exports = objectSorter;
+/**
+ * Object sorter module.
+ * It provides object sorter function constructor.
+ * @module node-object-hash/objectSorter
+ * @type {module:node-object-hash/objectSorter~makeObjectSorter~objectToString}
+ */
+module.exports = makeObjectSorter;

package.json

 {
   "name": "node-object-hash",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Node.js object hash library with properties/arrays sorting to provide constant hashes",
-  "main": "hash2.js",
+  "main": "index.js",
   "directories": {
@@ -17,4 +17,5 @@ "test": "test"
     "istanbul": "^0.4.5",
+    "jsdoc-to-markdown": "^2.0.1",
     "mocha": "^2.5.3",
-    "object-hash": "^1.1.4"
+    "object-hash": "^1.1.5"
   },
@@ -26,3 +27,4 @@ "scripts": {
     "bench": "node --expose-gc ./bench/index.js",
-    "bench2": "node --expose-gc ./bench/bench.js"
+    "bench2": "node --expose-gc ./bench/bench.js",
+    "jsdoc": "jsdoc2md -t ./README.hbs --private 'objectSorter.js' 'index.js' > README.md && jsdoc2md --private 'objectSorter.js' 'index.js' > API.md"
   },
@@ -29,0 +31,0 @@ "repository": {

README.md

@@ -5,4 +5,5 @@ # node-object-hash
 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 
+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.
@@ -18,6 +19,7 @@
 
-### Installation
+# Installation
+
 `npm i node-object-hash -S`
 
-### Features
+# Features
 - Supports object property sorting for constant hashes for objects with same properties, but different order.
@@ -31,5 +33,8 @@ - Supports ES6 (Weak)Maps and (Weak)Sets.
 - Supports large objects and arrays
+- Very fast comparing to other libs (see [Benchmarks](#Benchmarks) section)
 
-### Changes
-#### v0.x.x -> v1.0.0
+# Changes
+
+## v0.x.x -> v1.0.0
+
 - Sorting mechanism rewritten form ES6 Maps to simple arrays
@@ -44,40 +49,275 @@ (add <=node-4.0.0 support)
 file.
-### API
 
-#### Constructor `require('node-object-hash')([options])`
+## v1.0.X -> v1.1.0
+
+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`);
+*  `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;
+*  `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])`
+## 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'`);
+*  `object`:`*` object for calculating hash;
+*  `options`:`object` object with options;
+*  `options.alg`:`string` - hash algorithm (default: `'sha256'`);
+*  `options.enc`:`string` - hash encoding (default: `'hex'`);
 
-##### `sortObject(object)`
+### `sort(object)`
+
 Returns sorted string generated from object (can be used for object comparison)
-*  `object`:`<*>` - object for sorting;
+*  `object`:`*` - object for sorting;
 
-### Requirements
+# Full API docs
 
-#### version \>=1.0.0
+## Modules
+
+<dl>
+<dt><a href="#module_node-object-hash/objectSorter">node-object-hash/objectSorter</a> : <code><a href="#module_node-object-hash/objectSorter..makeObjectSorter..objectToString">objectToString</a></code></dt>
+<dd><p>Object sorter module.
+It provides object sorter function constructor.</p>
+</dd>
+<dt><a href="#module_node-object-hash">node-object-hash</a> : <code><a href="#module_node-object-hash..apiConstructor">apiConstructor</a></code></dt>
+<dd><p>Node object hash module.
+It provides a methods that return object hash or sorted object string.</p>
+</dd>
+</dl>
+
+<a name="module_node-object-hash/objectSorter"></a>
+
+## node-object-hash/objectSorter : <code>[objectToString](#module_node-object-hash/objectSorter..makeObjectSorter..objectToString)</code>
+Object sorter module.
+It provides object sorter function constructor.
+
+
+* [node-object-hash/objectSorter](#module_node-object-hash/objectSorter) : <code>[objectToString](#module_node-object-hash/objectSorter..makeObjectSorter..objectToString)</code>
+    * [~_guessObjectType(obj)](#module_node-object-hash/objectSorter.._guessObjectType) ⇒ <code>string</code> ℗
+    * [~_guessType(obj)](#module_node-object-hash/objectSorter.._guessType) ⇒ <code>string</code> ℗
+    * [~makeObjectSorter([options])](#module_node-object-hash/objectSorter..makeObjectSorter) ⇒ <code>[objectToString](#module_node-object-hash/objectSorter..makeObjectSorter..objectToString)</code> ℗
+        * [~objectToString(obj)](#module_node-object-hash/objectSorter..makeObjectSorter..objectToString) ⇒ <code>string</code> ℗
+
+<a name="module_node-object-hash/objectSorter.._guessObjectType"></a>
+
+### node-object-hash/objectSorter~_guessObjectType(obj) ⇒ <code>string</code> ℗
+Guesses object's type
+
+**Kind**: inner method of <code>[node-object-hash/objectSorter](#module_node-object-hash/objectSorter)</code>  
+**Returns**: <code>string</code> - Object type  
+**Access:** private  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| obj | <code>Object</code> | Object to guess type |
+
+**Example**  
+```js
+var a = [];
+_guessObjectType(a) === 'array'; // true
+```
+<a name="module_node-object-hash/objectSorter.._guessType"></a>
+
+### node-object-hash/objectSorter~_guessType(obj) ⇒ <code>string</code> ℗
+Guesses variable type
+
+**Kind**: inner method of <code>[node-object-hash/objectSorter](#module_node-object-hash/objectSorter)</code>  
+**Returns**: <code>string</code> - Variable type  
+**Access:** private  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| obj | <code>\*</code> | Variable to guess type |
+
+**Example**  
+```js
+var a = '';
+_guessType(a) === 'string'; // true
+```
+<a name="module_node-object-hash/objectSorter..makeObjectSorter"></a>
+
+### node-object-hash/objectSorter~makeObjectSorter([options]) ⇒ <code>[objectToString](#module_node-object-hash/objectSorter..makeObjectSorter..objectToString)</code> ℗
+Creates object sorter function
+
+**Kind**: inner method of <code>[node-object-hash/objectSorter](#module_node-object-hash/objectSorter)</code>  
+**Returns**: <code>[objectToString](#module_node-object-hash/objectSorter..makeObjectSorter..objectToString)</code> - Object sorting function  
+**Access:** private  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>Object</code> |  | Sorter options |
+| [options.coerce] | <code>boolean</code> | <code>&quot;true&quot;</code> | Performs type coercion |
+| [options.sort] | <code>boolean</code> | <code>&quot;true&quot;</code> | Performs array, object, etc. sorting |
+
+**Example**  
+```js
+// 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
+```
+<a name="module_node-object-hash/objectSorter..makeObjectSorter..objectToString"></a>
+
+#### makeObjectSorter~objectToString(obj) ⇒ <code>string</code> ℗
+Object sorting function
+
+**Kind**: inner method of <code>[makeObjectSorter](#module_node-object-hash/objectSorter..makeObjectSorter)</code>  
+**Returns**: <code>string</code> - Sorted string  
+**Access:** private  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| obj | <code>Object</code> | Object to sort |
+
+<a name="module_node-object-hash"></a>
+
+## node-object-hash : <code>[apiConstructor](#module_node-object-hash..apiConstructor)</code>
+Node object hash module.
+It provides a methods that return object hash or sorted object string.
+
+
+* [node-object-hash](#module_node-object-hash) : <code>[apiConstructor](#module_node-object-hash..apiConstructor)</code>
+    * _instance_
+        * [.sort(obj)](#module_node-object-hash+sort) ⇒ <code>string</code>
+        * [.hash(obj, [opts])](#module_node-object-hash+hash) ⇒ <code>string</code>
+    * _inner_
+        * [~apiConstructor([options])](#module_node-object-hash..apiConstructor) ⇒ <code>[API](#module_node-object-hash..API)</code>
+        * [~API](#module_node-object-hash..API) : <code>Object</code>
+
+<a name="module_node-object-hash+sort"></a>
+
+### node-object-hash.sort(obj) ⇒ <code>string</code>
+Creates sorted string from given object
+
+**Kind**: instance method of <code>[node-object-hash](#module_node-object-hash)</code>  
+**Returns**: <code>string</code> - Sorted object string  
+**Access:** public  
+**See**: [objectToString](#module_node-object-hash/objectSorter..makeObjectSorter..objectToString)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| obj | <code>\*</code> | JS object to be sorted |
+
+**Example**  
+```js
+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}"
+```
+<a name="module_node-object-hash+hash"></a>
+
+### node-object-hash.hash(obj, [opts]) ⇒ <code>string</code>
+Creates hash from given object
+
+**Kind**: instance method of <code>[node-object-hash](#module_node-object-hash)</code>  
+**Returns**: <code>string</code> - Object hash value  
+**Access:** public  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| obj | <code>\*</code> |  | JS object to hash |
+| [opts] | <code>Object</code> |  | Options |
+| [opts.alg] | <code>string</code> | <code>&quot;sha256&quot;</code> | Crypto algorithm to use |
+| [opts.enc] | <code>string</code> | <code>&quot;hex&quot;</code> | Hash string encoding |
+
+**Example**  
+```js
+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"
+```
+<a name="module_node-object-hash..apiConstructor"></a>
+
+### node-object-hash~apiConstructor([options]) ⇒ <code>[API](#module_node-object-hash..API)</code>
+Generates node-object-hash API object
+
+**Kind**: inner method of <code>[node-object-hash](#module_node-object-hash)</code>  
+**Returns**: <code>[API](#module_node-object-hash..API)</code> - Node object hash API instance  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>Object</code> |  | Library options |
+| [options.coerce] | <code>boolean</code> | <code>true</code> | Performs type coercion |
+| [options.sort] | <code>boolean</code> | <code>true</code> | Performs array, object, etc. sorting |
+| [options.alg] | <code>string</code> | <code>&quot;sha256&quot;</code> | Default crypto algorithm to use (can be overridden) |
+| [options.enc] | <code>string</code> | <code>&quot;hex&quot;</code> | Hash string encoding (can be overridden) |
+
+**Example**  
+```js
+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]'
+```
+<a name="module_node-object-hash..API"></a>
+
+### node-object-hash~API : <code>Object</code>
+Node object hash API object
+
+**Kind**: inner typedef of <code>[node-object-hash](#module_node-object-hash)</code>  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| hash | <code>function</code> | Returns object hash string (see [hash](#module_node-object-hash+hash)) |
+| sort | <code>function</code> | Returns sorted object string (see [sort](#module_node-object-hash+sort)) |
+
+
+# Requirements
+
+## version \>=1.0.0
 - `>=nodejs-0.10.0`
 
-#### version \>=0.1.0 && <1.0.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)
+## browsers
+- nodejs `crypto` module for browsers (e.g. [browserify-crypto](https://github.com/crypto-browserify/crypto-browserify)).
 
-### Example
+# Example
 ```js
@@ -109,3 +349,3 @@ var hasher = require('node-object-hash');
 
-hashSortCoerce.sortObject(object.c)
+hashSortCoerce.sort(object.c);
 // returns '[0,1,2,3,4]'
@@ -117,9 +357,15 @@ ```
 
-### Benchmark results
+# Benchmarks
+
 Bench data - array of 100000 complex objects
 
-#### Usage
-`npm run bench`
+## Usage
 
-#### Results
+* `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)        |
@@ -129,2 +375,4 @@ |------------------------|------------|--------------------|
 | node-object-hash-1.0.0 | 2805.581   | 27                 |
+| node-object-hash-2.0.0 | 2555.583   | 27                 |
+| object-hash-1.1.5      | 28115.553  | 39                 |
 | object-hash-1.1.4      | 534528.254 | 41                 |
@@ -134,7 +382,18 @@ | object-hash-1.1.3      | ERROR      | Out of heap memory |
 
-### Similar libraries
+### 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
+# License
+
 ISC

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

43490

increased by192.31%

Number of package files

8

increased by33.33%

Lines of code

371

increased by31.56%

Number of lines in readme file

392

increased by194.74%

Worsened metrics

Dev dependency count

9

increased by12.5%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes