@x-spacy/pagination 1.0.5

package/@types/index.d.ts

@@ -0,0 +1,18 @@
+declare module '@x-spacy/pagination' {
+  import { Page } from '@x-spacy/pagination/schemas/Page';
+  import { PaginatedResponse } from '@x-spacy/pagination/schemas/Paginate';
+
+  export enum PaginationLinkType {
+    FIRST = 'FIRST',
+    LAST = 'LAST',
+    PREV = 'PREV',
+    NEXT = 'NEXT',
+    PAGE = 'PAGE'
+  }
+
+  export declare class PaginateInterceptor<T> implements NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<PaginatedResponse<T>>>;
+  }
+
+  export function paginate<T>(items: Array<T>, total: number): Page<T>;
+}

package/LICENSE

@@ -0,0 +1,9 @@
+(The MIT License)
+
+Copyright (c) 2026 X Spacy <https://xspacy.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# Pagination
+
+A pagination library for NestJS with metadata and navigation links support.
+
+## Installation
+
+```bash
+# Using npm
+npm install @x-spacy/pagination
+
+# Using yarn
+yarn add @x-spacy/pagination
+
+# Using pnpm
+pnpm add @x-spacy/pagination
+
+# Using bun
+bun add @x-spacy/pagination
+```
+
+## Configuration
+
+### Required: `reflect-metadata`
+
+This library uses `class-transformer` for object serialization, which relies on **decorators** and **metadata reflection**. For the transformers to work correctly, it is **mandatory** to have `reflect-metadata` configured in your project.
+
+#### 1. Install `reflect-metadata`
+
+```bash
+# Using npm
+npm install reflect-metadata
+
+# Using yarn
+yarn add reflect-metadata
+
+# Using pnpm
+pnpm add reflect-metadata
+
+# Using bun
+bun add reflect-metadata
+```
+
+#### 2. Import in Entry Point
+
+Add the `reflect-metadata` import in your application's entry file (`main.ts`) **before any other imports**:
+
+```typescript
+import 'reflect-metadata';
+
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+#### 3. Configure `tsconfig.json`
+
+Make sure the following options are enabled in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## Usage
+
+### Basic Example
+
+To use pagination, you need **two mandatory elements**:
+
+1. **`PaginateInterceptor`**: Interceptor that processes the response and generates pagination metadata
+2. **`paginate()`**: Function that wraps the data to be processed by the interceptor
+
+```typescript
+import { Controller, Get, HttpCode, HttpStatus, Query, UseInterceptors } from '@nestjs/common';
+
+import { PaginateInterceptor, paginate } from '@x-spacy/pagination';
+
+import { ListServicesService } from './list-services.service';
+import { ListServicesHttpControllerQueryValidator } from './validators/list-services-http-controller-query.validator';
+import { ServiceHttpControllerSerializer } from './serializers/service-http-controller.serializer';
+
+@Controller('services')
+export class ListServicesHttpController {
+  @Inject('ListServicesService')
+  private readonly listServicesService: ListServicesService
+
+  @Get()
+  @HttpCode(HttpStatus.OK)
+  @UseInterceptors(PaginateInterceptor)
+  public async list(@Query() { page, perPage }: ListServicesHttpControllerQueryValidator) {
+    const { services, total } = await this.listServicesService.execute(page, perPage);
+
+    return paginate(services.map(service => ServiceHttpControllerSerializer.serialize(service)), total);
+  }
+}
+```
+
+### Query Parameters
+
+The interceptor expects the following query parameters:
+
+| Parameter | Type   | Default | Description                              |
+|-----------|--------|---------|------------------------------------------|
+| `page`    | number | 1       | Current page number                      |
+| `perPage` | number | 10      | Number of items per page (max: 100)      |
+
+## Response Structure
+
+The paginated response follows this format:
+
+```json
+{
+  "items": [...],
+  "meta": {
+    "from": 1,
+    "to": 10,
+    "current_page": 1,
+    "last_page": 5,
+    "per_page": 10,
+    "total": 50
+  },
+  "path": "https://api.example.com/services",
+  "first_page_url": "https://api.example.com/services?page=1&perPage=10",
+  "prev_page_url": null,
+  "next_page_url": "https://api.example.com/services?page=2&perPage=10",
+  "last_page_url": "https://api.example.com/services?page=5&perPage=10",
+  "links": [
+    {
+      "url": null,
+      "label": "« Previous",
+      "type": "PREV",
+      "active": false
+    },
+    {
+      "url": "https://api.example.com/services?page=1&perPage=10",
+      "label": "1",
+      "type": "PAGE",
+      "active": true
+    },
+    {
+      "url": "https://api.example.com/services?page=2&perPage=10",
+      "label": "2",
+      "type": "PAGE",
+      "active": false
+    },
+    {
+      "url": "https://api.example.com/services?page=2&perPage=10",
+      "label": "Next »",
+      "type": "NEXT",
+      "active": false
+    }
+  ]
+}
+```
+
+## API Reference
+
+### `paginate<T>(items: Array<T>, total: number): Page<T>`
+
+Wraps the items and total to be processed by `PaginateInterceptor`.
+
+**Parameters:**
+
+- `items`: Array of items for the current page
+- `total`: Total number of items (used to calculate pagination)
+
+**Returns:**
+
+- `Page<T>`: Object that will be intercepted and transformed into `PaginatedResponse<T>`
+
+### `PaginateInterceptor`
+
+NestJS interceptor that transforms a `Page<T>` into a complete paginated response with metadata and navigation links.
+
+### Exported Types
+
+```typescript
+// Enums
+export { PaginationLinkType } from '@x-spacy/pagination';
+
+// Interceptors
+export { PaginateInterceptor } from '@x-spacy/pagination';
+
+// Operators
+export { paginate } from '@x-spacy/pagination';
+```
+
+### `PaginationLinkType`
+
+Enum that defines the types of navigation links:
+
+```typescript
+enum PaginationLinkType {
+  FIRST = 'FIRST',
+  LAST = 'LAST',
+  PREV = 'PREV',
+  NEXT = 'NEXT',
+  PAGE = 'PAGE'
+}
+```
+
+## License
+
+[MIT licensed](LICENSE).

package/dist/enums/PaginationLinkType.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginationLinkType = void 0;
+var PaginationLinkType;
+(function (PaginationLinkType) {
+    PaginationLinkType["FIRST"] = "FIRST";
+    PaginationLinkType["LAST"] = "LAST";
+    PaginationLinkType["PREV"] = "PREV";
+    PaginationLinkType["NEXT"] = "NEXT";
+    PaginationLinkType["PAGE"] = "PAGE";
+})(PaginationLinkType || (exports.PaginationLinkType = PaginationLinkType = {}));

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./interceptors/PaginationInterceptor"), exports);
+__exportStar(require("./operators/paginate"), exports);
+__exportStar(require("./schemas/Page"), exports);
+__exportStar(require("./schemas/PaginatedResponse"), exports);
+__exportStar(require("./schemas/PaginationLink"), exports);
+__exportStar(require("./schemas/PaginationMeta"), exports);

package/dist/interceptors/PaginationInterceptor.js

@@ -0,0 +1,52 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginateInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const operators_1 = require("rxjs/operators");
+const Page_1 = require("../schemas/Page");
+const PaginatedResponse_1 = require("../schemas/PaginatedResponse");
+const PaginationLink_1 = require("../schemas/PaginationLink");
+const PaginationMeta_1 = require("../schemas/PaginationMeta");
+const PaginationLinkType_1 = require("../enums/PaginationLinkType");
+let PaginateInterceptor = class PaginateInterceptor {
+    intercept(context, next) {
+        const request = context.switchToHttp().getRequest();
+        const page = Math.max(1, parseInt(request.query.page, 10) ?? 1);
+        const perPage = Math.min(100, Math.max(1, parseInt(request.query.perPage, 10) ?? 10));
+        const path = `${request.protocol}://${request.get('host') + request.path}`;
+        return next.handle().pipe((0, operators_1.map)((data) => {
+            if (!(data instanceof Page_1.Page)) {
+                return data;
+            }
+            const { total, items } = data;
+            const lastPage = Math.max(1, Math.ceil(total / perPage));
+            const currentPage = Math.min(page, lastPage);
+            const startIndex = (currentPage - 1) * perPage;
+            const endIndex = Math.min(startIndex + perPage, total);
+            const from = total > 0 ? startIndex + 1 : 0;
+            const to = endIndex;
+            const buildUrl = (pageNumber) => `${path}?page=${pageNumber}&perPage=${perPage}`;
+            const links = this.buildLinks(currentPage, lastPage, buildUrl);
+            return new PaginatedResponse_1.PaginatedResponse(items, new PaginationMeta_1.PaginationMeta(from, to, currentPage, lastPage, perPage, total), path, buildUrl(1), currentPage > 1 ? buildUrl(currentPage - 1) : null, currentPage < lastPage ? buildUrl(currentPage + 1) : null, buildUrl(lastPage), links);
+        }));
+    }
+    buildLinks(currentPage, lastPage, buildUrl) {
+        const links = new Array();
+        links.push(new PaginationLink_1.PaginationLink(currentPage > 1 ? buildUrl(currentPage - 1) : null, '&laquo; Anterior', PaginationLinkType_1.PaginationLinkType.PREV, false));
+        for (let i = 1; i <= lastPage; i++) {
+            links.push(new PaginationLink_1.PaginationLink(buildUrl(i), String(i), PaginationLinkType_1.PaginationLinkType.PAGE, i === currentPage));
+        }
+        links.push(new PaginationLink_1.PaginationLink(currentPage < lastPage ? buildUrl(currentPage + 1) : null, 'Próximo &raquo;', PaginationLinkType_1.PaginationLinkType.NEXT, false));
+        return links;
+    }
+};
+exports.PaginateInterceptor = PaginateInterceptor;
+exports.PaginateInterceptor = PaginateInterceptor = __decorate([
+    (0, common_1.Injectable)()
+], PaginateInterceptor);

