Batching docs

docs/integrations/apis/shopify-triggers.mdx

@@ -12,25 +12,58 @@ You can use these triggers to start a job when a Shopify event occurs.
 All triggers can be create folllowing the same pattern:
 
 ```ts
-shopify.on("topic")
+shopify.on("topic");
 ```
 
 <ParamField body="topic" type="string">
   The webhook topic you want to subscribe to. Generally a pattern of `<resource>/<action>`.
 </ParamField>
 
-### Helpers
+## Helpers
+
+### filter()
 
 The `filter()` method returns a new trigger with the applied payload filter:
 
 ```ts
-const trigger = shopify.on("topic").filter(filter)
+shopify.on("topic").filter(filter);
 ```
 
 <ResponseField name="filter" type="EventFilter" required>
   A filter to apply to the event. See our [EventFilter guide](/documentation/guides/event-filter).
 </ResponseField>
 
+### batch()
+
+The `batch()` method returns a new trigger with batching enabled.
+
+Batching will cause the `payload` parameter of the run function to become an array of payloads instead.
+
+```ts
+shopify.on("topic").batch({
+  // receive no more than 5 payloads per batch
+  maxPayloads: 5,
+  // send out incomplete batches after 10 seconds
+  maxInterval: 10,
+});
+
+// shortcut to enable with sensible defaults
+shopify.on("topic").batch();
+```
+
+<ResponseField name="options" type="object">
+  Used to configure batching options. An empty or absent object will enable batching with server defaults.
+
+  <Expandable title="batch options" defaultOpen>
+    <ResponseField name="maxPayloads" type="number">
+      How many event payloads you will at most receive per batch. May be reduced by server limits..
+    </ResponseField>
+    <ResponseField name="maxInterval" type="number">
+      How many seconds to wait before sending out incomplete batches. May be cut short by server limits.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
 ## Events
 
 What follows is a small selection of webhook topics and associated payloads. A complete list of possible topic names and payloads can be found [here](https://shopify.dev/docs/api/admin-rest/2023-07/resources/webhook#event-topics).

docs/sdk/eventtrigger.mdx

@@ -66,9 +66,51 @@ You can have multiple Jobs that subscribe to the same event, they will all trigg
       </Expandable>
     </ResponseField>
 
+    <ResponseField name="batch" type="object">
+      Used to configure batching options. An empty object will enable batching with server defaults.
+
+      Batching will cause the `payload` parameter of the run function to become an array of payloads instead.
+
+      <Expandable title="batch options" defaultOpen>
+        <ResponseField name="maxPayloads" type="number">
+          How many event payloads you will at most receive per batch. May be reduced by server limits..
+        </ResponseField>
+        <ResponseField name="maxInterval" type="number">
+          How many seconds to wait before sending out incomplete batches. May be cut short by server limits.
+        </ResponseField>
+      </Expandable>
+    </ResponseField>
+
   </Expandable>
 </ResponseField>
 
+## Batching
+
+Batching will cause the `payload` parameter of the run function to become an array of payloads instead.
+
+It can be enabled via the `batch` property or alternatively via the `batch()` method on existing triggers:
+
+```typescript
+eventTrigger({
+  name: "batch.this",
+  batch: {
+    // receive no more than 5 payloads per batch
+    maxPayloads: 5,
+    // send out incomplete batches after 10 seconds
+    maxInterval: 10,
+  }
+});
+
+// alternatively
+eventTrigger({ name: "batch.this" }).batch({
+  maxPayloads: 5,
+  maxInterval: 10,
+});
+
+// shortcut to enable with sensible defaults
+eventTrigger({ name: "batch.this" }).batch();
+```
+
 <RequestExample>
 
 ```typescript eventTrigger()

packages/trigger-sdk/src/triggers/eventTrigger.ts

@@ -63,9 +63,11 @@ export class EventTrigger<
   /**
    * Used to configure batching options. An empty object will enable batching with server defaults.
    *
+   * Batching will cause the `payload` parameter of the run function to become an array of payloads instead.
+   *
    * @param options - Is an object containing the following properties:
-   * @param {number} options.maxPayloads - The `maxPayloads` property defines how many event payloads you will receive at most per batch. This is affected by server limits, but you should never receive more than this.
-   * @param {number} options.maxInterval - The `maxInterval` property defines how many seconds to wait before sending out batches that aren't full yet. This is affected by server limits, but you should never receive more than this.
+   * @param {number} options.maxPayloads - The `maxPayloads` property defines How many event payloads you will at most receive per batch. May be reduced by server limits..
+   * @param {number} options.maxInterval - The `maxInterval` property defines how many seconds to wait before sending out incomplete batches. May be cut short by server limits.
    */
   batch(options?: BatcherOptions): EventTrigger<TEventSpecification, {}> {
     const { batch, ...rest } = this.#options;
@@ -126,8 +128,10 @@ type TriggerOptions<TEvent, TBatcherOptions extends OptionalBatcherOptions = und
   /**
    * Used to configure batching options. An empty object will enable batching with server defaults.
    *
-   * @param {number} maxPayloads - The `maxPayloads` property defines how many event payloads you will receive at most per batch. This is affected by server limits, but you should never receive more than this.
-   * @param {number} maxInterval - The `maxInterval` property defines how many seconds to wait before sending out batches that aren't full yet. This is affected by server limits, but you should never receive more than this.
+   * Batching will cause the `payload` parameter of the run function to become an array of payloads instead.
+   *
+   * @param {number} maxPayloads - The `maxPayloads` property defines How many event payloads you will at most receive per batch. May be reduced by server limits..
+   * @param {number} maxInterval - The `maxInterval` property defines how many seconds to wait before sending out incomplete batches. May be cut short by server limits.
    */
   batch?: TBatcherOptions;
 

packages/trigger-sdk/src/triggers/webhook.ts

@@ -273,8 +273,10 @@ export type WebhookTriggerOptions<
   /**
    * Used to configure batching options. An empty object will enable batching with server defaults.
    *
-   * @param {number} maxPayloads - The `maxPayloads` property defines how many event payloads you will receive at most per batch. This is affected by server limits, but you should never receive more than this.
-   * @param {number} maxInterval - The `maxInterval` property defines how many seconds to wait before sending out batches that aren't full yet. This is affected by server limits, but you should never receive more than this.
+   * Batching will cause the `payload` parameter of the run function to become an array of payloads instead.
+   *
+   * @param {number} maxPayloads - The `maxPayloads` property defines How many event payloads you will at most receive per batch. May be reduced by server limits..
+   * @param {number} maxInterval - The `maxInterval` property defines how many seconds to wait before sending out incomplete batches. May be cut short by server limits.
    */
   batch?: TBatcherOptions;
 };
@@ -328,9 +330,11 @@ export class WebhookTrigger<
   /**
    * Used to configure batching options. An empty object will enable batching with server defaults.
    *
+   * Batching will cause the `payload` parameter of the run function to become an array of payloads instead.
+   *
    * @param options - Is an object containing the following properties:
-   * @param {number} options.maxPayloads - The `maxPayloads` property defines how many event payloads you will receive at most per batch. This is affected by server limits, but you should never receive more than this.
-   * @param {number} options.maxInterval - The `maxInterval` property defines how many seconds to wait before sending out batches that aren't full yet. This is affected by server limits, but you should never receive more than this.
+   * @param {number} options.maxPayloads - The `maxPayloads` property defines How many event payloads you will at most receive per batch. May be reduced by server limits..
+   * @param {number} options.maxInterval - The `maxInterval` property defines how many seconds to wait before sending out incomplete batches. May be cut short by server limits.
    */
   batch(options?: BatcherOptions): WebhookTrigger<TEventSpecification, TEventSource, TConfig, {}> {
     const { batch, ...rest } = this.options;