Add example for cursor based pagination (#45)

* Add example for cursor based pagination

* Add link in main readme

* Moved to different directory, renamed example and simplified

* Update package-lock.json

---------

Co-authored-by: Roy Derks <[email protected]>

Author: royderks

README.md

@@ -83,6 +83,14 @@ These are available in `/sequence`:
 - `/transformsInMaterializer` shows how connecting two subgraphs can invoke transformations in between. For example, the `city` of a customer can be fed into a `weather` that takes `lat,lon` by calling some geocoding in the sequence
 - `/useOfJSON` shows how, in long sequences, a new type does not have to created for every step--treat everything as JSON up to the last step, and your type system stays clean.
 
+## @dbquery
+
+View the documentation for the [`@dbquery` custom directive](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=directives-directive-dbquery) in the documentation.
+
+Uses a database filled with mock data.
+
+- `/pagination` shows how to implement connection model pagination for a database.
+
 ## protection
 
 For more information on protecting your API, [see our documentation](https://stepzen.com/docs/access-control).

dbquery/pagination/README.md

@@ -0,0 +1,42 @@
+# Pagination with `@dbquery`
+
+This snippet shows how `@dbquery` fields are configured to support pagination.
+
+## Getting Started
+
+[Install](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=setting-up-your-environment) the StepZen command line interface.
+
+To run these examples,
+
+- `git clone` this repo
+- Change to the right working directory.
+- run `stepzen deploy`
+
+This example uses a demo database filled with mock data, you can inspect the `config.yaml` file to find the credentials for this database.
+
+
+## GraphQL pagination
+
+StepZen supports pagination through the standard [GraphQL Cursor Connection Specification](https://relay.dev/graphql/connections.htm).
+
+This allows clients consuming a StepZen GraphQL endpoint to page through resultsmregardless of the originating backend type (e.g. GraphQL endpoint, database, REST API).
+
+For the `@dbquery` directive, StepZen supports a connection based model for pagination out of the box.
+
+This snippet demonstrates the typical `@dbquery` response and directive configuration for pagination.
+
+In StepZen, Query fields that return a connection type must have two field arguments,
+
+- `first` which specifies the number of nodes to fetch
+- `after` which is an opaque cursor.
+
+## Using paginated fields
+
+The easiest way to use paginated fields is with a GraphQL operation that has variables for the arguments `first` and `after`. Examples
+are show in `requests.graphql`.
+
+To retrieve the first page of a result, the operation is called with `after` omitted or set to the empty string (`""`), and `first` is set to the number of results to return in a page.
+
+Subsequent pages can then be retrieved by setting `after` to the value of `endCursor` from `pageInfo` from the previous request. `first` should be set to the value used in the first request.
+
+This is continued until `hasNextPage` is `false`.

dbquery/pagination/api.graphql

@@ -0,0 +1,51 @@
+# This example shows how @dbquery is configured for pagination.
+#
+# @dbquery supports connection based pagination out of the box by
+# mapping database responses to a consistent standard
+# GraphQL pagination approach, specifically
+# GraphQL Cursor Connections Specification
+# https://relay.dev/graphql/connections.htm
+#
+#
+
+"""
+Sample customer type.
+"""
+type Customer {
+  id: ID!
+  name: String
+  email: String
+}
+
+"""
+`CustomerConnection` is the connection type for `Customer` pagination.
+In StepZen, a field returning a connection type must have arguments
+`first` (number of nodes to fetch) and `after` (opaque cursor indicating
+the starting point).
+"""
+type CustomerConnection {
+  edges: [CustomerEdge]
+  pageInfo: PageInfo!
+}
+
+"""
+`CustomerEdge` provides access to the node and its cursor.
+"""
+type CustomerEdge {
+  node: Customer
+  cursor: String
+}
+
+type Query {
+  """
+  `customers` pages through mock `Customer` objects in a demo PostgreSQL database.
+  The data is exposed using standard GraphQL pagination using the connection model.
+  """
+  customers(first: Int! = 10, after: String! = ""): CustomerConnection
+    @dbquery(
+      type: "postgresql"
+      table: "customer"
+      schema: "public"
+      configuration: "postgresql_config"
+    )
+}

dbquery/pagination/config.yaml

@@ -0,0 +1,4 @@
+configurationset:
+  - configuration:
+      name: postgresql_config
+      uri: postgresql://postgresql.introspection.stepzen.net/introspection?user=testUserIntrospection&password=HurricaneStartingSample1934

dbquery/pagination/index.graphql

@@ -0,0 +1,3 @@
+schema @sdl(files: ["api.graphql"]) {
+  query: Query
+}

dbquery/pagination/requests.graphql

@@ -0,0 +1,15 @@
+# Page through customers from a database connection based pagination
+query CustomersConnectionBased($first: Int!, $after: String = "") {    
+  customers(first: $first, after: $after) {
+    edges {
+      node {
+        id
+        name
+      }
+    }
+    pageInfo {
+      endCursor
+      hasNextPage
+    }
+  }
+}

dbquery/pagination/stepzen.config.json

@@ -0,0 +1,3 @@
+{
+  "endpoint": "api/miscellaneous"
+}

dbquery/pagination/tests/Test.js

@@ -0,0 +1,83 @@
+const fs = require("fs");
+const path = require("node:path");
+const {
+  deployAndRun,
+  authTypes,
+  getTestDescription,
+} = require("../../../tests/gqltest.js");
+
+testDescription = getTestDescription("snippets", __dirname);
+
+const requestsFile = path.join(path.dirname(__dirname), "requests.graphql");
+const requests = fs.readFileSync(requestsFile, "utf8").toString();
+
+describe(testDescription, function () {
+  const CURSOR = "eyJjIjoiTDpRdWVyeTpjdXN0b21lcnMiLCJvIjoxfQ=="
+
+  const tests = [
+    {
+      label: "first set of results",
+      query: requests,
+      operationName: "CustomersConnectionBased",
+      variables: { 
+        first: 2 
+      },
+      expected: {
+        customers: {
+          edges: [
+            { 
+              node: { 
+                id: "1", 
+                name: "Lucas Bill                                        " 
+              } 
+            },
+            { 
+              node: { 
+                id: "2", 
+                name: "Mandy Jones                                       " 
+              } 
+            }
+          ],
+          pageInfo: {
+            hasNextPage: true,
+            endCursor: CURSOR
+          }
+        }
+      },
+      authType: authTypes.adminKey,
+    },
+    {
+      label: "next set of results",
+      query: requests,
+      operationName: "CustomersConnectionBased",
+      variables: {
+        first: 2,
+        after: CURSOR
+      },
+      expected: {
+        customers: {
+          edges: [
+            {
+              node: {
+                id: "3",
+                name: "Salim Ali                                         "
+              }
+            },
+            {
+              node: {
+                id: "4",
+                name: "Jane Xiu                                          "
+              }
+            }
+          ],
+          pageInfo: {
+            endCursor: "eyJjIjoiTDpRdWVyeTpjdXN0b21lcnMiLCJvIjozfQ==",
+            hasNextPage: true
+          }
+        }
+      },
+      authType: authTypes.adminKey,
+    },
+  ];
+  return deployAndRun(__dirname, tests);
+});