Include batch context on ActionContext (#521)

Adds `context.batch` so a component can tell whether the flow it is running in
dispatches its trigger's items as batches, and at what size. Available to every
perform — triggers need it before the first fetch to size that fetch, and CNI
steps downstream of a batched trigger can branch on it too.

Author: internetlee

packages/spectral/src/batch-context.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { flow, trigger } from ".";
+import { invokeFlow, invokeTrigger } from "./testing";
+import type { BatchInfo } from "./types/BatchContext";
+
+describe("context.batch", () => {
+  const echoBatch = trigger({
+    display: { label: "Echo Batch", description: "Returns the batch context it saw." },
+    inputs: {},
+    perform: async (context) => ({
+      payload: {
+        ...({} as never),
+        body: { data: context.batch ?? null },
+      },
+    }),
+    scheduleSupport: "invalid",
+    synchronousResponseSupport: "invalid",
+  });
+
+  it("reaches a component trigger's perform", async () => {
+    const { result } = await invokeTrigger(echoBatch, {
+      batch: { enabled: true, batchSize: 50 },
+    });
+    expect(result?.payload.body.data).toEqual({ enabled: true, batchSize: 50 });
+  });
+
+  it("is undefined when the context omits it", async () => {
+    const { result } = await invokeTrigger(echoBatch);
+    expect(result?.payload.body.data).toBeNull();
+  });
+
+  it("carries enabled false through to the perform", async () => {
+    const { result } = await invokeTrigger(echoBatch, { batch: { enabled: false } });
+    expect(result?.payload.body.data).toEqual({ enabled: false });
+  });
+
+  it("exposes batchSize on the enabled variant", () => {
+    const disabled: BatchInfo = { enabled: false };
+    const enabled: BatchInfo = { enabled: true, batchSize: 25 };
+    // @ts-expect-error batchSize belongs to the enabled variant.
+    expect(disabled.batchSize).toBeUndefined();
+    expect(enabled.enabled ? enabled.batchSize : 0).toBe(25);
+  });
+
+  it("reaches a CNI flow's onExecution", async () => {
+    const seen: unknown[] = [];
+    const cniFlow = flow({
+      name: "Batch Aware Flow",
+      stableKey: "batch-aware-flow",
+      description: "Records the batch context its step body saw.",
+      onExecution: async (context) => {
+        seen.push(context.batch ?? null);
+        return Promise.resolve({ data: null });
+      },
+    });
+
+    await invokeFlow(cniFlow, { context: { batch: { enabled: true, batchSize: 25 } } });
+
+    expect(seen).toEqual([{ enabled: true, batchSize: 25 }]);
+  });
+});

packages/spectral/src/serverTypes/index.ts

@@ -2,6 +2,7 @@
  * component and integration definitions. */
 
 import type {
+  BatchInfo,
   ComponentManifest,
   ConfigVarResultCollection,
   CustomerAttributes,
@@ -144,6 +145,8 @@ export type ActionContext<
   startedAt: string;
   executionFrame: ExecutionFrame;
   flowSchemas: FlowSchemas;
+  /** How this flow dispatches its trigger's items. */
+  batch?: BatchInfo;
 
   // @TODO - Hidden from the user-facing ActionContext.
   globalDebug?: boolean;

packages/spectral/src/types/ActionPerformFunction.ts

@@ -2,6 +2,7 @@ import type { AxiosRequestConfig, AxiosResponse } from "axios";
 import type { ActionInputParameters } from "./ActionInputParameters";
 import type { ActionLogger } from "./ActionLogger";
 import type { ActionPerformReturn } from "./ActionPerformReturn";
+import type { BatchInfo } from "./BatchContext";
 import type { ComponentManifest } from "./ComponentManifest";
 import type { CustomerAttributes } from "./CustomerAttributes";
 import type { FlowAttributes } from "./FlowAttributes";
@@ -168,4 +169,9 @@ export type ActionContext<
   flowSchemas: FlowSchemas;
   /** Whether the execution is being run with simulated data. */
   isSimulatedTestExecution?: boolean;
+  /**
+   * How this flow dispatches its trigger's items, and when batching is enabled,
+   * the size of the batches for each run of the flow.
+   */
+  batch?: BatchInfo;
 };

packages/spectral/src/types/BatchContext.ts

@@ -0,0 +1,17 @@
+/**
+ * How the flow this execution belongs to dispatches its trigger's items.
+ *
+ * Discriminated on `enabled` - a flow that is not using batching has no batch
+ * size to report.
+ */
+export type BatchInfo =
+  | {
+      /** This flow dispatches its trigger's items one execution at a time. */
+      enabled: false;
+    }
+  | {
+      /** This flow dispatches its trigger's items as batches. */
+      enabled: true;
+      /** Items dispatched per batch. */
+      batchSize: number;
+    };

packages/spectral/src/types/index.ts

@@ -8,6 +8,7 @@ export * from "./ActionInputParameters";
 export * from "./ActionLogger";
 export * from "./ActionPerformFunction";
 export * from "./ActionPerformReturn";
+export * from "./BatchContext";
 export * from "./ComponentDefinition";
 export * from "./ComponentManifest";
 export * from "./ComponentRegistry";