Documentation
¶
Overview ¶
Package page validates offset pagination parameters against the policy of an endpoint.
A client may send a page number and a size. The endpoint decides the default size, the largest size and, optionally, the largest offset its storage serves. Make combines the two into a Page:
current, err := page.Make(
page.Params{Number: number, Size: size},
page.Config{DefaultSize: 20, MaxSize: 100},
)
if err != nil {
return err
}
articles, err := store.List(ctx, current.Limit(), current.Offset())
Params holds pointers: nil means the client did not send the value and the default applies, while a pointer to zero is an explicit invalid value. Page numbers start at 1.
Errors ¶
Make returns a *Error with an ErrorKind, the rejected Value and the Limit it breaks. An offset limit is reported in page numbers, the requested page and the last page allowed, because the page number is what the client controls.
ErrorInvalidDefaultSize, ErrorInvalidMaxSize and ErrorDefaultSizeExceedsMaximum describe a wrong Config. They are server bugs, not client input, and the problem package answers them with status 500.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
DefaultSize uint64
MaxSize uint64
// MaxOffset is an optional downstream offset limit. Zero disables it.
MaxOffset uint64
}
Config defines the pagination policy chosen by an application endpoint.
Example (MaxOffset) ¶
package main
import (
"fmt"
"github.com/uchaloop/httpx/page"
)
func main() {
// Storage that skips at most 1000 rows serves pages up to 51 of size 20.
number := uint64(60)
_, err := page.Make(
page.Params{Number: &number},
page.Config{DefaultSize: 20, MaxSize: 100, MaxOffset: 1000},
)
fmt.Println(err)
}
Output: page number 60 exceeds maximum 51 allowed by the offset limit
type Error ¶
Error describes an invalid pagination policy or parameter. Value is the rejected value and Limit the bound it violates. For offset errors both are page numbers: the requested page and the largest page allowed.
Example ¶
package main
import (
"errors"
"fmt"
"github.com/uchaloop/httpx/page"
)
func main() {
size := uint64(500)
_, err := page.Make(page.Params{Size: &size}, page.Config{DefaultSize: 10, MaxSize: 100})
if pageErr, ok := errors.AsType[*page.Error](err); ok && pageErr.Kind == page.ErrorSizeExceedsMaximum {
fmt.Println(pageErr.Value, "is over", pageErr.Limit)
}
}
Output: 500 is over 100
type Page ¶
type Page struct {
// contains filtered or unexported fields
}
Page contains validated pagination values.
func Make ¶
Make validates params against cfg and calculates a page.
Example ¶
package main
import (
"fmt"
"log"
"github.com/uchaloop/httpx/page"
)
func main() {
number, size := uint64(3), uint64(20)
current, err := page.Make(
page.Params{Number: &number, Size: &size},
page.Config{DefaultSize: 10, MaxSize: 100},
)
if err != nil {
log.Fatal(err)
}
fmt.Println(current.Number(), current.Size(), current.Offset())
}
Output: 3 20 40
Example (Defaults) ¶
package main
import (
"fmt"
"log"
"github.com/uchaloop/httpx/page"
)
func main() {
// A client that sends nothing gets the first page of the default size.
current, err := page.Make(page.Params{}, page.Config{DefaultSize: 10, MaxSize: 100})
if err != nil {
log.Fatal(err)
}
fmt.Println(current.Number(), current.Size(), current.Offset())
}
Output: 1 10 0
Source Files