Uh oh!
There was an error while loading. Please reload this page.
Make start() types unknown when deploymentId is provided - #1367
Merged
Conversation
Ensure types are 'unknown[]' and 'unknown' for 'deploymentId' and update exports and documentation. Slack-Thread: https://vercel.slack.com/archives/C09G3EQAL84/p1773368990070059?thread_ts=1773368990.070059&cid=C09G3EQAL84 Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
🦋 Changeset detectedLatest commit: 1f22fd4 The changes in this PR will be included in the next version bump. This PR includes changesets to release 16 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests🌍 Community Worlds (55 failed)mongodb (2 failed):
redis (2 failed):
turso (51 failed):
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
✅ 📋 Other
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adjusts @workflow/core’s start() TypeScript API so that providing an explicit deploymentId no longer implies compile-time argument/return type compatibility with the local workflow code, avoiding misleading type inference when targeting other deployments.
Changes:
- Split
StartOptionsintoStartOptionsBase,StartOptionsWithDeploymentId, andStartOptionsWithoutDeploymentId. - Added
start()overloads sodeploymentIdcalls useunknown[]args and returnPromise<Run<unknown>>. - Exported the new option types from
packages/core/src/runtime.tsand documented theunknowntyping behavior.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| packages/core/src/runtime/start.ts | Refactors start option types and adds overloads to switch to unknown typing when deploymentId is provided. |
| packages/core/src/runtime.ts | Re-exports the newly split start option types. |
| docs/content/docs/api-reference/workflow-api/start.mdx | Documents that passing deploymentId makes args/return type unknown. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| */ | ||
| specVersion?: number; | ||
| export interface StartOptionsWithoutDeploymentId extends StartOptionsBase { | ||
| deploymentId?: undefined; |
ContributorAuthor
There was a problem hiding this comment.
Acknowledged — the string | undefined pattern no longer type-checks with the split options types. Since main has since updated the deploymentId docs to remove the @deprecated annotation and frame it as a standard option, this is an acceptable trade-off for the improved type safety.
Comment on lines
+83
to
+90
| export function start( | ||
| workflow: WorkflowFunction<unknown[], unknown> | WorkflowMetadata, | ||
| args: unknown[], | ||
| options: StartOptionsWithDeploymentId | ||
| ): Promise<Run<unknown>>; | ||
| export function start( | ||
| workflow: WorkflowFunction<unknown[], unknown> | WorkflowMetadata, |
ContributorAuthor
There was a problem hiding this comment.
Fixed — changed the deploymentId overloads to use generics (WorkflowFunction<TArgs, TResult>) instead of WorkflowFunction<unknown[], unknown>, which resolves the contravariance issue. Typed workflows like WorkflowFunction<[string], number> are now assignable. The return type remains Run<unknown> and args remain unknown[] as intended. Also added type-level tests to prevent regressions.
| ): Promise<Run<unknown>>; | ||
| export function start( | ||
| workflow: WorkflowFunction<unknown[], unknown> | WorkflowMetadata, |
ContributorAuthor
There was a problem hiding this comment.
Good catch — the no-args overload for the deploymentId case now constrains to WorkflowFunction<[], TResult>, so only zero-arg workflows can omit the args array.
karthikscale3
commented
Mar 13, 2026
Contributor
Claude flagged a blocker and some more comments: PR #1367 Review: Make start() types unknown when deploymentId is providedIntent: When BlockerOverload with The // (from the PR diff - new overloads)exportfunctionstart(workflow: WorkflowFunction<unknown[],unknown>|WorkflowMetadata,args: unknown[],options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;exportfunctionstart(workflow: WorkflowFunction<unknown[],unknown>|WorkflowMetadata,options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;Due to TypeScript's function parameter contravariance under import{myWorkflow}from'./workflows/my-workflow';// WorkflowFunction<[string], number>start(myWorkflow,['hello'],{deploymentId: 'dpl_xxx'});// TYPE ERRORThis defeats the purpose of the PR since the main use case is calling exportfunctionstart<TArgsextendsunknown[],TResult>(workflow: WorkflowFunction<TArgs,TResult>|WorkflowMetadata,args: unknown[],options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;(Copilot's review comment #2 flagged the same issue.) Potential Regressions
Minor Issues
VerdictThe contravariance issue with the |
…ssue Addresses PR review feedback: typed workflows like WorkflowFunction<[string], number> were not assignable to WorkflowFunction<unknown[], unknown> under strictFunctionTypes. Changed to generic parameters while keeping Run<unknown> return type. Also adds type-level tests for overload resolution. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…naygp-6fadd605 * 'main' of https://github.com/vercel/workflow: (73 commits) chore: bump next to 16.2.1 and fix deferred build (#1496) chore: bump nitropack to ^2.13.1 (#1501) chore: bump nuxt ecosystem dependencies (#1500) chore: bump sveltekit ecosystem (#1498) chore: bump express and fastify in workbenches (#1499) chore: bump @nestjs/* to ^11.1.17 (#1497) chore: bump hono to ^4.12.8 (#1495) Revert "Inline class serialization registration to fix 3rd-party package supp…" (#1493) [world] Add stream pagination and metadata endpoints (#1470) [cli] [world-local] Ensure update checks don't suggest upgrading from stable release to pre-releases (#1490) Remove NestJS Vercel integration while in experimental phase (#1485) feat: export semantic error types and add API reference docs (#1447) feat: enforce max queue deliveries in handlers with graceful failure (#1344) [world-postgres] Migrate client from `postgres.js` to `pg` (#1484) Inline class serialization registration to fix 3rd-party package support (#1480) [ai] Add experimental_context to DurableAgentOptions (#1489) [ai] Expose configured tools on DurableAgent instances (#1488) fix(builders): catch node builtin usage when entry fields diverge (#1455) [web-shared] Fix timeline duration format and precision (#1482) [cli] Add bulk cancel, --status filter, fix step JSON hydration (#1467) ... # Conflicts: # packages/core/src/runtime/start.ts
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
pranaygp
commented
Mar 24, 2026
ContributorAuthor
Thanks for the thorough review! Here's how each item was addressed: Blocker (contravariance) — Fixed. The Issue 1 (string | undefined) — Acknowledged. The split types mean Issue 2 (sub-types not re-exported) — These are internal implementation types; users interact via the Issue 3 (changeset) — Added a changeset with an accurate description. Issue 4 (type-level tests) — Added in the test file using Also merged latest main (73 commits) and resolved the conflict in |
start() types unknown when deploymentId is providedTooTallNate
approved these changes
Mar 24, 2026
TooTallNate
left a comment
Member
There was a problem hiding this comment.
Review Summary
Clean, well-thought-out change. The overload design correctly handles the type-safety tradeoff when deploymentId is provided — making args unknown[] and return Run<unknown> is the right call since there's no guarantee the remote deployment's workflow function has the same signature.
What looks good:
- Overload ordering is correct:
deploymentIdoverloads first (with requireddeploymentId), then the type-preserving overloads. TypeScript resolves them in order so the right one always wins. - Using generics on the
deploymentIdoverloads (<TArgs extends unknown[], TResult>) avoids contravariance issues — aWorkflowFunction<[string, number], boolean>is assignable without needing a cast. - The
StartOptionsWithoutDeploymentIdvariant withdeploymentId?: undefinedis the correct discriminated union pattern. - Type-level tests with
expectTypeOfare a great addition. - Implementation body is unchanged — this is purely a type-level refactor of the public API surface.
- Changeset is appropriately scoped as
patch. - Unrelated formatting changes (classify-error.test.ts, serialization.ts) are trivial Biome reformats.
Minor observations (non-blocking):
- The new sub-types (
StartOptionsBase,StartOptionsWithDeploymentId,StartOptionsWithoutDeploymentId) are exported from@workflow/corebut not re-exported from theworkflowpackage (api.ts/api-workflow.ts). SinceStartOptions(the union) is already re-exported and is likely what most consumers use, this is fine — but worth noting if users later need to narrow to a specific variant. - There is a merge commit (
77fd9ad3) for the inline class serialization change. The diff is clean so this does not cause issues, but consider rebasing to keep history linear if that is the repo convention.
LGTM — no blocking issues found.
Uh oh!
There was an error while loading. Please reload this page.
pranaygp added a commit
that referenced
this pull request
Apr 3, 2026
…1-refresh * origin/main: (21 commits) Fix node-module-error plugin matching identifiers in multi-line comments (#1554) fix(swc-plugin): use binding name for class expression method registrations (#1599) fix(builders): override `sideEffects: false` for discovered workflow/step/serde entries (#1598) [world-vercel] align header names to `x-vercel-workflow-*` convention (#1602) [docs] Add vercel world consumer function security documentation (#1543) Make `start()` types `unknown` when `deploymentId` is provided (#1367) fix(next): stop force-setting WORKFLOW_PUBLIC_MANIFEST=1 during next dev (#1597) Version Packages (beta) (#1593) [docs] Tidy world API docs and document new stream helpers (#1581) Rename 'Workflow Development Kit' / 'DevKit' to 'Workflow SDK' (#1595) [world] Use zod/v4 in queue files to match @workflow/world schemas (#1588) [ai] Fix fatal stream errors surfacing as [object Object] (#1589) [web] Fix server crash on unmatched routes (#1590) docs: rename 'Complex Example' to 'Instance Methods as Steps' (#1592) Version Packages (beta) (#1563) [core] Extend flow route duration to "max" and fail runs where replay takes too long (#1567) fix: check target run capabilities before encrypting hook payloads (#1572) [core] Combine initial run fetch, event fetch, and run_started event creation (#1569) [docs] Split World API docs into sub-pages, update skill.md (#1457) [nitro] Preserve workflow step registration side effects (#1386) ... # Conflicts: # skills/workflow/SKILL.md
Merged
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 freeto 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.
When
deploymentIdis explicitly provided tostart(), the workflow function at that deployment may have different argument and return types than the current codebase. This change splitsStartOptionsinto separate types and adds function overloads so that:deploymentId: Full type inference is preserved (TArgsandTResult)deploymentId: Args becomeunknown[]and return becomesRun<unknown>to avoid false type expectationsWhat changed
StartOptionsintoStartOptionsBase,StartOptionsWithDeploymentId, andStartOptionsWithoutDeploymentIdstart()that returnRun<unknown>whendeploymentIdis providedruntime.tsdeploymentId