Changed `RetryableError` to use milliseconds instead of seconds for numeric `retryAfter` values.
### What changed?
- Modified the `RetryableError` class to interpret numeric `retryAfter` values as milliseconds instead of seconds
- Updated documentation and examples to reflect this change
- Added dependency on `@workflow/utils` package to use the `parseDurationToDate` function
- Updated examples in documentation to show proper usage with:
- Duration strings (e.g., "5m", "30s")
- Millisecond values (e.g., 5000 for 5 seconds)
- Date objects
### How to test?
1. Create a workflow that uses `RetryableError` with different `retryAfter` formats:
```typescript
// With milliseconds
throw new RetryableError("Test retry", { retryAfter: 5000 });
// With duration string
throw new RetryableError("Test retry", { retryAfter: "5m" });
// With Date object
throw new RetryableError("Test retry", { retryAfter: new Date(Date.now() + 10000) });
```
2. Verify that the retry behavior correctly respects the specified durations
### Why make this change?
Using milliseconds as the unit for numeric time values is more consistent with JavaScript conventions (like `setTimeout` and other timing functions). This change makes the API more intuitive for JavaScript developers and aligns with standard practices in the ecosystem.
Signed-off-by: Nathan Rajlich <n@n8.io>
Add a new `@workflow/utils` package to extract common utility functions.
- Created a new `@workflow/utils` package with common utility functions:
- `parseDurationToDate()` - Parses duration strings, numbers, or Date objects
- `withResolvers()` - Polyfill for `Promise.withResolvers()`
- `once()` - Creates a lazily-evaluated, memoized function
- `PromiseWithResolvers` - Type interface for promise resolvers
- Moved these utility functions from the core package to the new utils package
- Updated imports in the core package to use the new utils package
- Added tests for the utility functions in the new package
Signed-off-by: Nathan Rajlich <n@n8.io>
The overloads parsing logic is now covered in unit tests, so we only
need one e2e test for the specific sleep functionality.
Signed-off-by: Nathan Rajlich <n@n8.io>
* feat: add type safety for builder configurations with discriminated unions
Improves type safety by creating discriminated union types for builder-specific
configurations, making it clear which configuration options are required for
each builder type.
Changes:
- Created BaseWorkflowConfig interface with common options
- Created StandaloneConfig, VercelBuildOutputConfig, and NextConfig types
- Made WorkflowConfig a discriminated union based on buildTarget
- Added documentation for each configuration type
- Exported new types from @workflow/builders
This enables better IntelliSense and type checking when constructing builder
configurations, preventing invalid configuration combinations at compile time.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: consolidate builder configuration patterns
Extracts common builder configuration pattern into a reusable helper function,
improving consistency across framework integrations.
Changes:
- Created createBaseBuilderConfig() helper in @workflow/builders
- Updated @workflow/nitro builders to use the new helper
- Removed CommonBuildOptions constant from nitro package
- Added clear documentation for when bundle paths are not used
This makes it easier for framework integrations to create properly configured
builder instances without manually specifying unused bundle path properties.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: add documentation and improve code clarity
Adds comprehensive JSDoc comments to BaseBuilder methods and improves code
documentation throughout the builders package.
Changes:
- Added class-level documentation for BaseBuilder
- Added JSDoc comments for all major public/protected methods
- Documented the discoveredEntries WeakMap caching mechanism
- Cleaned up TODO comment about debug file location
- Improved method parameter documentation
This makes the builders package more maintainable and easier to understand
for contributors and users extending the base builder functionality.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Apply suggestion from @vercel[bot]
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Nathan Rajlich <n@n8.io>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
* refactor: consolidate builder configuration patterns
Extracts common builder configuration pattern into a reusable helper function,
improving consistency across framework integrations.
Changes:
- Created createBaseBuilderConfig() helper in @workflow/builders
- Updated @workflow/nitro builders to use the new helper
- Removed CommonBuildOptions constant from nitro package
- Added clear documentation for when bundle paths are not used
This makes it easier for framework integrations to create properly configured
builder instances without manually specifying unused bundle path properties.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* .
Signed-off-by: Nathan Rajlich <n@n8.io>
---------
Signed-off-by: Nathan Rajlich <n@n8.io>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Nathan Rajlich <n@n8.io>
Enhances logEsbuildMessages to throw on critical errors by default,
ensuring build failures are properly surfaced instead of being silently logged.
Changes:
- Added throwOnError parameter to logEsbuildMessages (defaults to true)
- When errors occur, now throws with formatted error messages
- Collects all error messages and locations for comprehensive error reporting
This prevents builds from appearing successful when esbuild encounters
critical errors, improving debugging and build reliability.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
* feat: add type safety for builder configurations with discriminated unions
Improves type safety by creating discriminated union types for builder-specific
configurations, making it clear which configuration options are required for
each builder type.
Changes:
- Created BaseWorkflowConfig interface with common options
- Created StandaloneConfig, VercelBuildOutputConfig, and NextConfig types
- Made WorkflowConfig a discriminated union based on buildTarget
- Added documentation for each configuration type
- Exported new types from @workflow/builders
This enables better IntelliSense and type checking when constructing builder
configurations, preventing invalid configuration combinations at compile time.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: extract path resolution and directory creation helpers
Adds reusable helper methods to BaseBuilder for common path operations,
reducing code duplication and improving readability in builder subclasses.
Changes:
- Added resolvePath() helper in BaseBuilder
- Added ensureDirectory() helper in BaseBuilder
- Updated StandaloneBuilder (both in @workflow/builders and @workflow/cli)
to use the new helpers
- Removed unnecessary imports from StandaloneBuilder
This simplifies path handling code from:
const path = resolve(this.config.workingDir, this.config.somePath);
await mkdir(dirname(path), { recursive: true });
To:
const path = this.resolvePath(this.config.somePath);
await this.ensureDirectory(path);
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Nathan Rajlich <n@n8.io>
---------
Signed-off-by: Nathan Rajlich <n@n8.io>
Co-authored-by: Claude <noreply@anthropic.com>
* feat: add type safety for builder configurations with discriminated unions
Improves type safety by creating discriminated union types for builder-specific
configurations, making it clear which configuration options are required for
each builder type.
Changes:
- Created BaseWorkflowConfig interface with common options
- Created StandaloneConfig, VercelBuildOutputConfig, and NextConfig types
- Made WorkflowConfig a discriminated union based on buildTarget
- Added documentation for each configuration type
- Exported new types from @workflow/builders
This enables better IntelliSense and type checking when constructing builder
configurations, preventing invalid configuration combinations at compile time.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* .
Signed-off-by: Nathan Rajlich <n@n8.io>
---------
Signed-off-by: Nathan Rajlich <n@n8.io>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Nathan Rajlich <n@n8.io>
Improves code consistency by standardizing method naming conventions and
clarifying log messages across builders.
Changes:
- Renamed buildClientLibrary() to createClientLibrary() in BaseBuilder to match
the convention where "create" is used for protected/shared methods
- Updated all callers in StandaloneBuilder and VercelBuildOutputAPIBuilder
- Clarified log messages in StandaloneBuilder by removing "Vercel API" prefix
since this builder is framework-agnostic
This establishes a clear pattern:
- Public/template methods in subclasses: build* (buildStepsFunction, etc.)
- Protected/shared methods in BaseBuilder: create* (createStepsBundle, etc.)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Extracts repeated package.json and .vc-config.json generation logic into
reusable helper methods in BaseBuilder, eliminating code duplication across
VercelBuildOutputAPIBuilder.
Changes:
- Added createPackageJson() helper method to BaseBuilder
- Added createVcConfig() helper method with sensible defaults
- Updated VercelBuildOutputAPIBuilder (both in @workflow/builders and @workflow/cli)
to use the new helper methods
- Reduced configuration code from ~20 lines per function to ~3 lines
This makes the build code more maintainable and ensures consistent configuration
across all Vercel Build Output API functions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Consolidates duplicated queue trigger configurations into shared constants
in @workflow/builders package, eliminating repetition across multiple builders.
Changes:
- Created STEP_QUEUE_TRIGGER and WORKFLOW_QUEUE_TRIGGER constants
- Updated VercelBuildOutputAPIBuilder to use shared constants
- Updated NextBuilder (both in @workflow/next and @workflow/cli) to use constants
- Exported constants from @workflow/builders index
This ensures consistent queue configuration across all builders and makes
future updates to these settings easier to manage from a single location.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
* export WorkflowReadableStreamOptions from workflow/api
* docs: add WorkflowReadableStreamOptions to start api reference
* changeset
* docs: update getRun api reference to show WorkflowReadableStreamOptions
* refactor: link to WorkflowReadableStreamOptions on getRun docs
* Apply suggestion from @TooTallNate
---------
Co-authored-by: Nathan Rajlich <n@n8.io>
Moves NextBuilder from @workflow/cli to @workflow/next package, establishing
proper package boundaries where framework-specific builders live in their
respective framework integration packages.
Changes:
- Moved NextBuilder from @workflow/cli to @workflow/next
- Added @workflow/builders and watchpack dependencies to @workflow/next
- Updated runtime re-export to use @workflow/core/dist/runtime directly
- Removed direct dependency on @workflow/cli from @workflow/next
This aligns the Next.js builder with the Nitro builder pattern (which already
lives in @workflow/nitro), creating consistent package organization.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adrian