Hyperdrive

Hyperdrive stores filesystem metadata in a Hyperbee and file contents in a blob store, typically backed by one Corestore. Use this page for the instance surface; use the linked how-to guides for end-to-end replication flows.

Install

npm i hyperdrive

Quickstart

import Corestore from 'corestore'
import Hyperdrive from 'hyperdrive'

const store = new Corestore('./storage')
const drive = new Hyperdrive(store)

await drive.ready()

await drive.put('/hello.txt', Buffer.from('hello world'), {
  metadata: { type: 'text/plain' }
})

const buffer = await drive.get('/hello.txt')
const entry = await drive.entry('/hello.txt')

console.log(buffer.toString())
console.log(entry?.value.metadata)

await drive.close()

API Reference

Constructor and lifecycle

new Hyperdrive(store, [key], [options])

API definition on GitHub

• Signature: new Hyperdrive(store, [key], [options])
• Parameters: store is the Corestore used for metadata and blob storage; key optionally opens an existing drive by public key instead of using the default named core. options may be passed in place of key and supports encryptionKey to encrypt the backing cores, onwait for a per-core wait hook, and active (defaults to true) to control whether the drive keeps its cores active.
• Returns: A Hyperdrive instance.
• Example:

const drive = new Hyperdrive(store, key)
await drive.ready()

await drive.ready()

API definition on GitHub

• Signature: await drive.ready()
• Parameters: None.
• Returns: A promise that resolves when synchronous properties such as drive.discoveryKey are safe to read.
• Example:

await drive.ready()
console.log(drive.discoveryKey)

await drive.close()

API definition on GitHub

• Signature: await drive.close()
• Parameters: None.
• Returns: A promise that resolves after the drive and its underlying storage objects are closed.
• Example:

await drive.close()

await drive.purge()

API definition on GitHub

• Signature: await drive.purge()
• Parameters: None.
• Returns: A promise that resolves after both the metadata core and blob storage are removed from local storage.
• Example:

await drive.purge()

Drive properties

drive.corestore

API definition on GitHub

• Returns: The Corestore instance backing the drive.

drive.db

API definition on GitHub

• Returns: The underlying Hyperbee that stores the drive's directory structure and entry metadata.

drive.core

API definition on GitHub

• Returns: The Hypercore used by drive.db.

drive.id

API definition on GitHub

• Returns: A z-base-32 string identifier derived from the drive's public key.

drive.key

API definition on GitHub

• Returns: The public key of the metadata Hypercore backing the drive.

drive.discoveryKey

API definition on GitHub

• Returns: The discovery key derived from drive.key, typically used as a Hyperswarm topic.

drive.contentKey

API definition on GitHub

• Returns: The public key of the Hyperblobs instance that stores file contents.

drive.writable

API definition on GitHub

• Returns: true when the current instance can mutate entries in the drive.

drive.readable

API definition on GitHub

• Returns: true when the instance can still read data; becomes false after close().

drive.version

API definition on GitHub

• Returns: The current drive version number, incremented as filesystem mutations are committed.

drive.supportsMetadata

API definition on GitHub

• Returns: true. Hyperdrive always supports entry metadata.

Files

await drive.put(path, buffer, [options])

API definition on GitHub

• Signature: await drive.put(path, buffer, [options])
• Parameters: path is the absolute drive path to write; buffer is the file content; options matches drive.createWriteStream(...) and supports executable and metadata.
• Returns: A promise that resolves after the file entry and blob are committed.
• Example:

await drive.put('/docs/readme.txt', Buffer.from('hello'))

const buffer = await drive.get(path, [options])

API definition on GitHub

• Signature: const buffer = await drive.get(path, [options])
• Parameters: path is the file path to read; options.wait waits for remote blocks and options.timeout bounds that wait in milliseconds.
• Returns: A Buffer for the file contents, or null if the file is missing or the path is a symlink.
• Example:

const buffer = await drive.get('/docs/readme.txt')
console.log(buffer?.toString())

const entry = await drive.entry(path, [options])

API definition on GitHub

• Signature: const entry = await drive.entry(path, [options])
• Parameters: path is the path to inspect; options.follow follows symlinks, while wait and timeout control remote reads.
• Returns: The current entry object, including seq, key, and value metadata, or null when no entry exists.
• Example:

const entry = await drive.entry('/docs/readme.txt')
console.log(entry?.value.metadata)

const exists = await drive.exists(path)

API definition on GitHub

• Signature: const exists = await drive.exists(path)
• Parameters: path is the path to test.
• Returns: true if an entry exists at that path, otherwise false.
• Example:

const exists = await drive.exists('/docs/readme.txt')

await drive.has(path)

API definition on GitHub

• Signature: await drive.has(path)
• Parameters: path is the file path to check.
• Returns: true when the data for that path is already stored locally.
• Example:

const hasLocalData = await drive.has('/docs/readme.txt')

await drive.del(path)

API definition on GitHub

