Add @Pagination Decorator

[dpomerantz-jci]

Sorting

• I'm submitting a ...

  • [ ] bug report
  • [X] feature request
  • [ ] support request

• I confirm that I

  • [X] used the search to make sure that a similar issue hasn't already been submit

Expected Behavior

I would like to have a decorator which can be applied to controller methods which indicate that the result set is paginated. This would mean....

limit and page parameters can be passed into the method in the querystring, and then set to class fields. The parameter and field names could be over-written.

The results, which are normally an array, will have required and optional values, requestCount, list, responseCount, TotalCount, TotalPages.

Current Behavior

As far as I can tell, this is not available.

Possible Solution

Create a @Pagination attribute and support it.

Steps to Reproduce

Context (Environment)

Version of the library: 4.0.0-alpha.2 Version of NodeJS: 14.17.1

• Confirm you were using yarn not npm: [X]

Detailed Description

I would like to have a decorator which can be applied to controller methods which indicate that the result set is paginated. This would mean....

limit and page parameters can be passed into the method in the querystring, and then set to class fields. The parameter and field names could be over-written.

The results, which are normally an array, will have required and optional values, requestCount, list, responseCount, TotalCount, TotalPages.

Breaking change?

No.

[WoH]

I am not convinced that this is something tsoa should provide, iterating through a large set is use-case specific. Why is this something tsoa should provide over a solution in userland?

[dpomerantz-jci]

I would put this in the syntactical candy area of request. Users could roll their own, but I feel that pagination is such a frequently requested feature and is more often than not implemented in such a standard way, that it could be added to help users. I would use it. If you don't feel that it is appropriate, then users will have to continue to roll their own.

[mrattner]

Not every pagination scheme is the same; it's definitely use-case specific. To me it doesn't seem appropriate to add this feature to tsoa unless it's based on an OpenAPI standard, since that's what the other tsoa features are based on. However, since it's such a common thing to need in an API, tsoa's documentation could direct users to possible pagination strategies such as JSON:API's specification and its cursor pagination extension?