# 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

```typescript
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

```typescript
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.

```typescript
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.