`ApolloPagination` usage docs #262

Iron-Ham · 2024-02-09T22:21:36Z

This PR added ApolloPagination to the list of valid targets for the DocumentationGenerator command. I added the ApolloPagination package as a dependency of the project.

NOTE: I am receiving the following warning –

warning: 'apollo-ios-pagination': 'apollo-ios-pagination' dependency on 'https://github.com/apollographql/apollo-ios.git' conflicts with dependency on '/Users/zer0/Developer/OSS/apollo-ios-dev/apollo-ios' which has the same identity 'apollo-ios'. this will be escalated to an error in future versions of SwiftPM.

This PR also adds a new pagination entry in the sidebar & a short intro md.
For now, I've left the visibility of the pagination entry as false.

I wasn't able to get this running locally, so I have no clue what this would look like in the doc portal.

netlify · 2024-02-09T22:21:40Z

👷 Deploy request for eclectic-pie-88a2ba pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	`2581199`

AnthonyMDev

This is an awesome start! I've got a few minor suggestions and questions.

I also want to start a running list of things to be added to documentation (can be done in the future):

Example of Reverse/Bidirectional Pagination
Example of Offset based pagination
Example of using different queries for initial query vs additional pages

docs/source/pagination/introduction.mdx

Iron-Ham · 2024-02-13T17:36:53Z

Happy to address these – @AnthonyMDev do you have advice for running this locally, so I can see how the changes would present on the web? I wasn't able to get it running locally, which certainly made things a little tougher.

AnthonyMDev · 2024-02-13T18:41:53Z

Our docs deployment repo is actually public, so you can clone it, and then use the instructions here to run the docs locally.
https://github.com/apollographql/docs?tab=readme-ov-file#developing-a-single-docset

Iron-Ham · 2024-02-13T19:34:47Z

Our docs deployment repo is actually public, so you can clone it, and then use the instructions here to run the docs locally. https://github.com/apollographql/docs?tab=readme-ov-file#developing-a-single-docset

mvp

Iron-Ham · 2024-02-13T22:22:19Z

cc: @AnthonyMDev I've gone ahead and added 3 more pages & added a single example of an offset pager within the Introduction. However, in writing the offset docs, i recognized there are some improvements and conveniences afforded to cursor pagination that are not extended out to offset. I'll correct that shortly.

docs/source/pagination/introduction.mdx

docs/source/pagination/directional-pagers.mdx

docs/source/config.json

Iron-Ham · 2024-02-23T14:08:18Z

apollo-ios-pagination/Sources/ApolloPagination/GraphQLQueryPager+Convenience.swift

