progress 2.0.3: ProgressBar

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify ProgressBar in pkg:npm/progress@2.0.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/progress@2.0.3
Demonstrate these symbols/APIs:
  - ProgressBar

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:06eb70a96566737c20be4a317c59ac13d5f990970a3e6c27fd44287549d6aa16","contract":["ProgressBar constructor initializes with format string and options or total","ProgressBar throws error when format or total is omitted","ProgressBar.tick advances curr and marks complete when reaching total","ProgressBar.update advances curr to match the specified ratio","ProgressBar supports custom tokens and callback upon completion","ProgressBar.interrupt and terminate operate on stream without corrupting state"],"goal":"verify ProgressBar in pkg:npm/progress@2.0.3","kind":"HOW","packages":["pkg:npm/progress@2.0.3"],"schemaVersion":1,"symbols":["ProgressBar"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/progress@2.0.3"],"schemaVersion":1,"subject":"pkg:npm/progress@2.0.3","symbols":["ProgressBar"],"verifierAdapter":"node-typescript@1"}

const ProgressBar = require('progress');

/**
 * Creates a configured ProgressBar instance.
 *
 * @param {string} fmt - The string pattern for the progress bar.
 * @param {Object|number} [options] - Options or total count.
 * @returns {ProgressBar}
 */
function createProgressBar(fmt, options) {
  return new ProgressBar(fmt, options);
}

module.exports = {
  ProgressBar,
  createProgressBar,
};

{
  "name": "sample-progress",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-progress",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "progress": "2.0.3"
      }
    },
    "node_modules/progress": {
      "version": "2.0.3",
      "resolved": "https://registry.npmjs.org/progress/-/progress-2.0.3.tgz",
      "integrity": "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==",
      "license": "MIT",
      "engines": {
        "node": ">=0.4.0"
      }
    }
  }
}

{
  "name": "sample-progress",
  "version": "1.0.0",
  "description": "Clean-room sample verifying pkg:npm/progress@2.0.3 functionality",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "progress": "2.0.3"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify ProgressBar in pkg:npm/progress@2.0.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/progress@2.0.3"
  ],
  "symbols": [
    "ProgressBar"
  ]
}

import assert from 'node:assert/strict';
import { Writable } from 'node:stream';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const ProgressBar = require('progress');
const { createProgressBar } = require('../index.js');

class MockTTYStream extends Writable {
  constructor() {
    super();
    this.isTTY = true;
    this.columns = 80;
    this.writes = [];
  }
  _write(chunk, encoding, callback) {
    this.writes.push(chunk.toString());
    callback();
  }
  cursorTo(x) {}
  clearLine(dir) {}
}

// 1. ProgressBar constructor initializes with format string and options or total
{
  const stream = new MockTTYStream();
  const barNum = new ProgressBar(':bar', 20);
  assert.equal(barNum.total, 20);
  assert.equal(barNum.curr, 0);
  assert.equal(barNum.width, 20);

  const barOpt = createProgressBar('[:bar] :percent', {
    total: 50,
    width: 30,
    stream,
    complete: '#',
    incomplete: '.'
  });
  assert.equal(barOpt.total, 50);
  assert.equal(barOpt.curr, 0);
  assert.equal(barOpt.width, 30);
  assert.equal(barOpt.stream, stream);
  assert.equal(barOpt.chars.complete, '#');
  assert.equal(barOpt.chars.incomplete, '.');
  assert.equal(barOpt.complete, undefined);
}

// 2. ProgressBar throws error when format or total is omitted
{
  assert.throws(
    () => new ProgressBar(123, { total: 10 }),
    { message: 'format required' }
  );
  assert.throws(
    () => new ProgressBar(':bar', {}),
    { message: 'total required' }
  );
  assert.throws(
    () => new ProgressBar(':bar', { total: '10' }),
    { message: 'total required' }
  );
}

// 3. ProgressBar.tick advances curr and marks complete when reaching total
{
  const stream = new MockTTYStream();
  const bar = createProgressBar(':bar', { total: 10, stream });
  assert.equal(bar.curr, 0);

  bar.tick();
  assert.equal(bar.curr, 1);
  assert.equal(bar.complete, undefined);

  bar.tick(4);
  assert.equal(bar.curr, 5);
  assert.equal(bar.complete, undefined);

  bar.tick(5);
  assert.equal(bar.curr, 10);
  assert.equal(bar.complete, true);
}

// 4. ProgressBar.update advances curr to match the specified ratio
{
  const stream = new MockTTYStream();
  const bar = new ProgressBar(':bar', { total: 100, stream });

  bar.update(0.25);
  assert.equal(bar.curr, 25);

  bar.update(0.8);
  assert.equal(bar.curr, 80);

  bar.update(1.0);
  assert.equal(bar.curr, 100);
  assert.equal(bar.complete, true);
}

// 5. ProgressBar supports custom tokens and callback upon completion
{
  const stream = new MockTTYStream();
  let callbackCalled = false;
  let receivedBar = null;

  const bar = new ProgressBar(':bar :task', {
    total: 3,
    stream,
    callback: (b) => {
      callbackCalled = true;
      receivedBar = b;
    }
  });

  bar.tick({ task: 'downloading' });
  assert.equal(bar.tokens.task, 'downloading');
  assert.equal(callbackCalled, false);

  bar.tick(2, { task: 'done' });
  assert.equal(bar.tokens.task, 'done');
  assert.equal(callbackCalled, true);
  assert.equal(receivedBar, bar);
  assert.equal(bar.complete, true);
}

// 6. ProgressBar.interrupt and terminate operate on stream without corrupting state
{
  const stream = new MockTTYStream();
  const bar = new ProgressBar(':bar', { total: 10, stream, clear: true });

  bar.tick(3);
  assert.equal(bar.curr, 3);

  bar.interrupt('notice message');
  assert.ok(stream.writes.some(w => w.includes('notice message')));
  assert.equal(bar.curr, 3);

  bar.terminate();
  assert.equal(bar.curr, 3);
}

console.log('All ProgressBar contract assertions passed.');