Pagination Error Codes

Purpose

Defines and registers all stable error codes for the @suaveplan/pagination package using defineCodes from @suaveplan/error. Every error thrown by @suaveplan/pagination carries one of these codes, enabling downstream consumers — loggers, HTTP problem-detail responders, retry wrappers — to classify failures without string-matching against messages.

Features

All codes grouped under the PAGINATION namespace (e.g. PAGINATION.INVALID_CURSOR)
Registered once at module load via a side-effect import in src/index.ts
Exports the PaginationCode union type for exhaustive switch discrimination
Seven stable codes covering every failure mode: invalid cursor, page, limit, keyset cursor, page token, sort config, and aborted iteration

Usage: Basic Example

import { PAGINATION_CODES, type PaginationCode } from "@suaveplan/pagination/errors";

// Use code constants in switch statements
function handlePaginationError(code: PaginationCode) {
  switch (code) {
    case PAGINATION_CODES.INVALID_CURSOR:
      return "The provided cursor is malformed or expired.";
    case PAGINATION_CODES.INVALID_PAGE:
      return "Page number must be ≥ 1.";
    case PAGINATION_CODES.ABORTED:
      return "Pagination was cancelled by the caller.";
    default:
      return "Unknown pagination error.";
  }
}

Usage: Advanced Example

import { PaginationError } from "@suaveplan/pagination/errors";
import { PAGINATION_CODES } from "@suaveplan/pagination/errors";

// Catch and discriminate programmatically
try {
  const page = await fetchAfter(adapter, request, { signal });
} catch (err) {
  if (err instanceof PaginationError) {
    if (err.code === PAGINATION_CODES.ABORTED) {
      // User cancelled — not a real error
      return null;
    }
    if (err.code === PAGINATION_CODES.INVALID_CURSOR) {
      // Stale cursor from a previous session — restart from page 1
      return fetchFirstPage(adapter, request);
    }
    throw err;
  }
}

API Reference

`PAGINATION_CODES`

Record of stable error code strings produced by defineCodes("PAGINATION", [...]).

Key	Value
`INVALID_CURSOR`	`"PAGINATION.INVALID_CURSOR"`
`INVALID_PAGE`	`"PAGINATION.INVALID_PAGE"`
`INVALID_LIMIT`	`"PAGINATION.INVALID_LIMIT"`
`INVALID_KEYSET_CURSOR`	`"PAGINATION.INVALID_KEYSET_CURSOR"`
`INVALID_TOKEN`	`"PAGINATION.INVALID_TOKEN"`
`INVALID_SORT`	`"PAGINATION.INVALID_SORT"`
`ABORTED`	`"PAGINATION.ABORTED"`

`PaginationCode`

Union type of all values in PAGINATION_CODES. Use this as a discriminant in switch statements.

type PaginationCode = "PAGINATION.INVALID_CURSOR" | "PAGINATION.INVALID_PAGE" | ...

Implementation Notes

The codes are defined with defineCodes from @suaveplan/error, which registers them in the process-wide error code registry and ensures no namespace collision with other packages. The module is imported as a side effect from src/index.ts so registration happens automatically when the package is loaded. Tests can call defineCodes directly if they need to clear and re-register in isolation.

3.1 KiB Raw Blame History