Skip to content

feat(api): add onProgress callback to copy() and scan() APIs#98

Merged
gregpriday merged 2 commits into
developfrom
feature/issue-64-add-onprogress-callback-copy
Feb 26, 2026
Merged

feat(api): add onProgress callback to copy() and scan() APIs#98
gregpriday merged 2 commits into
developfrom
feature/issue-64-add-onprogress-callback-copy

Conversation

@gregpriday
Copy link
Copy Markdown
Owner

Summary

Implements the onProgress callback option for copy() and scan() 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 operation
  • src/api/scan.js — wires ProgressTracker into the pipeline when options.onProgress is provided; respects options.progressThrottleMs
  • src/api/copy.js — adds emitProgress wrapper with monotonic guard and try/catch; scan phase covers 0–80%, format phase 80–100%; always emits 0% on start and 100% on complete
  • src/index.js — exports ProgressTracker for advanced consumers
  • types/index.d.ts — adds ProgressTracker class, ProgressTrackerOptions interface; totalStages is optional; onProgress/progressThrottleMs already present in ScanOptions/CopyOptions
  • tests/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 for scan() and copy() including dry run, throttle, edge cases

Usage

import { copy } from 'copytree';

const result = await copy('./large-repo', {
  onProgress: ({ percent, message }) => {
    mainWindow.webContents.send('copy-progress', { percent, message });
  }
});

- 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()
@gregpriday gregpriday merged commit d3279f7 into develop Feb 26, 2026
11 of 15 checks passed
@gregpriday gregpriday deleted the feature/issue-64-add-onprogress-callback-copy branch February 26, 2026 03:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add onProgress callback to copy API for progress tracking

1 participant