feat(v0.2): seek-predicate builder, signed cursors, net/http + GraphQL helpers, Postgres example

[hpower2]

v0.2 — the seek builder + wire-format helpers

Implements five v0.2 "good first issues" for the cursor pagination library. All
work stays in the dependency-free core module (stdlib only); no sub-modules.

Closes

• Closes Two-column seek-predicate builder + golden SQL tests #1 — Two-column seek-predicate builder + golden SQL tests
• Closes HMAC-signed cursor option #2 — HMAC-signed cursor option
• Closes net/http query-param helper with limit clamping #3 — net/http query-param helper with limit clamping
• Closes GraphQL pageInfo adapter #4 — GraphQL pageInfo adapter
• Closes Example: REST endpoint paginating Postgres on (created_at, id) #5 — Example: REST endpoint paginating Postgres on (created_at, id)

How each was implemented & tested

#1 Seek-predicate builder (seek.go) — SeekKey/Column/Direction/Dialect
emit the row-wise seek WHERE and matching ORDER BY from a typed composite key
with per-column ASC/DESC. Expands to the portable lexicographic form
(a > ?) OR (a = ? AND b > ?); supports database/sql (?) and pgx ($N)
placeholders; backward paging flips effective direction and comparison operators.
Golden tests assert exact SQL strings for forward/backward × ASC/DESC.

#2 HMAC-signed cursors (sign.go) — SignedCodec signs tokens as
base64url(payload).base64url(hmac-sha256); Decode verifies via constant-time
hmac.Equal and returns ErrTampered on forgery/wrong key. Tests: round-trip,
payload/signature tamper, wrong-key rejection, malformed input, key-copy isolation.

#3 net/http param helper (httpparam.go) — ParseParams parses ?cursor=&limit=
and clamps the limit (default/max caps, safe zero-value config). httptest-based
tests cover over-cap, missing, zero, negative, non-numeric, and custom param names.

#4 GraphQL adapter (graphql.go) — Connect builds a Relay Connection
(edges + pageInfo with startCursor/endCursor/hasNextPage/hasPreviousPage),
spec-compliant JSON tags, pure structs. Tests cover basic/empty/single/multi + JSON shape.

#5 Example (example_postgres_test.go) — runnable Example_postgresREST uses the
seek builder to paginate a (created_at, id)-sorted table behind an httptest handler
against an in-memory fake (no live DB), walks three pages, and prints the exact pgx SQL.

Verification (core module)

gofmt -l .   -> (empty)
go vet ./... -> ok
go test -race ./... -> ok  github.com/hpower2/cursor

CI keeps the Go 1.22 + 1.23 matrix and adds a "go mod tidy is clean" check.

🤖 Generated with Claude Code