• Signature: await drive.del(path)
• Parameters: path is the file path to remove.
• Returns: A promise that resolves after the entry is deleted from the drive.
• Example:

await drive.del('/docs/old.txt')

const cleared = await drive.clear(path, [options])

API definition on GitHub

• Signature: const cleared = await drive.clear(path, [options])
• Parameters: path is the file path whose blob data should be discarded locally; options.diff includes a byte-count diff in the return value.
• Returns: Information about cleared bytes when diff is enabled; otherwise null.
• Example:

await drive.clear('/videos/demo.mp4', { diff: true })

const cleared = await drive.clearAll([options])

API definition on GitHub

• Signature: const cleared = await drive.clearAll([options])
• Parameters: options.diff includes a byte-count diff in the return value.
• Returns: Information about cleared bytes when diff is enabled; otherwise null.
• Example:

await drive.clearAll({ diff: true })

await drive.symlink(path, linkname, [options])

API definition on GitHub

• Signature: await drive.symlink(path, linkname, [options])
• Parameters: path is the symlink entry to create; linkname is the destination path inside the drive; options.metadata optionally stores arbitrary JSON metadata on the symlink entry.
• Returns: A promise that resolves after the symlink entry is written.
• Example:

await drive.symlink('/images/logo.shortcut', '/images/logo.png')

const rs = drive.createReadStream(path, [options])

API definition on GitHub

• Signature: const rs = drive.createReadStream(path, [options])
• Parameters: path is the file path to stream; options.start, end, and length select a byte range, while wait and timeout control remote reads.
• Returns: A readable stream for the blob at path.
• Example:

for await (const chunk of drive.createReadStream('/hello.txt')) {
  console.log(chunk)
}

const ws = drive.createWriteStream(path, [options])

API definition on GitHub

• Signature: const ws = drive.createWriteStream(path, [options])
• Parameters: path is the file path to write; options.executable marks the file executable, options.metadata stores arbitrary JSON metadata, and options.dedup (defaults to false) reuses the existing blob when the new contents match the current entry.
• Returns: A writable stream that commits the file when closed.
• Example:

const ws = drive.createWriteStream('/notes.txt')
ws.end('hello from a stream')

Directories and listings

const stream = drive.list(folder, [options])

API definition on GitHub

• Signature: const stream = drive.list(folder, [options])
• Parameters: folder scopes the prefix to list; options.recursive controls descent, options.ignore skips names, and options.wait blocks for remote metadata.
• Returns: A stream of full entry records under the requested folder prefix.
• Example:

for await (const entry of drive.list('/images')) {
  console.log(entry.key)
}

const stream = drive.readdir(folder, [options])

API definition on GitHub

• Signature: const stream = drive.readdir(folder, [options])
• Parameters: folder is the directory to enumerate; options.wait waits for remote metadata before yielding names.
• Returns: A stream of child paths under the requested folder.
• Example:

for await (const name of drive.readdir('/images')) {
  console.log(name)
}

const stream = drive.entries([range], [options])

API definition on GitHub

• Signature: const stream = drive.entries([range], [options])
• Parameters: range limits the key space to read; options follows the same stream options as the underlying Hyperbee read stream and accepts options.ignore to skip matching keys.
• Returns: A read stream of drive entries in key order.
• Example:

for await (const entry of drive.entries()) {
  console.log(entry.key)
}

const comparison = drive.compare(entryA, entryB)

API definition on GitHub

• Signature: const comparison = drive.compare(entryA, entryB)
• Parameters: entryA and entryB are entry objects returned by Hyperdrive.
• Returns: 0 when the entries are equal, 1 when entryA is newer (higher seq), and -1 when entryA is older (lower seq).
• Example:

const comparison = drive.compare(currentEntry, previousEntry)

const watcher = drive.watch([folder])

API definition on GitHub

• Signature: const watcher = drive.watch([folder])
• Parameters: folder optionally narrows change detection to a subtree; defaults to /.
• Returns: An async iterator that yields [current, previous] snapshots. The watcher also exposes await watcher.ready() and await watcher.destroy().
• Example:

const watcher = drive.watch('/docs')
await watcher.ready()

for await (const [current, previous] of watcher) {
  console.log(previous.version, '->', current.version)
  break
}

await watcher.destroy()

Versions and batched mutations

const batch = drive.batch()

API definition on GitHub

• Signature: const batch = drive.batch()
• Parameters: None.
• Returns: A batch object with the same mutation interface as drive, allowing multiple writes to be staged atomically.
• Example:

const batch = drive.batch()
await batch.put('/a.txt', Buffer.from('a'))
await batch.put('/b.txt', Buffer.from('b'))
await batch.flush()

await batch.flush()

API definition on GitHub

• Signature: await batch.flush()
• Parameters: None.
• Returns: A promise that resolves once the staged batch mutations are committed to the underlying drive and the batch session is closed.
• Example:

const batch = drive.batch()
await batch.del('/old.txt')
await batch.flush()

const snapshot = drive.checkout(version)

API definition on GitHub

