GraphQL Pagination - Core

Core module of GraphQL Pagination providing spec and ready to use implementations.

1. CursorPager specification
2. DataSource specification
3. dataSourcePager implementation backed by DataSource
4. dataloaderPagerWrapper pagination wrapper using dataloader
5. ArrayDataSource implementation as fixed array of data
6. OffsetDataSourceWrapper Offset pagination wrapper
7. GraphQL Type Defs

Check additional modules:

1. @graphql-pagination/sql-knex - SQL (Knex.js) DataSource

DataSourcePager

DataSource Pager implements CursorPager backed by a DataSource. It's up to you to either use built-in ArrayDataSource or implement your own.

Configuration:

1. dataSource (optional) - pass your datasource at pager creation or pass on resolver level via forwardResolver or backwardResolver.
2. typeName (optional) - name to generate GraphQL Pagination type defs like BookConnection, BookEdge.
3. cursor (optional) - custom implementation how to encode/decode cursor
4. validateForwardArgs (optional) - function (or array) to validate input args used by forward resolver
5. validateBackwardArgs (optional) - function (or array) to validate input args used by backward resolver
6. fetchTotalCountInResolver (optional) - if false then totalCount is not fetched as part of forward/backward resolvers but totalCount resolver in Connection object needs to be defined separately. Pager provides .resolvers field for it.
7. typeDefDirectives (optional) - directives added to generated type definitions.

See more details in DataSourcePager.ts.

Basic Example

const { ArrayDataSource, DataSourcePager, dataSourcePager } = require("@graphql-pagination/core");

// Create Array Data Source from array of books
const ds = new ArrayDataSource(books);

const pager = dataSourcePager({
    dataSource: ds,
    typeName: "Book",
});

// BookConnection is generated by DataSourcePager
const typeDefs = gql`
    type Book {
        id: ID!
        title: String
        author: String
    }
    type Query {
        booksAsc(first: Int = 10 after: String): BookConnection
        booksDesc(last: Int = 10 before: String): BookConnection
    }
`;

const resolvers = {
    Query: {
        booksAsc: (_, args) => pager.forwardResolver(args),
        booksDesc: (_, args) => pager.backwardResolver(args),
    },
};

Advanced Example - DataLoader Wrapper Pager & Context

const { ArrayDataSource, DataSourcePager, dataSourcePager } = require("@graphql-pagination/core");

// Create Array Data Source from array of books
const dataSource = new ArrayDataSource(books);

// BookConnection is generated by DataSourcePager
const typeDefs = gql`
    type Book {
        id: ID!
        title: String
        author: String
    }
    type Query {
        booksAsc(first: Int = 10 after: String): BookConnection
        booksDesc(last: Int = 10 before: String): BookConnection
    }
`;

const resolvers = {
    Query: {
        booksAsc: (_, args, ctx) => ctx.pager.forwardResolver(args),
        booksDesc: (_, args, ctx) => ctx.pager.backwardResolver(args),
    },
};

// https://www.apollographql.com/docs/apollo-server/api/standalone/#example
const server = new ApolloServer({ typeDefs, resolvers });
const standAloneServer = await startStandaloneServer(server, {
    context: async () => ({ pager: dataSourceLoaderPager({ dataSource }) }),    // create new pager with dataloader for every request
    listen: { port: 4000 },
});
console.log(`🚀  Server ready at ${url}`);

Offset Data Source Paging

If your DS / API provides offset pagination resp. slicing (start + size) and you want to use this pagination then it's supported as wrapper.

You need to create your DS like any other but expect that Wrapper will store in encoded cursor the index value and not any field from your data. Then afterId / beforeId values in your DS will be index (start) value.

Example

const { ArrayDataSource, dataSourcePager, OffsetDataSourceWrapper } = require("@graphql-pagination/core");

class ArrayOffsetDs extends ArrayDataSource {

   async after(offset, size, args) {
      // No field data comparison involved. It's just offset slicing
      return this.getNodes(args).then(data => data.slice(offset, offset + size));
   }

}

const dsOffset = new ArrayOffsetDs(books, "_NOT_USED_");
const pagerOffset = dataSourcePager({
   dataSource: new OffsetDataSourceWrapper(dsOffset),
   typeName: "Book",
});

Complete Example

See fully working examples/in-memory.

The complete example includes:

1. Input validation
2. Extra input args for data filtering
3. DataSource using Date type
4. OffsetDataSourceWrapper
5. Custom directives used in Type Objects