are-we-there-yet

Track complex hierarchies of asynchronous task completion statuses. This is intended to give you a way of recording and reporting the progress of the big recursive fan-out and gather type workflows that are so common in async.

What you do with this completion data is up to you, but the most common use case is to feed it to one of the many progress bar modules.

Most progress bar modules include a rudimentary version of this, but this library provides a more robust and feature-rich solution.

Repository: https://github.com/openclawd-bot/are-we-there-yet
Issues: https://github.com/openclawd-bot/are-we-there-yet/issues

Features

• 🎯 Event-driven progress tracking
• 📊 Hierarchical task organization
• 🔄 Stream integration for file operations
• 📝 TypeScript support included
• 🧪 Comprehensive test coverage
• 🔧 Modern JavaScript (ES2022+)

Installation

npm install are-we-there-yet-v2

Usage

Basic Example

const { TrackerGroup } = require("are-we-there-yet")
const fs = require("fs")

const top = new TrackerGroup("program")

const single = top.newItem("one thing", 100)
single.completeWork(20)

console.log(top.completed()) // 0.2

fs.stat("file", (er, stat) => {
  if (er) throw er  
  const stream = top.newStream("file", stat.size)
  console.log(top.completed()) // now 0.1 as single is 50% of the job and is 20% complete
                              // and 50% * 20% == 10%
  fs.createReadStream("file").pipe(stream).on("data", (chunk) => {
    // do stuff with chunk
  })
  top.on("change", (name) => {
    // called each time a chunk is read from "file"
    // top.completed() will start at 0.1 and fill up to 0.6 as the file is read
  })
})

TypeScript Example

import { TrackerGroup, Tracker, TrackerStream } from 'are-we-there-yet'

const top = new TrackerGroup("download")
const fileTracker = top.newStream("file.txt", 1024)
const metadataTracker = top.newItem("metadata", 100)

// Track progress
top.on("change", (name, completed) => {
  console.log(`${name}: ${(completed * 100).toFixed(1)}%`)
})

Advanced Example with Nested Groups

const { TrackerGroup } = require("are-we-there-yet")

const main = new TrackerGroup("main-operation")
const downloadPhase = main.newGroup("download", 60) // 60% weight
const processPhase = main.newGroup("process", 40)   // 40% weight

// Add tasks to download phase
const file1 = downloadPhase.newItem("file1.txt", 1024)
const file2 = downloadPhase.newItem("file2.txt", 2048)

// Add tasks to process phase
const transform = processPhase.newItem("transform", 100)
const save = processPhase.newItem("save", 50)

main.on("change", (name, completed) => {
  console.log(`Overall progress: ${(completed * 100).toFixed(1)}%`)
})

API Reference

Shared Methods

These methods are available on all tracker classes (Tracker, TrackerGroup, TrackerStream):

completed()

Returns the ratio of completed work to work to be done. Range from 0 to 1.

const progress = tracker.completed()
console.log(`${(progress * 100).toFixed(1)}% complete`)

finish()

Marks the tracker as completed. With a TrackerGroup, this marks all of its components as completed.

tracker.finish()
// tracker.completed() now returns 1

Events

All tracker objects emit change events with the following signature:

tracker.on('change', (name, completed, tracker) => {
  console.log(`${name}: ${(completed * 100).toFixed(1)}%`)
})

• name: The name of the tracker that originally emitted the event, or if it didn't have one, the first containing tracker group that had one
• completed: The percent complete (as returned by tracker.completed() method)
• tracker: The tracker object that you are listening for events on

Classes

TrackerGroup

A tracker aggregation group whose completion status is determined by the completion status of other trackers added to it.

const tracker = new TrackerGroup("parent")
const foo = tracker.newItem("firstChild", 100)
const bar = tracker.newItem("secondChild", 100)

foo.finish()
console.log(tracker.completed()) // 0.5
bar.finish()
console.log(tracker.completed()) // 1

Constructor

new TrackerGroup(name?)

• name (optional): The name of this tracker group, used in change notifications

Methods

addUnit(otherTracker, weight?)

Adds another tracker to this aggregation group.

• otherTracker: Any of the are-we-there-yet tracker objects
• weight (optional): The weight to give the tracker, defaults to 1

Returns the added tracker.

newGroup(name?, weight?)

Creates and adds a new TrackerGroup as a sub-unit.

Equivalent to: tracker.addUnit(new TrackerGroup(name), weight)

newItem(name?, todo?, weight?)

Creates and adds a new Tracker as a sub-unit.

Equivalent to: tracker.addUnit(new Tracker(name, todo), weight)

newStream(name?, size?, weight?)

Creates and adds a new TrackerStream as a sub-unit.

Equivalent to: tracker.addUnit(new TrackerStream(name, size), weight)

debug(depth?)

Returns a tree showing the completion of this tracker group and all of its children.

• depth (optional): Indentation depth for debugging output

Tracker

An individual task tracker for tracking completion of a single unit of work.

const tracker = new Tracker("download", 1000)
tracker.completeWork(500)
console.log(tracker.completed()) // 0.5

Constructor

new Tracker(name?, todo?)

• name (optional): The name of this counter to report in change events
• todo (optional): The amount of work to be done. Defaults to 0

Methods

addWork(todo)

Increases the amount of work to be done, thus decreasing the completion percentage.

• todo: A number to add to the amount of work to be done

completeWork(completed)

Increases the amount of work completed, thus increasing the completion percentage. Will never increase work completed past the amount of work todo.

• completed: A number to add to the work completed

TrackerStream

A Transform stream that updates an internal tracker object each time data passes through. Intended for tracking downloads, file extraction, and other stream-based activities.

const tracker = new TrackerStream("download", fileSize)
fs.createReadStream('file.txt').pipe(tracker).pipe(fs.createWriteStream('output.txt'))

tracker.on('change', (name, completed) => {
  console.log(`Download: ${(completed * 100).toFixed(1)}%`)
})

Constructor

new TrackerStream(name?, size?, options?)

• name (optional): The name of this counter to report in change events
• size (optional): The number of bytes being sent through this stream
• options (optional): Stream options passed to Transform constructor

Methods

addWork(todo)

Increases the expected overall size by the specified amount.

• todo: Increase the expected overall size by this many bytes

Node.js Compatibility

This package requires Node.js 18.0.0 or higher and is tested on all actively maintained Node.js versions.

License

ISC