Object Hash Generator

Common errors

• TypeError: crypto.createHash is not a function

  cause This error typically occurs in browser environments where Node.js's built-in `crypto` module is not available or properly polyfilled.
  fix If bundling for the browser, configure your bundler (e.g., Webpack, Rollup) to polyfill the Node.js `crypto` module or use a browser-specific hashing library. Some bundlers automatically polyfill, but explicit configuration might be needed.

• Error: Cannot find module 'object-hash'

  cause The package `object-hash` is not installed or not resolvable in the current environment.
  fix Run `npm install object-hash` or `yarn add object-hash` in your project directory. Ensure your module resolution paths are correctly configured if working in a monorepo or custom environment.

• TypeError: hash is not a function (when using ESM 'import { hash } from ...')

  cause `object-hash` provides a default export function, not a named export `hash`.
  fix Change your import statement to `import hash from 'object-hash';` for ESM, or use `import * as hash from 'object-hash';` for TypeScript/ESM interop with CommonJS modules.

Warnings

• breaking Prior to version 1.1.8 (released April 2017), changes to the exact hash output were not considered semver-major, meaning minor or patch updates could alter hash values. Since 1.1.8, any change affecting hash values is a breaking change and will be reflected in a major version bump.
  Fix: For applications relying on consistent hash outputs across minor versions, ensure you are using `object-hash@^1.1.8` or newer and strictly adhere to semver for major version updates.
• gotcha The default hashing algorithm, SHA-1, and the readily available MD5 algorithm are not considered cryptographically secure for modern applications. They are vulnerable to collision attacks and should not be used for security-sensitive purposes like password hashing or digital signatures.
  Fix: For security-sensitive applications, explicitly specify a stronger algorithm like `sha256` or `sha512` using the `algorithm` option (e.g., `{ algorithm: 'sha256' }`).
• gotcha The `unorderedArrays` option, when set to `true`, affects the sorting of *all* iterable collections, including plain JavaScript arrays, `Set` instances, `Map` instances, and typed arrays. This might lead to unexpected behavior if users only anticipate it for basic arrays.
  Fix: Understand the broad impact of `unorderedArrays`. If you only need order-independent hashing for specific types, consider using `unorderedSets` or `unorderedObjects` selectively, or implement a custom `replacer` function for fine-grained control.
• gotcha In browser environments, `object-hash` relies on the Node.js `crypto` module. If not properly polyfilled or bundled for the browser, this can lead to runtime errors.
  Fix: When using `object-hash` in a browser environment, ensure your build process (e.g., Webpack, Rollup with appropriate plugins) provides a compatible polyfill for Node.js's `crypto` module, or use a library specifically designed for browser crypto APIs like `window.crypto.subtle`.
• gotcha Hash values generated by `object-hash` may differ from simple `JSON.stringify()` followed by a standard hashing algorithm (e.g., `crypto.createHash`). This is because `object-hash` prefixes values with their types and handles various JavaScript primitives and objects (e.g., functions, dates) differently.
  Fix: When comparing hashes with other systems, be aware that `object-hash` employs a specific internal serialization strategy. If interoperability is required, either both systems must use `object-hash`, or the hashing logic of `object-hash` (which involves type-prefixing) must be replicated. This behavior is not explicitly documented and may require inspecting the source code for precise replication.

Install

• npm install object-hash npm
• yarn add object-hash yarn
• pnpm add object-hash pnpm

Imports

• hash
  wrong:

  import { hash } from 'object-hash';

  correct:

  import hash from 'object-hash';

  The primary export is a default function. While modern bundlers often handle `import { hash } from 'object-hash'` due to interop, the canonical ESM import for a CJS default export is `import hash from 'object-hash;'` or `import * as hash from 'object-hash'`.
• hash

  const hash = require('object-hash');

  This is the standard CommonJS import pattern, as shown in the package's examples.
• hash.sha1
  wrong:

  import { sha1 } from 'object-hash';

  correct:

  const hash = require('object-hash');
  const myHash = hash.sha1({ a: 1 });

  Sugar methods like `sha1`, `MD5`, `keys` are properties of the main default export, not named exports themselves. Access them via the imported `hash` object.

Quickstart

Demonstrates basic object hashing, specifying a different algorithm and encoding, hashing only object keys, and ensuring order-independent hashing for objects and arrays.

const hash = require('object-hash');

// Basic hashing of an object
const objectHash = hash({ foo: 'bar', baz: [1, 2, { a: 3 }] });
console.log('Object Hash:', objectHash); // Example: '37a3c3d5e21d5a7b6c7a9f8d9b6e2d1f0a8c4b2e'

// Hashing with specific algorithm and encoding (e.g., SHA256)
const sha256Hash = hash({ data: 'sensitive info' }, { algorithm: 'sha256', encoding: 'base64' });
console.log('SHA256 Hash (Base64):', sha256Hash);

// Hashing an object, ignoring values (only keys contribute to hash)
const keysOnlyHash = hash({ name: 'Alice', age: 30 }, { excludeValues: true });
console.log('Keys-only Hash:', keysOnlyHash);

// Hashing with unordered objects and arrays for consistent results regardless of property/element order
const unorderedHash1 = hash({ x: 1, y: 2 }, { unorderedObjects: true, unorderedArrays: true });
const unorderedHash2 = hash({ y: 2, x: 1 }, { unorderedObjects: true, unorderedArrays: true });
console.log('Unordered Object Hash 1:', unorderedHash1);
console.log('Unordered Object Hash 2:', unorderedHash2);
console.log('Unordered hashes match:', unorderedHash1 === unorderedHash2);