api-paginate 1.0.0

package/README.md

@@ -0,0 +1,284 @@
+# api-paginate
+
+Paginate arrays in **Node** (and browsers). In-memory pagination for arrays. Use it in your return when sending data to users—in controllers, API routes, and try/catch blocks. Works with any array, regardless of ORM or database.
+
+Returns JSON with `data`, `meta`, and `links`—ready to send. Configure once, pass only `route`.
+
+### Features
+
+- **Framework-agnostic** — Use with Express, Next.js, Fastify, or plain Node
+- **ORM-agnostic** — Works with Mongoose, Prisma, Sequelize, raw SQL, or plain arrays
+- **JSON output** — `data`, `meta`, and `links` (familiar shape for API responses)
+- **Configure once** — Set `baseUrl` at startup; use only `route` in return statements
+- **Client & server** — Works in Node and browsers (auto-detects `window.location.origin`)
+- **TypeScript** — Types included
+- **Small** — No database queries, no heavy dependencies
+
+## Installation
+
+```bash
+npm install api-paginate
+```
+
+The package supports both **CommonJS** (`require`) and **ESM** (`import`). Use `require('api-paginate')` in Node CommonJS and `import { ... } from 'api-paginate'` in ESM or TypeScript.
+
+## Usage
+
+### 1. Configure once at startup
+
+```javascript
+// CommonJS
+const { configure } = require('api-paginate');
+
+// ESM / TypeScript
+import { configure } from 'api-paginate';
+
+configure({ baseUrl: process.env.API_BASE_URL || 'https://myserver.com' });
+```
+
+### 2. Use in your return—only route, never baseUrl
+
+```javascript
+// CommonJS
+const { paginate, paginateFromRequest } = require('api-paginate');
+
+// ESM / TypeScript
+import { paginate, paginateFromRequest } from 'api-paginate';
+
+// paginate:
+return res.json(paginate(docs, { route: '/users', current_page: 1, per_page: 20 }));
+
+// paginateFromRequest (page from req.query):
+return res.json(paginateFromRequest(req, users, { route: '/users', per_page: 15 }));
+```
+
+### Express example
+
+Both CommonJS and ESM are supported:
+
+```javascript
+// CommonJS
+const { paginateFromRequest, configure } = require('api-paginate');
+
+// ESM / TypeScript
+import { paginateFromRequest, configure } from 'api-paginate';
+
+configure({ baseUrl: process.env.API_BASE_URL });
+
+app.get('/users', async (req, res) => {
+  try {
+    const users = await User.find().lean();
+    res.json(paginateFromRequest(req, users, { route: '/users', per_page: 15 }));
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+
+Base URL is read from config—never pass it in return statements. In the browser, `route` uses `window.location.origin` if you skip `configure`.
+
+### When to use `paginate` vs `paginateFromRequest`
+
+| Use | When |
+|-----|------|
+| `paginate` | You have the page number (e.g. from `req.query`, search params, or state) |
+| `paginateFromRequest` | Express/Node backend: it reads `page` from `req.query` and builds `baseUrl` from `req` automatically |
+
+### Next.js App Router example
+
+```javascript
+// app/api/users/route.js
+import { paginate } from 'api-paginate';
+
+export async function GET(request) {
+  const { searchParams } = new URL(request.url);
+  const users = await User.find().lean();
+  const result = paginate(users, {
+    current_page: parseInt(searchParams.get('page') || '1'),
+    per_page: 15,
+    route: '/api/users',
+  });
+  return Response.json(result);
+}
+```
+
+### Error handling
+
+Paginator throws `PaginatorError` when validation fails (invalid data, unsafe `pageParam`, etc.):
+
+```javascript
+// CommonJS: const { paginate, PaginatorError } = require('api-paginate');
+// ESM / TypeScript:
+import { paginate, PaginatorError } from 'api-paginate';
+
+try {
+  return res.json(paginate(docs, { route: '/users', per_page: 20 }));
+} catch (err) {
+  if (err instanceof PaginatorError) {
+    return res.status(400).json({ error: err.message });
+  }
+  throw err;
+}
+```
+
+## Options
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `current_page` | number | 1 | Current page (1-based) |
+| `per_page` | number | 15 | Items per page |
+| `route` | string | - | Route for links (e.g. `/api/users`); combined with configured baseUrl or auto-detected origin |
+| `baseUrl` | string | - | Override: full base URL (e.g. `https://api.example.com/users`); use route + configure instead |
+| `path` | string | - | Deprecated alias for route |
+| `pageParam` | string | 'page' | Query param name for page links (alphanumeric + underscore only; safe against injection) |
+
+### Config (`configure()`)
+
+| Parameter | Description |
+|-----------|-------------|
+| `baseUrl` | Application origin (e.g. `https://api.example.com`) |
+| `per_page` | Default items per page |
+| `pageParam` | Default query param name |
+| `route` | Default route when omitted in `paginate()` |
+
+## Response shape
+
+```json
+{
+  "data": [{ "id": 1, "name": "Alice" }],
+  "meta": {
+    "current_page": 2,
+    "per_page": 15,
+    "total": 150,
+    "total_pages": 10,
+    "has_next": true,
+    "has_prev": true,
+    "from": 16,
+    "to": 30
+  },
+  "links": {
+    "first": "https://api.example.com/users?page=1",
+    "prev": "https://api.example.com/users?page=1",
+    "next": "https://api.example.com/users?page=3",
+    "last": "https://api.example.com/users?page=10"
+  }
+}
+```
+
+- **`data`** — Slice of items for the current page
+- **`meta`** — Pagination metadata; `from` and `to` are 1-based (e.g. "items 16–30 of 47")
+- **`links`** — `first`, `prev`, `next`, `last` URLs; `null` when not applicable (e.g. `prev` on page 1)
+
+---
+
+## Development (this package)
+
+From the repository root:
+
+```bash
+npm install
+npm run build    # build dist (cjs + esm + types)
+npm test         # run tests
+```
+
+The docs and interactive simulator live in a separate repo (see the **api-paginate-web** repository).
+
+---
+
+## Pagination Algorithm
+
+This section describes the exact algorithm used for in-memory pagination. The implementation is deterministic and predictable.
+
+### Overview
+
+The algorithm takes a plain array and returns a subset (the current page) plus metadata and optional navigation links. All indexing is **1-based** for pages but **0-based** internally for array slicing.
+
+### Step-by-step
+
+#### 1. Input normalization
+
+| Input | Rule | Example |
+|-------|------|---------|
+| `current_page` | `Math.max(1, current_page ?? 1)` | `0`, `-1` → `1` |
+| `per_page` | `Math.max(1, per_page ?? 15)` | `0`, `-5` → `1` |
+
+Invalid values are clamped to at least 1 so every call yields a valid page.
+
+#### 2. Derived values
+
+```
+total        = data.length
+totalPages   = total === 0 ? 1 : Math.ceil(total / per_page)
+currentPage  = Math.min(page, totalPages)
+```
+
+- `totalPages` is 1 when there are no items (empty result, not zero pages).
+- `currentPage` is clamped so requesting page 99 with 10 total pages returns page 10 instead of an empty slice.
+
+#### 3. Slice indices (0-based)
+
+```
+start = (currentPage - 1) * per_page
+end   = start + per_page
+pageData = data.slice(start, end)
+```
+
+`Array.prototype.slice(start, end)` is used, so the range is `[start, end)` (end is exclusive).
+
+**Example:** `total = 47`, `per_page = 10`, `current_page = 3`  
+- `totalPages = 5`  
+- `currentPage = 3`  
+- `start = 20`, `end = 30`  
+- `pageData = data[20..29]` (10 items)
+
+#### 4. Meta
+
+| Field | Formula | Notes |
+|-------|---------|-------|
+| `current_page` | `currentPage` | 1-based |
+| `per_page` | per_page | Items per page |
+| `total` | `data.length` | Total items |
+| `total_pages` | `totalPages` | At least 1 |
+| `has_next` | `currentPage < totalPages` | True if a next page exists |
+| `has_prev` | `currentPage > 1` | True if a previous page exists |
+| `from` | `start + 1` if page non-empty, else `null` | 1-based first item index |
+| `to` | `Math.min(end, total)` if page non-empty, else `null` | 1-based last item index |
+
+`from` and `to` use 1-based, human-readable indexing (e.g. “items 16–30 of 47”).
+
+#### 5. Links (optional)
+
+If `baseUrl` or `path` is provided:
+
+- Append `?page=N` or `&page=N` depending on whether the URL already contains `?`
+- Use `pageParam` (default `"page"`) for the query parameter name
+- `first`, `prev`, `next`, `last` are built from `current_page` and `total_pages`
+- Any link that does not apply (e.g. `prev` on page 1) is `null`
+
+### Edge cases
+
+| Case | Behavior |
+|------|----------|
+| Empty array | `data: []`, `meta.total: 0`, `meta.total_pages: 1`, `from`/`to`: `null` |
+| Page beyond last page | Clamped to last page; returns last page’s data |
+| `per_page` larger than total | Single page with all items |
+| `per_page = 1` | One item per page |
+
+### Complexity
+
+- **Time:** O(1) for meta and links; O(`per_page`) for `Array.prototype.slice` (shallow copy of that slice).
+- **Space:** O(`per_page`) for the `data` slice; O(1) extra for metadata and link strings.
+
+### Invariants
+
+1. `1 ≤ current_page ≤ total_pages` always.
+2. `pageData.length ≤ per_page`.
+3. `from` and `to` are 1-based indices, or `null` when the page is empty.
+4. `from ≤ to` when both are non-null.
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,109 @@
+interface PaginateOptions {
+    /** Current page (1-based); use this instead of deprecated page */
+    current_page?: number;
+    /** Items per page; use this instead of deprecated perPage */
+    per_page?: number;
+    /** Base URL for link generation; if omitted, uses configured baseUrl or auto-detects in browser */
+    baseUrl?: string;
+    /** Route/path for links (e.g. '/api/users'). Combines with configured baseUrl or window.origin. */
+    route?: string;
+    /** @deprecated Use route instead. Path for link generation. */
+    path?: string;
+    /** Query param name for page (default: 'page') */
+    pageParam?: string;
+}
+interface PaginateMeta {
+    current_page: number;
+    per_page: number;
+    total: number;
+    total_pages: number;
+    has_next: boolean;
+    has_prev: boolean;
+    from: number | null;
+    to: number | null;
+}
+interface PaginateLinks {
+    first: string | null;
+    prev: string | null;
+    next: string | null;
+    last: string | null;
+}
+interface PaginatedResult<T> {
+    data: T[];
+    meta: PaginateMeta;
+    links: PaginateLinks;
+}
+/** Express-style request (subset needed for paginateFromRequest) */
+interface PaginateRequest {
+    query?: Record<string, string | string[] | undefined>;
+    protocol?: string;
+    get?: (name: string) => string | undefined;
+    path?: string;
+    originalUrl?: string;
+}
+
+interface PaginatorConfig {
+    /** Application base URL (origin), e.g. https://myserver.com or http://localhost:3000 */
+    baseUrl?: string;
+    /** Default route, e.g. /api (used when paginate is called without route) */
+    route?: string;
+    /** @deprecated Use route instead */
+    path?: string;
+    /** Default page param name */
+    pageParam?: string;
+    /** Default per_page */
+    per_page?: number;
+    /** @deprecated Use per_page instead */
+    perPage?: number;
+}
+/**
+ * Configure default options once. These are used when not overridden per-call.
+ * Call at app startup, e.g. configure({ baseUrl: process.env.NEXT_PUBLIC_BASE_URL })
+ */
+declare function configure(options: PaginatorConfig): void;
+/**
+ * Get current config (for testing or inspection)
+ */
+declare function getConfig(): Readonly<PaginatorConfig>;
+/**
+ * Reset config (mainly for testing)
+ */
+declare function resetConfig(): void;
+
+/** Custom error for paginator validation failures */
+declare class PaginatorError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Paginate an array of data with Laravel-style meta and links.
+ * Validates inputs and throws PaginatorError on invalid data.
+ */
+declare function paginate<T>(data: T[], options?: PaginateOptions): PaginatedResult<T>;
+
+interface PaginateFromRequestOptions {
+    /** Route/path for links (defaults to request path) */
+    route?: string;
+    /** Items per page (default: 15); use per_page instead of deprecated perPage */
+    per_page?: number;
+    /** @deprecated Use per_page instead */
+    perPage?: number;
+    /** Query param name for page (default: 'page') */
+    pageParam?: string;
+}
+/**
+ * Paginate data for a backend response. Use in controllers: res.json(paginateFromRequest(req, data))
+ *
+ * Extracts page from req.query, builds baseUrl from req, and returns { data, meta, links }
+ * ready for res.json() or Response.json().
+ *
+ * @example
+ * // Express
+ * app.get('/users', async (req, res) => {
+ *   const users = await User.find().lean();
+ *   res.json(paginateFromRequest(req, users, { per_page: 15 }));
+ * });
+ */
+declare function paginateFromRequest<T>(request: PaginateRequest, data: T[], options?: PaginateFromRequestOptions): PaginatedResult<T>;
+
+export { type PaginateFromRequestOptions, type PaginateLinks, type PaginateMeta, type PaginateOptions, type PaginateRequest, type PaginatedResult, type PaginatorConfig, PaginatorError, configure, getConfig, paginate, paginateFromRequest, resetConfig };

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+interface PaginateOptions {
+    /** Current page (1-based); use this instead of deprecated page */
+    current_page?: number;
+    /** Items per page; use this instead of deprecated perPage */
+    per_page?: number;
+    /** Base URL for link generation; if omitted, uses configured baseUrl or auto-detects in browser */
+    baseUrl?: string;
+    /** Route/path for links (e.g. '/api/users'). Combines with configured baseUrl or window.origin. */
+    route?: string;
+    /** @deprecated Use route instead. Path for link generation. */
+    path?: string;
+    /** Query param name for page (default: 'page') */
+    pageParam?: string;
+}
+interface PaginateMeta {
+    current_page: number;
+    per_page: number;
+    total: number;
+    total_pages: number;
+    has_next: boolean;
+    has_prev: boolean;
+    from: number | null;
+    to: number | null;
+}
+interface PaginateLinks {
+    first: string | null;
+    prev: string | null;
+    next: string | null;
+    last: string | null;
+}
+interface PaginatedResult<T> {
+    data: T[];
+    meta: PaginateMeta;
+    links: PaginateLinks;
+}
+/** Express-style request (subset needed for paginateFromRequest) */
+interface PaginateRequest {
+    query?: Record<string, string | string[] | undefined>;
+    protocol?: string;
+    get?: (name: string) => string | undefined;
+    path?: string;
+    originalUrl?: string;
+}
+
+interface PaginatorConfig {
+    /** Application base URL (origin), e.g. https://myserver.com or http://localhost:3000 */
+    baseUrl?: string;
+    /** Default route, e.g. /api (used when paginate is called without route) */
+    route?: string;
+    /** @deprecated Use route instead */
+    path?: string;
+    /** Default page param name */
+    pageParam?: string;
+    /** Default per_page */
+    per_page?: number;
+    /** @deprecated Use per_page instead */
+    perPage?: number;
+}
+/**
+ * Configure default options once. These are used when not overridden per-call.
+ * Call at app startup, e.g. configure({ baseUrl: process.env.NEXT_PUBLIC_BASE_URL })
+ */
+declare function configure(options: PaginatorConfig): void;
+/**
+ * Get current config (for testing or inspection)
+ */
+declare function getConfig(): Readonly<PaginatorConfig>;
+/**
+ * Reset config (mainly for testing)
+ */
+declare function resetConfig(): void;
+
+/** Custom error for paginator validation failures */
+declare class PaginatorError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Paginate an array of data with Laravel-style meta and links.
+ * Validates inputs and throws PaginatorError on invalid data.
+ */
+declare function paginate<T>(data: T[], options?: PaginateOptions): PaginatedResult<T>;
+
+interface PaginateFromRequestOptions {
+    /** Route/path for links (defaults to request path) */
+    route?: string;
+    /** Items per page (default: 15); use per_page instead of deprecated perPage */
+    per_page?: number;
+    /** @deprecated Use per_page instead */
+    perPage?: number;
+    /** Query param name for page (default: 'page') */
+    pageParam?: string;
+}
+/**
+ * Paginate data for a backend response. Use in controllers: res.json(paginateFromRequest(req, data))
+ *
+ * Extracts page from req.query, builds baseUrl from req, and returns { data, meta, links }
+ * ready for res.json() or Response.json().
+ *
+ * @example
+ * // Express
+ * app.get('/users', async (req, res) => {
+ *   const users = await User.find().lean();
+ *   res.json(paginateFromRequest(req, users, { per_page: 15 }));
+ * });
+ */
+declare function paginateFromRequest<T>(request: PaginateRequest, data: T[], options?: PaginateFromRequestOptions): PaginatedResult<T>;
+
+export { type PaginateFromRequestOptions, type PaginateLinks, type PaginateMeta, type PaginateOptions, type PaginateRequest, type PaginatedResult, type PaginatorConfig, PaginatorError, configure, getConfig, paginate, paginateFromRequest, resetConfig };

