Nodestream - Progress Transform

Progress monitor for Nodestream

Identity:: progress

API docs

Description

This transformer will report detailed stats about the ongoing upload/download back to you via a custom, per-file function.

Usage

Installation

npm install --save nodestream-transform-progress

Configuration

You need to register this tranform with Nodestream before you can use it:

// Assuming you already have a nodestream instance configured with an adapter
nodestream.registerTransform('progress')

Now you can create a pipeline which will use this transform:

const pipeline = nodestream.pipeline()
  .use('progress')

The transform accepts two per-file options:

• total: Nodestream cannot determine how much data will flow through it - if you want to have some stats available (like % completed), you must provide the expected size of the stream (in bytes, as integer). How you obtain this information is completely up to you.
• update: Pass a function here. This function will be called repeatedly until the stream is finished with detailed statistics about current progress.

Progress monitoring

The following example demonstrates how to monitor the progress of a single file upload.

const file = fs.createReadStream('/users/me/profile-pic.png')
// WARNING - Do not use *Sync() methods in production! Used for demo purposes only.
const size = fs.statSync('/users/me/profile-pic.png').size
pipeline.upload(file, {
  progress: {
    total: size,
    update(stats) {
      // stats now contains a bunch of interesting properties about current progress
      console.log(stats)
    }
  }
})

Stats available

The following progress stats are available for you:

• openedAt (Date) - When the stream has been opened. This occurs approximately when you call .upload() or .download().
• startedAt (Date) - When the first byte has been received
• finishedAt (Date) - When the stream has been completely processed
• duration (Number) - For how long (in ms) has the upload been going on? This is updated continuously.
• total - (Number|null) - Total number of bytes - you must provide this value yourself. Will be set to the total amount of processed bytes once the stream has finished processing.
• processed (Number) - Number of bytes processed so far
• remaining (Number|null) - Bytes still remaining - requires total to be available. Will be set to 0 once the stream has finished processing.
• progress (Number|null) - Percentage of current progress - requires total to be available. Will be set to 100 once the stream has finished processing.

Results

This transform will publish its final progress stats via stats on the progress (this transform's identity) property on the results response:

// Uploads
const file = fs.createReadStream('/users/me/profile-pic.png')
pipeline.upload(file, { name: 'avatar.png' })
.then(results => {
  results.progress.stats
})

// Downloads
const dest = fs.createWriteStream('/users/me/profile-pic.png')
pipeline.download('avatars/user-123.png', dest)
.then(results => {
  results.progress.stats
})

License

This software is licensed under the BSD-3-Clause License. See the LICENSE file for more information.