feat: make create instance api take a single options parameter (#2950)

Not only this allows for a better DX, it allows us to customize and add
new fields later without breaking changes.

src/cloudflare/internal/test/workflows/workflows-api-test.js

@@ -8,7 +8,10 @@ export const tests = {
   async test(_, env) {
     {
       // Test create instance
-      const instance = await env.workflow.create('foo', { bar: 'baz' });
+      const instance = await env.workflow.create({
+        name: 'foo',
+        payload: { bar: 'baz' },
+      });
       assert.deepStrictEqual(instance.id, 'foo');
     }
 

src/cloudflare/internal/test/workflows/workflows-mock.js

@@ -26,7 +26,7 @@ export default {
       return Response.json(
         {
           result: {
-            instanceId: data.id,
+            instanceId: data.name,
           },
         },
         {

src/cloudflare/internal/workflows-api.ts

@@ -96,11 +96,13 @@ class WorkflowImpl {
     return new InstanceImpl(result.instanceId, this.fetcher);
   }
 
-  public async create(id: string, params?: unknown): Promise<Instance> {
+  public async create(
+    options?: WorkflowInstanceCreateOptions
+  ): Promise<Instance> {
     const result = await callFetcher<{ instanceId: string }>(
       this.fetcher,
       '/create',
-      { id, params }
+      options ?? {}
     );
 
     return new InstanceImpl(result.instanceId, this.fetcher);

src/cloudflare/internal/workflows.d.ts

@@ -32,11 +32,21 @@ declare abstract class Workflow {
 
   /**
    * Create a new instance and return a handle to it. If a provided id exists, an error will be thrown.
-   * @param id Id to create the instance of this Workflow with
-   * @param params Optional params to send over to this instance
+   * @param options optional fields to customize the instance creation
    * @returns A promise that resolves with a handle for the Instance
    */
-  public create(id: string, params?: unknown): Promise<Instance>;
+  public create(options?: WorkflowInstanceCreateOptions): Promise<Instance>;
+}
+
+interface WorkflowInstanceCreateOptions {
+  /**
+   * Name to create the instance of this Workflow with - it should always be unique
+   */
+  name?: string;
+  /**
+   * The payload to send over to this instance, this is optional since you might need to pass params into the instance
+   */
+  params?: unknown;
 }
 
 type InstanceStatus = {

types/defines/workflows.d.ts

@@ -18,11 +18,21 @@ declare abstract class Workflow {
 
   /**
    * Create a new instance and return a handle to it. If a provided id exists, an error will be thrown.
-   * @param id Id to create the instance of this Workflow with
-   * @param params The payload to send over to this instance
+   * @param options optional fields to customize the instance creation
    * @returns A promise that resolves with a handle for the Instance
    */
-  public create(id: string, params: object): Promise<Instance>;
+  public create(options?: WorkflowInstanceCreateOptions): Promise<Instance>;
+}
+
+interface WorkflowInstanceCreateOptions {
+  /**
+   * Name to create the instance of this Workflow with - it should always be unique
+   */
+  name?: string;
+  /**
+   * The payload to send over to this instance, this is optional since you might need to pass params into the instance
+   */
+  params?: unknown;
 }
 
 type InstanceStatus = {