workflows: update type params docs (#18416)

* workflows: update type params docs

* workflows: add type validation partial

* workflows: doc type params for create

* Apply suggestions from code review

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

* Update events-and-parameters.mdx

* Update workers-api.mdx

* Update workers-api.mdx

* Update events-and-parameters.mdx

---------

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

Author: 2 people

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

@@ -6,6 +6,8 @@ sidebar:
 
 ---
 
+import { MetaInfo, Render, Type } from "~/components";
+
 When a Workflow is triggered, it can receive an optional event. This event can include data that your Workflow can act on, including request details, user data fetched from your database (such as D1 or KV) or from a webhook, or messages from a Queue consumer.
 
 Events are a powerful part of a Workflow, as you often want a Workflow to act on data. Because a given Workflow instance executes durably, events are a useful way to provide a Workflow with data that should be immutable (not changing) and/or represents data the Workflow needs to operate on at that point in time.
@@ -104,4 +106,4 @@ export class MyWorkflow extends WorkflowEntrypoint {
 }
 ```
 
-Note that type parameters do not _validate_ that the incoming event matches your type definition. Properties (fields) that do not exist or conform to the type you provided will be dropped. If you need to validate incoming events, we recommend a library such as [zod](https://zod.dev/) or your own validator logic.
+<Render file="workflows-type-parameters"/>

src/content/docs/workflows/build/workers-api.mdx

@@ -6,7 +6,7 @@ sidebar:
 
 ---
 
-import { MetaInfo, Type } from "~/components";
+import { MetaInfo, Render, Type } from "~/components";
 
 This guide details the Workflows API within Cloudflare Workers, including methods, types, and usage examples.
 
@@ -183,13 +183,16 @@ Create (trigger) a new instance of the given Workflow.
 
 * <code>create(options?: WorkflowInstanceCreateOptions): Promise&lt;WorkflowInstance&gt;</code>
 
-  * `options` - optional properties to pass when creating an instance.
+  * `options` - optional properties to pass when creating an instance, includng a user-provided ID and payload parameters.
 
-An ID is automatically generated, but a user-provided ID can be specified (up to 64 characters [^1]). This can be useful when mapping Workflows to users, merchants or other identifiers in your system.
+An ID is automatically generated, but a user-provided ID can be specified (up to 64 characters [^1]). This can be useful when mapping Workflows to users, merchants or other identifiers in your system. You can also provide a JSON object as the `params` property, allowing you to pass data for the Workflow instance to act on as its [`WorkflowEvent`](/workflows/build/events-and-parameters/).
 
 ```ts
-// Create a new Workflow instance with your own ID:
-let instance = await env.MY_WORKFLOW.create({ id: myIdDefinedFromOtherSystem })
+// Create a new Workflow instance with your own ID and pass params to the Workflow instance
+let instance = await env.MY_WORKFLOW.create({
+	id: myIdDefinedFromOtherSystem,
+	params: { "hello": "world" }
+})
 return Response.json({
 	id: instance.id,
 	details: await instance.status(),
@@ -198,6 +201,42 @@ return Response.json({
 
 Returns a `WorkflowInstance`.
 
+<Render file="workflows-type-parameters"/>
+
+To provide an optional type parameter to the `Workflow`, pass a type argument with your type when defining your Workflow bindings:
+
+```ts
+interface User {
+	email: string;
+	createdTimestamp: number;
+}
+
+interface Env {
+	// Pass our User type as the type parameter to the Workflow definition
+  MY_WORKFLOW: Workflow<User>;
+}
+
+export default {
+	async fetch(request, env, ctx) {
+		// More likely to come from your database or via the request body!
+		const user: User = {
+			email: user@example.com,
+			createdTimestamp: Date.now()
+		}
+
+		let instance = await env.MY_WORKFLOW.create({
+			// params expects the type User
+			params: user
+		})
+		
+		return Response.json({
+			id: instance.id,
+			details: await instance.status(),
+		});
+	}
+}
+```
+
 ### get
 
 Get a specific Workflow instance by ID.

src/content/partials/workflows/workflows-type-parameters.mdx

@@ -0,0 +1,14 @@
+---
+{}
+
+---
+
+import { Markdown } from "~/components"
+
+:::caution
+
+Providing a type parameter does _not_ validate that the incoming event matches your type definition. In TypeScript, properties (fields) that do not exist or conform to the type you provided will be dropped. If you need to validate incoming events, we recommend a library such as [zod](https://zod.dev/) or your own validator logic.
+
+:::
+
+You can also provide a type parameter to the `Workflows` type when creating (triggering) a Workflow instance using the `create` method of the [Workers API](/workflows/build/workers-api/#workflow). Note that this does _not_ propagate type information into the Workflow itself, as TypeScript types are a build-time construct. To provide the type of an incoming `WorkflowEvent`, refer to the [TypeScript and type parameters](/workflows/build/events-and-parameters/#typescript-and-type-parameters) section of the Workflows documentation.