hypercore-block-progress v0.1.4
hypercore-block-progress
Track the block download progress of a Hypercore feed.
Installation
$ npm install hypercore-block-progress
Status
Stable
Usage
const capture = require('hypercore-block-progress')
const progress = capture(feed, {
// called for every 'download' event on emitted on `feed`
onblock(index, data, peer, progress, ctx) {
},
// called when 'sync' event is emitted on `feed`
onsync(progress, ctx) {
},
// handle `err`
onerror(err, progress, ctx) {
},
})
API
The following section details how to capture download progress information for a Hypercore feed in real time.
progress = capture(feed[, opts])
Creates a Progress
instance from feed
and optional opts
where
feed
is a Hypercore feed and opts
is an optional options
object that can be:
{
// context is the last argument for the `onerror()`, `onsync()`, and
// `onblock()` function handlers
context: {
// static and dynamic context properties
},
onerror(err, progress, ctx) {
// handle errors emitted on the feed while progress is captured
},
onsync(progress, ctx) {
// 'sync' event emitted on feed
},
onblock(index, data, peer, progress, ctx) {
// called when a block is downloaded
},
}
Example
const capture = require('hypercore-block-progress')
const pretty = require('pretty-bytes')
const Bar = require('progress')
const progress = capture(feed, {
context: {
// static context property
bar: new Bar('downloading :byteLength: [:bar] :percent'),
// dynamic context property
byteLength: (progress, ctx) => pretty(feed.byteLength),
},
onblock(index, data, peer, progress, ctx) {
ctx.bar.update(progress.ratio, {
byteLength: ctx.byteLength
})
},
})
await capture(feed[, opts])
The await
keyword can also be used on the returned instance to wait
for the download to complete or fail with stats
returned to the awaited caller.
progress.total
The total number of blocks that can be downloaded in the feed.
progress.downloaded
The total number of blocks downloaded in the feed.
progress.missing
The total number of blocks not downloaded in the feed.
progress.ratio
The ratio between the total number of blocks that are downloaded and the total number of blocks that can be downloaded.
progress.percent
The integer percentage of the total number of blocks that are downloaded compared to the total number of blocks that can be downloaded.
progress.elapsed
The number of milliseconds since the first block was downloaded.
progress.eta
The computed estimated time of arrival in milliseconds when the downloaded should be complete.
progress.rate
The computed average block download rate.
progress.stats
Read-only, JSON.stringify()
, safe plain object view of the statistics
captured while the feed is downloading.
A stats object may look soemthing like this:
{ eta: 0,
rate: 10.940782122905027,
total: 9792,
ratio: 1,
elapsed: 895,
missing: 0,
percent: 100,
downloaded: 9792 }
progress.destroy()
Destroys the instance, removing all attached event listeners, and
marking the instance as destroyed (progress.destroyed = true
).
progress.onerror(err, progress, ctx)
Method handler called when an 'error'
event is emitted on feed
during
the life time the download is captured. This can be overwritten by
supplying opts.onerror
to the capture()
function.
progress.onsync(progress, ctx)
Method handler called when a 'sync'
event is emitted on feed
during
the life time the download is captured. This can be overwritten by
supplying opts.onsync
to the capture()
function.
progress.onblock(index, data, peer, progress, ctx)
Method handler called when a 'download'
event is emitted on feed
during
the life time the download is captured. This can be overwritten by
supplying opts.onblock
to the capture()
function.
License
MIT