BLAKE3 Hashing (WebAssembly)

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES `import` syntax in a CommonJS context (e.g., a `.js` file without `"type": "module"` in `package.json`, or a Node.js version prior to v16).
  fix Ensure your project is configured for ES Modules. Add `"type": "module"` to your `package.json` or rename your file to `.mjs`. If using Node.js, upgrade to version 16 or newer.

• Error: BLAKE3 module not initialized. Call init() first.

  cause The WebAssembly module was not loaded or initialized by calling `await init()` before a hashing function was invoked.
  fix Make sure `await init()` is called once and completes successfully before any calls to `hash()` or `createHasher()`.

• TypeError: hash is not a function

  cause This can occur if `init()` was not `await`ed, or if the `blake3-wasm` module was imported incorrectly (e.g., trying to use a default import for named exports).
  fix Verify that `await init()` has completed and that you are using named imports: `import { init, hash } from 'blake3-wasm';`.

• WebAssembly.instantiateStreaming failed

  cause This browser-specific error usually indicates a network issue loading the `.wasm` file (e.g., CORS, incorrect path) or an invalid MIME type from the server.
  fix Check your server configuration to ensure `.wasm` files are served with the `Content-Type: application/wasm` header. Verify the `.wasm` file path is correct and accessible. If self-hosting, ensure proper CORS headers are set if loading from a different origin.

Warnings

• breaking Version 3.0.0 completely drops CommonJS (require) support. It is now an ES Module (import) only package.
  Fix: Migrate your project to use ES Modules. For Node.js, ensure your `package.json` has `"type": "module"` or use `.mjs` file extension. Replace `require('blake3-wasm')` with `import { ... } from 'blake3-wasm'`.
• breaking Explicit asynchronous initialization via `await init()` is now mandatory before using any hashing functions.
  Fix: Always call and `await` the `init()` function once at the start of your application before attempting to use `hash` or `createHasher`. Example: `import { init, hash } from 'blake3-wasm'; await init();`
• gotcha WebAssembly module loading can fail due to network issues, incorrect paths, or improper MIME types when served in a browser environment.
  Fix: Ensure the `.wasm` file (if external) is correctly served with `application/wasm` MIME type and is accessible from your application's origin. Handle potential `init()` rejection gracefully with a `try...catch` block.
• gotcha The `hash` function is designed for convenience with smaller inputs. For very large files or data streams, `createHasher` offers better performance and memory efficiency.
  Fix: For large inputs, instantiate a hasher with `createHasher()`, feed data in chunks using `hasher.update(chunk)`, and retrieve the final hash with `hasher.digest()`.

Install

• npm install blake3-wasm npm
• yarn add blake3-wasm yarn
• pnpm add blake3-wasm pnpm

Imports

• init
  wrong:

  const { init, hash } = require('blake3-wasm');

  correct:

  import { init, hash } from 'blake3-wasm';
  await init();

  Since v3.0.0, this package is ESM-only. The `init()` function must be called and awaited once before any other BLAKE3 operations can be performed, ensuring the WebAssembly module is loaded.
• hash
  wrong:

  const result = blake3.hash(data); // if blake3 imported as default

  correct:

  import { init, hash } from 'blake3-wasm';
  // ... after await init() ...
  const data = new Uint8Array([1, 2, 3]);
  const result = hash(data);

  The `hash` function performs a one-shot hash. It expects `Uint8Array` as input and returns a `Uint8Array`. Ensure `init()` has been awaited.
• createHasher
  wrong:

  const finalHash = createHasher(data).digest(); // missing update step for streaming

  correct:

  import { init, createHasher } from 'blake3-wasm';
  // ... after await init() ...
  const hasher = createHasher();
  hasher.update(new TextEncoder().encode('hello'));
  hasher.update(new TextEncoder().encode('world'));
  const finalHash = hasher.digest();

  Use `createHasher()` for incremental hashing of large inputs. The returned hasher object exposes `update()` for adding data chunks and `digest()` to finalize the hash.

Quickstart

Demonstrates asynchronous initialization, one-shot hashing, and incremental hashing using `createHasher` for larger data streams, including custom output lengths.

import { init, hash, createHasher } from 'blake3-wasm';

async function runBlake3Example() {
  console.log('Initializing BLAKE3 WebAssembly module...');
  await init();
  console.log('BLAKE3 module initialized.');

  // --- One-shot hashing ---
  const dataOneShot = new TextEncoder().encode('Hello, BLAKE3!');
  const hashResult = hash(dataOneShot);
  console.log('One-shot hash (Uint8Array):', hashResult);
  console.log('One-shot hash (hex):', Array.from(hashResult).map(b => b.toString(16).padStart(2, '0')).join(''));

  // --- Incremental hashing ---
  const hasher = createHasher();
  const chunk1 = new TextEncoder().encode('This is the first part');
  const chunk2 = new TextEncoder().encode(' and this is the second part.');

  hasher.update(chunk1);
  hasher.update(chunk2);

  const streamingHashResult = hasher.digest();
  console.log('Streaming hash (Uint8Array):', streamingHashResult);
  console.log('Streaming hash (hex):', Array.from(streamingHashResult).map(b => b.toString(16).padStart(2, '0')).join(''));

  // Example with custom output length (e.g., 16 bytes)
  const customLengthHash = hash(new TextEncoder().encode('Short hash example'), { length: 16 });
  console.log('Custom length hash (16 bytes hex):', Array.from(customLengthHash).map(b => b.toString(16).padStart(2, '0')).join(''));
}

runBlake3Example().catch(console.error);