@dashevo/blake3
Advanced tools
BLAKE3 hashing for JavaScript: native Node bindings (where available) and WebAssembly
BLAKE3 running in JavaScript (node.js and browsers) via native bindings, where available, or WebAssembly.
npm install blake3
Additionally, there's a flavor of the package which is identical except that it will not download native Node.js bindings and use only WebAssembly:
npm install blake3-wasm
hash(data: BinaryLike, options?: { length: number }): BufferkeyedHash(key: Buffer, data: BinaryLike, options?: { length: number }): BufferderiveKey(context: string, material: BinaryLike, options?: { length: number }): BuffercreateHash(): HashercreateKeyed(key: Buffer): HashercreateDeriveKey(context: string): Hasherhasher.update(data: BinaryLike): thishasher.digest(encoding?: string, options?: { length: number, dispose: boolean })): Buffer | stringhasher.reader(options?: { dispose: boolean }): HashReaderhasher.dispose()using(disposable: IDisposable, fn: disposable => T): Thash(data: BinaryLike, options?: { length: number }): HashkeyedHash(key: Buffer, data: BinaryLike, options?: { length: number }): HashderiveKey(context: string, material: BinaryLike, options?: { length: number }): HashHash
createHash(): HashercreateKeyed(key: Buffer): HashercreateDeriveKey(context: string): Hasherhasher.update(data: BinaryLike): thishasher.digest(encoding?: 'hex' | 'base64' | 'utf8', options?: { length: number, dispose: boolean })): Hash | stringhasher.reader(options?: { dispose: boolean }): HashReaderhasher.dispose()using(disposable: IDisposable, fn: disposable => T): TIf you're on Node, import the module via
const blake3 = require('blake3');
blake3.hash('foo'); // => Buffer
If you're in the browser, import blake3/browser. This includes a WebAssembly binary, so you probably want to import it asynchronously, like so:
import('blake3/browser').then(blake3 => {
blake3.hash('foo'); // => Uint8Array
});
The API is very similar in Node.js and browsers, but Node supports and returns Buffers and a wider range of input and output encoding.
More complete example:
const { hash, createHash } = require('blake3');
hash('some string'); // => hash a string to a uint8array
// Update incrementally (Node and Browsers):
const hash = createHash();
stream.on('data', d => hash.update(d));
stream.on('error', err => {
// hashes use unmanaged memory in WebAssembly, always free them if you don't digest()!
hash.dispose();
throw err;
});
stream.on('end', () => finishedHash(hash.digest()));
// Or, in Node, it's also a transform stream:
createReadStream('file.txt')
.pipe(createHash())
.on('data', hash => console.log(hash.toString('hex')));
The Node API can be imported via require('blake3').
hash(data: BinaryLike, options?: { length: number }): BufferReturns a hash for the given data. The data can be a string, buffer, typedarray, array buffer, or array. By default, it generates the first 32 bytes of the hash for the data, but this is configurable. It returns a Buffer.
keyedHash(key: Buffer, data: BinaryLike, options?: { length: number }): BufferReturns keyed a hash for the given data. The key must be exactly 32 bytes. The data can be a string, buffer, typedarray, array buffer, or array. By default, it generates the first 32 bytes of the hash for the data, but this is configurable. It returns a Buffer.
For more information, see the blake3 docs.
deriveKey(context: string, material: BinaryLike, options?: { length: number }): BufferThe key derivation function. The data can be a string, buffer, typedarray, array buffer, or array. By default, it generates the first 32 bytes of the hash for the data, but this is configurable. It returns a Buffer.
For more information, see the blake3 docs.
The hasher is a type that lets you incrementally build a hash. It's compatible with Node's crypto hash instance. For instance, it implements a transform stream, so you could do something like:
createReadStream('file.txt')
.pipe(createHash())
.on('data', hash => console.log(hash.toString('hex')));
createHash(): HasherCreates a new hasher instance using the standard hash function.
createKeyed(key: Buffer): HasherCreates a new hasher instance for a keyed hash. For more information, see the blake3 docs.
createDeriveKey(context: string): HasherCreates a new hasher instance for the key derivation function. For more information, see the blake3 docs.
hasher.update(data: BinaryLike): thisAdds data to a hash. The data can be a string, buffer, typedarray, array buffer, or array. This will throw if called after digest() or dispose().
hasher.digest(encoding?: string, options?: { length: number, dispose: boolean })): Buffer | stringReturns the hash of the data. If an encoding is given, a string will be returned. Otherwise, a Buffer is returned. Optionally, you can specify the requested byte length of the hash.
If dispose: false is given in the options, the hash will not automatically be disposed of, allowing you to continue updating it after obtaining the current reader.
hasher.reader(options?: { dispose: boolean }): HashReaderReturns a HashReader for the current hash.
If dispose: false is given in the options, the hash will not automatically be disposed of, allowing you to continue updating it after obtaining the current reader.
hasher.dispose()Disposes of unmanaged resources. You should always call this if you don't call digest() to free umanaged (WebAssembly-based) memory.
The hash reader can be returned from hashing functions. Up to 264-1 bytes of data can be read from BLAKE3 hashes; this structure lets you read those. Note that, like hash, this is an object which needs to be manually disposed of.
reader.position: bigintA property which gets or sets the position of the reader in the output stream. A RangeError is thrown if setting this to a value less than 0 or greater than 264-1. Note that this is a bigint, not a standard number.
reader.position += 32n; // advance the reader 32 bytes
reader.readInto(target: Buffer): voidReads bytes into the target array, filling it up and advancing the reader's position. A RangeError is thrown if reading this data puts the reader past 264-1 bytes.
reader.read(bytes: number): BufferReads and returns the given number of bytes from the reader, and advances the position. A RangeError is thrown if reading this data puts the reader past 264-1 bytes.
reader.toString([encoding]): stringConverts first 32 bytes of the hash to a string with the given encoding. Defaults to hex encoding.
reader.toBuffer(): BufferConverts first 32 bytes of the hash to a Buffer.
reader.dispose()Disposes of unmanaged resources. You should always call this to free umanaged (WebAssembly-based) memory, or you application will leak memory.
using(disposable: IDisposable, fn: disposable => T): TA helper method that takes a disposable, and automatically calls the dispose method when the function returns, or the promise returned from the function is settled.
// read and auto-dispose the first 64 bytes
const first64Bytes = using(hash.reader(), reader => reader.toBuffer(64));
// you can also return promises/use async methods:
using(hash.reader(), async reader => {
do {
await send(reader.read(64));
} while (needsMoreData());
});
The browser API can be imported via import('blake3/browser'), which works well with Webpack.
If you aren't using a bundler or using a more "pure" bundler like Parcel, you can import blake3/browser-async which exports a function to asynchronously load the WebAssembly code and resolves to the package contents.
import load from 'blake3/browser-async';
load().then(blake3 => {
console.log(blake3.hash('hello world'));
});
hash(data: BinaryLike, options?: { length: number }): HashReturns a hash for the given data. The data can be a string, typedarray, array buffer, or array. By default, it generates the first 32 bytes of the hash for the data, but this is configurable. It returns a Hash instance.
keyedHash(key: Buffer, data: BinaryLike, options?: { length: number }): HashReturns keyed a hash for the given data. The key must be exactly 32 bytes. The data can be a string, typedarray, array buffer, or array. By default, it generates the first 32 bytes of the hash for the data, but this is configurable. It returns a Hash instance.
For more information, see the blake3 docs.
deriveKey(context: string, material: BinaryLike, options?: { length: number }): HashThe key derivation function. The data can be a string, typedarray, array buffer, or array. By default, it generates the first 32 bytes of the hash for the data, but this is configurable. It returns a Hash instance.
For more information, see the blake3 docs.
HashA Hash is the type returned from hash functions and the hasher in the browser. It's a Uint8Array with a few additional helper methods.
hash.equals(other: Uint8Array)Returns whether this hash equals the other hash, via a constant-time equality check.
hash.toString(encoding: 'hex' | 'base64' | 'utf8'): stringThe hasher is a type that lets you incrementally build a hash. For instance, you can hash a fetched page like:
const res = await fetch('https://example.com');
const body = await res.body;
const hasher = blake3.createHash();
const reader = body.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) {
break;
}
hasher.update(value);
}
console.log('Hash of', res.url, 'is', hasher.digest('hex'));
Converts the hash to a string with the given encoding.
createHash(): HasherCreates a new hasher instance using the standard hash function.
createKeyed(key: Buffer): HasherCreates a new hasher instance for a keyed hash. For more information, see the blake3 docs.
createDeriveKey(context: string): HasherCreates a new hasher instance for the key derivation function. For more information, see the blake3 docs.
hasher.update(data: BinaryLike): thisAdds data to a hash. The data can be a string, buffer, typedarray, array buffer, or array. This will throw if called after digest() or dispose().
hasher.digest(encoding?: 'hex' | 'base64' | 'utf8', options?: { length: number, dispose: boolean })): Hash | stringReturns the hash of the data. If an encoding is given, a string will be returned. Otherwise, a Hash is returned. Optionally, you can specify the requested byte length of the hash.
If dispose: false is given in the options, the hash will not automatically be disposed of, allowing you to continue updating it after obtaining the current reader.
hasher.reader(options?: { dispose: boolean }): HashReaderReturns a HashReader for the current hash.
If dispose: false is given in the options, the hash will not automatically be disposed of, allowing you to continue updating it after obtaining the current reader.
hasher.dispose()Disposes of unmanaged resources. You should always call this if you don't call digest() to free umanaged (WebAssembly-based) memory.
The hash reader can be returned from hashing functions. Up to 264-1 bytes of data can be read from BLAKE3 hashes; this structure lets you read those. Note that, like hash, this is an object which needs to be manually disposed of.
reader.position: bigintA property which gets or sets the position of the reader in the output stream. A RangeError is thrown if setting this to a value less than 0 or greater than 264-1. Note that this is a bigint, not a standard number.
reader.position += 32n; // advance the reader 32 bytes
reader.readInto(target: Uint8Array): voidReads bytes into the target array, filling it up and advancing the reader's position. A RangeError is thrown if reading this data puts the reader past 264-1 bytes.
reader.read(bytes: number): HashReads and returns the given number of bytes from the reader, and advances the position. A RangeError is thrown if reading this data puts the reader past 264-1 bytes.
reader.toString(encoding?: string): stringConverts first 32 bytes of the hash to a string with the given encoding. Defaults to hex encoding.
reader.toArray(): Uint8ArrayConverts first 32 bytes of the hash to an array.
reader.dispose()Disposes of unmanaged resources. You should always call this to free umanaged (WebAssembly-based) memory, or you application will leak memory.
using(disposable: IDisposable, fn: disposable => T): TA helper method that takes a disposable, and automatically calls the dispose method when the function returns, or the promise returned from the function is settled.
// read and auto-dispose the first 64 bytes
const first64Bytes = using(hash.reader(), reader => reader.toArray(64));
// you can also return promises/use async methods:
using(hash.reader(), async reader => {
do {
await send(reader.read(64));
} while (needsMoreData());
});
Native Node.js bindings are a work in progress.
You can run benchmarks by installing npm install -g @c4312/matcha, then running matcha benchmark.js. These are the results running on Node 12 on my MacBook. Blake3 is significantly faster than Node's built-in hashing.
276,000 ops/sec > 64B#md5 (4,240x)
263,000 ops/sec > 64B#sha1 (4,040x)
271,000 ops/sec > 64B#sha256 (4,160x)
1,040,000 ops/sec > 64B#blake3 wasm (15,900x)
625,000 ops/sec > 64B#blake3 native (9,590x)
9,900 ops/sec > 64KB#md5 (152x)
13,900 ops/sec > 64KB#sha1 (214x)
6,470 ops/sec > 64KB#sha256 (99.2x)
6,410 ops/sec > 64KB#blake3 wasm (98.4x)
48,900 ops/sec > 64KB#blake3 native (750x)
106 ops/sec > 6MB#md5 (1.63x)
150 ops/sec > 6MB#sha1 (2.3x)
69.2 ops/sec > 6MB#sha256 (1.06x)
65.2 ops/sec > 6MB#blake3 wasm (1x)
502 ops/sec > 6MB#blake3 native (7.7x)
This build is a little esoteric due to the mixing of languages. We use a Makefile to coodinate things.
To get set up, you'll want to open the repository in VS Code. Make sure you have Remote Containers installed, and then accept the "Reopen in Container" prompt when opening the folder. This will get the environment set up with everything you need. Then, run make prepare to install local dependencies.
Finally, make will create a build for you; you can run make MODE=release for a production release, and certainly should if you want to benchmark it.
src/lib.rs to pkg/browser and pkg/nodets/*.ts into distIn case I get hit by a bus or get other contributors, these are the steps for publishing:
make prepare-binaries. This will update the branch generate-binary, which kicks off a build via Github actions to create .node binaries for every relevant Node.js version.npm version <type> to update the version in git. git push --tags.npm publish.2.1.5 - 2020-11-28
FAQs
BLAKE3 hashing for JavaScript: native Node bindings (where available) and WebAssembly
We found that @dashevo/blake3 demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.