package/dist/operators/paginate.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paginate = paginate;
+const Page_1 = require("../schemas/Page");
+function paginate(items, total) {
+    return new Page_1.Page(items, total);
+}

package/dist/schemas/Page.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Page = void 0;
+class Page {
+    items;
+    total;
+    constructor(items, total) {
+        this.items = items;
+        this.total = total;
+    }
+}
+exports.Page = Page;

package/dist/schemas/PaginatedResponse.js

@@ -0,0 +1,67 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginatedResponse = void 0;
+const class_transformer_1 = require("class-transformer");
+const PaginationMeta_1 = require("./PaginationMeta");
+class PaginatedResponse {
+    items;
+    meta;
+    path;
+    firstPageUrl;
+    prevPageUrl;
+    nextPageUrl;
+    lastPageUrl;
+    links;
+    constructor(items, meta, path, firstPageUrl, prevPageUrl, nextPageUrl, lastPageUrl, links) {
+        this.items = items;
+        this.meta = meta;
+        this.path = path;
+        this.firstPageUrl = firstPageUrl;
+        this.prevPageUrl = prevPageUrl;
+        this.nextPageUrl = nextPageUrl;
+        this.lastPageUrl = lastPageUrl;
+        this.links = links;
+    }
+}
+exports.PaginatedResponse = PaginatedResponse;
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'items' }),
+    __metadata("design:type", Array)
+], PaginatedResponse.prototype, "items", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'meta' }),
+    __metadata("design:type", PaginationMeta_1.PaginationMeta)
+], PaginatedResponse.prototype, "meta", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'path' }),
+    __metadata("design:type", String)
+], PaginatedResponse.prototype, "path", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'first_page_url' }),
+    __metadata("design:type", String)
+], PaginatedResponse.prototype, "firstPageUrl", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'prev_page_url' }),
+    __metadata("design:type", Object)
+], PaginatedResponse.prototype, "prevPageUrl", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'next_page_url' }),
+    __metadata("design:type", Object)
+], PaginatedResponse.prototype, "nextPageUrl", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'last_page_url' }),
+    __metadata("design:type", String)
+], PaginatedResponse.prototype, "lastPageUrl", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'links' }),
+    __metadata("design:type", Array)
+], PaginatedResponse.prototype, "links", void 0);