• Signature: const snapshot = drive.checkout(version)
• Parameters: version is the earlier drive version to open.
• Returns: A read-only snapshot of that version of the drive.
• Example:

const snapshot = drive.checkout(10)
const buffer = await snapshot.get('/hello.txt')

const stream = drive.diff(version, folder, [options])

API definition on GitHub

• Signature: const stream = drive.diff(version, folder, [options])
• Parameters: version is the baseline version to compare against; folder scopes the diff to one subtree; options passes through to the diff stream.
• Returns: A stream of { left, right } objects describing shallow changes between version and the current drive version.
• Example:

for await (const change of drive.diff(10, '/docs')) {
  console.log(change.left, change.right)
}

await drive.truncate(version, [options])

API definition on GitHub

• Signature: await drive.truncate(version, [options])
• Parameters: version is the drive version to roll back to; options.blobs can be provided when the matching blob length is already known.
• Returns: A promise that resolves after the drive is truncated to that earlier state.
• Example:

await drive.truncate(10)

Replication, downloads, and blob access

const mirror = drive.mirror(out, [options])

API definition on GitHub

• Signature: const mirror = drive.mirror(out, [options])
• Parameters: out is another drive-like destination such as Localdrive; options are forwarded to the underlying Mirrordrive instance.
• Returns: A MirrorDrive instance. Call await mirror.done() to wait for the copy to finish.
• Example:

const mirror = drive.mirror(localdrive)
await mirror.done()

const download = drive.download(folder, [options])

API definition on GitHub

• Signature: const download = drive.download(folder, [options])
• Parameters: folder scopes which subtree to fetch; options match drive.list(...).
• Returns: A Download handle for blob downloads. Use await download.done() to wait for completion or download.destroy() to cancel.
• Example:

const download = drive.download('/images')
await download.done()

const download = await drive.downloadDiff(version, folder, [options])

API definition on GitHub

• Signature: const download = await drive.downloadDiff(version, folder, [options])
• Parameters: version is the historical version to compare; folder scopes the subtree; options match drive.list(...).
• Returns: A Download handle for blobs that exist in drive.checkout(version) but not in the current drive state.
• Example:

const download = await drive.downloadDiff(10, '/images')
await download.done()

const download = await drive.downloadRange(dbRanges, blobRanges)

API definition on GitHub

• Signature: const download = await drive.downloadRange(dbRanges, blobRanges)
• Parameters: dbRanges selects metadata ranges and blobRanges selects blob ranges, using the range format accepted by Hypercore.
• Returns: A Download handle for the requested metadata and blob ranges.
• Example:

const download = await drive.downloadRange([{ start: 0, end: 10 }], [])
await download.done()

const done = drive.findingPeers()

API definition on GitHub

• Signature: const done = drive.findingPeers()
• Parameters: None.
• Returns: A callback that should be invoked when the current peer-discovery pass finishes, allowing pending updates to unblock.
• Example:

const done = drive.findingPeers()
swarm.flush().then(done, done)

const stream = drive.replicate(isInitiator, [options])

API definition on GitHub

• Signature: const stream = drive.replicate(isInitiator, [options])
• Parameters: Pass an existing replication stream, or an isInitiator boolean with optional options. Both forms are forwarded to the underlying Corestore replication API.
• Returns: The replication stream for the drive and its loaded backing data.
• Example:

swarm.on('connection', (socket) => drive.replicate(socket))

const updated = await drive.update([options])

API definition on GitHub

• Signature: const updated = await drive.update([options])
• Parameters: options.wait can force a blocking wait for a newer version.
• Returns: A boolean indicating whether the drive observed a new version.
• Example:

const done = drive.findingPeers()
swarm.flush().then(done, done)
const updated = await drive.update()

const blobs = await drive.getBlobs()

API definition on GitHub

• Signature: const blobs = await drive.getBlobs()
• Parameters: None.
• Returns: The Hyperblobs instance storing file contents for the drive.
• Example:

const blobs = await drive.getBlobs()
const entry = await drive.entry('/hello.txt')
const buffer = await blobs.get(entry.value.blob)

const blobsLength = await drive.getBlobsLength(checkout)

API definition on GitHub

• Signature: const blobsLength = await drive.getBlobsLength(checkout)
• Parameters: checkout optionally selects the drive version whose blob length should be resolved.
• Returns: The Hyperblobs length associated with that version of the drive.
• Example:

const blobsLength = await drive.getBlobsLength()

See also

• Create a full peer-to-peer filesystem with Hyperdrive — end-to-end filesystem replication walkthrough.
• Work with many Hypercores using Corestore — recommended pattern when one app manages multiple drives or related cores.
• Localdrive — map a Hyperdrive-like API onto the local filesystem.
• Mirrordrive — sync between Hyperdrive and other drive-like destinations.
• Corestore — shared storage and replication manager for drive metadata and content.
• Hyperbee — Hyperdrive uses a Hyperbee internally for metadata indexing.
• Drives — CLI tool for creating, mirroring, and seeding Hyperdrives.