Repository navigation
Expand file tree
/
Copy pathpagination.go
More file actions
140 lines (119 loc) · 5.41 KB
/
Copy pathpagination.go
File metadata and controls
140 lines (119 loc) · 5.41 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
package restapi
// OffsetPaginationRequest is the offset/limit form of a pagination request,
// suitable for binding from query parameters with Gin.
//
// Offset is optional: omitting the `offset` query parameter binds to 0,
// which means the first page. Supplying `offset=0` explicitly is also
// accepted. The `binding:"gte=0"` tag (without `required`) is what makes
// this work — Gin's `required` treats the integer zero value as missing.
type OffsetPaginationRequest struct {
// Limit is the maximum number of items to return. Must be positive.
Limit int `json:"limit" form:"limit" binding:"required,gt=0" example:"10"`
// Offset is the number of items to skip. It is optional and defaults
// to 0 when the `offset` query parameter is absent. Must be
// non-negative.
Offset int `json:"offset" form:"offset" binding:"gte=0" example:"100"`
}
// Validate returns [ErrInvalidPaginationLimit] if Limit is non-positive, or
// [ErrInvalidPaginationOffset] if Offset is negative. It is the non-Gin
// defense-in-depth path for callers that do not rely on Gin's binding
// validator.
func (r *OffsetPaginationRequest) Validate() error {
if r.Limit <= 0 {
return ErrInvalidPaginationLimit
}
if r.Offset < 0 {
return ErrInvalidPaginationOffset
}
return nil
}
// Response returns a matching [OffsetPaginationResponse] carrying r.Limit,
// r.Offset, and the supplied total.
func (r *OffsetPaginationRequest) Response(total int) *OffsetPaginationResponse {
return &OffsetPaginationResponse{Limit: r.Limit, Offset: r.Offset, Total: total}
}
// OffsetPaginationResponse is the matching response shape for
// [OffsetPaginationRequest].
type OffsetPaginationResponse struct {
// Limit echoes the request's Limit.
Limit int `json:"limit" example:"10"`
// Offset echoes the request's Offset.
Offset int `json:"offset" example:"100"`
// Total is the total number of items available across all pages.
Total int `json:"total" example:"1000"`
}
// PagePaginationRequest is the page-number/page-size form of a pagination
// request, suitable for binding from query parameters with Gin.
//
// PageNumber is optional: omitting the `pageNumber` query parameter binds
// to 0 (the first page). The `binding:"gte=0"` tag (without `required`)
// is what makes this work — Gin's `required` treats the integer zero
// value as missing.
type PagePaginationRequest struct {
// PageSize is the maximum number of items per page. Must be positive.
PageSize int64 `json:"pageSize" form:"pageSize" binding:"required,gt=0" example:"10"`
// PageNumber is the zero-based page index. It is optional and defaults
// to 0 when the `pageNumber` query parameter is absent. Must be
// non-negative.
PageNumber int64 `json:"pageNumber" form:"pageNumber" binding:"gte=0" example:"1"`
}
// Validate returns [ErrInvalidPaginationPageSize] if PageSize is non-positive,
// or [ErrInvalidPaginationPageNumber] if PageNumber is negative.
func (r *PagePaginationRequest) Validate() error {
if r.PageSize <= 0 {
return ErrInvalidPaginationPageSize
}
if r.PageNumber < 0 {
return ErrInvalidPaginationPageNumber
}
return nil
}
// Response returns a matching [PagePaginationResponse] carrying r.PageSize,
// r.PageNumber, and the supplied totalPages.
func (r *PagePaginationRequest) Response(totalPages int64) *PagePaginationResponse {
return &PagePaginationResponse{PageSize: r.PageSize, PageNumber: r.PageNumber, TotalPages: totalPages}
}
// PagePaginationResponse is the matching response shape for
// [PagePaginationRequest].
type PagePaginationResponse struct {
// PageSize echoes the request's PageSize.
PageSize int64 `json:"pageSize" example:"10"`
// PageNumber echoes the request's PageNumber.
PageNumber int64 `json:"pageNumber" example:"1"`
// TotalPages is the total number of pages available.
TotalPages int64 `json:"totalPages" example:"1000"`
}
// CursorPaginationRequest is the cursor/limit form of a pagination request,
// suitable for binding from query parameters with Gin. An empty Cursor is a
// legitimate first-page request.
type CursorPaginationRequest struct {
// Cursor is an opaque token that identifies the starting point of the
// page. An empty string requests the first page.
Cursor string `json:"cursor" form:"cursor" example:"eyJpZCI6IjEyMzU1In0="`
// Limit is the maximum number of items to return. Must be positive.
Limit int `json:"limit" form:"limit" binding:"required,gt=0" example:"10"`
}
// Validate returns [ErrInvalidPaginationLimit] if Limit is non-positive.
func (r *CursorPaginationRequest) Validate() error {
if r.Limit <= 0 {
return ErrInvalidPaginationLimit
}
return nil
}
// Response returns a matching [CursorPaginationResponse] with the supplied
// next/previous cursors and the request's Limit.
func (r *CursorPaginationRequest) Response(nextCursor, prevCursor string) *CursorPaginationResponse {
return &CursorPaginationResponse{NextCursor: nextCursor, PrevCursor: prevCursor, Limit: r.Limit}
}
// CursorPaginationResponse is the matching response shape for
// [CursorPaginationRequest].
type CursorPaginationResponse struct {
// NextCursor is the opaque token that identifies the next page. Empty
// when no next page exists.
NextCursor string `json:"nextCursor" example:"eyJpZCI6IjEyMzU2In0="`
// PrevCursor is the opaque token that identifies the previous page.
// Empty when no previous page exists.
PrevCursor string `json:"prevCursor" example:"eyJpZCI6IjEyMzU1In0="`
// Limit echoes the request's Limit.
Limit int `json:"limit" example:"10"`
}