Reorder phases and refactor runner with improved error handling

[adelrodriguez]

This pull request reorders the implementation phases and improves error handling consistency throughout the codebase.

Phase Reordering:

• Moved gen implementation from Phase 11 to Phase 9
• Shifted all and allSettled from Phase 9 to Phase 10
• Moved flow + $exit from Phase 10 to Phase 11

Error Handling Improvements:

• Replaced generic Error instances with Panic errors in builder methods, dispose, gen, and utility functions
• Updated test assertions to expect Panic instead of generic errors or specific error messages
• Standardized error messages for sync/async mismatch scenarios

Package Metadata Updates:

• Updated keywords to reflect the library's actual purpose (abort-signal, error-handling, retry, timeout, try-catch)
• Removed template-related scripts and files

Code Refactoring:

• Refactored the runner implementation into a RunExecution class to better encapsulate execution state and logic
• Simplified method naming and improved code organization within the runner
• Removed template initialization script that was no longer needed

Greptile Summary

This PR improves error handling consistency and refactors the runner implementation for better code organization.

Key Changes:

• Refactored runner.ts into a RunExecution class that encapsulates execution state (#config, #ctx, #signal, #timeout) and logic, improving maintainability
• Standardized error handling by replacing generic Error instances with Panic throughout the codebase (builder, dispose, gen, utils, runner)
• Updated all test assertions to expect Panic error type instead of checking specific error message strings
• Reordered implementation phases in plan.md: gen moved to Phase 9, all/allSettled to Phase 10, flow/$exit to Phase 11
• Cleaned up package.json keywords to reflect the library's actual purpose and removed template initialization script

The refactoring maintains all existing behavior while improving code organization and error handling consistency.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• All changes are internal refactoring with no behavior changes to the public API. The runner refactoring into RunExecution class improves code organization without altering logic. Error handling standardization using Panic is consistent with the existing error model. Test updates properly validate the new error expectations. Phase reordering is a documentation-only change.
• No files require special attention

Important Files Changed

Filename	Overview
.context/plan.md	Reordered phases: gen moved to Phase 9, all/allSettled to Phase 10, flow/$exit to Phase 11
src/lib/builder.ts	Replaced generic Error with Panic in unimplemented method stubs (all, allSettled, flow)
src/lib/dispose.ts	Replaced generic Error with Panic in unimplemented stub
src/lib/gen.ts	Replaced generic Error with Panic in unimplemented stub
src/lib/runner.ts	Major refactoring: encapsulated execution state in RunExecution class, replaced generic errors with Panic, simplified method names
src/lib/utils.ts	Replaced generic Error with Panic in assertUnreachable function

Class Diagram

%%{init: {'theme': 'neutral'}}%%
classDiagram
    class RunExecution {
        -BuilderConfig config
        -TryCtx ctx
        -SignalController signal
        -TimeoutController timeout
        -RunCatchFn catchFn
        -SyncRunTryFn|AsyncRunTryFn tryFn
        +execute() T|E|RunnerError|Promise
        -dispose() void
        -checkDidControlFail() CancellationError|TimeoutError
        -raceWithControl() Promise
        -finalizeError() E|RunnerError|Promise
        -evaluateRetryDecision() RetryDecision
        -resolveAttemptError() E|RunnerError|RetryResult
        -handleAttemptErrorSync() T|E|RunnerError|SyncRetryContinuation
        -handleAttemptErrorAsync() Promise
        -executeAttemptAsync() Promise
        -executeAttemptSync() T|E|RunnerError|Promise
    }

    class executeRunSync {
        <<function>>
        +executeRunSync(config, input) T|E|RunnerError
    }

    class executeRunAsync {
        <<function>>
        +executeRunAsync(config, input) Promise
    }

    executeRunSync ..> RunExecution : creates
    executeRunAsync ..> RunExecution : creates

    note for RunExecution "Encapsulates all execution state and logic for a single run.\nHandles retry, timeout, cancellation, and error mapping."

Loading

_{Last reviewed commit: 05803ee}

[coderabbitai]

Warning

Rate limit exceeded

@adelrodriguez has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 4 minutes and 19 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between c3bb21e and 4fe9c4a.

📒 Files selected for processing (12)

• .context/plan.md
• package.json
• scripts/init.ts
• src/__tests__/ctx-features.test.ts
• src/__tests__/index.test.ts
• src/lib/__tests__/retry.test.ts
• src/lib/__tests__/runner.test.ts
• src/lib/builder.ts
• src/lib/dispose.ts
• src/lib/gen.ts
• src/lib/runner.ts
• src/lib/utils.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 02-22-reorder_phases_and_refactor_runner_with_improved_error_handling

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[adelrodriguez]

• Disable allSettled() after retry() and fix retry behavior in all() #20
• Fix flow execution to wait for all tasks to settle before retry #19
• code cleanup #18
• Complete Phase 12 - Hardening + release readiness #16
• Replace settled().all() with dedicated allSettled() method #17
• Implement Phase 11 flow with $exit functionality #15
• Implement all and allSettled for parallel task execution #14
• Add gen integration tests and improve error handling #13
• Refactor API to async-first with runSync for sync-only operations #12
• Support multiple abort signals and refactor signal/timeout controllers #11
• Implement Phase 8 dispose with AsyncDisposableStack #10
• Complete Phase 7 - Builder API + root namespace exports #9
• Implement Phase 6 wrap middleware with full-run scope #8
• Reorder phases and refactor runner with improved error handling #7 👈 (View in Graphite)
• Implement Phase 5 signal cancellation with AbortController integration #6
• Implement Phase 4 timeout functionality with full builder chain support #5
• Split run into sync run() and async runAsync() #4
• Implement Phase 3 retry behavior and type refactors #2
• Refactor retry and timeout types with improved documentation #3
• feat: add execution runner #1
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR successfully refactors the runner implementation and standardizes error handling across the codebase. The main change encapsulates execution logic into a RunExecution class, replacing nested closures with private methods for better organization and maintainability.

Key Changes:

• Refactored runner.ts from nested closures to RunExecution class with private methods
• Converted recursive async retry logic to iterative loops for better stack safety
• Replaced generic Error instances with Panic errors throughout the codebase (builder, dispose, gen, utils)
• Updated all test assertions to check for Panic type instead of specific error messages
• Reordered implementation phases in plan.md (gen → Phase 9, all/allSettled → Phase 10, flow/$exit → Phase 11)
• Updated package.json keywords to reflect actual library purpose
• Removed template initialization script

The refactoring preserves all existing functionality while improving code organization. Error handling is now consistent, and tests are more resilient to error message changes.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk.
• The refactoring is well-executed with clear separation of concerns. The conversion from nested closures to a class improves maintainability without changing behavior. All test files have been updated consistently, and the error handling standardization makes the codebase more predictable.
• No files require special attention

Important Files Changed

Filename	Overview
src/lib/runner.ts	Refactored execution logic from nested closures into RunExecution class with private methods. Converted recursive async retry to iterative loop. Consistent error handling with Panic for sync/async mismatches.
src/lib/builder.ts	Updated unimplemented methods (all, allSettled, flow) to throw Panic instead of generic Error.
src/tests/index.test.ts	Updated test assertions to expect Panic type instead of specific error messages, making tests more resilient to message changes.
src/lib/tests/retry.test.ts	Updated sync/async mismatch test assertions to expect Panic type instead of specific error messages.
package.json	Updated keywords to reflect library purpose (abort-signal, error-handling, retry, timeout, try-catch) and removed template init script.
.context/plan.md	Reordered implementation phases: moved gen to Phase 9, all/allSettled to Phase 10, and flow/$exit to Phase 11.

_{Last reviewed commit: 4fe9c4a}

[adelrodriguez]

@greptileai review
@coderabbitai review

[coderabbitai]

@adelrodriguez, I'll review the changes in this PR.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.