hash-it

What is hash-it?

The hash-it npm package is a utility for creating unique hash values from JavaScript objects. It is particularly useful for creating hash keys for complex objects, ensuring that the same object will always produce the same hash value.

What are hash-it's main functionalities?

Hashing Objects

This feature allows you to generate a unique hash value for a given JavaScript object. The same object will always produce the same hash value, which is useful for caching or quick comparisons.

const { hash } = require('hash-it');
const obj = { a: 1, b: 2 };
const hashValue = hash(obj);
console.log(hashValue);

Hashing Arrays

This feature allows you to generate a unique hash value for an array. It ensures that the same array will always produce the same hash value, which can be useful for array comparisons or caching.

const { hash } = require('hash-it');
const arr = [1, 2, 3];
const hashValue = hash(arr);
console.log(hashValue);

Hashing Nested Structures

This feature allows you to generate a unique hash value for nested structures, including objects within objects and arrays within objects. It ensures consistency in hash values for complex data structures.

const { hash } = require('hash-it');
const nestedObj = { a: { b: 2 }, c: [1, 2, 3] };
const hashValue = hash(nestedObj);
console.log(hashValue);

Other packages similar to hash-it

object-hash

The object-hash package provides similar functionality to hash-it by generating unique hash values for JavaScript objects. It supports a variety of hashing algorithms and can handle complex nested structures. Compared to hash-it, object-hash offers more customization options for the hashing process.

hasha

The hasha package is a versatile hashing utility that supports multiple hashing algorithms like MD5, SHA-1, and SHA-256. While it is not specifically designed for hashing objects, it can be used to hash strings, buffers, and other data types. It is more general-purpose compared to hash-it.

crypto

The built-in Node.js crypto module provides a wide range of cryptographic functionalities, including hashing. While it is more complex and requires more setup to hash objects compared to hash-it, it offers extensive options for cryptographic operations and is highly customizable.

README

hash-it

Fast and consistent hashCode for any object type

Table of contents

• hash-it
  • Table of contents
  • Usage
  • Overview
  • Hash consistency
  • Support
    • Browsers
    • Node
  • Development

Usage

// ES2015
import hash from 'hash-it';

// CommonJS
const hash = require('hash-it');

// hash any standard object
console.log(hash({ foo: 'bar' })); // 13729774857125

// or a circular object
console.log(hash(window)); // 3270731309314

Overview

hash-it has a simple goal: provide a fast, consistent, unique hashCode for any object type that is uniquely based on its values. This has a number of uses such as duplication prevention, equality comparisons, blockchain construction, etc.

Any object type?

Yes, any object type. Primitives, ES2015 classes like Symbol, DOM elements (yes, you can even hash the window object if you want). Any object type. Here is the list of object classes that produce consistent, unique hashes based on their value:

• Arguments
• Array
• ArrayBuffer
• AsyncFunction (based on toString)
• AsyncGeneratorFunction (based on toString)
• BigInt
• BigInt64Array
• BigUint64Array
• Boolean
• DataView (based on its buffer)
• Date (based on getTime)
• DocumentFragment (based on outerHTML of all children)
• Error (based on stack)
  • Includes all sub-types (e.g., TypeError, ReferenceError, etc.)
• Event (based on all properties other than Event.timeStamp)
  • Includes all sub-types (e.g., MouseEvent, KeyboardEvent, etc.)
• Float32Array
• Float64Array
• Function (based on toString)
• GeneratorFunction (based on toString)
• Int8Array
• Int16Array
• Int32Array
• HTMLElement (based on outerHTML)
  • Includes all sub-types (e.g., HTMLAnchorElement, HTMLDivElement, etc.)
• Map (order-agnostic)
• Null
• Number
• Object (handles circular objects, order-agnostic)
• Proxy
• RegExp
• Set (order-agnostic)
• SharedArrayBuffer
• String
• SVGElement (based on outerHTML)
  • Includes all sub-types (e.g., SVGRectElement, SVGPolygonElement, etc.)
• Symbol (based on toString)
• Uint8Array
• Uint8ClampedArray
• Uint16Array
• Uint32Array
• Undefined
• Window

Are there any exceptions?

Sadly, yes, there are a few scenarios where internal values cannot be introspected for the object. In this case, the object is hashed based on its class type and reference.

• Promise
  • There is no way to obtain the values contained within due to its asynchronous nature
• Generator (the result of calling a GeneratorFunction)
  • Like Promise, there is no way to obtain the values contained within due to its dynamic iterable nature
• WeakMap / WeakRef / WeakSet
  • The spec explicitly forbids iteration over them, so the unique values cannot be discovered

const promise = Promise.resolve(123);

console.log(hash(promise)); // 16843037491939
console.log(hash(promise)); // 16843037491939
console.log(hash(Promise.resolve(123))); // 4622327363876

If there is an object class or data type that is missing, please submit an issue.

Hash consistency

While the hashes will be consistent when calculated within the same environment, there is no guarantee that the resulting hash will be the same across different environments due to environment-specific or browser-specific implementations of features. This is limited to extreme edge cases, such as hashing the window object, but should be considered if being used with persistence over different environments.

Support

Browsers

• Chrome (all versions)
• Firefox (all versions)
• Edge (all versions)
• Opera 15+
• IE 9+
• Safari 6+
• iOS 8+
• Android 4+

Node

• 4+

Development

Clone the repo and dependencies via yarn. The npm scripts available:

• benchmark => run benchmark of various data types
• benchmark:compare => run benchmark of some data types comparing against other hashing modules
• build => run rollup to build ESM, CJS, and UMD files
• clean => remove files produced from build script
• dev => run webpack dev server to run example app / playground
• lint => run ESLint against all files in the src folder
• lint:fix => run lint script, automatically applying fixable changes
• prepublishOnly => run typecheck, lint, test, and build
• start => alias for dev script
• test => run jest test functions with NODE_ENV=test
• test:coverage => run test with coverage checker
• test:watch => run test with persistent watcher
• typecheck => run tsc to validate internal typings

Changelog

6.0.0

Breaking changes

• Equality utilities (is / is.any / is.all / is.not) are no longer provided
• Error type hashes now include the message (previously only included stack)
• Non-enumerable type hashes (Generator, Promise, WeakMap, WeakSet) now hash uniquely based on reference
• WeakMap is now required at runtime (used as cache for circular references)

Enhancements

• Better support for system-specific loading (ESM vs CJS vs UMD)
• Added support for primitive wrappers (e.g. new Number('123'))
• Added support for more object classes
  • AsyncFunction
  • AsyncGeneratorFunction
  • BigInt64Array
  • BigUint64Array
  • GeneratorFunction
  • SharedArrayBuffer
  • WeakRef (same limitations as those for WeakMap / WeakSet)