{"id":17749,"library":"koa-pagination-v2","title":"Koa Query Parameter Pagination Middleware","description":"koa-pagination-v2 is a middleware designed for Koa applications to simplify handling pagination logic based on `page` and `limit` query parameters from the request. Currently at version 1.3.2, this package was last published approximately four years ago, indicating it is in a maintenance state rather than active development, with no recent releases or active contribution. Unlike its predecessor or other Koa pagination libraries that might focus on HTTP Range headers (e.g., the original `koa-pagination`), this version specifically processes `page` and `limit` from the URL query string. It exposes computed `limit` and `offset` values, along with a `pageable` helper function, via `ctx.state.paginate`. These values are directly usable with common ORMs (like Sequelize, as shown in the examples) to fetch a subset of data, and the `pageable` function helps construct comprehensive pagination metadata for API responses, including total count, page count, and navigation links. Its key differentiator is its straightforward, query-parameter-based approach, making it easy to integrate for simple REST API pagination.","status":"maintenance","version":"1.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/ArtashMardoyan/koa-pagination","tags":["javascript","paginate","pagination","koa-paginate","koa-pagination"],"install":[{"cmd":"npm install koa-pagination-v2","lang":"bash","label":"npm"},{"cmd":"yarn add koa-pagination-v2","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-pagination-v2","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` is shown in the README, modern Koa applications typically use ESM `import`. The package is older and might not officially support `exports` in `package.json`, but `import` should resolve correctly. However, a `require` statement is safer for older Node environments.","wrong":"const pagination = require('koa-pagination-v2');","symbol":"pagination","correct":"import pagination from 'koa-pagination-v2';"}],"quickstart":{"code":"const Koa = require('koa');\nconst pagination = require('koa-pagination-v2');\n\nconst app = new Koa();\n\n// Mock database function for demonstration\nconst mockFindAndCountAll = async ({ offset, limit }) => {\n    const allItems = Array.from({ length: 100 }, (_, i) => ({ id: i + 1, name: `Item ${i + 1}` }));\n    const rows = allItems.slice(offset, offset + limit);\n    const count = allItems.length;\n    return { rows, count };\n};\n\napp.use(pagination({ defaultLimit: 10, maximumLimit: 50 }));\n\napp.use(async ctx => {\n    if (ctx.path === '/items') {\n        const { limit, offset, pageable } = ctx.state.paginate;\n\n        const { rows: items, count: total } = await mockFindAndCountAll({\n            offset,\n            limit\n        });\n\n        ctx.body = {\n            data: items,\n            _meta: pageable(total) // Pass the total count to generate meta-data\n        };\n    } else {\n        ctx.body = 'Visit /items?page=1&limit=10 for pagination example.';\n    }\n});\n\nconst port = process.env.PORT || 3000;\napp.listen(port, () => {\n    console.log(`Server running on http://localhost:${port}`);\n    console.log(`Try: http://localhost:${port}/items?page=1&limit=5`);\n    console.log(`Try: http://localhost:${port}/items?page=2&limit=5`);\n    console.log(`Try: http://localhost:${port}/items?page=1&limit=60 (will cap at maxLimit of 50)`);\n});","lang":"javascript","description":"This quickstart demonstrates how to apply `koa-pagination-v2` middleware to a Koa application, fetch paginated data using mock data, and return a response with pagination metadata. It shows accessing `limit`, `offset`, and the `pageable` helper from `ctx.state.paginate`."},"warnings":[{"fix":"Ensure you understand whether your API expects query parameters (`page`, `limit`) or HTTP `Range` headers, and choose the appropriate middleware. If migrating, update client-side pagination logic accordingly.","message":"This package, `koa-pagination-v2`, processes `page` and `limit` query parameters. Be aware that it is distinct from other `koa-pagination` packages (e.g., `koa-pagination` by Uphold) that parse HTTP `Range` headers for pagination. Using them interchangeably will lead to unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Evaluate alternatives if active maintenance and modern feature support are critical for your project. If using, ensure thorough testing with your specific Koa and Node.js versions.","message":"The package was last published over four years ago (as of April 2026). While it generally works, it may not receive updates for new Koa versions, Node.js features, or critical security patches. Consider its maintenance status for long-term project viability.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure that your data fetching logic accurately determines the total count of items that match the query *before* pagination is applied, and pass this `total` count to `ctx.state.paginate.pageable()`.","message":"The `pageable` helper function, exposed on `ctx.state.paginate`, requires the total count of items in the dataset as an argument (`pageable(total)`). If `total` is not provided or is incorrect, the generated `_meta` object in the response will contain inaccurate pagination information (e.g., `pageCount`, `hasNext`).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully choose `defaultLimit` and `maximumLimit` values to align with your API's design and expected usage. Clearly document these limits for API consumers so they understand the effective pagination behavior.","message":"The configuration options `defaultLimit` and `maximumLimit` affect how `limit` and `offset` are calculated. If `maximumLimit` is set too low, user-requested limits might be silently capped, leading to unexpected results if not communicated to the client.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `app.use(pagination({ /* config */ }));` is called *before* any route handlers that depend on pagination data.","cause":"The `koa-pagination-v2` middleware has not been correctly applied to the Koa application via `app.use(pagination())` before the route handler attempts to access `ctx.state.paginate`.","error":"TypeError: ctx.state.paginate is undefined"},{"fix":"Verify that your database query correctly returns the *total* number of records matching any filters, ignoring the `limit` and `offset` for the actual data retrieval, and pass this accurate total to the `pageable` function.","cause":"The `total` count passed to `ctx.state.paginate.pageable(total)` is incorrect or missing. This usually happens if the total count is not fetched from the database or if a filtered count is not used.","error":"Incorrect pagination metadata (e.g., `pageCount` is 1 when it should be higher)"},{"fix":"Check the `maximumLimit` option provided when initializing the `koa-pagination-v2` middleware. The middleware will cap the `limit` at this maximum, even if a higher value is requested by the client.","cause":"The `limit` parameter in the request query might exceed the `maximumLimit` configured in the middleware, or `defaultLimit` is being incorrectly used.","error":"User-requested `limit` parameter is not respected in the response"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}