feat(api): add onProgress callback to copy() and scan() APIs#98
Merged
gregpriday merged 2 commits intoFeb 26, 2026
Merged
Conversation
- Add ProgressTracker utility that normalizes pipeline events to { percent, message }
- Wire ProgressTracker into scan() when options.onProgress is provided
- Add progress wrapping in copy() with scan=0-80% and format=80-100% split
- Add monotonic guard and try/catch in copy() so callback errors are non-fatal
- Export ProgressTracker from src/index.js for advanced consumers
- Add TypeScript definitions for ProgressTracker, ProgressTrackerOptions
- Make ProgressTrackerOptions.totalStages optional (defaults to 1)
- Add 24 unit tests for ProgressTracker (lifecycle, throttle, edge cases)
- Add 12 integration tests for onProgress in scan() and copy()
…ogress for onProgress PR
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the
onProgresscallback option forcopy()andscan()APIs, enabling consumers to show real-time progress bars without needing to construct the pipeline manually.Closes #64
Changes Made
src/utils/ProgressTracker.js(new) — normalizes pipeline events (stage:start,stage:complete,file:batch,stage:progress) into a simple{ percent, message }format; throttled (default 100ms); monotonically increasing; exceptions in the callback are swallowed so progress tracking never breaks the operationsrc/api/scan.js— wiresProgressTrackerinto the pipeline whenoptions.onProgressis provided; respectsoptions.progressThrottleMssrc/api/copy.js— addsemitProgresswrapper with monotonic guard and try/catch; scan phase covers 0–80%, format phase 80–100%; always emits 0% on start and 100% on completesrc/index.js— exportsProgressTrackerfor advanced consumerstypes/index.d.ts— addsProgressTrackerclass,ProgressTrackerOptionsinterface;totalStagesis optional;onProgress/progressThrottleMsalready present inScanOptions/CopyOptionstests/unit/utils/ProgressTracker.test.js(new) — 24 unit tests covering lifecycle, monotonic enforcement, throttling, edge cases (null lastFile, missing message, throwing callbacks)tests/integration/onProgress.test.js(new) — 12 integration tests forscan()andcopy()including dry run, throttle, edge casesUsage