From fa63aac5aa972dfceb90cbfcba0244acb56827f1 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Tue, 26 Nov 2024 09:01:50 -0500 Subject: [PATCH 1/8] workflows: update type params docs --- src/content/docs/workflows/build/events-and-parameters.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/events-and-parameters.mdx b/src/content/docs/workflows/build/events-and-parameters.mdx index 50c04d21b153800..68a07f85ba8eaaa 100644 --- a/src/content/docs/workflows/build/events-and-parameters.mdx +++ b/src/content/docs/workflows/build/events-and-parameters.mdx @@ -104,4 +104,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. + From 6333d9b1ecb013489c15ec371335ec7bc3655d3e Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Tue, 26 Nov 2024 09:05:19 -0500 Subject: [PATCH 2/8] workflows: add type validation partial --- .../workflows/workflows-type-parameters.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 src/content/partials/workflows/workflows-type-parameters.mdx diff --git a/src/content/partials/workflows/workflows-type-parameters.mdx b/src/content/partials/workflows/workflows-type-parameters.mdx new file mode 100644 index 000000000000000..3c81c7b20c6fbc6 --- /dev/null +++ b/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. From b6cd4bbece43c303b9588cc6e6a867ef4aaf81d7 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Tue, 26 Nov 2024 09:16:10 -0500 Subject: [PATCH 3/8] workflows: doc type params for create --- .../docs/workflows/build/workers-api.mdx | 47 +++++++++++++++++-- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index 1b48851d49bbb6b..ea4aebf6ca9fcf8 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -171,13 +171,16 @@ Create (trigger) a new instance of the given Workflow. * create(options?: WorkflowInstanceCreateOptions): Promise<WorkflowInstance> - * `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(), @@ -186,6 +189,42 @@ return Response.json({ Returns a `WorkflowInstance`. + + +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; +} + +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. From 150a839f144836a098c2c00f5f86e1142b64e737 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Wed, 27 Nov 2024 05:57:45 -0500 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: Skye <46286597+Skye-31@users.noreply.github.com> --- src/content/docs/workflows/build/workers-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index ea4aebf6ca9fcf8..0ecffa9d3399155 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -179,7 +179,7 @@ An ID is automatically generated, but a user-provided ID can be specified (up to // 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 } + params: { "hello": "world" } }) return Response.json({ id: instance.id, From 0921123ec0348e00fce7ee629f6d1fe3bf93284f Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Wed, 27 Nov 2024 06:18:31 -0500 Subject: [PATCH 5/8] Update events-and-parameters.mdx --- src/content/docs/workflows/build/events-and-parameters.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/events-and-parameters.mdx b/src/content/docs/workflows/build/events-and-parameters.mdx index 68a07f85ba8eaaa..9a000601d42a60c 100644 --- a/src/content/docs/workflows/build/events-and-parameters.mdx +++ b/src/content/docs/workflows/build/events-and-parameters.mdx @@ -104,4 +104,4 @@ export class MyWorkflow extends WorkflowEntrypoint { } ``` - + From 4b6f3fd58aa739f9ed40707bc00ebaf4bdb1882f Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Wed, 27 Nov 2024 06:19:11 -0500 Subject: [PATCH 6/8] Update workers-api.mdx --- src/content/docs/workflows/build/workers-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index 0ecffa9d3399155..6353076b4a826ae 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -189,7 +189,7 @@ return Response.json({ Returns a `WorkflowInstance`. - + To provide an optional type parameter to the `Workflow`, pass a type argument with your type when defining your Workflow bindings: From 346962272490293e7677ac1668b79073871b1e2c Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Wed, 27 Nov 2024 06:35:11 -0500 Subject: [PATCH 7/8] Update workers-api.mdx --- src/content/docs/workflows/build/workers-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index 6353076b4a826ae..95d4f64e5f3df9d 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/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. From 29c1448b516a982f8834240338c9c779be7bc362 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Wed, 27 Nov 2024 06:35:51 -0500 Subject: [PATCH 8/8] Update events-and-parameters.mdx --- src/content/docs/workflows/build/events-and-parameters.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/workflows/build/events-and-parameters.mdx b/src/content/docs/workflows/build/events-and-parameters.mdx index 9a000601d42a60c..3acc65a03aac534 100644 --- a/src/content/docs/workflows/build/events-and-parameters.mdx +++ b/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.