@@ -27,7 +27,7 @@ public extension GraphQLQueryPager {
    client: ApolloClientProtocol,
    watcherDispatchQueue: DispatchQueue = .main,
    initialQuery: InitialQuery,
-    pageResolver: @escaping (P, PaginationDirection) -> InitialQuery,
+    pageResolver: @escaping (P, PaginationDirection) -> InitialQuery?,


@AnthonyMDev I can pull this out of this PR if you prefer and into a second – but I noticed that the pageResolver wasn't expecting an Optional<InitialQuery> in the GraphQLQueryPager definitions, but was in the AsyncGraphQLQueryPager definitions.

Nah, that's fine!

AnthonyMDev

Wow, reading through these docs, this library is just so incredibly feature rich already! What an awesome job @Iron-Ham!

Couple of edits to add some more information and minor fixes!

docs/source/pagination/introduction.mdx

AnthonyMDev · 2024-02-23T18:01:53Z

docs/source/pagination/introduction.mdx

+    client: client,
+    initialQuery: initialQuery,
+    pageResolver: { page, paginationDirection in
+        // As we only want to support forward pagination, we can return `nil` for reverse pagination


For the convenience functions that only support single direction paging, can we just omit the pagination direction from the pageResolver closure signature? It should only be needed for bidirectional paging, right?

Discussed this on our call just now – but this can be an improvement for 0.2.x

We could do it by declaring ForwardPageInfo and ReversePageInfo protocols, and then declaring the convenience functions around those protocols.

docs/source/pagination/introduction.mdx

docs/source/pagination/custom-types.mdx

docs/source/pagination/directional-pagers.mdx

AnthonyMDev · 2024-02-23T18:17:20Z

docs/source/pagination/directional-pagers.mdx

+
+## Forward Pagination
+
+Forward pagination is the most common form of pagination. It is used to fetch the next `n` items in a list. We can use the convenience `make` functions to create a configured `GraphQLQueryPager`. While we have many options depending on our requirements -- whether we use one query or two, whether we want to use a cursor or an offset, whether we want to transform the results, etc. -- we will examine using a cursor with a single query.


Let's talk about my question related to omitting paginationDirection in single directional convenience functions. If we can go that route, then I have some suggestions to tweak this.

docs/source/pagination/multi-query.mdx

Co-authored-by: Anthony Miller <[email protected]>

AnthonyMDev · 2024-02-23T19:01:50Z

apollo-ios-pagination/Sources/ApolloPagination/AsyncGraphQLQueryPager.swift

@@ -237,6 +237,8 @@ public class AsyncGraphQLQueryPager<Model>: Publisher {
  /// Resets pagination state and cancels further updates from the pager.
  public func cancel() async {
    await pager.cancel()
+    _subject.send(completion: .finished)


Do we need to update unit tests for this? Can also be done in a separate PR later.

I think that'd be wise, yes.
As written, I think this would require us to re-init a new pager – in the same sense that cancelling a watcher stops it from being used again.

AnthonyMDev · 2024-02-23T19:09:59Z

docs/source/pagination/introduction.mdx

+
+## Cancelling ongoing requests
+
+The `GraphQLQueryPager` class provides a `cancel` method, which can be used to cancel any ongoing fetch operations as well as cease all subscriptions. Once cancelled, the pager's state is reset. Any subscriber that was subscribed to the pager will receive a termination signal, and will no longer receive updates. After calling the `cancel` method, you msut resubscribe to the pager in order to receive updates.


Suggested change

The `GraphQLQueryPager` class provides a `cancel` method, which can be used to cancel any ongoing fetch operations as well as cease all subscriptions. Once cancelled, the pager's state is reset. Any subscriber that was subscribed to the pager will receive a termination signal, and will no longer receive updates. After calling the `cancel` method, you msut resubscribe to the pager in order to receive updates.

The `GraphQLQueryPager` class provides a `cancel` method, which can be used to cancel any ongoing fetch operations as well as cease all subscriptions. Once cancelled, the pager's state is reset. Any subscriber that was subscribed to the pager will receive a completion signal, and will no longer receive updates. After calling the `cancel` method the pager is invalid. You will need to create a new pager in order to receive updates again.

14038690 usage docs (#262) git-subtree-dir: apollo-ios-pagination git-subtree-split: 1403869013cfbe8cdf565cec39744d24b447fba7

git-subtree-dir: apollo-ios-pagination git-subtree-mainline: bda25cd git-subtree-split: 1403869013cfbe8cdf565cec39744d24b447fba7

Iron-Ham requested a review from a team as a code owner February 9, 2024 22:21

Iron-Ham force-pushed the hs/generate-docc branch 2 times, most recently from 652cfb8 to 9162553 Compare February 10, 2024 03:04

Iron-Ham changed the title ~~Add ApolloPagination to the DocC generation project~~ Add ApolloPagination to DocC generation, generate short Introduction Feb 10, 2024

AnthonyMDev requested changes Feb 13, 2024

View reviewed changes

Iron-Ham changed the title ~~Add ApolloPagination to DocC generation, generate short Introduction~~ ApolloPagination usage docs Feb 13, 2024

Iron-Ham marked this pull request as draft February 13, 2024 21:19

Iron-Ham marked this pull request as ready for review February 13, 2024 22:21

This was referenced Feb 14, 2024

[ApolloPagination] Additional conveniences for offset pagination #267

Closed

[ApolloPagination] Remove convenience functions, improved Offset-pagination support #268

Merged

AnthonyMDev requested changes Feb 16, 2024

View reviewed changes

docs/source/pagination/introduction.mdx Outdated Show resolved Hide resolved

docs/source/pagination/introduction.mdx Outdated Show resolved Hide resolved

docs/source/pagination/directional-pagers.mdx Outdated Show resolved Hide resolved

docs/source/config.json Outdated Show resolved Hide resolved

Iron-Ham added 10 commits February 22, 2024 15:24

Add ApolloPagination to the DocC generation project

557bea7

A short intro guide to Apollo Pagination

4e776ea

Comments (1)

ede7488

Cleanup existing content

103aefc

Field => Property

1a1a273

Second page: Using custom response models

3bc1675

Third page: Directionality

8ba1d79

Multi-query pager

644649e

Offset

e7c1b00

One more

30529e8

Iron-Ham force-pushed the hs/generate-docc branch from c170b7e to 30529e8 Compare February 22, 2024 20:24

Iron-Ham added 3 commits February 22, 2024 15:25

Generated docs again

f1cae88

Touchup

0786446

Re-generate docs

fee7e30

Iron-Ham added 6 commits February 22, 2024 15:42

Update intro

bb153dd

Update Custom-Types

750183a

Move to Directional Pag

87f0f9e

Update directional

2cbab20

Update multi-query

d72e23c

Rename in sidebar

fb1fcff

Iron-Ham commented Feb 23, 2024

View reviewed changes

AnthonyMDev reviewed Feb 23, 2024

View reviewed changes

Iron-Ham and others added 11 commits February 23, 2024 13:54

Update cancel() function [breaking change]

0a56b1a

Update docs/source/pagination/introduction.mdx

167544b

Co-authored-by: Anthony Miller <[email protected]>

Update docs/source/pagination/introduction.mdx

f9c9d05

Co-authored-by: Anthony Miller <[email protected]>

Update docs/source/pagination/custom-types.mdx

5aee925

Co-authored-by: Anthony Miller <[email protected]>

Update docs/source/pagination/custom-types.mdx

e220678

Co-authored-by: Anthony Miller <[email protected]>

Update docs/source/pagination/custom-types.mdx

321bf95

Co-authored-by: Anthony Miller <[email protected]>

Update docs/source/pagination/directional-pagers.mdx

40a6414

Co-authored-by: Anthony Miller <[email protected]>

Update docs/source/pagination/multi-query.mdx

fe66eec

Co-authored-by: Anthony Miller <[email protected]>

Update docs/source/pagination/multi-query.mdx

bdc33be

Co-authored-by: Anthony Miller <[email protected]>

Update docs/source/pagination/multi-query.mdx

dc5fc9e

Co-authored-by: Anthony Miller <[email protected]>

Update cancel docs

c101fbf

AnthonyMDev reviewed Feb 23, 2024

View reviewed changes

Again

2581199

AnthonyMDev approved these changes Feb 23, 2024

View reviewed changes

AnthonyMDev merged commit 6e32e88 into apollographql:main Feb 23, 2024
14 checks passed

BobaFetters pushed a commit that referenced this pull request Feb 23, 2024

usage docs (#262)

bda25cd

BobaFetters pushed a commit to apollographql/apollo-ios-pagination that referenced this pull request Feb 23, 2024

usage docs (apollographql/apollo-ios-dev#262)

1403869

BobaFetters pushed a commit that referenced this pull request Feb 23, 2024

Squashed 'apollo-ios-pagination/' changes from c762dcf0..14038690

f374b51

14038690 usage docs (#262) git-subtree-dir: apollo-ios-pagination git-subtree-split: 1403869013cfbe8cdf565cec39744d24b447fba7

BobaFetters pushed a commit that referenced this pull request Feb 23, 2024

split: apollo-ios-pagination - PR #262 - usage docs

fe41dcd

git-subtree-dir: apollo-ios-pagination git-subtree-mainline: bda25cd git-subtree-split: 1403869013cfbe8cdf565cec39744d24b447fba7

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`ApolloPagination` usage docs #262

`ApolloPagination` usage docs #262

Iron-Ham commented Feb 9, 2024 •

edited

Loading

netlify bot commented Feb 9, 2024 •

edited

Loading

AnthonyMDev left a comment •

edited

Loading

Iron-Ham commented Feb 13, 2024

AnthonyMDev commented Feb 13, 2024

Iron-Ham commented Feb 13, 2024

Iron-Ham commented Feb 13, 2024 •

edited

Loading

Iron-Ham Feb 23, 2024

AnthonyMDev Feb 23, 2024

AnthonyMDev left a comment

AnthonyMDev Feb 23, 2024

Iron-Ham Feb 23, 2024

AnthonyMDev Feb 23, 2024

AnthonyMDev Feb 23, 2024

Iron-Ham Feb 23, 2024

AnthonyMDev Feb 23, 2024


		## Forward Pagination

		Forward pagination is the most common form of pagination. It is used to fetch the next `n` items in a list. We can use the convenience `make` functions to create a configured `GraphQLQueryPager`. While we have many options depending on our requirements -- whether we use one query or two, whether we want to use a cursor or an offset, whether we want to transform the results, etc. -- we will examine using a cursor with a single query.


		## Cancelling ongoing requests

		The `GraphQLQueryPager` class provides a `cancel` method, which can be used to cancel any ongoing fetch operations as well as cease all subscriptions. Once cancelled, the pager's state is reset. Any subscriber that was subscribed to the pager will receive a termination signal, and will no longer receive updates. After calling the `cancel` method, you msut resubscribe to the pager in order to receive updates.

ApolloPagination usage docs #262

ApolloPagination usage docs #262

Conversation

Iron-Ham commented Feb 9, 2024 • edited Loading

netlify bot commented Feb 9, 2024 • edited Loading

👷 Deploy request for eclectic-pie-88a2ba pending review.

AnthonyMDev left a comment • edited Loading

Choose a reason for hiding this comment

Iron-Ham commented Feb 13, 2024

AnthonyMDev commented Feb 13, 2024

Iron-Ham commented Feb 13, 2024

Iron-Ham commented Feb 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AnthonyMDev left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

`ApolloPagination` usage docs #262

`ApolloPagination` usage docs #262

Iron-Ham commented Feb 9, 2024 •

edited

Loading

netlify bot commented Feb 9, 2024 •

edited

Loading

AnthonyMDev left a comment •

edited

Loading

Iron-Ham commented Feb 13, 2024 •

edited

Loading