@eggjs/router 2.0.1 → 3.0.0

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+import { Router } from './Router.js';
+export * from './Router.js';
+export * from './EggRouter.js';
+export declare const KoaRouter: typeof Router;
+export default Router;

package/dist/esm/index.js

@@ -0,0 +1,6 @@
+import { Router } from './Router.js';
+export * from './Router.js';
+export * from './EggRouter.js';
+export const KoaRouter = Router;
+export default Router;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLE1BQU0sRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUVyQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGdCQUFnQixDQUFDO0FBRS9CLE1BQU0sQ0FBQyxNQUFNLFNBQVMsR0FBRyxNQUFNLENBQUM7QUFDaEMsZUFBZSxNQUFNLENBQUMifQ==

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,18 @@
+export type Next = () => Promise<void>;
+export type MiddlewareFunc = (ctx: any, next: Next) => Promise<void> | void;
+export type MiddlewareFuncWithParamProperty = MiddlewareFunc & {
+    param?: string;
+};
+export type ParamMiddlewareFunc = (param: string, ctx: any, next: Next) => Promise<void> | void;
+export type MiddlewareFuncWithRouter<T> = MiddlewareFunc & {
+    router: T;
+};
+export interface ResourcesController {
+    index?: MiddlewareFunc;
+    new?: MiddlewareFunc;
+    create?: MiddlewareFunc;
+    show?: MiddlewareFunc;
+    edit?: MiddlewareFunc;
+    update?: MiddlewareFunc;
+    destroy?: MiddlewareFunc;
+}

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "@eggjs/router",
-  "version": "2.0.1",
+  "version": "3.0.0",
+  "engines": {
+    "node": ">= 18.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "Router middleware for egg/koa. Provides RESTful resource routing.",
   "repository": {
     "type": "git",
@@ -9,10 +15,6 @@
   "bugs": {
     "url": "https://github.com/eggjs/egg/issues"
   },
-  "files": [
-    "lib",
-    "index.js"
-  ],
   "author": "eggjs",
   "keywords": [
     "koa",
@@ -21,41 +23,70 @@
     "route"
   ],
   "dependencies": {
-    "co": "^4.6.0",
-    "debug": "^3.1.0",
-    "http-errors": "^1.3.1",
-    "inflection": "^1.12.0",
-    "is-type-of": "^1.2.1",
-    "koa-compose": "^3.0.0",
-    "koa-convert": "^1.2.0",
-    "methods": "^1.0.1",
+    "http-errors": "^2.0.0",
+    "inflection": "^3.0.0",
+    "is-type-of": "^2.1.0",
+    "koa-compose": "^4.1.0",
+    "methods": "^1.1.2",
     "path-to-regexp": "^1.1.1",
-    "urijs": "^1.19.0",
-    "utility": "^1.15.0"
+    "urijs": "^1.19.11",
+    "utility": "^2.1.0"
   },
   "devDependencies": {
-    "egg-bin": "^4.10.0",
-    "egg-ci": "^1.11.0",
-    "eslint": "^5.13.0",
-    "eslint-config-egg": "^7.1.0",
-    "expect.js": "^0.3.1",
-    "koa": "^2.7.0",
-    "mocha": "^2.0.1",
-    "should": "^6.0.3",
-    "supertest": "^1.0.1"
+    "@eggjs/koa": "^2.18.1",
+    "@eggjs/tsconfig": "^1.3.3",
+    "@types/koa-compose": "^3.2.8",
+    "@types/methods": "^1.1.4",
+    "@types/mocha": "^10.0.6",
+    "@types/supertest": "^6.0.2",
+    "@types/urijs": "^1.19.25",
+    "egg-bin": "6",
+    "eslint": "8",
+    "eslint-config-egg": "13",
+    "git-contributor": "^2.1.5",
+    "supertest": "^1.0.1",
+    "tshy": "^1.15.1",
+    "tshy-after": "^1.0.0",
+    "typescript": "^5.4.5"
   },
   "scripts": {
+    "lint": "eslint src test --ext ts",
+    "pretest": "npm run lint -- --fix && npm run prepublishOnly",
+    "test": "egg-bin test",
     "test-local": "egg-bin test",
-    "test": "npm run lint && egg-bin test",
-    "ci": "npm run lint && egg-bin cov",
-    "lint": "eslint ."
+    "preci": "npm run lint && npm run prepublishOnly",
+    "ci": "egg-bin cov",
+    "contributor": "git-contributor",
+    "prepublishOnly": "tshy && tshy-after",
+    "bench": "cd bench && make"
   },
-  "ci": {
-    "type": "github",
-    "version": "8, 10, 11"
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "tshy": {
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    }
   },
-  "engines": {
-    "node": ">= 8"
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "source": "./src/index.ts",
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "source": "./src/index.ts",
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    }
   },
-  "license": "MIT"
+  "main": "./dist/commonjs/index.js",
+  "types": "./dist/commonjs/index.d.ts"
 }

package/src/EggRouter.ts

