{"_id":"@denis_bruns/nestjs-route-handler","_rev":"3-938ffdb67fdab267dbd6c1c11d686842","name":"@denis_bruns/nestjs-route-handler","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@denis_bruns/nestjs-route-handler","version":"0.1.0","keywords":["clean-architecture","typescript","gateway"],"author":{"name":"denis_bruns@protonmail.com"},"license":"MIT","_id":"@denis_bruns/nestjs-route-handler@0.1.0","maintainers":[{"name":"denis_bruns","email":"denis_bruns@protonmail.com"}],"dist":{"shasum":"84d1ed3d9cdb7fb0ba3dac99908c3437443c8f4f","tarball":"https://registry.npmjs.org/@denis_bruns/nestjs-route-handler/-/nestjs-route-handler-0.1.0.tgz","fileCount":13,"integrity":"sha512-73s2QZDDkOl1ENgKKQbS8aUl0kM6DBGk2tjF+Brn6Hv8iRpxN3HSXKySZdsRnyx+BP0pd9IQ6jKU91qToXEB6g==","signatures":[{"sig":"MEYCIQCp93gWcasvhptfWLrONQ7chx9refg3ydlDPzIT6ZaKiQIhAN0C+3vxHyB/UgdR8dTy9Fel3GvztOdimLz/we7N1ejS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62158},"main":"./dist/index.js","types":"./dist/types/index.d.ts","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"gitHead":"768a769cb7fe3a4f19b6182d8f8daf62fbd5c48f","scripts":{"jest":"jest","lint":"eslint src/lib --ext .ts","test":"jest src/tests --detectOpenHandles --forceExit","build":"tsc && npm run postbuild","clean":"rimraf dist","release":"bash release.sh patch","postbuild":"cp package.json README.md dist/","release:major":"bash release.sh major","release:minor":"bash release.sh minor","release:patch":"bash release.sh patch","prepublishOnly":"npm cache clean && npm run build","release:premajor":"bash release.sh premajor","release:prepatch":"bash release.sh prepatch","release:premminor":"bash release.sh preminor","release:prerelease":"bash release.sh prerelease"},"_npmUser":{"name":"denis_bruns","email":"denis_bruns@protonmail.com"},"_npmVersion":"10.8.2","description":"> **A flexible NestJS route handler builder that offers JSON Schema validation, async/Observable flows, and various configurations.**","directories":{},"_nodeVersion":"18.20.5","dependencies":{"ajv":"^8.17.1","rxjs":"^7.8.1","uuid":"^11.0.5","ajv-errors":"^3.0.0","ajv-formats":"^3.0.1","@denis_bruns/core":"^0.1.0","@denis_bruns/reflection":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","axios":"^1.7.9","ts-jest":"^29.2.5","ts-node":"^10.9.2","aws-lambda":"^1.0.7","typescript":"^5.7.2","@types/jest":"^29.5.14","@types/node":"^22.10.6","@types/axios":"^0.9.36","@types/express":"^5.0.0","@types/aws-lambda":"^8.10.147","axios-mock-adapter":"^2.1.0","@denis_bruns/http-axios":"^0.1.2"},"_npmOperationalInternal":{"tmp":"tmp/nestjs-route-handler_0.1.0_1737667314931_0.40611464158804345","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@denis_bruns/nestjs-route-handler","version":"0.1.1","keywords":["clean-architecture","typescript","gateway"],"author":{"name":"denis_bruns@protonmail.com"},"license":"MIT","_id":"@denis_bruns/nestjs-route-handler@0.1.1","maintainers":[{"name":"denis_bruns","email":"denis_bruns@protonmail.com"}],"dist":{"shasum":"1efdf407ea4937977463467890bf9441601fc7ff","tarball":"https://registry.npmjs.org/@denis_bruns/nestjs-route-handler/-/nestjs-route-handler-0.1.1.tgz","fileCount":10,"integrity":"sha512-zWkuV9o+t1sgdPlTBJZLGyT/AGL2KbD7Lu8myOlHYk2BdsRDzljXrlI6STlvZX0QCNxKQpHZTTxvcW2CoRUS3g==","signatures":[{"sig":"MEYCIQDUY4ao8QFdjJM1pMHFGJwV0OTFBA69IyYBQCDO/IOKfwIhALP1ZgYlrHFt6rppyVyAoKGRX0YEDc56FRpkDlRYq81Y","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38329},"main":"./dist/index.js","types":"./dist/types/index.d.ts","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"gitHead":"f89922edcc68a159c00972a7da4d848f8702fee2","scripts":{"jest":"jest","lint":"eslint src/lib --ext .ts","test":"jest src/tests --detectOpenHandles --forceExit","build":"tsc && npm run postbuild","clean":"rimraf dist","release":"bash release.sh patch","postbuild":"cp package.json README.md dist/","release:major":"bash release.sh major","release:minor":"bash release.sh minor","release:patch":"bash release.sh patch","prepublishOnly":"npm cache clean && npm run build","release:premajor":"bash release.sh premajor","release:prepatch":"bash release.sh prepatch","release:premminor":"bash release.sh preminor","release:prerelease":"bash release.sh prerelease"},"_npmUser":{"name":"denis_bruns","email":"denis_bruns@protonmail.com"},"_npmVersion":"10.2.3","description":"> **A flexible NestJS route handler builder that offers JSON Schema validation, async/Observable flows, and various configurations.**","directories":{},"_nodeVersion":"18.19.0","dependencies":{"ajv":"^8.17.1","rxjs":"^7.8.1","uuid":"^11.0.5","ajv-errors":"^3.0.0","ajv-formats":"^3.0.1","@denis_bruns/core":"^0.1.2","@denis_bruns/reflection":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","axios":"^1.7.9","ts-jest":"^29.2.5","ts-node":"^10.9.2","aws-lambda":"^1.0.7","typescript":"^5.7.2","@types/jest":"^29.5.14","@types/node":"^22.10.6","@types/axios":"^0.9.36","@types/express":"^5.0.0","@types/aws-lambda":"^8.10.147","axios-mock-adapter":"^2.1.0","@denis_bruns/http-axios":"^0.1.2"},"_npmOperationalInternal":{"tmp":"tmp/nestjs-route-handler_0.1.1_1737885426534_0.09859689114758319","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@denis_bruns/nestjs-route-handler","version":"0.1.3","main":"./dist/index.js","types":"./dist/types/index.d.ts","exports":{".":{"require":"./dist/index.js","import":"./dist/index.js","types":"./dist/types/index.d.ts"}},"scripts":{"build":"tsc && npm run postbuild","postbuild":"cp package.json README.md dist/","lint":"eslint src/lib --ext .ts","clean":"rimraf dist","prepublishOnly":"npm cache clean && npm run build","release":"bash release.sh patch","release:prerelease":"bash release.sh prerelease","release:minor":"bash release.sh minor","release:major":"bash release.sh major","release:patch":"bash release.sh patch","release:prepatch":"bash release.sh prepatch","release:premminor":"bash release.sh preminor","release:premajor":"bash release.sh premajor","jest":"jest","test":"jest src/tests --detectOpenHandles --forceExit"},"keywords":["clean-architecture","typescript","gateway"],"author":{"name":"denis_bruns@protonmail.com"},"license":"MIT","dependencies":{"@denis_bruns/core":"^0.1.2","@denis_bruns/reflection":"^0.1.0","ajv":"^8.17.1","ajv-errors":"^3.0.0","ajv-formats":"^3.0.1","rxjs":"^7.8.1","uuid":"^11.0.5"},"devDependencies":{"@denis_bruns/http-axios":"^0.1.2","@types/aws-lambda":"^8.10.147","@types/axios":"^0.9.36","@types/express":"^5.0.0","@types/jest":"^29.5.14","@types/node":"^22.10.6","aws-lambda":"^1.0.7","axios":"^1.7.9","axios-mock-adapter":"^2.1.0","jest":"^29.7.0","ts-jest":"^29.2.5","ts-node":"^10.9.2","typescript":"^5.7.2"},"_id":"@denis_bruns/nestjs-route-handler@0.1.3","gitHead":"a3d593550a3d7e417d88cbbddbf27f51d7bcdd67","description":"> **A flexible NestJS route handler builder that offers JSON Schema validation, async/Observable flows, and various configurations.**","_nodeVersion":"18.19.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-UKp/YXD4gbk1E7amPU93jSlNcX95uFbHU/nAZpvd8T4YZrJ+6pvUU6rhn5jsEYiPSxWe3vIDT3OjRCOvtAA0dA==","shasum":"91a6bf9d065f24aa03bcf7c72cac7cf8a68ba93f","tarball":"https://registry.npmjs.org/@denis_bruns/nestjs-route-handler/-/nestjs-route-handler-0.1.3.tgz","fileCount":10,"unpackedSize":38734,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICjKkIaZfOrpUAzkcDKUpi9P0A43h5MljQHbCsd0piTvAiEAyANL+myMB/BfqdWiCVE6d9jUWpA6EOde8ye+B+CG+5c="}]},"_npmUser":{"name":"denis_bruns","email":"denis_bruns@protonmail.com"},"directories":{},"maintainers":[{"name":"denis_bruns","email":"denis_bruns@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nestjs-route-handler_0.1.3_1742152033559_0.5169863755189068"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-23T21:21:54.847Z","modified":"2025-03-16T19:07:13.939Z","0.1.0":"2025-01-23T21:21:55.109Z","0.1.1":"2025-01-26T09:57:06.721Z","0.1.3":"2025-03-16T19:07:13.771Z"},"author":{"name":"denis_bruns@protonmail.com"},"license":"MIT","keywords":["clean-architecture","typescript","gateway"],"description":"> **A flexible NestJS route handler builder that offers JSON Schema validation, async/Observable flows, and various configurations.**","maintainers":[{"name":"denis_bruns","email":"denis_bruns@protonmail.com"}],"readme":"# @denis_bruns/nestjs-route-handler\n\n> **A flexible NestJS route handler builder that offers JSON Schema validation, async/Observable flows, and various configurations.**\n\n[![NPM Version](https://img.shields.io/npm/v/@denis_bruns/nestjs-route-handler?style=flat-square&logo=npm)](https://www.npmjs.com/package/@denis_bruns/nestjs-route-handler)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n[![GitHub](https://img.shields.io/badge/GitHub--181717.svg?style=flat-square&logo=github)](https://github.com/h3llf1r33/nestjs-route-handler)\n\n---\n\n## Overview\n\n`@denis_bruns/nestjs-route-handler` brings together **NestJS**, **RxJS**, and **AJV**-based **JSON Schema** validation to simplify server request handling. It helps you:\n\n- **Validate** request bodies against JSON Schemas at runtime\n- **Reflect** initial body or query parameters using [`@denis_bruns/reflection`](https://www.npmjs.com/package/@denis_bruns/reflection)\n- Build **async** or **Observable**-based flows using your own “use cases” or **inline** handler functions\n- Generate consistent **CORS** and **security** headers out of the box\n- Define **custom** error mappings (HTTP status codes for particular error classes)\n- Enforce a **payload size limit** and optional **request timeout** to guard against resource hogs\n\nThis library is particularly useful in a **clean architecture** or **onion architecture** context, where you separate concerns into **use cases** or **interactors** that run within each request.\n\n---\n\n## Key Features\n\n1. **Inline “Use Case” Functions**\n    - Provide a function that returns an **Observable** or **Promise** to handle the request logic.\n    - Chain multiple handlers in sequence to build complex flows.\n\n2. **JSON Schema Validation**\n    - Validate request bodies using `ajv` for robust error reporting.\n    - Provide your schema in the route config (`bodySchema`).\n\n3. **Reflectors for Body and Query**\n    - Use [`reflect`](https://www.npmjs.com/package/@denis_bruns/reflection) from `@denis_bruns/reflection` to transform request data or extract partial info from nested structures.\n\n4. **CORS & Security Headers**\n    - Built-in **CORS** origin whitelisting.\n    - Default security headers like `Strict-Transport-Security`, `X-Frame-Options`, etc.\n\n5. **Timeout & Payload Size Limits**\n    - **`timeoutMs`** option triggers `RequestTimeoutError` if the use case doesn’t resolve in time.\n    - **`maxResponseSize`** ensures final JSON response isn’t too large, returning `PayloadTooLargeError` if exceeded.\n\n6. **Custom Error-to-Status Mappings**\n    - Map your **custom** or built-in error classes to specific HTTP status codes.\n    - Example: `CustomNotFoundError -> 404`, `CustomAuthError -> 401`, etc.\n\n---\n\n## Installation\n\nWith **npm**:\n\n```bash\nnpm install @denis_bruns/nestjs-route-handler\n```\n\nOr with **yarn**:\n\n```bash\nyarn add @denis_bruns/nestjs-route-handler\n```\n\nYou also need **NestJS** and **Express** (or a Nest platform), plus any optional libraries you want:\n\n```bash\nnpm install ajv ajv-formats ajv-errors rxjs express\n```\n\n---\n\n## Basic Usage\n\nBelow is a **simple** NestJS controller example using `nestJsRouteHandlerBuilder`:\n\n```ts\n// user.controller.ts\nimport { Controller, Post, Req, Res, Next } from '@nestjs/common';\nimport { Request, Response, NextFunction } from 'express';\nimport { nestJsRouteHandlerBuilder } from '@denis_bruns/nestjs-route-handler';\nimport { IUseCaseInlineFunc, IJsonSchema } from '@denis_bruns/core';\n\ninterface UserDTO {\n  email: string;\n  name: string;\n  password: string;\n}\ninterface CreatedUser {\n  id: string;\n  name: string;\n}\n\n// 1) Define your AJV JSON schema\nconst userSchema: IJsonSchema = {\n  type: 'object',\n  properties: {\n    email: { type: 'string', format: 'email' },\n    name: { type: 'string', minLength: 2 },\n    password: { type: 'string', minLength: 8 }\n  },\n  required: ['email', 'name', 'password'],\n  additionalProperties: false\n};\n\n// 2) Example \"use case\" inline function\nconst createUserUseCase: IUseCaseInlineFunc<UserDTO, UserDTO, CreatedUser> = (query) => ({\n  execute: () => {\n    // your create user logic here...\n    return Promise.resolve({ id: '123', name: query.data?.name! });\n  }\n});\n\n@Controller('user')\nexport class UserController {\n  // 3) Build your route handler\n  private readonly createUserHandler = nestJsRouteHandlerBuilder<\n    UserDTO, // The shape for the initial query\n    [typeof createUserUseCase] // A tuple of inline functions\n  >({\n    // A \"reflector\" describing how to pick up data from the request body\n    initialQueryReflector: {\n      data: {\n        email: \"$['body']['email']\",\n        name: \"$['body']['name']\",\n        password: \"$['body']['password']\"\n      }\n    },\n    handlers: [createUserUseCase],\n    bodySchema: userSchema, // JSON Schema for request body\n    timeoutMs: 3000, // optional, throws RequestTimeoutError if over 3s\n    errorToStatusCodeMapping: {\n      400: [], // schema errors default to 400\n      404: [], \n      // ... custom errors\n    }\n  }, {\n    // Handler options\n    corsOriginWhitelist: ['https://mydomain.com'], // or undefined for no restriction\n    maxResponseSize: 3 * 1024 * 1024, // 3 MB\n    headers: {\n      // override default security headers\n      'X-Custom-Header': 'HelloWorld'\n    }\n  });\n\n  @Post()\n  async createUser(@Req() req: Request, @Res() res: Response, @Next() next: NextFunction) {\n    // 4) Just call the built handler (Express-compatible)\n    return await this.createUserHandler(req, res, next);\n  }\n}\n```\n\n### Explanation\n\n1. **`bodySchema`** – `ajv` uses this to validate the request body. If validation fails, an error with `validationErrors` is returned.\n2. **`initialQueryReflector`** – This uses `@denis_bruns/reflection` to parse the relevant fields out of `req.body` (or path/query parameters).\n3. **`handlers`** – The inline function(s) that will be executed in order, each returning an `Observable` or `Promise`.\n4. **`timeoutMs`** & **`maxResponseSize`** – Protect your service from slow or large payloads.\n5. **CORS** – Provide a `corsOriginWhitelist` array to allow specific origins or default to `*`.\n\n### Custom Error Mappings\n\nIf your “use case” throws custom errors, you can map them to specific status codes:\n\n```ts\nclass MyCustomError extends Error {}\n\nconst myUseCase: IUseCaseInlineFunc<UserDTO, UserDTO, CreatedUser> = (query) => ({\n  execute: () => {\n    if (!query.data?.email?.endsWith('@allowed.com')) {\n      throw new MyCustomError('Only allowed.com domain is permitted.');\n    }\n    return Promise.resolve({ id: '777', name: query.data.name! });\n  }\n});\n\nconst handler = nestJsRouteHandlerBuilder<UserDTO, [typeof myUseCase]>({\n  initialQueryReflector: {/* ... */},\n  handlers: [myUseCase],\n  errorToStatusCodeMapping: {\n    418: [MyCustomError], // Return 418 for MyCustomError\n  }\n});\n```\n\n---\n\n## Related Packages\n\n- **@denis_bruns/core**  \n  [![NPM](https://img.shields.io/npm/v/@denis_bruns/core?style=flat-square&logo=npm)](https://www.npmjs.com/package/@denis_bruns/core)  \n  [![GitHub](https://img.shields.io/badge/GitHub--181717.svg?style=flat-square&logo=github)](https://github.com/h3llf1r33/core)  \n  *Core types like `IUseCaseInlineFunc`, `IQueryType`, `IJsonSchema`, and essential error classes.*\n\n- **@denis_bruns/reflection**  \n  [![NPM](https://img.shields.io/npm/v/@denis_bruns/reflection?style=flat-square&logo=npm)](https://www.npmjs.com/package/@denis_bruns/reflection)  \n  [![GitHub](https://img.shields.io/badge/GitHub--181717.svg?style=flat-square&logo=github)](https://github.com/h3llf1r33/reflection)  \n  *Used for the “reflector” mechanism to extract/transform request data via JSONPath or functions.*\n\n---\n\n## Contributing\n\nQuestions, issues, or improvements? Feel free to open a pull request or file an issue on [GitHub](https://github.com/h3llf1r33/nestjs-route-handler).\n\n---\n\n## License\n\nThis project is [MIT licensed](LICENSE).\n\n---\n\n<p align=\"center\">\n  Built with ❤️ by <a href=\"https://github.com/h3llf1r33\">h3llf1r33</a>\n</p>","readmeFilename":"README.md"}