@tinkoff/router 0.1.65 → 0.1.69

package/README.md

@@ -60,14 +60,35 @@ export const myGuard: NavigationGuard = async ({ to }) => {
     return false; // block this transition
   }
 
-  if (to.config.redirect) {
-    return '/login/'; // call a redirect to the specified page
+  if (typeof to.config.redirect === 'string') {
+    return to.config.redirect; // call a redirect to the specified page
+  }
+
+  if (typeof to.config.needAuth && !isAuth()) {
+    return { url: '/login/', code: '302' }; // redirect to page with NavigateOptions
   }
 
   // if nothing is returned, the transition will be performed as usual
 };
+
+router.registerGuard(myGuard);
 ```
 
+#### Rules
+
+- guards are asynchronous and it execution will be awaited inside routing
+- all guards are running in parallel and they are all awaited
+- if several guars return something then the result from a guard that was registered early will be used
+
+#### Possible result
+
+The behaviour of routing depends on the result of executing guards functions and there result might be next:
+
+- if all of the guards returns `undefined` than navigation will continue executing
+- if any of the guards returns `false` than navigation is getting blocked and next action differs on server and client
+- if any of the guards returns `string` it is considered as url to which redirect should be happen
+- if any of the guards returns [`NavigateOptions`](#navigateoptions) interface, `url` property from it is considered as url to which redirect should be happen
+
 ### Transitions hooks
 
 Transition hooks allow you to perform your asynchronous actions at different stages of the transition.
@@ -78,8 +99,27 @@ import { NavigationHook } from '@tinkoff/router';
 export const myHook: NavigationHook = async ({ from, to, url, fromUrl }) => {
   console.log(`navigating from ${from} to route ${to}`);
 };
+
+router.registerHook('beforeNavigate', myHook);
 ```
 
