progress-state

library0.1.0jsnpmunverified

A lightweight, zero-dependency TypeScript library for typed weighted progress state primitives (v0.1.0, initial release, not yet on a regular cadence). It provides `createProgressGroup` and `ProgressItem` to track weighted completion progress as a number between 0 and 1, with snapshot support for terminal UIs, logs, or dashboards. Unlike the unmaintained `are-we-there-yet`, it offers a compact, fully typed API and does not include any UI or logging; it is purely a state primitive. The package is an independent migration helper for projects moving away from `are-we-there-yet`, but is not a drop-in replacement.

devops testing

npm install progress-state

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PROGRESS-STATE

progress-state

devopsjavascriptv0.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createProgressGroup

✓ import { createProgressGroup } from 'progress-state'

✗ const createProgressGroup = require('progress-state').createProgressGroup

ESM-only; ship with Node >=18. No CommonJS support.

ProgressGroup

✓ import type { ProgressGroup } from 'progress-state'

✗ import { ProgressGroup } from 'progress-state'

ProgressGroup is a type (interface), not a runtime value. Use type import to avoid runtime errors.

ProgressItem

✓ import type { ProgressItem } from 'progress-state'

✗ import { ProgressItem } from 'progress-state'

ProgressItem is also a type. Import with `type` modifier.

Creates a progress group, adds two weighted items, partially completes one, and logs overall weighted percentage.

import { createProgressGroup } from 'progress-state'; const group = createProgressGroup(); const install = group.add('install', 2); const build = group.add('build', 1); install.complete(0.5); build.complete(1); console.log(group.snapshot().percent); // Output: 0.666...

Debug

Known issues

gotchaThe `complete(value)` method expects a number between 0 and 1. Passing values outside this range may produce unexpected results.

fix

Ensure `value` is clamped to [0,1] before calling `complete()`.

affects: >=0.1.0

gotchaThe `snapshot()` method returns a plain object (not reactive). UI users must manually re-render on updates.

fix

Call `snapshot()` and re-render after each `complete()` call.

affects: >=0.1.0

deprecatedThis package is not a drop-in replacement for `are-we-there-yet`. The API is completely different.

fix

Manually migrate from `are-we-there-yet` patterns to `createProgressGroup` and `ProgressItem`.

affects: >=0.1.0

gotchaTypeScript types are bundled but not explicitly declared in `package.json` `types` field. Some bundlers may not auto-detect types.

fix

Add `"types": "./dist/index.d.ts"` to tsconfig or explicitly import types.

affects: 0.1.0

Errors

Common errors & fixes

Cannot find module 'progress-state' or its corresponding type declarations.

Missing dependency or TypeScript unable to resolve types because package not installed or types not declared.

fix

Run `npm install progress-state`. Ensure Node >=18. If using TypeScript, check that `types` field is correctly resolved (see warnings).

Uncaught TypeError: group.add is not a function

Incorrect import (e.g., using `require` in ESM context) or destructuring the default export which does not exist.

fix

Use `import { createProgressGroup } from 'progress-state'` and call `createProgressGroup()` to get a group.

Property 'complete' does not exist on type 'ProgressItem'

Imported `ProgressItem` as a value instead of a type, or using a very old TypeScript version.

fix

Ensure you use `import type { ProgressItem } from 'progress-state'` and have TypeScript >=4.5.

Uncaught TypeError: snapshot is not a function

Trying to call `snapshot` on an object that is not a ProgressGroup (e.g., on the result of `createProgressGroup` itself?).

fix

After creating the group with `createProgressGroup()`, use `const group = createProgressGroup(); group.snapshot()`.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

typescriptoptionalFor type checking and development, though not a runtime dependency; the library ships with bundled types

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/iexitdev/progress-state ↗

packageprogress-state ↗

homepagehttps://github.com/iexitdev/progress-state#readme ↗