Merge pull request #531 from equalogic/flexible-edges

sgarner · web-flow · commit f75947dab636 · 2025-04-30T15:12:21.000+12:00
feat: allow passing edges directly to ConnectionBuilder.build()
diff --git a/README.md b/README.md
@@ -80,7 +80,13 @@ Now define a `ConnectionBuilder` class for your `Connection` object. The builder
 pagination arguments for the connection, and creating the cursors and `Edge` objects that make up the connection.
 
 ```ts
-import { ConnectionBuilder, Cursor, PageInfo, validateParamsUsingSchema } from 'nestjs-graphql-connection';
+import {
+  ConnectionBuilder,
+  Cursor,
+  EdgeInputWithCursor,
+  PageInfo,
+  validateParamsUsingSchema,
+} from 'nestjs-graphql-connection';
 
 export type PersonCursorParams = { id: string };
 export type PersonCursor = Cursor<PersonCursorParams>;
@@ -96,7 +102,7 @@ export class PersonConnectionBuilder extends ConnectionBuilder<
     return new PersonConnection(fields);
   }
 
-  public createEdge(fields: { node: TestNode; cursor: string }): TestEdge {
+  public createEdge(fields: EdgeInputWithCursor<PersonEdge>): PersonEdge {
     return new PersonEdge(fields);
   }
 
@@ -108,7 +114,7 @@ export class PersonConnectionBuilder extends ConnectionBuilder<
     // A cursor sent to or received from a client is represented as a base64-encoded, URL-style query string containing
     // one or more key/value pairs describing the referenced node's position in the result set (its ID, a date, etc.)
     // Validation is optional, but recommended to enforce that cursor values supplied by clients must be well-formed.
-    // See documentation for Joi at https://joi.dev/api/?v=17#object
+    // This example uses Joi for validation, see documentation at https://joi.dev/api/?v=17#object
     // The following schema accepts only an object matching the type { id: string }:
     const schema: Joi.ObjectSchema<PersonCursorParams> = Joi.object({
       id: Joi.string().empty('').required(),
@@ -168,7 +174,12 @@ determining what the last result was on page 9.
 To use offset cursors, extend your builder class from `OffsetPaginatedConnectionBuilder` instead of `ConnectionBuilder`:
 
 ```ts
-import { OffsetPaginatedConnectionBuilder, PageInfo, validateParamsUsingSchema } from 'nestjs-graphql-connection';
+import {
+  EdgeInputWithCursor,
+  OffsetPaginatedConnectionBuilder,
+  PageInfo,
+  validateParamsUsingSchema,
+} from 'nestjs-graphql-connection';
 
 export class PersonConnectionBuilder extends OffsetPaginatedConnectionBuilder<
   PersonConnection,
@@ -180,7 +191,7 @@ export class PersonConnectionBuilder extends OffsetPaginatedConnectionBuilder<
     return new PersonConnection(fields);
   }
 
-  public createEdge(fields: { node: TestNode; cursor: string }): TestEdge {
+  public createEdge(fields: EdgeInputWithCursor<PersonEdge>): PersonEdge {
     return new PersonEdge(fields);
   }
 
@@ -236,24 +247,32 @@ properties -- such as the date that the friend was added, or the type of relatio
 this is analogous to having a Many-to-Many relation where the intermediate join table contains additional data columns
 beyond just the keys of the two joined tables.)
 