+#### Rules
+
+- all hooks from the same event are running in parallel
+- most of the hooks are asynchronous and are awaited inside router
+- if some error happens when running hook it will be logged to console but wont affect navigation (except for the `beforeResolve` hook - error for it will be rethrown)
+
+#### List of available hooks
+
+Async hooks:
+
+- [navigate hooks](#navigate-hooks) - asynchronous hooks only for navigate calls
+- [updateCurrentRoute hooks](#updatecurrentroute-hooks) - asynchronous hooks only for updateCurrentRoute calls
+
+Sync hooks:
+
+- `change` - runs when any of changes to current route\url happens
+
 ## API
 
 ### Getting data about the current route or url
@@ -102,12 +142,20 @@ router.navigate('/test');
 router.navigate({ url: './test', query: { a: '1' } });
 ```
 
-Transition hooks:
+##### navigate hooks
 
 - beforeResolve
 - beforeNavigate
 - afterNavigate
 
+##### navigate workflow
+
+1. `beforeResolve` hook
+2. [guards](#router-guards)
+3. `beforeNavigate`
+4. `change`
+5. `afterNavigate`
+
 #### updateCurrentRoute
 
 The transition is based on the current route (therefore this method cannot be called on the server) and allows you to simply update some data for the current page
@@ -117,11 +165,24 @@ router.updateCurrentRoute({ params: { id: 'abc' } });
 router.updateCurrentRoute({ query: { a: '1' } });
 ```
 
-Hooks:
+##### updateCurrentRoute hooks
 
 - beforeUpdateCurrent
 - afterUpdateCurrent
 
+##### updateCurrentRoute workflow
+
+1. `beforeUpdateCurrent`
+2. `change`
+3. `afterUpdateCurrent`
+
+### NavigateOptions
+
+Object that allows to specify transition options both to [navigate](#navigate) and [updateCurrentRoute](#updatecurrentroute) transitions
+
+- `code` - redirect code that is returned on server in case of redirects
+- `navigateState` - any additional data that is stored with route
+
 ### Working with query
 
 #### query option
@@ -161,6 +222,11 @@ router.updateCurrentRoute({ query: { a: undefined, c: 'c' }, preserveQuery: true
 router.getCurrentUrl().query; // { b: 'b', c: 'c' }
 ```
 
+### Constructor options
+
+- `trailingSlash` - do router should force all urls to end with slash. If `true` - force trailing slash for every path, `false` - force no trailing slash, `undefined` - trailing slash is specified by request and both trailing and not trailing slashes are used. By default value if `undefined`
+- `mergeSlashes` - replace several consecutive slashes by single slashes (slashes after protocol are still be with `//` after protocol name). By default is `false` - no merge for slashes.
+
 ### Integration with React
 
 Library has some useful React hooks and components for working with routing
@@ -229,3 +295,26 @@ export const WrapLink = () => {
   return <Link url="/test/">Click me</Link>;
 };
 ```
+
+## How to
+
+### Load route config from external api
+
+Use [transition hook](#transitions-hooks) `beforeResolve` and load routes config based on url.
+
+```ts
+router.registerHook('beforeResolve', async (navigation) => {
+  const route = await routeResolve(navigation);
+
+  if (route) {
+    router.addRoute(routeTransform(route));
+  }
+});
+```
+
+### App behind proxy
+
+Router doesn't support proxy setup directly. But proxy still can be used with some limitations:
+
+- setup proxy server to pass requests to app with rewriting request and response paths. (E.g. for [nginx](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect))
+- it wont work as expected on spa navigation on client, so only option in this case is use the `NoSpaRouter`

package/lib/index.browser.js

@@ -220,17 +220,16 @@ class AbstractRouter {
         await this.runHooks('afterUpdateCurrent', navigation);
     }
     async navigate(navigateOptions) {
-        return this.internalNavigate(navigateOptions, {});
+        return this.internalNavigate(typeof navigateOptions === 'string' ? { url: navigateOptions } : navigateOptions, {});
     }
     async internalNavigate(navigateOptions, { history }) {
         var _a;
-        const options = typeof navigateOptions === 'string' ? { url: navigateOptions } : navigateOptions;
-        const { url, replace, params, navigateState, code } = options;
+        const { url, replace, params, navigateState, code } = navigateOptions;
         const prevNavigation = (_a = this.currentNavigation) !== null && _a !== void 0 ? _a : this.lastNavigation;
         if (!url && !prevNavigation) {
             throw new Error('Navigate url should be specified and cannot be omitted for first navigation');
         }
-        const resolvedUrl = this.resolveUrl(options);
+        const resolvedUrl = this.resolveUrl(navigateOptions);
         const { to: from, url: fromUrl } = prevNavigation !== null && prevNavigation !== void 0 ? prevNavigation : {};
         let navigation = {
             type: 'navigate',

package/lib/index.es.js

@@ -220,17 +220,16 @@ class AbstractRouter {
         await this.runHooks('afterUpdateCurrent', navigation);
     }
     async navigate(navigateOptions) {
-        return this.internalNavigate(navigateOptions, {});
+        return this.internalNavigate(typeof navigateOptions === 'string' ? { url: navigateOptions } : navigateOptions, {});
     }
     async internalNavigate(navigateOptions, { history }) {
         var _a;
-        const options = typeof navigateOptions === 'string' ? { url: navigateOptions } : navigateOptions;
-        const { url, replace, params, navigateState, code } = options;
+        const { url, replace, params, navigateState, code } = navigateOptions;
         const prevNavigation = (_a = this.currentNavigation) !== null && _a !== void 0 ? _a : this.lastNavigation;
         if (!url && !prevNavigation) {
             throw new Error('Navigate url should be specified and cannot be omitted for first navigation');
         }
-        const resolvedUrl = this.resolveUrl(options);
+        const resolvedUrl = this.resolveUrl(navigateOptions);
         const { to: from, url: fromUrl } = prevNavigation !== null && prevNavigation !== void 0 ? prevNavigation : {};
         let navigation = {
             type: 'navigate',
@@ -682,13 +681,16 @@ class Router extends AbstractRouter {
         });
         return this.lastNavigation;
     }
-    async run(navigation) {
-        if (this.redirectCode) {
-            return this.redirect(navigation, { url: navigation.url.path, code: this.redirectCode });
-        }
+    async internalNavigate(navigateOptions, internalOptions) {
         // any navigation after initial should be considered as redirects
         if (this.getCurrentRoute()) {
-            return this.redirect(navigation, { url: navigation.url.path, code: navigation.code });
+            return this.redirect(this.lastNavigation, navigateOptions);
+        }
+        return super.internalNavigate(navigateOptions, internalOptions);
+    }
+    async run(navigation) {
+        if (this.redirectCode) {
+            return this.redirect(navigation, { url: navigation.url.href, code: this.redirectCode });
         }
         await super.run(navigation);
     }

package/lib/index.js

@@ -236,17 +236,16 @@ class AbstractRouter {
         await this.runHooks('afterUpdateCurrent', navigation);
     }
     async navigate(navigateOptions) {
-        return this.internalNavigate(navigateOptions, {});
+        return this.internalNavigate(typeof navigateOptions === 'string' ? { url: navigateOptions } : navigateOptions, {});
     }
     async internalNavigate(navigateOptions, { history }) {
         var _a;
-        const options = typeof navigateOptions === 'string' ? { url: navigateOptions } : navigateOptions;
-        const { url, replace, params, navigateState, code } = options;
+        const { url, replace, params, navigateState, code } = navigateOptions;
         const prevNavigation = (_a = this.currentNavigation) !== null && _a !== void 0 ? _a : this.lastNavigation;
         if (!url && !prevNavigation) {
             throw new Error('Navigate url should be specified and cannot be omitted for first navigation');
         }
-        const resolvedUrl = this.resolveUrl(options);
+        const resolvedUrl = this.resolveUrl(navigateOptions);
         const { to: from, url: fromUrl } = prevNavigation !== null && prevNavigation !== void 0 ? prevNavigation : {};
         let navigation = {
             type: 'navigate',
@@ -698,13 +697,16 @@ class Router extends AbstractRouter {
         });
         return this.lastNavigation;
     }
-    async run(navigation) {
-        if (this.redirectCode) {
-            return this.redirect(navigation, { url: navigation.url.path, code: this.redirectCode });
-        }
+    async internalNavigate(navigateOptions, internalOptions) {
         // any navigation after initial should be considered as redirects
         if (this.getCurrentRoute()) {
-            return this.redirect(navigation, { url: navigation.url.path, code: navigation.code });
+            return this.redirect(this.lastNavigation, navigateOptions);
+        }
+        return super.internalNavigate(navigateOptions, internalOptions);
+    }
+    async run(navigation) {
+        if (this.redirectCode) {
+            return this.redirect(navigation, { url: navigation.url.href, code: this.redirectCode });
         }
         await super.run(navigation);
     }

package/lib/router/abstract.d.ts

@@ -45,7 +45,7 @@ export declare abstract class AbstractRouter {
     protected internalUpdateCurrentRoute(updateRouteOptions: UpdateCurrentRouteOptions, { history }: InternalOptions): Promise<void>;
     protected runUpdateCurrentRoute(navigation: Navigation): Promise<void>;
     navigate(navigateOptions: NavigateOptions | string): Promise<void>;
-    protected internalNavigate(navigateOptions: NavigateOptions | string, { history }: InternalOptions): Promise<void>;
+    protected internalNavigate(navigateOptions: NavigateOptions, { history }: InternalOptions): Promise<void>;
     protected runNavigate(navigation: Navigation): Promise<void>;
     protected run(navigation: Navigation): Promise<void>;
     resolve(resolveOptions: NavigateOptions | string, options?: Parameters<AbstractRouter['resolveRoute']>[1]): import("../types").NavigationRoute;

package/lib/router/server.d.ts

@@ -8,6 +8,7 @@ export declare class Router extends AbstractRouter {
     constructor(options: Options);
     protected onRedirect: (navigation: Navigation) => Promise<void>;
     dehydrate(): Promise<Navigation>;
+    protected internalNavigate(navigateOptions: NavigateOptions, internalOptions: any): Promise<void>;
     protected run(navigation: Navigation): Promise<void>;
     protected redirect(navigation: Navigation, target: NavigateOptions): Promise<void>;
     protected notfound(navigation: Navigation): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinkoff/router",
-  "version": "0.1.65",
+  "version": "0.1.69",
   "description": "router",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -14,7 +14,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git@github.com:TinkoffCreditSystems/tramvai.git"
+    "url": "git@github.com:Tinkoff/tramvai.git"
   },
   "scripts": {
     "build": "tramvai-build --for-publish",