package/dist/index.js

@@ -0,0 +1,181 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PaginatorError: () => PaginatorError,
+  configure: () => configure,
+  getConfig: () => getConfig,
+  paginate: () => paginate,
+  paginateFromRequest: () => paginateFromRequest,
+  resetConfig: () => resetConfig
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/config.ts
+var config = {};
+function configure(options) {
+  config = { ...config, ...options };
+}
+function getConfig() {
+  return { ...config };
+}
+function resetConfig() {
+  config = {};
+}
+function joinBaseAndPath(base, path) {
+  const b = base.replace(/\/+$/, "");
+  const p = path.startsWith("/") ? path : `/${path}`;
+  return `${b}${p}`;
+}
+function resolveBaseUrl(options) {
+  const opts = options ?? {};
+  if (typeof opts.baseUrl === "string" && opts.baseUrl.trim()) {
+    return opts.baseUrl.trim();
+  }
+  const path = (typeof opts.route === "string" ? opts.route : opts.path) ?? "";
+  const pathTrimmed = typeof path === "string" ? path.trim() : "";
+  if (pathTrimmed && config.baseUrl) {
+    return joinBaseAndPath(config.baseUrl.trim(), pathTrimmed);
+  }
+  if (pathTrimmed && typeof window !== "undefined" && window?.location?.origin) {
+    return joinBaseAndPath(window.location.origin, pathTrimmed);
+  }
+  if (pathTrimmed) return pathTrimmed;
+  const configRoute = config.route ?? config.path;
+  if (config.baseUrl && configRoute) {
+    return joinBaseAndPath(config.baseUrl.trim(), configRoute.trim());
+  }
+  return config.baseUrl?.trim() ?? "";
+}
+
+// src/validate.ts
+var MAX_PER_PAGE = 1e4;
+var SAFE_PARAM_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var PaginatorError = class _PaginatorError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PaginatorError";
+    Object.setPrototypeOf(this, _PaginatorError.prototype);
+  }
+};
+function toSafeInt(value, defaults) {
+  if (value === void 0 || value === null) return defaults.fallback;
+  const n = typeof value === "number" ? value : parseInt(String(value), 10);
+  if (!Number.isFinite(n) || n < defaults.min) return defaults.min;
+  if (n > defaults.max) return defaults.max;
+  return Math.floor(n);
+}
+function validatePaginateInputs(data, options) {
+  if (data === null || data === void 0) {
+    throw new PaginatorError("paginate(data, options): data is required and must be an array");
+  }
+  if (!Array.isArray(data)) {
+    throw new PaginatorError(
+      `paginate(data, options): data must be an array, got ${typeof data}`
+    );
+  }
+  const opts = options ?? {};
+  const page = toSafeInt(opts.current_page, { min: 1, max: Number.MAX_SAFE_INTEGER, fallback: 1 });
+  const per_page = toSafeInt(opts.per_page, { min: 1, max: MAX_PER_PAGE, fallback: 15 });
+  const baseUrl = resolveBaseUrl(opts);
+  const rawParam = opts.pageParam ?? "page";
+  const param = typeof rawParam === "string" ? rawParam.trim() : "page";
+  if (!param) {
+    throw new PaginatorError("paginate: pageParam cannot be empty");
+  }
+  if (!SAFE_PARAM_REGEX.test(param)) {
+    throw new PaginatorError(
+      `paginate: pageParam must be a safe query param name (letters, numbers, underscore), got "${param}"`
+    );
+  }
+  return {
+    data,
+    page,
+    per_page,
+    baseUrl,
+    pageParam: param
+  };
+}
+
+// src/paginate.ts
+function paginate(data, options) {
+  const { data: arr, page, per_page, baseUrl, pageParam } = validatePaginateInputs(data, options);
+  const total = arr.length;
+  const totalPages = total === 0 ? 1 : Math.ceil(total / per_page);
+  const currentPage = Math.min(page, totalPages);
+  const start = (currentPage - 1) * per_page;
+  const end = start + per_page;
+  const pageData = arr.slice(start, end);
+  const meta = {
+    current_page: currentPage,
+    per_page,
+    total,
+    total_pages: totalPages,
+    has_next: currentPage < totalPages,
+    has_prev: currentPage > 1,
+    from: pageData.length > 0 ? start + 1 : null,
+    to: pageData.length > 0 ? Math.min(end, total) : null
+  };
+  const links = buildLinks(baseUrl, pageParam, meta);
+  return { data: pageData, meta, links };
+}
+var UNSAFE_URL_PREFIX = /^(javascript|data|vbscript):/i;
+function buildLinks(baseUrl, param, meta) {
+  if (!baseUrl || UNSAFE_URL_PREFIX.test(baseUrl)) {
+    return { first: null, prev: null, next: null, last: null };
+  }
+  const sep = baseUrl.includes("?") ? "&" : "?";
+  const pageNum = (n) => String(n);
+  return {
+    first: meta.total_pages > 0 ? `${baseUrl}${sep}${encodeURIComponent(param)}=1` : null,
+    prev: meta.current_page > 1 ? `${baseUrl}${sep}${encodeURIComponent(param)}=${pageNum(meta.current_page - 1)}` : null,
+    next: meta.current_page < meta.total_pages ? `${baseUrl}${sep}${encodeURIComponent(param)}=${pageNum(meta.current_page + 1)}` : null,
+    last: meta.total_pages > 0 ? `${baseUrl}${sep}${encodeURIComponent(param)}=${pageNum(meta.total_pages)}` : null
+  };
+}
+
+// src/paginateFromRequest.ts
+function paginateFromRequest(request, data, options = {}) {
+  const req = request;
+  const pageParam = options.pageParam ?? "page";
+  const pageStr = req.query?.[pageParam];
+  const page = Array.isArray(pageStr) ? Math.max(1, parseInt(pageStr[0] ?? "1", 10) || 1) : Math.max(1, parseInt(String(pageStr ?? "1"), 10) || 1);
+  const protocol = req.protocol ?? "http";
+  const host = req.get?.("host") ?? "";
+  const pathname = (req.originalUrl ?? req.path ?? "/").split("?")[0];
+  const baseUrl = host ? `${protocol}://${host}${pathname}` : "";
+  return paginate(data, {
+    current_page: page,
+    per_page: options.per_page ?? options.perPage ?? 15,
+    baseUrl: baseUrl || void 0,
+    route: baseUrl ? void 0 : options.route ?? pathname,
+    pageParam
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PaginatorError,
+  configure,
+  getConfig,
+  paginate,
+  paginateFromRequest,
+  resetConfig
+});

package/dist/index.mjs

@@ -0,0 +1,149 @@
+// src/config.ts
+var config = {};
+function configure(options) {
+  config = { ...config, ...options };
+}
+function getConfig() {
+  return { ...config };
+}
+function resetConfig() {
+  config = {};
+}
+function joinBaseAndPath(base, path) {
+  const b = base.replace(/\/+$/, "");
+  const p = path.startsWith("/") ? path : `/${path}`;
+  return `${b}${p}`;
+}
+function resolveBaseUrl(options) {
+  const opts = options ?? {};
+  if (typeof opts.baseUrl === "string" && opts.baseUrl.trim()) {
+    return opts.baseUrl.trim();
+  }
+  const path = (typeof opts.route === "string" ? opts.route : opts.path) ?? "";
+  const pathTrimmed = typeof path === "string" ? path.trim() : "";
+  if (pathTrimmed && config.baseUrl) {
+    return joinBaseAndPath(config.baseUrl.trim(), pathTrimmed);
+  }
+  if (pathTrimmed && typeof window !== "undefined" && window?.location?.origin) {
+    return joinBaseAndPath(window.location.origin, pathTrimmed);
+  }
+  if (pathTrimmed) return pathTrimmed;
+  const configRoute = config.route ?? config.path;
+  if (config.baseUrl && configRoute) {
+    return joinBaseAndPath(config.baseUrl.trim(), configRoute.trim());
+  }
+  return config.baseUrl?.trim() ?? "";
+}
+
+// src/validate.ts
+var MAX_PER_PAGE = 1e4;
+var SAFE_PARAM_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var PaginatorError = class _PaginatorError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PaginatorError";
+    Object.setPrototypeOf(this, _PaginatorError.prototype);
+  }
+};
+function toSafeInt(value, defaults) {
+  if (value === void 0 || value === null) return defaults.fallback;
+  const n = typeof value === "number" ? value : parseInt(String(value), 10);
+  if (!Number.isFinite(n) || n < defaults.min) return defaults.min;
+  if (n > defaults.max) return defaults.max;
+  return Math.floor(n);
+}
+function validatePaginateInputs(data, options) {
+  if (data === null || data === void 0) {
+    throw new PaginatorError("paginate(data, options): data is required and must be an array");
+  }
+  if (!Array.isArray(data)) {
+    throw new PaginatorError(
+      `paginate(data, options): data must be an array, got ${typeof data}`
+    );
+  }
+  const opts = options ?? {};
+  const page = toSafeInt(opts.current_page, { min: 1, max: Number.MAX_SAFE_INTEGER, fallback: 1 });
+  const per_page = toSafeInt(opts.per_page, { min: 1, max: MAX_PER_PAGE, fallback: 15 });
+  const baseUrl = resolveBaseUrl(opts);
+  const rawParam = opts.pageParam ?? "page";
+  const param = typeof rawParam === "string" ? rawParam.trim() : "page";
+  if (!param) {
+    throw new PaginatorError("paginate: pageParam cannot be empty");
+  }
+  if (!SAFE_PARAM_REGEX.test(param)) {
+    throw new PaginatorError(
+      `paginate: pageParam must be a safe query param name (letters, numbers, underscore), got "${param}"`
+    );
+  }
+  return {
+    data,
+    page,
+    per_page,
+    baseUrl,
+    pageParam: param
+  };
+}
+
+// src/paginate.ts
+function paginate(data, options) {
+  const { data: arr, page, per_page, baseUrl, pageParam } = validatePaginateInputs(data, options);
+  const total = arr.length;
+  const totalPages = total === 0 ? 1 : Math.ceil(total / per_page);
+  const currentPage = Math.min(page, totalPages);
+  const start = (currentPage - 1) * per_page;
+  const end = start + per_page;
+  const pageData = arr.slice(start, end);
+  const meta = {
+    current_page: currentPage,
+    per_page,
+    total,
+    total_pages: totalPages,
+    has_next: currentPage < totalPages,
+    has_prev: currentPage > 1,
+    from: pageData.length > 0 ? start + 1 : null,
+    to: pageData.length > 0 ? Math.min(end, total) : null
+  };
+  const links = buildLinks(baseUrl, pageParam, meta);
+  return { data: pageData, meta, links };
+}
+var UNSAFE_URL_PREFIX = /^(javascript|data|vbscript):/i;
+function buildLinks(baseUrl, param, meta) {
+  if (!baseUrl || UNSAFE_URL_PREFIX.test(baseUrl)) {
+    return { first: null, prev: null, next: null, last: null };
+  }
+  const sep = baseUrl.includes("?") ? "&" : "?";
+  const pageNum = (n) => String(n);
+  return {
+    first: meta.total_pages > 0 ? `${baseUrl}${sep}${encodeURIComponent(param)}=1` : null,
+    prev: meta.current_page > 1 ? `${baseUrl}${sep}${encodeURIComponent(param)}=${pageNum(meta.current_page - 1)}` : null,
+    next: meta.current_page < meta.total_pages ? `${baseUrl}${sep}${encodeURIComponent(param)}=${pageNum(meta.current_page + 1)}` : null,
+    last: meta.total_pages > 0 ? `${baseUrl}${sep}${encodeURIComponent(param)}=${pageNum(meta.total_pages)}` : null
+  };
+}
+
+// src/paginateFromRequest.ts
+function paginateFromRequest(request, data, options = {}) {
+  const req = request;
+  const pageParam = options.pageParam ?? "page";
+  const pageStr = req.query?.[pageParam];
+  const page = Array.isArray(pageStr) ? Math.max(1, parseInt(pageStr[0] ?? "1", 10) || 1) : Math.max(1, parseInt(String(pageStr ?? "1"), 10) || 1);
+  const protocol = req.protocol ?? "http";
+  const host = req.get?.("host") ?? "";
+  const pathname = (req.originalUrl ?? req.path ?? "/").split("?")[0];
+  const baseUrl = host ? `${protocol}://${host}${pathname}` : "";
+  return paginate(data, {
+    current_page: page,
+    per_page: options.per_page ?? options.perPage ?? 15,
+    baseUrl: baseUrl || void 0,
+    route: baseUrl ? void 0 : options.route ?? pathname,
+    pageParam
+  });
+}
+export {
+  PaginatorError,
+  configure,
+  getConfig,
+  paginate,
+  paginateFromRequest,
+  resetConfig
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "api-paginate",
+  "version": "1.0.0",
+  "description": "Paginate arrays for Node and browsers. Returns JSON with data, meta, and links—ready for API responses.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "keywords": ["pagination", "array", "node", "nodejs", "api", "express", "nextjs", "react", "angular", "json", "res.json", "meta", "links"],
+  "license": "MIT",
+  "author": "Kabanda Kpanti Michael <michaelkpantiramp@gmail.com> (https://github.com/Michael-Builds)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Michael-Builds/paginate-json.git"
+  },
+  "homepage": "https://github.com/Michael-Builds/paginate-json#readme",
+  "bugs": {
+    "url": "https://github.com/Michael-Builds/paginate-json/issues"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "demo": "npm run build && npx serve -p 3000",
+    "fixtures": "node scripts/generate-fixtures.js",
+    "web": "cd web && npm run dev -- -p 3001"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "tailwindcss": "^4",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}