workflows: incorporate user feedback (#26871)

* workflows: incorporate user feedback

* add TypeScriptExample to other code examples

* Update src/content/docs/workflows/reference/limits.mdx

Co-authored-by: mia303 <[email protected]>

---------

Co-authored-by: mia303 <[email protected]>

Author: elithrar

src/content/docs/workflows/build/events-and-parameters.mdx

@@ -120,6 +120,29 @@ let event = await step.waitForEvent(
 
 You can specify a timeout between 1 second and up to 365 days.
 
+:::caution[Timeout behavior]
+
+When `waitForEvent` times out, the Workflow will throw an error and the instance will fail. If you want your Workflow to continue even if the event is not received, wrap the `waitForEvent` call in a try-catch block:
+
+<TypeScriptExample>
+
+```ts
+try {
+	const event = await step.waitForEvent("wait for approval", {
+		type: "approval",
+		timeout: "1 hour",
+	});
+	// Handle the received event
+} catch (e) {
+	// Timeout occurred - handle the case where no event was received
+	console.log("No approval received, proceeding with default action");
+}
+```
+
+</TypeScriptExample>
+
+:::
+
 ### Send events to running workflows
 
 Workflow instances that are waiting on events using the `waitForEvent` API can be sent events using the `instance.sendEvent` API:
@@ -153,6 +176,12 @@ export default {
 - To send multiple events to a Workflow that has multiple `waitForEvent` calls, call `sendEvent` with the corresponding `type` property set (up to 100 characters [^1]).
 - Events can also be sent using the REST API (HTTP API)'s [Events endpoint](/api/resources/workflows/subresources/instances/subresources/events/methods/create/).
 
+:::note[Event timing]
+
+You can send an event to a Workflow instance _before_ it reaches the corresponding `waitForEvent` call, as long as the instance has been created. The event will be buffered and delivered when the Workflow reaches the `waitForEvent` step with the matching `type`.
+
+:::
+
 ## TypeScript and type parameters
 
 By default, the `WorkflowEvent` passed to the `run` method of your Workflow definition has a type that conforms to the following, with `payload` (your data), `timestamp`, and `instanceId` properties:

src/content/docs/workflows/build/rules-of-workflows.mdx

@@ -509,6 +509,52 @@ export class MyWorkflow extends WorkflowEntrypoint {
 
 </TypeScriptExample>
 
+### Use conditional logic carefully
+
+You can use `if` statements, loops, and other control flow outside of steps. However, conditions must be based on **deterministic values** — either values from `event.payload` or return values from previous steps. Non-deterministic conditions (such as `Math.random()` or `Date.now()`) outside of steps can cause unexpected behavior if the Workflow restarts.
+
+<TypeScriptExample filename="index.ts">
+
+```ts
+export class MyWorkflow extends WorkflowEntrypoint {
+	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+		const config = await step.do("fetch config", async () => {
+			return await this.env.KV.get("feature-flags", { type: "json" });
+		});
+
+		// ✅ Good: Condition based on step output (deterministic)
+		if (config.enableEmailNotifications) {
+			await step.do("send email", async () => {
+				// Send email logic
+			});
+		}
+
+		// ✅ Good: Condition based on event payload (deterministic)
+		if (event.payload.userType === "premium") {
+			await step.do("premium processing", async () => {
+				// Premium-only logic
+			});
+		}
+
+		// 🔴 Bad: Condition based on non-deterministic value outside a step
+		// This could behave differently if the Workflow restarts
+		if (Math.random() > 0.5) {
+			await step.do("maybe do something", async () => {});
+		}
+
+		// ✅ Good: Wrap non-deterministic values in a step
+		const shouldProcess = await step.do("decide randomly", async () => {
+			return Math.random() > 0.5;
+		});
+		if (shouldProcess) {
+			await step.do("conditionally do something", async () => {});
+		}
+	}
+}
+```
+
+</TypeScriptExample>
+
 ### Batch multiple Workflow invocations
 
 When creating multiple Workflow instances, use the [`createBatch`](/workflows/build/workers-api/#createBatch) method to batch the invocations together. This allows you to create multiple Workflow instances in a single request, which will reduce the number of requests made to the Workflows API and increase the number of instances you can create per minute.
@@ -542,3 +588,40 @@ export default {
 ```
 
 </TypeScriptExample>
+
+### Keep step return values under 1 MiB
+
+Each step can persist up to 1 MiB (2^20 bytes) of state. If your step returns data exceeding this limit, the step will fail. This is a common issue when fetching large API responses or processing large files.
+
+To work around this limit, store large data externally (for example, in R2 or KV) and return only a reference:
+
+<TypeScriptExample filename="index.ts">
+
+```ts
+export class MyWorkflow extends WorkflowEntrypoint {
+	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+		// 🔴 Bad: Returning a large response that may exceed 1 MiB
+		const largeData = await step.do("fetch large dataset", async () => {
+			const response = await fetch("https://api.example.com/large-dataset");
+			return await response.json(); // Could exceed 1 MiB
+		});
+
+		// ✅ Good: Store large data externally and return a reference
+		const dataRef = await step.do("fetch and store large dataset", async () => {
+			const response = await fetch("https://api.example.com/large-dataset");
+			const data = await response.json();
+			// Store in R2 and return a reference
+			await this.env.MY_BUCKET.put("dataset-123", JSON.stringify(data));
+			return { key: "dataset-123" };
+		});
+
+		// Retrieve the data in a later step when needed
+		const data = await step.do("process dataset", async () => {
+			const stored = await this.env.MY_BUCKET.get(dataRef.key);
+			return processData(await stored.json());
+		});
+	}
+}
+```
+
+</TypeScriptExample>

src/content/docs/workflows/build/trigger-workflows.mdx

@@ -7,7 +7,7 @@ sidebar:
   order: 3
 ---
 
-import { WranglerConfig } from "~/components";
+import { TypeScriptExample, WranglerConfig } from "~/components";
 
 You can trigger Workflows both programmatically and via the Workflows APIs, including:
 
@@ -162,6 +162,42 @@ await instance.restart(); // Returns Promise<void>
 
 Restarting an instance will immediately cancel any in-progress steps, erase any intermediate state, and treat the Workflow as if it was run for the first time.
 
+### Trigger a Workflow from another Workflow
+
+You can create a new Workflow instance from within a step of another Workflow. The parent Workflow will not block waiting for the child Workflow to complete — it continues execution immediately after the child instance is successfully created.
+
+<TypeScriptExample>
+
+```ts
+export class ParentWorkflow extends WorkflowEntrypoint<Env, Params> {
+	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+		// Perform initial work
+		const result = await step.do("initial processing", async () => {
+			// ... processing logic
+			return { fileKey: "output.pdf" };
+		});
+
+		// Trigger a child workflow for additional processing
+		const childInstance = await step.do("trigger child workflow", async () => {
+			return await this.env.CHILD_WORKFLOW.create({
+				id: `child-${event.instanceId}`,
+				params: { fileKey: result.fileKey },
+			});
+		});
+
+		// Parent continues immediately - not blocked by child workflow
+		await step.do("continue with other work", async () => {
+			console.log(`Started child workflow: ${childInstance.id}`);
+			// This runs right away, regardless of child workflow status
+		});
+	}
+}
+```
+
+</TypeScriptExample>
+
+If the child Workflow fails to start, the step will fail and be retried according to your retry configuration. Once the child instance is successfully created, it runs independently from the parent.
+
 ## REST API (HTTP)
 
 Refer to the [Workflows REST API documentation](/api/resources/workflows/subresources/instances/methods/create/).

src/content/docs/workflows/reference/limits.mdx

@@ -49,7 +49,9 @@ Many limits are inherited from those applied to Workers scripts and as documente
 
 ### `waiting` instances do not count towards instance concurrency limits
 
-Instances that are on a `waiting` state - either sleeping, waiting for a retry, or waiting for an event - do **not** count towards concurrency limits. This means that other `queued` instances will be scheduled when an instance goes from a `running` state to a `waiting` one, usually the oldest instance queued, on a best-effort basis. This state transition - `running` to `waiting` - may not occur if the wait duration is too short.
+Instances that are in a `waiting` state — either sleeping via `step.sleep`, waiting for a retry, or waiting for an event via `step.waitForEvent` — do **not** count towards concurrency limits. This means you can have millions of Workflow instances sleeping or waiting for events simultaneously, as only actively `running` instances count toward the 10,000 concurrent instance limit.
+However, if there are 10,000 concurrent instances actively running, an instance that has been in a `waiting` state will be queued instead of resuming immediately. 
+When an instance transitions from `running` to `waiting`, other `queued` instances will be scheduled (usually the oldest queued instance, on a best-effort basis). This state transition may not occur if the wait duration is very short.
 
 For example, consider a Workflow that does some work, waits for 30 days, and then continues with more work: