pageable

A Go library for REST API pagination. Supports offset-based and cursor-based pagination with generic responses. Zero dependencies.

Features

• Zero dependencies — only Go standard library
• Framework-agnostic — works with net/http, Gin, Echo, Chi, Fiber, or any framework
• Type-safe generics — Page[T] and CursorPage[T] for compile-time safety
• Offset & cursor pagination — choose what fits your use case
• Flexible sorting — ?sort=name,desc&sort=id,asc
• Sort safety — whitelist allowed sort fields to prevent SQL injection
• Clamping over errors — invalid inputs get sensible defaults, never errors
• SQL-ready helpers — Offset(), Limit(), OrderBy() for direct use in queries

Quick Example

func listUsers(w http.ResponseWriter, r *http.Request) {
    req := pageable.PageRequestFromQuery(r.URL.Query()).
        SortableFields("id", "name", "created_at").
        WithDefaultSort(pageable.Sort{Field: "id", Direction: pageable.ASC})

    users, total := queryUsers(req.Offset(), req.Limit(), req.OrderBy())

    page := pageable.NewPage(users, req, total)

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(page)
}

{
  "items": [
    {"id": 21, "name": "Alice"},
    {"id": 22, "name": "Bob"}
  ],
  "metadata": {
    "page": 2,
    "size": 20,
    "totalItems": 95,
    "totalPages": 5
  }
}

Requirements

Go 1.21+