-In this case your edge type would look like the following example. Notice that we pass a `{ createdAt: Date }` type
-argument to `createEdgeType`; this specifies typings for the fields that are allowed to be passed to your edge class's
-constructor for initialization when doing `new PersonFriendEdge({ ...fields })`.
+In this case your edge type would look like the following example. Notice that we also now define a
+`PersonFriendEdgeInterface` type which we pass as a generic argument to `createEdgeType`; this ensures correct typings
+for the fields that are allowed to be passed to your edge class's constructor for initialization when doing
+`new PersonFriendEdge({ ...fields })`.
 
 ```ts
 import { Field, GraphQLISODateTime, ObjectType } from '@nestjs/graphql';
-import { createEdgeType } from 'nestjs-graphql-connection';
+import { createEdgeType, EdgeInterface } from 'nestjs-graphql-connection';
 import { Person } from './entities';
 
+export interface PersonFriendEdgeInterface extends EdgeInterface<Person> {
+  createdAt: Date;
+}
+
 @ObjectType()
-export class PersonFriendEdge extends createEdgeType<{ createdAt: Date }>(Person) {
+export class PersonFriendEdge
+  extends createEdgeType<PersonFriendEdgeInterface>(Person)
+  implements PersonFriendEdgeInterface
+{
   @Field(type => GraphQLISODateTime)
   public createdAt: Date;
 }
 ```
 
-`ConnectionBuilder` supports overriding the `createConnection()` and `createEdge()` methods when calling `build()`. This
-enables you to enrich the connection and edges with additional metadata at resolve time.
+To achieve this, you can pass an array of partial `edges` (instead of `nodes`) to `build()`. This enables you to
+provide values for any additional fields present on the edges.
 
 The following example assumes you have a GraphQL schema that defines a `friends` field on your `Person` object, which
 resolves to a `PersonFriendConnection` containing the person's friends. In your database you would have a `friend` table
@@ -284,19 +303,34 @@ export class PersonResolver {
     // Return resolved PersonFriendConnection with edges and pageInfo
     return connectionBuilder.build({
       totalEdges,
-      nodes: friends.map(friend => friend.otherPerson),
-      createEdge: ({ node, cursor }) => {
-        const friend = friends.find(friend => friend.otherPerson.id === node.id);
-
-        return new PersonFriendEdge({ node, cursor, createdAt: friend.createdAt });
-      },
+      edges: friends.map(friend => ({
+        node: friend.otherPerson,
+        createdAt: friend.createdAt,
+      })),
     });
   }
 }
 ```
 
-Alternatively, you could build the connection result yourself by replacing the `connectionBuilder.build(...)` statement
-with something like the following:
+Alternatively, you can override the `createEdge()` or `createConnection()` methods when calling `build()`.
+
+```ts
+return connectionBuilder.build({
+  totalEdges,
+  nodes: friends.map(friend => friend.otherPerson),
+  createConnection({ edges, pageInfo }) {
+    return new PersonFriendConnection({ edges, pageInfo, customField: 'hello-world' });
+  },
+  createEdge: ({ node, cursor }) => {
+    const friend = friends.find(friend => friend.otherPerson.id === node.id);
+
+    return new PersonFriendEdge({ node, cursor, createdAt: friend.createdAt });
+  },
+});
+```
+
+Finally, if the above methods don't meet your needs you can always build the connection result yourself by replacing
+`connectionBuilder.build(...)` with something like the following:
 
 ```ts
 // Resolve edges with cursor, node, and additional metadata
diff --git a/src/builder/ConnectionBuilder.spec.ts b/src/builder/ConnectionBuilder.spec.ts
@@ -1,19 +1,37 @@
 import Joi from 'joi';
 import { Cursor } from '../cursor/Cursor';
 import { validateParamsUsingSchema } from '../cursor/validateParamsUsingSchema';
-import { ConnectionArgs, createConnectionType, createEdgeType, PageInfo } from '../type';
-import { ConnectionBuilder } from './ConnectionBuilder';
+import {
+  ConnectionArgs,
+  ConnectionInterface,
+  createConnectionType,
+  createEdgeType,
+  EdgeInterface,
+  PageInfo,
+} from '../type';
+import { ConnectionBuilder, EdgeInputWithCursor } from './ConnectionBuilder';
 
 class TestNode {
   id: string;
   name: string;
 }
 
