\n\n# Description\n\nURL Generation is used to dynamically generate URL that point to NestJS controller method (Route).\n\n@anthwal/nestjs-url-generator can generate plain and signed URLs\n\n# Installation\n\n```bash\nnpm i --save @anthwal/nestjs-url-generator\n```\n\nOr if you use Yarn:\n\n```bash\nyarn add @anthwal/nestjs-url-generator\n```\n\n# Requirements\n\n`@anthwal/nestjs-url-generator` is built to work with Nest 7 and newer versions.\n\n# Basic Usage\n\n### Include Module\n\nFirst you need to import [UrlGeneratorModule]:\n\n> app.module.ts\n\n```ts\nimport { UrlGeneratorModule } from '@anthwal/nestjs-url-generator';\n\n@Module({\n imports: [\n UrlGeneratorModule.forRoot({\n secret: 'secret', // optional, required only for signed URL\n appUrl: 'https://localhost:3000',\n }),\n ],\n})\nexport class ApplicationModule {}\n```\n\nOr Async Import With .ENV usage\n\n> .ENV\n\n```.env\nAPP_KEY=secret\nAPP_URL=https://localhost:3000\n```\n\n> signed-url.config.ts\n\n```ts\nimport { UrlGeneratorModuleOptions } from '@anthwal/nestjs-url-generator';\n\nexport function urlGeneratorModuleConfig(): UrlGeneratorModuleOptions {\n return {\n secret: process.env.APP_KEY,\n appUrl: process.env.APP_URL,\n };\n}\n```\n\n> app.module.ts\n\n```ts\nimport { UrlGeneratorModule } from '@anthwal/nestjs-url-generator';\n\n@Module({\n imports: [\n ConfigModule.forRoot(),\n UrlGeneratorModule.forRootAsync({\n useFactory: () => urlGeneratorModuleConfig(),\n }),\n ],\n})\nexport class ApplicationModule {}\n```\n\n## Using Service\n\nNow you need to register the service, by injecting it to the constructor.\nThere are two methods for generating url:\n\n```typescript\ngenerateUrlFromController({\n controller,\n controllerMethod,\n /*?*/ query,\n /*?*/ params,\n});\n\ngenerateUrlFromPath({\n relativePath,\n /*?*/ query,\n /*?*/ params,\n});\n```\n\n> app.controller.ts\n\n```ts\nimport { UrlGeneratorService } from '@anthwal/nestjs-url-generator';\n\n@Controller()\nexport class AppController {\n constructor(private readonly urlGeneratorService: UrlGeneratorService) {}\n\n @Get('makeUrl')\n async makeUrl(): Promise {\n const params = {\n version: '1.0',\n userId: 12,\n };\n\n const query = {\n email: 'email@email',\n };\n\n // This will generate:\n // https://localhost:3000/emailVerification/1.0/12?email=email%40email\n return this.urlGeneratorService.generateUrlFromController({\n controller: AppController,\n controllerMethod: AppController.prototype.emailVerification,\n query: query,\n params: params,\n });\n }\n}\n```\n\n### Generate Signed URL\n\nThere are two methods for generating url:\n\n```typescript\nSignControllerUrl({\n controller,\n controllerMethod,\n /*?*/ expirationDate,\n /*?*/ query,\n /*?*/ params,\n});\n\nSignUrl({\n relativePath,\n /*?*/ expirationDate,\n /*?*/ query,\n /*?*/ params,\n});\n```\n\n> app.controller.ts\n\n```ts\nimport { UrlGeneratorService } from '@anthwal/nestjs-url-generator';\n\n@Controller()\nexport class AppController {\n constructor(private readonly urlGeneratorService: UrlGeneratorService) {}\n\n @Get('makeSignUrl')\n async makeSignUrl(): Promise {\n // This will generate:\n // https://localhost:3000/emailVerification?\n // expirationDate=2021-12-12T00%3A00%3A00.000Z&\n // signed=84b5a021c433d0ee961932ac0ec04d5dd5ffd6f7fdb60b46083cfe474dfae3c0\n return this.urlGeneratorService.SignControllerUrl({\n controller: AppController,\n controllerMethod: AppController.prototype.emailVerification,\n expirationDate: new Date('2021-12-12'),\n // or using DateTime library of your choice\n // will be expired 30 minutes after it was created\n expirationDate: dayjs().add(30, 'minute').toDate(),\n });\n }\n}\n```\n\n- [expirationDate] and [signed] query keys are used for signed URL.\n\n- By default, the signed URLs lives forever.\n You can add expiration date to them at the time of generating one.\n\n### Reminder\n\nThe difference between params & query in ExpressJS\n\n\n \n\n## Using Guard\n\nYou can use SignUrlGuard to verify the signed url in controller.\n\nIf the url has been tampered or when the expiration date is due, then a Forbidden exception will be thrown.\n\n> app.controller.ts\n\n```ts\nimport { SignedUrlGuard } from '@anthwal/nestjs-url-generator';\n\n@Controller()\nexport class AppController {\n constructor(private readonly urlGeneratorService: UrlGeneratorService) {}\n\n @Get('emailVerification')\n @UseGuards(SignedUrlGuard)\n async emailVerification(): Promise {\n return 'You emailed has been verified.';\n }\n}\n```\n\n## Note\n\n- Changing the secret key will invalidate all signed urls\n- Signed URL is typically used for unsubscribe email, email verification, sign file permission, and more.\n\n- If you are using https with reverse proxy please make sure to enable trust proxy in express\n\n```typescript\nconst app = await NestFactory.create(AppModule);\n\napp.set('trust proxy', true);\n// or\nexpressSession({ proxy: true });\n```\n\n## Generating Keys using node REPL\n\n```javascript\nrequire('crypto').randomBytes(64, (err, buf) => {\n if (err) throw err;\n console.log(`${buf.length} bytes of random data: ${buf.toString('base64')}`);\n process.exit();\n});\n```\n\n### TODO\n\n- [ ] Create unit test (expiration, tampered, with or without globalPrefix, request with or without query & param, if target for signerUrl doesn't have guard)\n\n- [ ] Automate CI, npm run build, push, npm publish\n","readmeFilename":"README.md"}
![](\"https://user-images.githubusercontent.com/17086745/97110220-8bf2f780-170a-11eb-9bf4-ca38b8d41be9.png\")
\n![\"NPM](\"https://img.shields.io/npm/v/@anthwal/nestjs-url-generator.svg?style=flat-square&sanitize=true\")
\n \n \n ![\"NPM](\"https://img.shields.io/npm/dm/@anthwal/nestjs-url-generator.svg?style=flat-square&sanitize=true\")
\n \n \n ![\"License\"/](\"https://img.shields.io/npm/l/@anthwal/nestjs-url-generator.svg?colorB=black&label=LICENSE&style=flat-square&sanitize=true\")
\n \n![](\"https://user-images.githubusercontent.com/17086745/97456127-22bdef00-196b-11eb-89d2-d64d4324498d.png\")
\n