{"_id":"@edcarroll/koa-router-decorators","_rev":"3-7d3eb57183f0e4145c8c63a0b9db590b","name":"@edcarroll/koa-router-decorators","description":"Convenience decorators for koa-router","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@edcarroll/koa-router-decorators","version":"1.0.0","description":"Convenience decorators for koa-router","main":"index.js","typings":"index.d.ts","dependencies":{"@types/koa":"^2.0.32","@types/koa-router":"^7.0.20","@types/node":"^6.0.38","koa-router":"^7.0.1","reflect-metadata":"^0.1.8"},"devDependencies":{"typescript":"~2.0.2"},"scripts":{"prepublish":"tsc"},"repository":{"type":"git","url":"git+https://github.com/edcarroll/koa-router-decorators.git"},"author":{"name":"Edward Carroll"},"license":"MIT","bugs":{"url":"https://github.com/edcarroll/koa-router-decorators/issues"},"homepage":"https://github.com/edcarroll/koa-router-decorators#readme","gitHead":"43e2218c9526e8f75e0c591674d035d3c55c5365","_id":"@edcarroll/koa-router-decorators@1.0.0","_shasum":"16b6df328a35d72ae06c6b65fcaad1e874b67009","_from":".","_npmVersion":"3.10.10","_nodeVersion":"7.2.1","_npmUser":{"name":"edcarroll","email":"ed@edcarroll.co.uk"},"dist":{"shasum":"16b6df328a35d72ae06c6b65fcaad1e874b67009","tarball":"https://registry.npmjs.org/@edcarroll/koa-router-decorators/-/koa-router-decorators-1.0.0.tgz","integrity":"sha512-ZjhSiN2MUUw48YHvQo95/yqXa9GcEhRhTeRWROvanu/9QSh+V3ro3NsddwpSu4+Q3XDByGa/abm/yTwssSvLNg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDFAAU0nA1yNzg9jhmT7i/6+iWvQXQE/J/+tHlJjhO/2gIgH5iKxZk9sT276+JRTGVI+1/0T5NLlzCssyB1PZwwIx4="}]},"maintainers":[{"name":"edcarroll","email":"ed@edcarroll.co.uk"}],"_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/koa-router-decorators-1.0.0.tgz_1483273407848_0.6933452016673982"}}},"readme":"# Koa Router Decorators\r\n\r\nConvenience decorators for [koa-router](https://github.com/alexmingoia/koa-router/tree/master). Adds concept of controller classes, with route methods on the class.\r\n\r\n## Installation\r\n\r\n```sh\r\n$ npm install --save @edcarroll/koa-router-decorators\r\n```\r\n\r\n## Quickstart\r\n\r\nImport the necessary decorators and the `useController` helper function from the library:\r\n\r\n```typescript\r\nimport * as Koa from \"koa\";\r\nimport * as KoaRouter from \"koa-router\";\r\nimport {Controller, Get, IMiddleware, useController} from \"@edcarroll/koa-router-decorators\";\r\n\r\nconst app = new Koa();\r\nconst router = new KoaRouter();\r\n```\r\n\r\nCreate your first controller:\r\n\r\n```typescript\r\n@Controller('/')\r\nclass RootController {\r\n    @Get('/')\r\n    public helloWorld:IMiddleware[] = [\r\n        async ctx => {\r\n            ctx.body = \"hello, world!\";\r\n        }];\r\n}\r\n```\r\n\r\nConnect the controller to the root router and you're good to go!\r\n\r\n```typescript\r\nuseController(router, new RootController());\r\n\r\napp.use(router.routes());\r\napp.use(router.allowedMethods());\r\n\r\napp.listen(20000);\r\n```\r\n\r\n## Decorators\r\n\r\n### @Controller(pathPrefix:string, ...middleware?:IMiddleware[])\r\n\r\nMarks class as router controller. To make use of the controller either connect it directly to a `KoaRouter` instance with `useController` or nest it within an existing controller using `@NestedController`.\r\n\r\nRoutes are defined on the controller itself, as properties, decorated with `@Route` or its equivalent convenience decorators. The `pathPrefix` property is used to prefix each route within the controller's path with a specified string. The `middleware` property is a spread array of middleware that when set are applied to all of the child routes of the controller and its nested controllers.\r\n\r\n#### Path Prefix Usage\r\n\r\n```typescript\r\n@Controller('/demo')\r\nclass DemoController {\r\n    @Get('/')\r\n    public demo:IMiddleware[] = [async ctx => ctx.body = \"demo\"];\r\n}\r\n\r\n// GET /demo/ : 200 : \"demo\"\r\n```\r\n\r\n#### Middleware Usage\r\n\r\n```typescript\r\nimport {Controller, Get, Post} from \"@edcarroll/koa-router-decorators\";\r\nimport {loggingMiddleware, authMiddleware} from \"...\";\r\n\r\n@Controller('/demo', loggingMiddleware, authMiddleware)\r\nclass DemoController {\r\n    @Get('/')\r\n    public demo:IMiddleware[] = [async ctx => ctx.body = \"demo\"];\r\n\r\n    @Post('/')\r\n    public example:IMiddleware[] = [async ctx => ctx.body = \"example\"];\r\n}\r\n\r\n// GET  : /demo : 401\r\n// POST : /demo : 401\r\n```\r\n\r\n### @NestedController()\r\n\r\nNested controllers are how complex controllers can be built up from a single root controller. When you have defined your 'sub-controller' class and decorated it with `@Controller`, place an of it instance within the parent controller with the `@NestedController` decorator.\r\n\r\n#### Usage\r\n\r\n```typescript\r\nimport {Controller, NestedController, Get} from \"@edcarroll/koa-router-decorators\";\r\n\r\n@Controller('/nested')\r\nclass SubController {\r\n    @Get('/route')\r\n    public nested:IMiddleware[] = [async ctx => ctx.body = \"nested\"];\r\n}\r\n\r\n@Controller('/demo')\r\nclass DemoController {\r\n    @NestedController()\r\n    public nestedController = new SubController();\r\n}\r\n\r\n// GET : /demo/nested/route : 200 : \"nested\"\r\n```\r\n\r\n### @Route(method:RequestMethod, path:string)\r\n\r\nDefines a route on the controller. To set up a route, use this to decorate an array of `IMiddleware`. The array of middleware will be attached to the controller, using the provided method and path, and are executed in order.\r\n\r\nRoute parameters work as expected, e.g. `/people/:id` will set `ctx.params.id`.\r\n\r\n#### Usage\r\n\r\n```typescript\r\nimport {Controller, Route, RequestMethod} from \"@edcarroll/koa-router-decorators\";\r\n\r\n@Controller('/')\r\nclass RootController {\r\n    @Route(RequestMethod.Get, '/example')\r\n    public exampleRoute:IMiddleware[] = [\r\n        async (ctx, next) => {\r\n            // 1. This middleware is called first\r\n            ctx.status == 204; // false\r\n\r\n            await next(); // 2. We then await downstream\r\n\r\n            // 4. Control flows back upstream\r\n            ctx.status == 204; // true\r\n        },\r\n        async ctx => {\r\n            ctx.status = 204; // 3. This middleware is called, changing the status then returning\r\n        }];\r\n}\r\n\r\n// GET : /example : 204\r\n```\r\n\r\n### @Get(path:string), @Put(...), @Post(...)...\r\n\r\nThese are convenience decorators, and are each shorthand for `@Route(RequestMethod.[Get|Put|Post|...], path)`\r\n\r\n#### Usage\r\n\r\n```typescript\r\n@Controller('/')\r\nclass DemoController {\r\n    @Get('/example')\r\n    @Post('/example')\r\n    public example:IMiddleware[] = [async ctx => ctx.body = \"hello, world!\"];\r\n}\r\n```\r\n\r\n## API\r\n\r\n### useController(router:KoaRouter, controller:any):void\r\n\r\nHelper function that connects a controller to a `KoaRouter` instance. Usually you will only call this function once, when your application starts up.\r\n\r\n#### Usage\r\n\r\n```typescript\r\nimport * as KoaRouter from \"koa-router\";\r\nimport {Controller} from \"@edcarroll/koa-router-decorators\";\r\n\r\nconst router = new KoaRouter();\r\n\r\n@Controller('/')\r\nclass RootController {}\r\n\r\nuseController(router, new RootController());\r\n\r\napp.use(router.routes());\r\napp.use(router.allowedMethods());\r\n```","maintainers":[{"name":"edcarroll","email":"ed@edcarroll.co.uk"}],"time":{"modified":"2022-06-12T17:28:15.440Z","created":"2017-01-01T12:23:29.912Z","1.0.0":"2017-01-01T12:23:29.912Z"},"homepage":"https://github.com/edcarroll/koa-router-decorators#readme","repository":{"type":"git","url":"git+https://github.com/edcarroll/koa-router-decorators.git"},"author":{"name":"Edward Carroll"},"bugs":{"url":"https://github.com/edcarroll/koa-router-decorators/issues"},"license":"MIT","readmeFilename":"README.md"}