-class TestEdge extends createEdgeType<{ customEdgeField?: number }>(TestNode) {
+interface TestEdgeInterface extends EdgeInterface<TestNode> {
+  customEdgeField?: number;
+}
+
+class TestEdge extends createEdgeType<TestEdgeInterface>(TestNode) implements TestEdgeInterface {
   public customEdgeField?: number;
 }
 
-class TestConnection extends createConnectionType<{ customConnectionField?: number }>(TestEdge) {
+interface TestConnectionInterface extends ConnectionInterface<TestEdge> {
+  customConnectionField?: number;
+}
+
+class TestConnection
+  extends createConnectionType<TestConnectionInterface>(TestEdge)
+  implements TestConnectionInterface
+{
   public customConnectionField?: number;
 }
 
@@ -36,7 +54,7 @@ class TestConnectionBuilder extends ConnectionBuilder<
     return new TestConnection(fields);
   }
 
-  public createEdge(fields: { node: TestNode; cursor: string }): TestEdge {
+  public createEdge(fields: EdgeInputWithCursor<TestEdge>): TestEdge {
     return new TestEdge(fields);
   }
 
@@ -271,4 +289,37 @@ describe('ConnectionBuilder', () => {
       ],
     });
   });
+
+  test('Can build Connection using partial Edges', () => {
+    const builder = new TestConnectionBuilder({
+      first: 5,
+    });
+    const connection = builder.build({
+      totalEdges: 12,
+      edges: [
+        { node: { id: 'node1', name: 'A' }, customEdgeField: 1 },
+        { node: { id: 'node2', name: 'B' }, customEdgeField: 2 },
+        { node: { id: 'node3', name: 'C' }, customEdgeField: 3 },
+        { node: { id: 'node4', name: 'D' }, customEdgeField: 4 },
+        { node: { id: 'node5', name: 'E' }, customEdgeField: 5 },
+      ],
+    });
+
+    expect(connection).toMatchObject({
+      pageInfo: {
+        totalEdges: 12,
+        hasNextPage: true,
+        hasPreviousPage: false,
+        startCursor: new Cursor({ id: 'node1' }).encode(),
+        endCursor: new Cursor({ id: 'node5' }).encode(),
+      },
+      edges: [
+        { node: { id: 'node1', name: 'A' }, cursor: new Cursor({ id: 'node1' }).encode(), customEdgeField: 1 },
+        { node: { id: 'node2', name: 'B' }, cursor: new Cursor({ id: 'node2' }).encode(), customEdgeField: 2 },
+        { node: { id: 'node3', name: 'C' }, cursor: new Cursor({ id: 'node3' }).encode(), customEdgeField: 3 },
+        { node: { id: 'node4', name: 'D' }, cursor: new Cursor({ id: 'node4' }).encode(), customEdgeField: 4 },
+        { node: { id: 'node5', name: 'E' }, cursor: new Cursor({ id: 'node5' }).encode(), customEdgeField: 5 },
+      ],
+    });
+  });
 });
diff --git a/src/builder/ConnectionBuilder.ts b/src/builder/ConnectionBuilder.ts
@@ -8,6 +8,52 @@ export interface ConnectionBuilderOptions {
   allowReverseOrder?: boolean;
 }
 
