Skip to content

Commit

Permalink
chore: tidy up docs and npm files (#4)
Browse files Browse the repository at this point in the history
  • Loading branch information
luke88jones authored Jan 12, 2024
1 parent e9c3ac2 commit 00ebacc
Show file tree
Hide file tree
Showing 4 changed files with 16 additions and 12 deletions.
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -128,3 +128,5 @@ dist
.yarn/build-state.yml
.yarn/install-state.gz
.pnp.*

.DS_Store
3 changes: 3 additions & 0 deletions .npmignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
coverage/
examples/
**/*.test.js
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This library provides a GQL directive to more easily implement pagination based

## What / why?

Cursor-based pagination, the style implemented by the Relay specific, involves wrapping a dataset in a `connection` object which presents your dataset items as a collection of `edges`. When making your query you provide a `first` (page size) value and an optional `after` value. `first` sets the number of items to return and `after` sets the start point for item selection. For example, given 100 records with sequential IDs, your initial query could include a `first` value of 10 and the second query would include 10 as the `after` value (the id of the last item in the first page).
Cursor-based pagination, the style implemented by the Relay specific, involves wrapping a dataset in a `connection` object which presents your dataset items as a collection of `edges`. When making your query you provide a `first` (page size) value and an optional `after` value. `first` sets the number of items to return and `after` sets the start point for item selection. For example, given 100 records with sequential IDs, your initial query could include a `first` value of 10 and the second query would include 10 as the `after` value (the `id` of the last item on the first page).

To support this pattern in GQL we need to

Expand All @@ -18,11 +18,11 @@ This library aims to reduce this overhead by providing a GQL directive that allo
## Install

```
yarn add relay-pagination
yarn add relay-pagination-directive
# or
npm i relay-pagination
npm i relay-pagination-directive
# or
pnpm add relay-pagination
pnpm add relay-pagination-directive
```

## Usage
Expand All @@ -34,7 +34,7 @@ Annotate any types you wish to paginate with the `@connection` directive. Apply

const Fastify = require("fastify");
const mercurius = require("..");
const { connectionDirective } = require('relay-pagination')
const { connectionDirective } = require('relay-pagination-directive')

const app = Fastify();

Expand Down Expand Up @@ -187,7 +187,7 @@ const resolvers = {

### Custom Connection/Edge properties

Often it is desirable to add additional properties to our connection and/or edge objects. This is possible using the `typeOptionsMap` config object. This is a mapping of the base type name to the configuration detail. For example if we wanted to add a `totalCount` property.
Often it is desirable to add additional properties to our connection and/or edge objects. This is possible using the `typeOptionsMap` config object. This is a mapping of the base type name to the configuration detail. For example, if we wanted to add a `totalCount` property.

```js
...
Expand Down Expand Up @@ -436,12 +436,12 @@ An object with the following properties

## `hasNextPage` Strategies

The intention of the `pageInfo.hasNextPage` property is to indicate to the consuming application whether it needs to query for subsequent pages of results. By default, this library will set this value to true if the data set returned from your resolver has the same length as the `first` argument. Depending on your use case this could be enough for you. For example, in a scenario where you're using pagination to load a large dataset and your UI does not display page numbers having another page is not a problem. However if your pagination is enabling some `Next` style UI button this would be bad as the user could click next and receive a blank page.
The intention of the `pageInfo.hasNextPage` property is to indicate to the consuming application whether it needs to query for subsequent pages of results. By default, this library will set this value to true if the data set returned from your resolver has the same length as the `first` argument. Depending on your use case this could be enough for you. For example, in a scenario where you're using pagination to load a large dataset and your UI does not display page numbers having another page is not a problem. However, if your pagination is enabling some `Next` style UI button this would be bad as the user could click next and receive a blank page.

These are two additional strategies that can be used to generate your own `hasNextPage` value and provide it in the resolver response.

- The simplest and lowest overhead option is to simply add 1 to the received `first` value e.g. if 100 items are requested, query your DB for 101. You'll then known if 101 records are returned that there is at least 1 more page.
- A window function can be added to you SQL query to retrieve the total (remaining) records found by a query. Most DB products support window functions and with a simple count, we can retrieve the total number of records. You can then infer that if the total remaining count is greater than the request page size that there are more pages.
- The simplest and lowest overhead option is to simply add 1 to the received `first` value e.g. if 100 items are requested, query your DB for 101. You'll then know if 101 records are returned that there is at least 1 more page.
- A window function can be added to your SQL query to retrieve the total (remaining) records found by a query. Most DB products support window functions and with a simple count, we can retrieve the total number of records. You can then infer that if the total remaining count is greater than the requested page size there are more pages.

You can view full examples of all three strategies in [this example](./examples/hasNextPageStrategies.js)

Expand Down
5 changes: 2 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,8 @@
"type": "module",
"scripts": {
"lint": "eslint .",
"test": "node --test src/",
"test": "c8 node --test src/",
"test:watch": "c8 node --test --watch src/",
"coverage": "c8 npm run test",
"prepare": "husky install"
},
"repository": {
Expand All @@ -22,7 +21,7 @@
"pagination"
],
"author": "Luke Jones",
"license": "ISC",
"license": "MIT",
"bugs": {
"url": "https://github.com/nearform/relay-pagination-directive/issues"
},
Expand Down

0 comments on commit 00ebacc

Please sign in to comment.