BLAKE2 Hash Functions (JavaScript)

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` in an ECMAScript Module (ESM) context (e.g., in a modern Node.js project with `"type": "module"` in package.json or a browser environment).
  fix Use `import * as blake from 'blakejs';` for ESM environments, or ensure your file is treated as a CommonJS module.

• TypeError: blake.blake2bHex is not a function

  cause Incorrectly importing `blakejs` or attempting to destructure named exports when the package primarily exports a single object.
  fix Ensure you are using `import * as blake from 'blakejs';` (ESM) or `const blake = require('blakejs');` (CJS), and then access functions via `blake.blake2bHex`.

• TypeError: Input must be a string, Buffer, or Uint8Array

  cause The input provided to a hashing function (e.g., `blake2bHex`) is not a JavaScript string, Node.js Buffer, or a standard `Uint8Array`.
  fix Convert the input data to an accepted type before passing it to `blakejs` functions. For example, use `new TextEncoder().encode('your string')` to convert a string to a `Uint8Array`.

• Error: blake2b: output length too large

  cause The specified `outlen` parameter for a BLAKE2b hash function exceeds its maximum allowed value of 64 bytes (or 32 bytes for BLAKE2s).
  fix Adjust the `outlen` parameter to be less than or equal to 64 bytes for BLAKE2b functions, or less than or equal to 32 bytes for BLAKE2s functions.

Warnings

• gotcha This pure JavaScript implementation is significantly slower than native or WebAssembly alternatives (e.g., node-blake2 or blake2.wasm). For performance-critical applications, especially on Node.js servers, consider those alternatives.
  Fix: For Node.js, use `node-blake2`. For browsers with WASM support, consider `blake2.wasm` for better performance.
• gotcha Pure JavaScript cryptographic implementations, while generally secure algorithmically, can be more susceptible to timing side-channel attacks compared to native implementations. Avoid using `blakejs` for hashing highly sensitive keys in environments where an attacker can precisely measure execution time.
  Fix: Use hardware-accelerated or native cryptographic libraries for operations involving highly sensitive cryptographic keys in untrusted environments.
• gotcha The library has an internal limitation of handling input up to 2^53 bytes (approximately 8 petabytes). While extremely large, applications processing truly massive datasets should be aware of this theoretical limit.
  Fix: For inputs exceeding 2^53 bytes, an alternative hashing solution or custom streaming logic capable of handling such scale would be required, though this is an extreme edge case.
• gotcha When using BLAKE2b, the maximum output length and key length is 64 bytes. For BLAKE2s, it's 32 bytes. Exceeding these limits will result in an error.
  Fix: Ensure `outlen` and `key` array lengths passed to `blake2b*` functions are <= 64 bytes, and for `blake2s*` functions, <= 32 bytes.

Install

• npm install blakejs npm
• yarn add blakejs yarn
• pnpm add blakejs pnpm

Imports

• blake
  wrong:

  import blake from 'blakejs';

  correct:

  import * as blake from 'blakejs';

  For ESM, use a namespace import (`* as blake`) to reliably get an object containing all functions, mirroring how it's used in CommonJS. A direct default import (`import blake`) might work in some transpilation setups but can be less robust for CJS interop.
• blake

  const blake = require('blakejs');

  Standard CommonJS import for Node.js and older browser environments. The 'blake' constant will be an object containing all hashing functions (e.g., `blake.blake2bHex`).
• blake2bHex
  wrong:

  import { blake2bHex } from 'blakejs';

  correct:

  blake.blake2bHex(data);

  Individual hashing functions like `blake2bHex` are properties of the imported 'blake' object, not direct named exports. They should be accessed via dot notation on the imported object.

Quickstart

Demonstrates both synchronous (hex string and Uint8Array) and streaming BLAKE2b/BLAKE2s hashing with optional keys, using an ESM import pattern.

import * as blake from 'blakejs';

const inputString = 'hello blakejs world';
const inputBytes = new Uint8Array([0x61, 0x62, 0x63, 0x64, 0x65]); // 'abcde'
const key = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); // Optional key for MAC

// Compute BLAKE2b hash of a string, returning a hex string
const blake2bHexString = blake.blake2bHex(inputString, null, 64);
console.log('BLAKE2b (string) hex:', blake2bHexString);

// Compute BLAKE2s hash of a Uint8Array, returning a Uint8Array
const blake2sByteArray = blake.blake2s(inputBytes, key, 32);
console.log('BLAKE2s (bytes) array:', blake2sByteArray);

// Streaming BLAKE2b hash example
const OUTPUT_LENGTH = 64;
const streamingKey = null; // Optional key
const context = blake.blake2bInit(OUTPUT_LENGTH, streamingKey);
blake.blake2bUpdate(context, new TextEncoder().encode('first part '));
blake.blake2bUpdate(context, new TextEncoder().encode('second part of data'));
const finalHash = blake.blake2bFinal(context);
console.log('Streaming BLAKE2b hex:', Array.from(finalHash).map(b => b.toString(16).padStart(2, '0')).join(''));