+export type EdgeExtraFields<TEdge extends EdgeInterface<TNode>, TNode = any> = Partial<Omit<TEdge, 'node' | 'cursor'>>;
+
+export type EdgeInput<TEdge extends EdgeInterface<TNode>, TNode = any> = {
+  node: TNode;
+  cursor?: string;
+} & EdgeExtraFields<TEdge>;
+
+export type EdgeInputWithCursor<TEdge extends EdgeInterface<TNode>, TNode = any> = {
+  node: TNode;
+  cursor: string;
+} & EdgeExtraFields<TEdge>;
+
+interface CommonBuildParams<
+  TNode,
+  TEdge extends EdgeInterface<TNode>,
+  TConnection extends ConnectionInterface<TEdge>,
+  TCursor extends Cursor = Cursor,
+> {
+  totalEdges?: number;
+  hasNextPage?: boolean;
+  hasPreviousPage?: boolean;
+  createConnection?: (fields: { edges: TEdge[]; pageInfo: PageInfo }) => TConnection;
+  createEdge?: (fields: EdgeInputWithCursor<TEdge>) => TEdge;
+  createCursor?: (node: TNode, index: number) => TCursor;
+}
+
+type BuildFromNodesParams<
+  TNode,
+  TEdge extends EdgeInterface<TNode>,
+  TConnection extends ConnectionInterface<TEdge>,
+  TCursor extends Cursor = Cursor,
+> = {
+  nodes?: TNode[];
+  edges?: never;
+} & CommonBuildParams<TNode, TEdge, TConnection, TCursor>;
+
+type BuildFromEdgesParams<
+  TNode,
+  TEdge extends EdgeInterface<TNode>,
+  TConnection extends ConnectionInterface<TEdge>,
+  TCursor extends Cursor = Cursor,
+> = {
+  nodes?: never;
+  edges?: EdgeInput<TEdge>[];
+} & CommonBuildParams<TNode, TEdge, TConnection, TCursor>;
+
 export abstract class ConnectionBuilder<
   TConnection extends ConnectionInterface<TEdge>,
   TConnectionArgs extends ConnectionArgs,
@@ -28,7 +74,7 @@ export abstract class ConnectionBuilder<
 
   public abstract createConnection(fields: { edges: TEdge[]; pageInfo: PageInfo }): TConnection;
 
-  public abstract createEdge(fields: { node: TNode; cursor: string }): TEdge;
+  public abstract createEdge(fields: EdgeInputWithCursor<TEdge>): TEdge;
 
   public abstract createCursor(node: TNode, index: number): TCursor;
 
@@ -58,34 +104,37 @@ export abstract class ConnectionBuilder<
 
   public build({
     nodes,
+    edges,
     totalEdges,
     hasNextPage,
     hasPreviousPage,
     createConnection = this.createConnection,
     createEdge = this.createEdge,
     createCursor = this.createCursor,
-  }: {
-    nodes: TNode[];
-    totalEdges?: number;
-    hasNextPage?: boolean;
-    hasPreviousPage?: boolean;
-    createConnection?: (fields: { edges: TEdge[]; pageInfo: PageInfo }) => TConnection;
-    createEdge?: (fields: { node: TNode; cursor: string }) => TEdge;
-    createCursor?: (node: TNode, index: number) => TCursor;
-  }): TConnection {
-    const edges = nodes.map((node, index) =>
-      createEdge.bind(this)({
-        node,
-        cursor: createCursor.bind(this)(node, index).encode(),
-      }),
-    );
+  }:
+    | BuildFromNodesParams<TNode, TEdge, TConnection, TCursor>
+    | BuildFromEdgesParams<TNode, TEdge, TConnection, TCursor>): TConnection {
+    const resolvedEdges: TEdge[] =
+      edges != null
+        ? edges.map((edge, index) =>
+            createEdge.bind(this)({
+              cursor: edge.cursor ?? createCursor.bind(this)(edge.node, index).encode(),
+              ...edge,
+            }),
+          )
+        : nodes!.map((node, index) =>
+            createEdge.bind(this)({
+              node,
+              cursor: createCursor.bind(this)(node, index).encode(),
+            }),
+          );
 
     return createConnection.bind(this)({
-      edges,
+      edges: resolvedEdges,
       pageInfo: this.createPageInfo({
-        edges,
+        edges: resolvedEdges,
         totalEdges,
-        hasNextPage: hasNextPage ?? (totalEdges != null && totalEdges > edges.length),
+        hasNextPage: hasNextPage ?? (totalEdges != null && totalEdges > resolvedEdges.length),
         hasPreviousPage: hasPreviousPage ?? (this.afterCursor != null || this.beforeCursor != null),
       }),
     });
