Hyperdrive
stable
Hyperdrive is a secure, real-time distributed file system designed for easy P2P file sharing. We use it extensively inside Holepunch; apps like Keet are distributed to users as Hyperdrives, as is the Holepunch platform itself.
- Basic:
- Methods:
npm install hyperdrive
By default, it uses the core at
{ name: 'db' }
from store
, unless you set the public key
.The Corestore instance used as storage.
The underlying Hyperbee backing the drive file structure.
The Hypercore used for
drive.db
.The public key of the Hypercore backing the drive.
The hash of the public key of the Hypercore backing the drive. It can be used as a
topic
to seed the drive using Hyperswarm.The number that indicates how many modifications were made, is useful as a version identifier.
Boolean indicating if the drive handles or not metadata. Always
true
.Waits until the internal state is loaded.
Use it once before reading synchronous properties like
drive.discoveryKey
, unless you called any of the other APIs.Fully close this drive, including its underlying Hypercore backed data structures.
Creates a file at
path
in the drive. options
are the same as in createWriteStream
.Returns the blob at
path
in the drive. If no blob exists, returns null
.It also returns
null
for symbolic links.Returns the entry at
path
in the drive. It looks like this:{
seq: Number,
key: String,
value: {
executable: Boolean, // Whether the blob at path is an executable
linkname: null, // If entry not symlink, otherwise a string to the entry this links to
blob: { // Hyperblobs id that can be used to fetch the blob associated with this entry
blockOffset: Number,
blockLength: Number,
byteOffset: Number,
byteLength: Number
},
metadata: null
}
}
Returns
true
if the entry at path
does exists, otherwise false
.Deletes the file at
path
from the drive.The underlying blob is not deleted, only the reference in the file structure.
Deletes the blob from storage to free up space, but the file structure reference is kept.
options
include:Property | Description | Type | Default |
---|---|---|---|
diff | Returned cleared bytes object is null unless you enable this | Boolean | false |
Deletes all the blobs from storage to free up space, similar to how
drive.clear()
works.options
include:Property | Description | Type | Default |
---|---|---|---|
diff | Returned cleared bytes object is null unless you enable this | Boolean | false |
Purge both cores (db and blobs) from your storage, completely removing all the drive's data.
Creates an entry in drive at
path
that points to the entry at linkname
.If a blob entry currently exists at
path
then it will get overwritten and drive.get(key)
will return null
, while drive.entry(key)
will return the entry with symlink information.Useful for atomically mutating the drive, has the same interface as Hyperdrive.
Commit a batch of mutations to the underlying drive.
Returns a stream of all entries in the drive at paths prefixed with
folder
.options
include:Property | Description | Type | Default |
---|---|---|---|
recursive | whether to descend into all subfolders or not | Boolean | true |
Returns a stream of all subpaths of entries in the drive stored at paths prefixed by
folder
.Returns a read stream of entries in the drive.
options
are the same as the options
to Hyperbee().createReadStream(options)
.Efficiently mirror this drive into another. Returns a MirrorDrive instance constructed with
options
.Call
await mirror.done()
to wait for the mirroring to finish.Returns an iterator that listens on
folder
to yield changes, by default on /
.Usage example:
for await (const [current, previous] of watcher) {
console.log(current.version)
console.log(previous.version)
}
current
and previous
are the snapshots that are auto-closed before next value.Do not close those snapshots yourself because they're used internally, let them be auto-closed.
Methods:
await watcher.ready()
Waits until the watcher is loaded and detecting changes.
await watcher.destroy()
Stops the watcher. You could also stop it by using
break
in the loop.Returns a stream to read out the blob stored in the drive at
path
.options
include:{
start: Number, // `start` and `end` are inclusive
end: Number,
length: Number, // `length` overrides `end`, they're not meant to be used together
wait: true, // Wait for blocks to be downloaded
timeout: 0 // Wait at max some milliseconds (0 means no timeout)
}
Stream a blob into the drive at
path
.options
include:Property | Description | Type | Default |
---|---|---|---|
executable | whether the blob is executable or not | Boolean | true |
metadata | Extended file information i.e., arbitrary JSON value | Object | null |
Downloads the blobs corresponding to all entries in the drive at paths prefixed with
folder
.options
are the same as those for drive.list(folder, [options])
.Get a read-only snapshot of a previous version.
Efficiently create a stream of shallow changes to
folder
between version
and drive.version
.Each entry is sorted by key and looks like this:
{
left: Object, // Entry in folder at drive.version for some path
right: Object // Entry in folder at drive.checkout(version) for some path
}
If an entry exists in
drive.version
of the folder
but not in version
, then left
is set and right
will be null
, and vice versa.Downloads all the blobs in
folder
corresponding to entries in drive.checkout(version)
that are not in drive.version
.In other words, downloads all the blobs added to
folder
up to version
of the drive.Indicate to Hyperdrive that you're finding peers in the background, requests will be on hold until this is done.
Call
done()
when your current discovery iteration is done, i.e., after swarm.flush()
finishes.Usage example:
const swarm = new Hyperswarm()
const done = drive.corestore.findingPeers()
swarm.on('connection', (socket) => drive.corestore.replicate(socket))
swarm.join(drive.discoveryKey)
swarm.flush().then(done, done)
Waits for initial proof of the new drive version until all
findingPeers
are done.options
include:{
wait: false
}
Use
drive.corestore.findingPeers()
or { wait: true }
to make await drive.update()
blocking.await drive.put('/file.txt', Buffer.from('hi'))
const buffer1 = await drive.get('/file.txt')
const blobs = await drive.getBlobs()
const entry = await drive.entry('/file.txt')
const buffer2 = await blobs.get(entry.value.blob)
// => buffer1 and buffer2 are equals
Last modified 13d ago