@eggjs/router 2.0.0 → 3.0.0

package/README.md

@@ -3,53 +3,60 @@
 Router core component for [Egg.js](https://github.com/eggjs).
 
 > **This repository is a fork of [koa-router](https://github.com/alexmingoia/koa-router).** with some additional features.
-
-> And thanks for the greate work of @alexmingoia and the original team.
+> And thanks for the great work of @alexmingoia and the original team.
 
 ## API Reference
 
-* [egg-router](#module_egg-router)
-    * [Router](#exp_module_egg-router--Router) ⏏
-        * [new Router([opts])](#new_module_egg-router--Router_new)
-        * _instance_
-            * [.get|put|post|patch|delete|del](#module_egg-router--Router+get|put|post|patch|delete|del) ⇒ <code>Router</code>
-            * [.routes](#module_egg-router--Router+routes) ⇒ <code>function</code>
-            * [.use([path], middleware)](#module_egg-router--Router+use) ⇒ <code>Router</code>
-            * [.prefix(prefix)](#module_egg-router--Router+prefix) ⇒ <code>Router</code>
-            * [.allowedMethods([options])](#module_egg-router--Router+allowedMethods) ⇒ <code>function</code>
-            * [.redirect(source, destination, [code])](#module_egg-router--Router+redirect) ⇒ <code>Router</code>
-            * [.route(name)](#module_egg-router--Router+route) ⇒ <code>Layer</code> &#124; <code>false</code>
-            * [.url(name, params, [options])](#module_egg-router--Router+url) ⇒ <code>String</code> &#124; <code>Error</code>
-            * [.param(param, middleware)](#module_egg-router--Router+param) ⇒ <code>Router</code>
-        * _static_
-            * [.url(path, params)](#module_egg-router--Router.url) ⇒ <code>String</code>
+- [@eggjs/router](#eggjsrouter)
+  - [API Reference](#api-reference)
+    - [Router ⏏](#router-)
+      - [new Router(\[opts\])](#new-routeropts)
+      - [router.get|put|post|patch|delete|del ⇒ Router](#routergetputpostpatchdeletedel--router)
+      - [Named routes](#named-routes)
+      - [Multiple middleware](#multiple-middleware)
+    - [Nested routers](#nested-routers)
+      - [Router prefixes](#router-prefixes)
+      - [URL parameters](#url-parameters)
+      - [router.routes ⇒ function](#routerroutes--function)
+      - [router.use(\[path\], middleware) ⇒ Router](#routerusepath-middleware--router)
+      - [router.prefix(prefix) ⇒ Router](#routerprefixprefix--router)
+      - [router.allowedMethods(\[options\]) ⇒ function](#routerallowedmethodsoptions--function)
+      - [router.redirect(source, destination, \[code\]) ⇒ Router](#routerredirectsource-destination-code--router)
+      - [router.route(name) ⇒ Layer | false](#routerroutename--layer--false)
+      - [router.url(name, params, \[options\]) ⇒ String | Error](#routerurlname-params-options--string--error)
+      - [router.param(param, middleware) ⇒ Router](#routerparamparam-middleware--router)
+      - [Router.url(path, params \[, options\]) ⇒ String](#routerurlpath-params--options--string)
+  - [Tests](#tests)
+  - [Breaking changes on v3](#breaking-changes-on-v3)
+  - [License](#license)
 
 <a name="exp_module_egg-router--Router"></a>
 
 ### Router ⏏
+
 **Kind**: Exported class
 <a name="new_module_egg-router--Router_new"></a>
 
 #### new Router([opts])
-Create a new router.
 
+Create a new router.
 
 | Param | Type | Description |
-| --- | --- | --- |
+| ---   | ---   | --- |
 | [opts] | <code>Object</code> |  |
 | [opts.prefix] | <code>String</code> | prefix router paths |
 
 **Example**
 Basic usage:
 
-```javascript
-var Koa = require('koa');
-var Router = require('@eggjs/router');
+```ts
+import Koa from '@eggjs/koa';
+import Router from '@eggjs/router';
 
-var app = new Koa();
-var router = new Router();
+const app = new Koa();
+const router = new Router();
 
-router.get('/', (ctx, next) => {
+router.get('/', async (ctx, next) => {
   // ctx.router available
 });
 
@@ -57,9 +64,11 @@ app
   .use(router.routes())
   .use(router.allowedMethods());
 ```
+
 <a name="module_egg-router--Router+get|put|post|patch|delete|del"></a>
 
 #### router.get|put|post|patch|delete|del ⇒ <code>Router</code>
+
 Create `router.verb()` methods, where *verb* is one of the HTTP verbs such
 as `router.get()` or `router.post()`.
 
@@ -68,7 +77,7 @@ where **verb** is one of the HTTP verbs such as `router.get()` or `router.post()
 
 Additionaly, `router.all()` can be used to match against all methods.
 
-```javascript
+```ts
 router
   .get('/', (ctx, next) => {
     ctx.body = 'Hello World!';
@@ -87,8 +96,8 @@ router
   });
 ```
 
-When a route is matched, its path is available at `ctx._matchedRoute` and if named,
-the name is available at `ctx._matchedRouteName`
+When a route is matched, its path is available at `ctx.routePath` and if named,
+the name is available at `ctx.routeName`
 
 Route paths will be translated to regular expressions using
 [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
@@ -100,7 +109,7 @@ Query strings will not be considered when matching requests.
 Routes can optionally have names. This allows generation of URLs and easy
 renaming of URLs during development.
 
-```javascript
+```ts
 router.get('user', '/users/:id', (ctx, next) => {
  // ...
 });
@@ -113,7 +122,7 @@ router.url('user', 3);
 
 Multiple middleware may be given:
 
-```javascript
+```ts
 router.get(
   '/users/:id',
   (ctx, next) => {
@@ -133,9 +142,9 @@ router.get(
 
 Nesting routers is supported:
 
-```javascript
-var forums = new Router();
-var posts = new Router();
+```ts
+const forums = new Router();
+const posts = new Router();
 
 posts.get('/', (ctx, next) => {...});
 posts.get('/:pid', (ctx, next) => {...});
@@ -149,8 +158,8 @@ app.use(forums.routes());
 
 Route paths can be prefixed at the router level:
 
-```javascript
-var router = new Router({
+```ts
+const router = new Router({
   prefix: '/users'
 });
 
@@ -162,7 +171,7 @@ router.get('/:id', ...); // responds to "/users/:id"
 
 Named route parameters are captured and added to `ctx.params`.
 
-```javascript
+```ts
 router.get('/:category/:title', (ctx, next) => {
   console.log(ctx.params);
   // => { category: 'programming', title: 'how-to-node' }
@@ -175,7 +184,7 @@ used to convert paths to regular expressions.
 **Kind**: instance property of <code>[Router](#exp_module_egg-router--Router)</code>
 
 | Param | Type | Description |
-| --- | --- | --- |
+| ---   | ---  | --- |
 | path | <code>String</code> |  |
 | [middleware] | <code>function</code> | route middleware(s) |
 | callback | <code>function</code> | route callback |
@@ -189,6 +198,7 @@ Returns router middleware which dispatches a route matching the request.
 <a name="module_egg-router--Router+use"></a>
 
 #### router.use([path], middleware) ⇒ <code>Router</code>
+
 Use given middleware.
 
 Middleware run in the order they are defined by `.use()`. They are invoked
@@ -204,7 +214,8 @@ sequentially, requests start at the first middleware and work their way
 | [...] | <code>function</code> |
 
 **Example**
-```javascript
+
+```ts
 // session middleware will run before authorize
 router
   .use(session())
@@ -218,9 +229,11 @@ router.use(['/users', '/admin'], userAuth());
 
 app.use(router.routes());
 ```
+
 <a name="module_egg-router--Router+prefix"></a>
 
 #### router.prefix(prefix) ⇒ <code>Router</code>
+
 Set the path prefix for a Router instance that was already initialized.
 
 **Kind**: instance method of <code>[Router](#exp_module_egg-router--Router)</code>
@@ -230,12 +243,15 @@ Set the path prefix for a Router instance that was already initialized.
 | prefix | <code>String</code> |
 
 **Example**
-```javascript
+
+```ts
 router.prefix('/things/:thing_id')
 ```
+
 <a name="module_egg-router--Router+allowedMethods"></a>
 
 #### router.allowedMethods([options]) ⇒ <code>function</code>
+
 Returns separate middleware for responding to `OPTIONS` requests with
 an `Allow` header containing the allowed methods, as well as responding
 with `405 Method Not Allowed` and `501 Not Implemented` as appropriate.
@@ -250,12 +266,13 @@ with `405 Method Not Allowed` and `501 Not Implemented` as appropriate.
 | [options.methodNotAllowed] | <code>function</code> | throw the returned value in place of the default MethodNotAllowed error |
 
 **Example**
-```javascript
-var Koa = require('koa');
-var Router = require('egg-router');
 
-var app = new Koa();
-var router = new Router();
+```ts
+import Koa from '@eggjs/koa';
+import Router from '@eggjs/router';
+
+const app = new Koa();
+const router = new Router();
 
 app.use(router.routes());
 app.use(router.allowedMethods());
@@ -263,13 +280,13 @@ app.use(router.allowedMethods());
 
 **Example with [Boom](https://github.com/hapijs/boom)**
 
-```javascript
-var Koa = require('koa');
-var Router = require('egg-router');
-var Boom = require('boom');
+```ts
+import Koa from '@eggjs/koa';
+import Router from '@eggjs/router';
+import Boom from 'boom';
 
-var app = new Koa();
-var router = new Router();
+const app = new Koa();
+const router = new Router();
 
 app.use(router.routes());
 app.use(router.allowedMethods({
@@ -278,9 +295,11 @@ app.use(router.allowedMethods({
   methodNotAllowed: () => new Boom.methodNotAllowed()
 }));
 ```
+
 <a name="module_egg-router--Router+redirect"></a>
 
 #### router.redirect(source, destination, [code]) ⇒ <code>Router</code>
+
 Redirect `source` to `destination` URL with optional 30x status `code`.
 
 Both `source` and `destination` can be route names.
@@ -291,7 +310,7 @@ router.redirect('/login', 'sign-in');
 
 This is equivalent to:
 
-```javascript
+```ts
 router.all('/login', ctx => {
   ctx.redirect('/sign-in');
   ctx.status = 301;
@@ -309,6 +328,7 @@ router.all('/login', ctx => {
 <a name="module_egg-router--Router+route"></a>
 
 #### router.route(name) ⇒ <code>Layer</code> &#124; <code>false</code>
+
 Lookup route with given `name`.
 
 **Kind**: instance method of <code>[Router](#exp_module_egg-router--Router)</code>
@@ -320,6 +340,7 @@ Lookup route with given `name`.
 <a name="module_egg-router--Router+url"></a>
 
 #### router.url(name, params, [options]) ⇒ <code>String</code> &#124; <code>Error</code>
+
 Generate URL for route. Takes a route name and map of named `params`.
 
 **Kind**: instance method of <code>[Router](#exp_module_egg-router--Router)</code>
@@ -332,7 +353,8 @@ Generate URL for route. Takes a route name and map of named `params`.
 | [options.query] | <code>Object</code> &#124; <code>String</code> | query options |
 
 **Example**
-```javascript
+
+```ts
 router.get('user', '/users/:id', (ctx, next) => {
   // ...
 });
@@ -354,9 +376,11 @@ router.url('user', { id: 3 }, { query: { limit: 1 } });
 router.url('user', { id: 3 }, { query: "limit=1" });
 // => "/users/3?limit=1"
 ```
+
 <a name="module_egg-router--Router+param"></a>
 
 #### router.param(param, middleware) ⇒ <code>Router</code>
+
 Run middleware for named route parameters. Useful for auto-loading or
 validation.
 
@@ -368,7 +392,8 @@ validation.
 | middleware | <code>function</code> |
 
 **Example**
-```javascript
+
+```ts
 router
   .param('user', (id, ctx, next) => {
     ctx.user = users[id];
@@ -386,9 +411,11 @@ router
   // /users/3 => {"id": 3, "name": "Alex"}
   // /users/3/friends => [{"id": 4, "name": "TJ"}]
 ```
+
 <a name="module_egg-router--Router.url"></a>
 
 #### Router.url(path, params [, options]) ⇒ <code>String</code>
+
 Generate URL from url pattern and given `params`.
 
 **Kind**: static method of <code>[Router](#exp_module_egg-router--Router)</code>
@@ -401,8 +428,9 @@ Generate URL from url pattern and given `params`.
 | [options.query] | <code>Object</code> &#124; <code>String</code> | query options |
 
 **Example**
-```javascript
-var url = Router.url('/users/:id', {id: 1});
+
+```ts
+const url = Router.url('/users/:id', {id: 1});
 // => "/users/1"
 
 const url = Router.url('/users/:id', {id: 1}, {query: { active: true }});
@@ -412,3 +440,12 @@ const url = Router.url('/users/:id', {id: 1}, {query: { active: true }});
 ## Tests
 
 Run tests using `npm test`.
+
+## Breaking changes on v3
+
+- Drop generator function support
+- Drop Node.js < 18.7.0 support
+
+## License
+
+[MIT](LICENSE)

package/dist/commonjs/EggRouter.d.ts

@@ -0,0 +1,102 @@
+import { RegisterOptions, Router, RouterMethod, RouterOptions } from './Router.js';
+import { MiddlewareFunc, ResourcesController } from './types.js';
+interface Application {
+    controller: Record<string, any>;
+}
+/**
+ * FIXME: move these patch into @eggjs/router
+ */
+export declare class EggRouter extends Router {
+    readonly app: Application;
+    /**
+     * @class
+     * @param {Object} opts - Router options.
+     * @param {Application} app - Application object.
+     */
+    constructor(opts: RouterOptions, app: Application);
+    verb(method: RouterMethod | RouterMethod[], nameOrPath: string | RegExp | (string | RegExp)[], pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc, ...middleware: (MiddlewareFunc | string)[]): this;
+    head(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    head(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    options(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    options(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    get(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    get(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    put(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    put(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    patch(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    patch(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    post(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    post(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    delete(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    delete(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    all(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    all(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+    register(path: string | RegExp | (string | RegExp)[], methods: string[], middleware: MiddlewareFunc | string | (MiddlewareFunc | string | ResourcesController)[], opts?: RegisterOptions): import("./Layer.js").Layer | import("./Layer.js").Layer[];
+    /**
+     * restful router api
+     * @param {String} name - Router name
+     * @param {String} prefix - url prefix
+     * @param {Function} middleware - middleware or controller
+     * @example
+     * ```js
+     * app.resources('/posts', 'posts')
+     * app.resources('posts', '/posts', 'posts')
+     * app.resources('posts', '/posts', app.role.can('user'), app.controller.posts)
+     * ```
+     *
+     * Examples:
+     *
+     * ```js
+     * app.resources('/posts', 'posts')
+     * ```
+     *
+     * yield router mapping
+     *
+     * Method | Path            | Route Name     | Controller.Action
+     * -------|-----------------|----------------|-----------------------------
+     * GET    | /posts          | posts          | app.controller.posts.index
+     * GET    | /posts/new      | new_post       | app.controller.posts.new
+     * GET    | /posts/:id      | post           | app.controller.posts.show
+     * GET    | /posts/:id/edit | edit_post      | app.controller.posts.edit
+     * POST   | /posts          | posts          | app.controller.posts.create
+     * PATCH  | /posts/:id      | post           | app.controller.posts.update
+     * DELETE | /posts/:id      | post           | app.controller.posts.destroy
+     *
+     * app.router.url can generate url based on arguments
+     * ```js
+     * app.router.url('posts')
+     * => /posts
+     * app.router.url('post', { id: 1 })
+     * => /posts/1
+     * app.router.url('new_post')
+     * => /posts/new
+     * app.router.url('edit_post', { id: 1 })
+     * => /posts/1/edit
+     * ```
+     * @return {Router} return route object.
+     * @since 1.0.0
+     */
+    resources(prefix: string, controller: string | ResourcesController): Router;
+    resources(prefix: string, middleware: MiddlewareFunc, controller: string | ResourcesController): Router;
+    resources(name: string, prefix: string, controller: string | ResourcesController): Router;
+    resources(name: string, prefix: string, middleware: MiddlewareFunc, controller: string | ResourcesController): Router;
+    /**
+     * @param {String} name - Router name
+     * @param {Object} params - more parameters
+     * @example
+     * ```js
+     * router.url('edit_post', { id: 1, name: 'foo', page: 2 })
+     * => /posts/1/edit?name=foo&page=2
+     * router.url('posts', { name: 'foo&1', page: 2 })
+     * => /posts?name=foo%261&page=2
+     * ```
+     * @return {String} url by path name and query params.
+     * @since 1.0.0
+     */
+    url(name: string, params?: Record<string, string | number | (string | number)[]>): string;
+    /**
+     * @alias to url()
+     */
+    pathFor(name: string, params?: Record<string, string | number | (string | number)[]>): string;
+}
+export {};