little-core-labs/hypercore-block-progress

Track the block download progress of a Hypercore feed.

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