api-paginate 1.0.1 → 1.0.3

package/README.md

@@ -4,6 +4,16 @@ Paginate arrays in **Node** (and browsers). In-memory pagination for arrays. Use
 
 Returns JSON with `data`, `meta`, and `links`—ready to send. Configure once, pass only `route`.
 
+### Why api-paginate?
+
+- **One place to configure** — Set `baseUrl` in your entry file; in every route you only pass `route` and `per_page`. No repeating yourself.
+- **Any array, any stack** — Mongoose, Prisma, Sequelize, raw SQL, or a plain `[]`. Pagination happens in memory after you fetch; no ORM magic or query hooks.
+- **Familiar JSON shape** — `data`, `meta`, and `links` (first/prev/next/last) match what many APIs and frontends expect. No custom envelope.
+- **Small and predictable** — No database layer, no heavy deps. Just slicing arrays and building links. Easy to reason about and safe to upgrade.
+- **Works in Node and browsers** — Use it in API routes or in the client; in the browser it uses `window.location.origin` when you don’t call `configure`.
+
+If you’ve ever copy-pasted pagination logic or built `meta`/`links` by hand, this package replaces that with a single call in your return.
+
 ### Features
 
 - **Framework-agnostic** — Use with Express, Next.js, Fastify, or plain Node
@@ -24,47 +34,53 @@ The package supports both **CommonJS** (`require`) and **ESM** (`import`). Use `
 
 ## Usage
 
-### 1. Configure once at startup
+### 1. Configure once in your entry point
 
-```javascript
-// CommonJS
-const { configure } = require('api-paginate');
+Call `configure` **once** in your app entry file (`app.ts`, `server.ts`, `index.js`, or `main.js`)—not in every route file.
 
-// ESM / TypeScript
+```javascript
+// app.ts or server.ts or index.js (your entry point)
+// CommonJS: const { configure } = require('api-paginate');
 import { configure } from 'api-paginate';
 
 configure({ baseUrl: process.env.API_BASE_URL || 'https://myserver.com' });
 ```
 
-### 2. Use in your return—only route, never baseUrl
+### 2. Use in route handlers—only route and per_page
 
-```javascript
-// CommonJS
-const { paginate, paginateFromRequest } = require('api-paginate');
+In your route files, **don’t call configure**. Just import and use `paginate` or `paginateFromRequest` with `route` and `per_page`. The package uses the `baseUrl` you set at startup.
 
-// ESM / TypeScript
+```javascript
+// routes/users.js or similar — no configure here
+// CommonJS: const { paginate, paginateFromRequest } = require('api-paginate');
 import { paginate, paginateFromRequest } from 'api-paginate';
 
-// paginate:
+// paginate (when you have the page number):
 return res.json(paginate(docs, { route: '/users', current_page: 1, per_page: 20 }));
 
-// paginateFromRequest (page from req.query):
+// paginateFromRequest (reads page from req.query):
 return res.json(paginateFromRequest(req, users, { route: '/users', per_page: 15 }));
 ```
 
-### Express example
+### Express example (two places)
 
-Both CommonJS and ESM are supported:
+**Entry point** (e.g. `app.ts` or `server.ts`):
 
 ```javascript
-// CommonJS
-const { paginateFromRequest, configure } = require('api-paginate');
-
-// ESM / TypeScript
-import { paginateFromRequest, configure } from 'api-paginate';
+import express from 'express';
+import { configure } from 'api-paginate';
 
 configure({ baseUrl: process.env.API_BASE_URL });
 
+const app = express();
+// ... middleware, then mount routes
+```
+
+**Route handler** (e.g. `routes/users.ts`)—no `configure`, only `paginateFromRequest`:
+
+```javascript
+import { paginateFromRequest } from 'api-paginate';
+
 app.get('/users', async (req, res) => {
   try {
     const users = await User.find().lean();
@@ -75,8 +91,7 @@ app.get('/users', async (req, res) => {
 });
 ```
 
-
-Base URL is read from config—never pass it in return statements. In the browser, `route` uses `window.location.origin` if you skip `configure`.
+Base URL is read from the config you set at startup—don’t pass it in route handlers. In the browser, `route` uses `window.location.origin` if you never call `configure`.
 
 ### When to use `paginate` vs `paginateFromRequest`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "api-paginate",
-  "version": "1.0.1",
-  "description": "Paginate arrays for Node and browsers. Returns JSON with data, meta, and links—ready for API responses.",
+  "version": "1.0.3",
+  "description": "Paginate arrays for Node and browsers. Configure once at app entry (app.ts/server.ts); use paginate/paginateFromRequest in routes. Returns JSON with data, meta, and links.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -13,7 +13,7 @@
     }
   },
   "files": ["dist", "README.md"],
-  "keywords": ["pagination", "array", "node", "nodejs", "api", "express", "nextjs", "react", "angular", "json", "res.json", "meta", "links"],
+  "keywords": ["pagination", "array", "node", "nodejs", "api", "express", "nextjs", "react", "angular", "json", "res.json", "meta", "links", "configure", "baseUrl"],
   "license": "MIT",
   "author": "Kabanda Kpanti Michael <michaelkpantiramp@gmail.com> (https://github.com/Michael-Builds)",
   "repository": {
@@ -21,6 +21,7 @@
     "url": "git+https://github.com/Michael-Builds/api-paginate.git"
   },
   "homepage": "https://api-paginate.vercel.app",
+  "docs": "https://api-paginate.vercel.app/docs",
   "bugs": {
     "url": "https://github.com/Michael-Builds/api-paginate/issues"
   },