Add Pagination classes to ODM

[alcaeus]

Q	A
Type	feature
BC Break	no
Fixed issues

Summary

This PR introduces four new paginator classes. We introduce two styles of paginator: offset-based and cursor-based. Both paginator styles come in flavours for aggregation pipeline and queries.

Offset-based pagination

Offset-based paginators take a page number and number of items per page (defaults to 24), along with a builder for aggregation or queries. It is Countable and returns the number of pages when counted. It provides an iterator for the current page. To accomplish this, it uses the count operation for queries, and $numDocuments for aggregation pipeline. When fetching items, it inserts the correct skip and limit options/stages.

Cursor-based pagination

Cursor-based pagination takes an ID where to continue paginating, the number of items per page, and an optional field name for the cursoring field (an ObjectId value in the _id field is usually a good choice). Together with the builder for aggregation or queries you can iterate over the items of the current "page". Iterating the paginator multiple times always returns the same items. You are responsible for extracting the ID of the last item, which is used when creating the paginator for the next page.

Todo

• Write documentation
• Add API to get next page from a cursor-based paginator?

[GromNaN]

You decided not using the $facet stage, as done in Api Platform.

[GromNaN]

What's the difference between hydrate(null) and hydrate(false) used in the query paginators?

[alcaeus]

The type, probably nothing else. We should eventually have a string|false type to control this.

[GromNaN]

This is immediately forgetting the exact number of pages. I think it would be better to make this value accessible with a method such as getNumberOfResults().

[alcaeus]

We can add something like this. Since we're discussing this, how do you feel about the paginator count being the number of pages? I felt that made more sense than returning the number of results (or worse, the number of items on the current page). If we don't want to change the Countable behaviour, I would use something like countResults (or similar) and use that to return the number of results, storing them in a private property as well.