package/dist/schemas/PaginationLink.js

@@ -0,0 +1,43 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginationLink = void 0;
+const class_transformer_1 = require("class-transformer");
+const PaginationLinkType_1 = require("../enums/PaginationLinkType");
+class PaginationLink {
+    url;
+    label;
+    type;
+    active;
+    constructor(url, label, type, active) {
+        this.url = url;
+        this.label = label;
+        this.type = type;
+        this.active = active;
+    }
+}
+exports.PaginationLink = PaginationLink;
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'url' }),
+    __metadata("design:type", Object)
+], PaginationLink.prototype, "url", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'label' }),
+    __metadata("design:type", String)
+], PaginationLink.prototype, "label", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'type' }),
+    __metadata("design:type", String)
+], PaginationLink.prototype, "type", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'active' }),
+    __metadata("design:type", Boolean)
+], PaginationLink.prototype, "active", void 0);

package/dist/schemas/PaginationMeta.js

@@ -0,0 +1,54 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginationMeta = void 0;
+const class_transformer_1 = require("class-transformer");
+class PaginationMeta {
+    from;
+    to;
+    currentPage;
+    lastPage;
+    perPage;
+    total;
+    constructor(from, to, currentPage, lastPage, perPage, total) {
+        this.from = from;
+        this.to = to;
+        this.currentPage = currentPage;
+        this.lastPage = lastPage;
+        this.perPage = perPage;
+        this.total = total;
+    }
+}
+exports.PaginationMeta = PaginationMeta;
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'from' }),
+    __metadata("design:type", Number)
+], PaginationMeta.prototype, "from", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'to' }),
+    __metadata("design:type", Number)
+], PaginationMeta.prototype, "to", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'current_page' }),
+    __metadata("design:type", Number)
+], PaginationMeta.prototype, "currentPage", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'last_page' }),
+    __metadata("design:type", Number)
+], PaginationMeta.prototype, "lastPage", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'per_page' }),
+    __metadata("design:type", Number)
+], PaginationMeta.prototype, "perPage", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)({ name: 'total' }),
+    __metadata("design:type", Number)
+], PaginationMeta.prototype, "total", void 0);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@x-spacy/pagination",
+  "version": "1.0.5",
+  "description": "A pagination library for NestJS",
+  "license": "X SPACY LICENSE AGREEMENT",
+  "private": false,
+  "main": "dist/index.js",
+  "types": "@types/index.d.ts",
+  "author": {
+    "name": "Vinícius Gutierrez da Silva Rocha",
+    "email": "srgutyerrez@gmail.com",
+    "url": "https://github.com/gutyerrez"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x-spacy/pagination.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "tag": "latest"
+  },
+  "engines": {
+    "bun": ">=1.3.9"
+  },
+  "scripts": {
+    "build": "nest build"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.1.13",
+    "@nestjs/core": "^11.1.13",
+    "@x-spacy/eslint-config": "^1.35.0",
+    "class-transformer": "^0.5.1",
+    "express": "^5.2.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^11.0.16",
+    "@types/express": "^5.0.6",
+    "typescript": "^5.9.3"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "module": "commonjs",
+    "outDir": "dist",
+    "paths": {
+      "@x-spacy/pagination/*": [
+        "./src/*"
+      ]
+    },
+    "strict": true,
+    "skipLibCheck": true,
+    "removeComments": true,
+    "esModuleInterop": true,
+    "strictNullChecks": true,
+    "resolveJsonModule": true,
+    "strictBindCallApply": false,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowSyntheticDefaultImports": true,
+    "strictPropertyInitialization": false,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "@types/**/*",
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}