Pagination helper and docs

Author: nicktrn

docs/integrations/apis/linear.mdx

@@ -122,6 +122,72 @@ client.defineJob({
 });
 ```
 
+### Pagination
+
+You can paginate responses three different ways:
+
+1. Via the raw Linear SDK exposed in `io.runTask()`
+2. Iterating the same integration task with different params
+3. Using the `getAll` helper exposed on the integration (**recommended!**)
+
+_When ordering results, make sure to use the `PaginationOrderBy` enum._
+
+```ts
+import { Linear, PaginationOrderBy, serializeLinearOutput } from "@trigger.dev/linear";
+...
+client.defineJob({
+  id: "linear-pagination",
+  name: "Linear Pagination",
+  version: "0.1.0",
+  integrations: {
+    linear,
+  },
+  trigger: eventTrigger({
+    name: "linear.paginate",
+  }),
+  run: async (payload, io, ctx) => {
+    //the same params will be used for all tasks
+    const params = { first: 5, orderBy: PaginationOrderBy.UpdatedAt };
+
+    //1. Linear SDK
+    const sdkIssues = await io.linear.runTask("all-issues-via-sdk", async (client) => {
+      const edges = await client.issues(params);
+
+      //this will keep appending nodes until there are no more
+      while (edges.pageInfo.hasNextPage) {
+        await edges.fetchNext();
+      }
+
+      //use serialization helper to remove functions etc
+      return serializeLinearOutput(edges.nodes);
+    });
+
+    //2. Linear integration - no pagination helper
+    let edges = await io.linear.issues("get-issues", params);
+    let noHelper = edges.nodes;
+
+    for (let i = 0; edges.pageInfo.hasNextPage; i++) {
+      edges = await io.linear.issues(`get-more-issues-${i}`, {
+        ...params,
+        after: edges.pageInfo.endCursor,
+      });
+      noHelper = noHelper.concat(edges.nodes);
+    }
+
+    //3. Linear integration - with the pagination helper
+    const withHelper = await io.linear.getAll(io.linear.issues, "get-all", params);
+
+    return {
+      issueCounts: {
+        withSdk: sdkIssues.length,
+        noHelper: noHelper.length,
+        withHelper: withHelper.length,
+      },
+    };
+  },
+});
+```
+
 ## Triggers
 
 ### Attachments

integrations/linear/src/index.ts

@@ -17,6 +17,7 @@ import {
   Comment,
   CommentConnection,
   CommentPayload,
+  Connection,
   CreateOrJoinOrganizationResponse,
   CycleArchivePayload,
   CyclePayload,
@@ -42,6 +43,7 @@ import {
   IssueRelationPayload,
   IssueSearchPayload,
   LinearClient,
+  LinearDocument,
   LinearError,
   Notification,
   NotificationArchivePayload,
@@ -80,8 +82,6 @@ import {
   WorkflowStateConnection,
   WorkflowStatePayload,
 } from "@linear/sdk";
-import * as events from "./events";
-import { TriggerParams, Webhooks, createTrigger, createWebhookEventSource } from "./webhooks";
 import {
   ArchiveIssueMutationVariables,
   ArchiveProjectMutationVariables,
@@ -139,8 +139,11 @@ import {
   WorkflowStateCreateInput,
   WorkflowStatesQueryVariables,
 } from "@linear/sdk/dist/_generated_documents";
+
+import * as events from "./events";
 import { AwaitNested, LinearReturnType, SerializedLinearOutput } from "./types";
-import { queryProperties } from "./utils";
+import { Nullable, QueryVariables, queryProperties } from "./utils";
+import { TriggerParams, Webhooks, createTrigger, createWebhookEventSource } from "./webhooks";
 
 export type LinearIntegrationOptions = {
   id: string;
@@ -228,6 +231,29 @@ export class Linear implements TriggerIntegration {
     );
   }
 
+  async getAll<
+    TTask extends (
+      key: IntegrationTaskKey,
+      params: Partial<Nullable<QueryVariables>>
+    ) => LinearReturnType<Connection<unknown>>,
+  >(
+    task: TTask,
+    key: IntegrationTaskKey,
+    params: Nullable<QueryVariables> = {}
+  ): Promise<Awaited<ReturnType<TTask>>["nodes"]> {
+    const boundTask = task.bind(this);
+
+    let edges = await boundTask(`${key}-0`, params);
+    let nodes = edges.nodes;
+
+    for (let i = 1; edges.pageInfo.hasNextPage; i++) {
+      edges = await boundTask(`${key}-${i}`, { ...params, after: edges.pageInfo.endCursor });
+      nodes = nodes.concat(edges.nodes);
+    }
+
+    return nodes;
+  }
+
   attachment(key: IntegrationTaskKey, params: { id: string }): LinearReturnType<Attachment> {
     return this.runTask(
       key,
@@ -2056,3 +2082,5 @@ export const serializeLinearOutput = <T>(obj: T): Prettify<SerializedLinearOutpu
 };
 
 export { events };
+
+export const PaginationOrderBy = LinearDocument.PaginationOrderBy

references/job-catalog/src/linear.ts

@@ -1,6 +1,6 @@
 import { createExpressServer } from "@trigger.dev/express";
 import { TriggerClient, eventTrigger } from "@trigger.dev/sdk";
-import { Linear, serializeLinearOutput } from "@trigger.dev/linear";
+import { Linear, PaginationOrderBy, serializeLinearOutput } from "@trigger.dev/linear";
 import { z } from "zod";
 
 export const client = new TriggerClient({
@@ -87,7 +87,7 @@ client.defineJob({
     await io.linear.viewer("get-viewer");
     await io.linear.organization("get-org");
 
-    const fourDigits = Math.floor(Math.random() * 1000)
+    const fourDigits = Math.floor(Math.random() * 1000);
 
     //create an organization
     await io.linear.createOrganizationFromOnboarding("create-org", {
@@ -118,4 +118,56 @@ client.defineJob({
   },
 });
 
+client.defineJob({
+  id: "linear-pagination",
+  name: "Linear Pagination",
+  version: "0.1.0",
+  integrations: {
+    linear,
+  },
+  trigger: eventTrigger({
+    name: "linear.paginate",
+  }),
+  run: async (payload, io, ctx) => {
+    //the same params will be used for all tasks
+    const params = { first: 5, orderBy: PaginationOrderBy.UpdatedAt };
+
+    //1. Linear SDK
+    const sdkIssues = await io.linear.runTask("all-issues-via-sdk", async (client) => {
+      const edges = await client.issues(params);
+
+      //this will keep appending nodes until there are no more
+      while (edges.pageInfo.hasNextPage) {
+        await edges.fetchNext();
+      }
+
+      //use serialization helper to remove functions etc
+      return serializeLinearOutput(edges.nodes);
+    });
+
+    //2. Linear integration - no pagination helper
+    let edges = await io.linear.issues("get-issues", params);
+    let noHelper = edges.nodes;
+
+    for (let i = 0; edges.pageInfo.hasNextPage; i++) {
+      edges = await io.linear.issues(`get-more-issues-${i}`, {
+        ...params,
+        after: edges.pageInfo.endCursor,
+      });
+      noHelper = noHelper.concat(edges.nodes);
+    }
+
+    //3. Linear integration - with the pagination helper
+    const withHelper = await io.linear.getAll(io.linear.issues, "get-all", params);
+
+    return {
+      issueCounts: {
+        withSdk: sdkIssues.length,
+        noHelper: noHelper.length,
+        withHelper: withHelper.length,
+      },
+    };
+  },
+});
+
 createExpressServer(client);