@@ -0,0 +1,338 @@
+import assert from 'node:assert';
+import { encodeURIComponent as safeEncodeURIComponent } from 'utility';
+import inflection from 'inflection';
+import methods from 'methods';
+import { RegisterOptions, Router, RouterMethod, RouterOptions } from './Router.js';
+import { MiddlewareFunc, ResourcesController } from './types.js';
+
+interface RestfulOptions {
+  suffix?: string;
+  namePrefix?: string;
+  method: string | string[];
+  member?: true;
+}
+
+const REST_MAP: Record<string, RestfulOptions> = {
+  index: {
+    suffix: '',
+    method: 'GET',
+  },
+  new: {
+    namePrefix: 'new_',
+    member: true,
+    suffix: 'new',
+    method: 'GET',
+  },
+  create: {
+    suffix: '',
+    method: 'POST',
+  },
+  show: {
+    member: true,
+    suffix: ':id',
+    method: 'GET',
+  },
+  edit: {
+    member: true,
+    namePrefix: 'edit_',
+    suffix: ':id/edit',
+    method: 'GET',
+  },
+  update: {
+    member: true,
+    namePrefix: '',
+    suffix: ':id',
+    method: [ 'PATCH', 'PUT' ],
+  },
+  destroy: {
+    member: true,
+    namePrefix: 'destroy_',
+    suffix: ':id',
+    method: 'DELETE',
+  },
+};
+
+interface Application {
+  controller: Record<string, any>;
+}
+
+/**
+ * FIXME: move these patch into @eggjs/router
+ */
+export class EggRouter extends Router {
+  readonly app: Application;
+
+  /**
+   * @class
+   * @param {Object} opts - Router options.
+   * @param {Application} app - Application object.
+   */
+  constructor(opts: RouterOptions, app: Application) {
+    super(opts);
+    this.app = app;
+  }
+
+  verb(method: RouterMethod | RouterMethod[],
+    nameOrPath: string | RegExp | (string | RegExp)[],
+    pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc,
+    ...middleware: (MiddlewareFunc | string)[]) {
+    const { path, middlewares, options } = this._formatRouteParams(nameOrPath, pathOrMiddleware, middleware);
+    if (typeof method === 'string') {
+      method = [ method ];
+    }
+    this.register(path, method, middlewares, options);
+    return this;
+  }
+
+  // const METHODS = [ 'head', 'options', 'get', 'put', 'patch', 'post', 'delete', 'all' ];
+  head(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  head(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  head(nameOrPath: string | RegExp | (string | RegExp)[],
+    pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc,
+    ...middlewares: (MiddlewareFunc | string)[]): Router {
+    return this.verb('head', nameOrPath, pathOrMiddleware, ...middlewares);
+  }
+  options(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  options(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  options(nameOrPath: string | RegExp | (string | RegExp)[],
+    pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc,
+    ...middlewares: (MiddlewareFunc | string)[]): Router {
+    return this.verb('options', nameOrPath, pathOrMiddleware, ...middlewares);
+  }
+  get(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  get(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  get(nameOrPath: string | RegExp | (string | RegExp)[],
+    pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc,
+    ...middlewares: (MiddlewareFunc | string)[]): Router {
+    return this.verb('get', nameOrPath, pathOrMiddleware, ...middlewares);
+  }
+  put(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  put(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  put(nameOrPath: string | RegExp | (string | RegExp)[],
+    pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc,
+    ...middlewares: (MiddlewareFunc | string)[]): Router {
+    return this.verb('put', nameOrPath, pathOrMiddleware, ...middlewares);
+  }
+  patch(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  patch(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  patch(nameOrPath: string | RegExp | (string | RegExp)[],
+    pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc,
+    ...middlewares: (MiddlewareFunc | string)[]): Router {
+    return this.verb('patch', nameOrPath, pathOrMiddleware, ...middlewares);
+  }
+  post(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  post(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  post(nameOrPath: string | RegExp | (string | RegExp)[],
+    pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc,
+    ...middlewares: (MiddlewareFunc | string)[]): Router {
+    return this.verb('post', nameOrPath, pathOrMiddleware, ...middlewares);
+  }
+  delete(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  delete(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  delete(nameOrPath: string | RegExp | (string | RegExp)[],
+    pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc,
+    ...middlewares: (MiddlewareFunc | string)[]): Router {
+    return this.verb('delete', nameOrPath, pathOrMiddleware, ...middlewares);
+  }
+  all(path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  all(name: string, path: string | RegExp | (string | RegExp)[], ...middlewares: (MiddlewareFunc | string)[]): Router;
+  all(nameOrPath: string | RegExp | (string | RegExp)[],
+    pathOrMiddleware: string | RegExp | (string | RegExp)[] | MiddlewareFunc,
+    ...middlewares: (MiddlewareFunc | string)[]): Router {
+    return this.verb(methods, nameOrPath, pathOrMiddleware, ...middlewares);
+  }
+
+  register(path: string | RegExp | (string | RegExp)[],
+    methods: string[],
+    middleware: MiddlewareFunc | string | (MiddlewareFunc | string | ResourcesController)[],
+    opts?: RegisterOptions) {
+    // patch register to support generator function middleware and string controller
+    middleware = Array.isArray(middleware) ? middleware : [ middleware ];
+    const middlewares = convertMiddlewares(middleware, this.app);
+    return super.register(path, methods, middlewares, opts);
+  }
+
+  /**
+   * 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;
+  resources(nameOrPath: string | RegExp, pathOrMiddleware: string | RegExp | MiddlewareFunc | ResourcesController,
+    ...middleware: (MiddlewareFunc | string | ResourcesController)[]): Router {
+    const { path, middlewares, options } = this._formatRouteParams(nameOrPath, pathOrMiddleware, middleware);
+    // last argument is Controller object
+    const controller = resolveController(middlewares.pop()!, this.app);
+    for (const key in REST_MAP) {
+      const action = controller[key] as MiddlewareFunc;
+      if (!action) continue;
+
+      const opts = REST_MAP[key];
+      let routeName;
+      if (opts.member) {
+        routeName = inflection.singularize(options.name ?? '');
+      } else {
+        routeName = inflection.pluralize(options.name ?? '');
+      }
+      if (opts.namePrefix) {
+        routeName = opts.namePrefix + routeName;
+      }
+      const prefix = (path as string).replace(/\/$/, '');
+      const urlPath = opts.suffix ? `${prefix}/${opts.suffix}` : prefix;
+      const method = Array.isArray(opts.method) ? opts.method : [ opts.method ];
+      this.register(urlPath, method, middlewares.concat(action), { name: routeName });
+    }
+    return this;
+  }
+
+  /**
+   * @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 {
+    const route = this.route(name);
+    if (!route) return '';
+
+    const args = params;
+    let url = route.path;
+
+    assert(!(url instanceof RegExp), `Can't get the url for regExp ${url} for by name '${name}'`);
+
+    const queries = [];
+    if (typeof args === 'object' && args !== null) {
+      const replacedParams: string[] = [];
+      url = url.replace(/:([a-zA-Z_]\w*)/g, ($0, key) => {
+        if (key in args) {
+          const values = args[key];
+          replacedParams.push(key);
+          return safeEncodeURIComponent(Array.isArray(values) ? String(values[0]) : String(values));
+        }
+        return $0;
+      });
+
+      for (const key in args) {
+        if (replacedParams.includes(key)) {
+          continue;
+        }
+        const values = args[key];
+        const encodedKey = safeEncodeURIComponent(key);
+        if (Array.isArray(values)) {
+          for (const val of values) {
+            queries.push(`${encodedKey}=${safeEncodeURIComponent(String(val))}`);
+          }
+        } else {
+          queries.push(`${encodedKey}=${safeEncodeURIComponent(String(values))}`);
+        }
+      }
+    }
+
+    if (queries.length > 0) {
+      const queryStr = queries.join('&');
+      if (!url.includes('?')) {
+        url = `${url}?${queryStr}`;
+      } else {
+        url = `${url}&${queryStr}`;
+      }
+    }
+
+    return url;
+  }
+
+  /**
+   * @alias to url()
+   */
+  pathFor(name: string, params?: Record<string, string | number | (string | number)[]>) {
+    return this.url(name, params);
+  }
+}
+
+/**
+ * resolve controller from string to function
+ * @param {String|Function} controller input controller
+ * @param {Application} app egg application instance
+ */
+function resolveController(controller: string | MiddlewareFunc | ResourcesController, app: Application) {
+  if (typeof controller === 'string') {
+    // resolveController('foo.bar.Home', app)
+    const actions = controller.split('.');
+    let obj = app.controller;
+    actions.forEach(key => {
+      obj = obj[key];
+      if (!obj) throw new Error(`app.controller.${controller} not exists`);
+    });
+    controller = obj as any;
+  }
+  // ensure controller is exists
+  if (!controller) throw new Error('controller not exists');
+  return controller as any;
+}
+
+/**
+ * 1. ensure controller(last argument) support string
+ * - [url, controller]: app.get('/home', 'home');
+ * - [name, url, controller(string)]: app.get('posts', '/posts', 'posts.list');
+ * - [name, url, controller]: app.get('posts', '/posts', app.controller.posts.list);
+ * - [name, url(regexp), controller]: app.get('regRouter', /\/home\/index/, 'home.index');
+ * - [name, url, middleware, [...], controller]: `app.get(/user/:id', hasLogin, canGetUser, 'user.show');`
+ *
+ * 2. make middleware support generator function
+ *
+ * @param  {Array} middlewares middlewares and controller(last middleware)
+ * @param  {Application} app  egg application instance
+ */
+function convertMiddlewares(middlewares: (MiddlewareFunc | string | ResourcesController)[], app: Application) {
+  // ensure controller is resolved
+  const controller = resolveController(middlewares.pop()!, app);
+  return [ ...middlewares as MiddlewareFunc[], controller ];
+}