1 | # object-hash
|
2 |
|
3 | Generate hashes from objects and values in node and the browser. Uses node.js
|
4 | crypto module for hashing. Supports SHA1 and many others (depending on the platform)
|
5 | as well as custom streams (e.g. CRC32).
|
6 |
|
7 | [![NPM](https://nodei.co/npm/object-hash.png?downloads=true&downloadRank=true)](https://www.npmjs.com/package/object-hash)
|
8 |
|
9 | [![Travis CI](https://secure.travis-ci.org/puleos/object-hash.png?branch=master)](https://secure.travis-ci.org/puleos/object-hash?branch=master)
|
10 | [![Coverage Status](https://coveralls.io/repos/puleos/object-hash/badge.svg?branch=master&service=github)](https://coveralls.io/github/puleos/object-hash?branch=master)
|
11 |
|
12 | * Hash values of any type.
|
13 | * Supports a keys only option for grouping similar objects with different values.
|
14 |
|
15 | ```js
|
16 | var hash = require('object-hash');
|
17 |
|
18 | hash({foo: 'bar'}) // => '67b69634f9880a282c14a0f0cb7ba20cf5d677e9'
|
19 | hash([1, 2, 2.718, 3.14159]) // => '136b9b88375971dff9f1af09d7356e3e04281951'
|
20 | ```
|
21 |
|
22 | ## Versioning Disclaimer
|
23 |
|
24 | Starting with version `1.1.8` (released April 2017), new versions will consider
|
25 | the exact returned hash part of the API contract, i.e. changes that will affect
|
26 | hash values will be considered `semver-major`. Previous versions may violate
|
27 | that expectation.
|
28 |
|
29 | For more information, see [this discussion](https://github.com/puleos/object-hash/issues/30).
|
30 |
|
31 | ## hash(value, options);
|
32 | Generate a hash from any object or type. Defaults to sha1 with hex encoding.
|
33 | * `algorithm` hash algo to be used: 'sha1', 'md5'. default: sha1
|
34 | * This supports the algorithms returned by `crypto.getHashes()`. Note that the default of SHA-1 is not considered secure, and a stronger algorithm should be used if a cryptographical hash is desired.
|
35 | * `excludeValues` {true|false} hash object keys, values ignored. default: false
|
36 | * `encoding` hash encoding, supports 'buffer', 'hex', 'binary', 'base64'. default: hex
|
37 | * `ignoreUnknown` {true|*false} ignore unknown object types. default: false
|
38 | * `replacer` optional function that replaces values before hashing. default: accept all values
|
39 | * `respectFunctionProperties` {true|false} Whether properties on functions are considered when hashing. default: true
|
40 | * `respectFunctionNames` {true|false} consider `name` property of functions for hashing. default: true
|
41 | * `respectType` {true|false} Whether special type attributes (`.prototype`, `.__proto__`, `.constructor`)
|
42 | are hashed. default: true
|
43 | * `unorderedArrays` {true|false} Sort all arrays using before hashing. Note that this affects *all* collections,
|
44 | i.e. including typed arrays, Sets, Maps, etc. default: false
|
45 | * `unorderedSets` {true|false} Sort `Set` and `Map` instances before hashing, i.e. make
|
46 | `hash(new Set([1, 2])) == hash(new Set([2, 1]))` return `true`. default: true
|
47 | * `unorderedObjects` {true|false} Sort objects before hashing, i.e. make `hash({ x: 1, y: 2 }) === hash({ y: 2, x: 1 })`. default: true
|
48 | * `excludeKeys` optional function for exclude specific key(s) from hashing, if returns true then exclude from hash. default: include all keys
|
49 |
|
50 | ## hash.sha1(value);
|
51 | Hash using the sha1 algorithm.
|
52 |
|
53 | Note that SHA-1 is not considered secure, and a stronger algorithm should be used if a cryptographical hash is desired.
|
54 |
|
55 | *Sugar method, equivalent to hash(value, {algorithm: 'sha1'})*
|
56 |
|
57 | ## hash.keys(value);
|
58 | Hash object keys using the sha1 algorithm, values ignored.
|
59 |
|
60 | *Sugar method, equivalent to hash(value, {excludeValues: true})*
|
61 |
|
62 | ## hash.MD5(value);
|
63 | Hash using the md5 algorithm.
|
64 |
|
65 | Note that the MD5 is not considered secure, and a stronger algorithm should be used if a cryptographical hash is desired.
|
66 |
|
67 | *Sugar method, equivalent to hash(value, {algorithm: 'md5'})*
|
68 |
|
69 | ## hash.keysMD5(value);
|
70 | Hash object keys using the md5 algorithm, values ignored.
|
71 |
|
72 | Note that the MD5 is not considered secure, and a stronger algorithm should be used if a cryptographical hash is desired.
|
73 |
|
74 | *Sugar method, equivalent to hash(value, {algorithm: 'md5', excludeValues: true})*
|
75 |
|
76 | ## hash.writeToStream(value, [options,] stream):
|
77 | Write the information that would otherwise have been hashed to a stream, e.g.:
|
78 | ```js
|
79 | hash.writeToStream({foo: 'bar', a: 42}, {respectType: false}, process.stdout)
|
80 | // => e.g. 'object:a:number:42foo:string:bar'
|
81 | ```
|
82 |
|
83 | ## Installation
|
84 |
|
85 | node:
|
86 | ```js
|
87 | npm install object-hash
|
88 | ```
|
89 |
|
90 | browser: */dist/object_hash.js*
|
91 | ```
|
92 | <script src="object_hash.js" type="text/javascript"></script>
|
93 |
|
94 | <script>
|
95 | var hash = objectHash.sha1({foo:'bar'});
|
96 |
|
97 | console.log(hash); // e003c89cdf35cdf46d8239b4692436364b7259f9
|
98 | </script>
|
99 | ```
|
100 |
|
101 | ## Example usage
|
102 | ```js
|
103 | var hash = require('object-hash');
|
104 |
|
105 | var peter = {name: 'Peter', stapler: false, friends: ['Joanna', 'Michael', 'Samir'] };
|
106 | var michael = {name: 'Michael', stapler: false, friends: ['Peter', 'Samir'] };
|
107 | var bob = {name: 'Bob', stapler: true, friends: [] };
|
108 |
|
109 | /***
|
110 | * sha1 hex encoding (default)
|
111 | */
|
112 | hash(peter);
|
113 | // 14fa461bf4b98155e82adc86532938553b4d33a9
|
114 | hash(michael);
|
115 | // 4b2b30e27699979ce46714253bc2213010db039c
|
116 | hash(bob);
|
117 | // 38d96106bc8ef3d8bd369b99bb6972702c9826d5
|
118 |
|
119 | /***
|
120 | * hash object keys, values ignored
|
121 | */
|
122 | hash(peter, { excludeValues: true });
|
123 | // 48f370a772c7496f6c9d2e6d92e920c87dd00a5c
|
124 | hash(michael, { excludeValues: true });
|
125 | // 48f370a772c7496f6c9d2e6d92e920c87dd00a5c
|
126 | hash.keys(bob);
|
127 | // 48f370a772c7496f6c9d2e6d92e920c87dd00a5c
|
128 |
|
129 | /***
|
130 | * hash object, ignore specific key(s)
|
131 | */
|
132 | hash(peter, { excludeKeys: function(key) {
|
133 | if ( key === 'friends') {
|
134 | return true;
|
135 | }
|
136 | return false;
|
137 | }
|
138 | });
|
139 | // 66b7d7e64871aa9fda1bdc8e88a28df797648d80
|
140 |
|
141 | /***
|
142 | * md5 base64 encoding
|
143 | */
|
144 | hash(peter, { algorithm: 'md5', encoding: 'base64' });
|
145 | // 6rkWaaDiG3NynWw4svGH7g==
|
146 | hash(michael, { algorithm: 'md5', encoding: 'base64' });
|
147 | // djXaWpuWVJeOF8Sb6SFFNg==
|
148 | hash(bob, { algorithm: 'md5', encoding: 'base64' });
|
149 | // lFzkw/IJ8/12jZI0rQeS3w==
|
150 | ```
|
151 |
|
152 | ## Legacy Browser Support
|
153 | IE <= 8 and Opera <= 11 support dropped in version 0.3.0. If you require
|
154 | legacy browser support you must either use an ES5 shim or use version 0.2.5
|
155 | of this module.
|
156 |
|
157 | ## Development
|
158 |
|
159 | ```
|
160 | git clone https://github.com/puleos/object-hash
|
161 | ```
|
162 |
|
163 | ## Node Docker Wrapper
|
164 |
|
165 | If you want to stand this up in a docker container, you should take at look
|
166 | at the [![node-object-hash](https://github.com/bean5/node-object-hash)](https://github.com/bean5/node-object-hash) project.
|
167 |
|
168 | ### gulp tasks
|
169 | * `gulp watch` (default) watch files, test and lint on change/add
|
170 | * `gulp test` unit tests
|
171 | * `gulp karma` browser unit tests
|
172 | * `gulp lint` jshint
|
173 | * `gulp dist` create browser version in /dist
|
174 |
|
175 | ## License
|
176 | MIT
|
177 |
|
178 | ## Changelog
|
179 |
|
180 | ### v2.0.0
|
181 |
|
182 | Only Node.js versions `>= 6.0.0` are being tested in CI now.
|
183 | No other breaking changes were introduced.
|