diff --git a/docs/content/docs/api-reference/workflow-api/start.mdx b/docs/content/docs/api-reference/workflow-api/start.mdx index a36d944d58..5ae4be8dbd 100644 --- a/docs/content/docs/api-reference/workflow-api/start.mdx +++ b/docs/content/docs/api-reference/workflow-api/start.mdx @@ -54,6 +54,7 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow- * This is different from calling workflow functions directly, which is the typical pattern in Next.js applications. * The function returns immediately after enqueuing the workflow - it doesn't wait for the workflow to complete. * All arguments must be [serializable](/docs/foundations/serialization). +* When `deploymentId` is provided, the argument types and return type become `unknown` since there is no guarantee the workflow function's types will be consistent across different deployments. ## Examples diff --git a/packages/core/src/runtime.ts b/packages/core/src/runtime.ts index 542898008d..fe83bbfa61 100644 --- a/packages/core/src/runtime.ts +++ b/packages/core/src/runtime.ts @@ -60,7 +60,13 @@ export { type StopSleepResult, wakeUpRun, } from './runtime/runs.js'; -export { type StartOptions, start } from './runtime/start.js'; +export { + type StartOptions, + type StartOptionsBase, + type StartOptionsWithDeploymentId, + type StartOptionsWithoutDeploymentId, + start, +} from './runtime/start.js'; export { stepEntrypoint } from './runtime/step-handler.js'; export { createWorld, diff --git a/packages/core/src/runtime/start.ts b/packages/core/src/runtime/start.ts index e8ba64908b..a7828cfb3a 100644 --- a/packages/core/src/runtime/start.ts +++ b/packages/core/src/runtime/start.ts @@ -17,7 +17,20 @@ import { getWorld } from './world.js'; /** ULID generator for client-side runId generation */ const ulid = monotonicFactory(); -export interface StartOptions { +export interface StartOptionsBase { + /** + * The world to use for the workflow run creation, + * by default the world is inferred from the environment variables. + */ + world?: World; + + /** + * The spec version to use for the workflow run. Defaults to the latest version. + */ + specVersion?: number; +} + +export interface StartOptionsWithDeploymentId extends StartOptionsBase { /** * The deployment ID to use for the workflow run. * @@ -28,21 +41,24 @@ export interface StartOptions { * @deprecated This property should not be set in user code under normal circumstances. * It is automatically inferred from environment variables when deploying to Vercel. * Only set this if you are doing something advanced and know what you are doing. + * + * **Note:** When `deploymentId` is provided, the argument and return types become `unknown` + * since there is no guarantee the types will be consistent across deployments. */ - deploymentId?: 'latest' | (string & {}); - - /** - * The world to use for the workflow run creation, - * by default the world is inferred from the environment variables. - */ - world?: World; + deploymentId: 'latest' | (string & {}); +} - /** - * The spec version to use for the workflow run. Defaults to the latest version. - */ - specVersion?: number; +export interface StartOptionsWithoutDeploymentId extends StartOptionsBase { + deploymentId?: undefined; } +/** + * Options for starting a workflow run. + */ +export type StartOptions = + | StartOptionsWithDeploymentId + | StartOptionsWithoutDeploymentId; + /** * Represents an imported workflow function. */ @@ -63,15 +79,28 @@ export type WorkflowMetadata = { workflowId: string }; * @param options - The options for the workflow run (optional). * @returns The unique run ID for the newly started workflow invocation. */ +// Overloads with deploymentId - args and return type become unknown +export function start( + workflow: WorkflowFunction | WorkflowMetadata, + args: unknown[], + options: StartOptionsWithDeploymentId +): Promise>; + +export function start( + workflow: WorkflowFunction | WorkflowMetadata, + options: StartOptionsWithDeploymentId +): Promise>; + +// Overloads without deploymentId - preserve type inference export function start( workflow: WorkflowFunction | WorkflowMetadata, args: TArgs, - options?: StartOptions + options?: StartOptionsWithoutDeploymentId ): Promise>; export function start( workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, - options?: StartOptions + options?: StartOptionsWithoutDeploymentId ): Promise>; export async function start(