first commit

docs/foundation/data/pagination/src/errors/codes.md

@@ -0,0 +1,84 @@
+# 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.