Support for easier customization of the JsonApiPaginateExpressionVisitor

[judgeaxl]

Is your feature request related to a problem? Please describe.

When the JSON:API server don't use the current naming convention for pagination, one currently has to override or re-implement JsonApiPaginateExpressionVisitor whereas for most cases I can think of, a setting to alter the query parameter names would suffice.

Describe the solution you'd like

I suggest adding an options block to the JsonApiPaginateExpressionVisitor constructor that can take the alternate query parameter strings as inputs, e.g. default to page[size]= and page[number]= but support easy overrides. The server I'm interacting with uses page[limit] and page[offset] as an example. I believe this is since JSON:API doesn't prescribe the exact terms to use, only the general idea.

Describe alternatives you've considered

The most obvious alternative to passing configuration is to override JsonApiPaginateExpressionVisitor. The possible benefit over parameterizing is that one can decide to support or not specific pagination modes without resorting to special values for those options. This is probably the biggest motivation for not implementing query parameter naming configuration.

A motivation against overriding would be that there are some small intricacies in how you have to use encodeURIComponent for the result to work correctly, and there's a benefit to not having to solve that problem more than once.

Additional context

N/A

[dpimonov]

Thanks for the perfect description and motivation. The solution with overrides and splitting pagination strategies was done for a reason. Spec reserves only the page parameter which means pagination can be done also like page=1 with a default page size defined on the server. Info about such configs may be provided through metadata which may be absolutely custom. That was a main reason for introducing overrides. So the part which is mandatory is separated from dynamic one. This dynamic part is unpredictable basically. Besides there are ideas to implement lazy iteration over paginated collection where information about total items will become really important.

However if we follow your suggestions and introduce options + default implementation for pagination visitor it will solve many issues. One who has specific pagination strategies (like one with JsonApiNetPaginateExpressionVisitor where some info provided throught the metadata) can still implement one. I like it.

[dpimonov]

Library now provides default pagination visitor implementation in v2.1.0 which is used out of the box and includes limit-offset strategy by default as well as some others.

Parameters will not be provided because of many variations of how pagination can be implemented by servers and they are not always present. Possible cases: page[offset]=10&page[limit]=10, page=1,10, page=2-10 and this is only a start. Because of that - extending base class will stay as a main way to override behaviour but now it is much easier and not forces to implement visitor from scratch. Just override one concrete method for a strategy used by a server.