Track the block download progress of a Hypercore feed.
$ npm install hypercore-block-progress
Stable
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) {
},
})
The following section details how to capture download progress information for a Hypercore feed in real time.
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
},
}
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
})
},
})
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.
The total number of blocks that can be downloaded in the feed.
The total number of blocks downloaded in the feed.
The total number of blocks not downloaded in the feed.
The ratio between the total number of blocks that are downloaded and the total number of blocks that can be downloaded.
The integer percentage of the total number of blocks that are downloaded compared to the total number of blocks that can be downloaded.
The number of milliseconds since the first block was downloaded.
The computed estimated time of arrival in milliseconds when the downloaded should be complete.
The computed average block download rate.
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 }
Destroys the instance, removing all attached event listeners, and
marking the instance as destroyed (progress.destroyed = true
).
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.
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.
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.
MIT