Add filtering to the pagination helper

[displague]

The current ListOptions support pagination fields (page, per_page, etc). When these fields are omitted, all pages are walked and the results are combined as though one request was made.

When fetching all devices, the user may intend to filter the results afterward, with an upper limit of matches in mind. It may be beneficial to filter from the stream of results and stop the pagination early when the expected or desired result count is met.

"I want the first device found with hostname abc123"
"I want any three devices that are in a failed state"

Can we improve ListOptions with a filter and count parameter?
Can we do this without needing a different ListOptions for every type supported by Packngo?

For example:

client.Devices.List(&packngo.ListOptions{Filter: func(d *packngo.Device) bool {
  var found bool
  if d.hostname == "abc123" { found = true }
  return found
}, FilterCount: 1})

One problem with this approach is that the Filter function parameter would need to accept interface parameters so that a single ListOptions could continue to work for all List functions.

It may also be beneficial to offer a way to use different filters and collect these results in different slices or channels (which may be the most idiomatic approach). In this way, a single expensive query of all devices could be used to build several feeds for the work to follow. When all of the buckets are filled, the paginated walk could stop.

Arguably, this level of support is beyond the scope of the pagination helper and one should merely not use the unpaginated helper in these cases.

[displague]

One problem with this approach is that the Filter function parameter would need to accept interface parameters so that a single ListOptions could continue to work for all List functions.

Another approach would be to make an interface for GetOptions, each resource would have a type that implements (mostly through embedding GetOptions) this interface. Each resource specific type could then provide their own Filter function in that type.