From 51cf98c5feb5fbbd8228fd5834a093cebdd09e43 Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Thu, 25 Aug 2022 20:38:24 +1000 Subject: [PATCH 1/4] docs(api): enhance abortNavigation util --- .../content/3.api/3.utils/abort-navigation.md | 52 ++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/content/3.api/3.utils/abort-navigation.md b/docs/content/3.api/3.utils/abort-navigation.md index 9271f599132..23cefa57fde 100644 --- a/docs/content/3.api/3.utils/abort-navigation.md +++ b/docs/content/3.api/3.utils/abort-navigation.md @@ -1,10 +1,16 @@ # `abortNavigation` +`abortNavigation` is a helper function that prevents the navigation from taking place. + +## Usage + ```ts abortNavigation(err?: Error | string): false ``` -* **err**: Optional error to be thrown by `abortNavigation()`. +`abortNavigation` takes one optional argument which can be of type `string` or an `Error` object. + +- **err**: Optional error to be thrown by `abortNavigation()`. ::alert{type="warning"} `abortNavigation()` is only usable inside a [route middleware handler](/guide/directory-structure/middleware). @@ -12,5 +18,49 @@ abortNavigation(err?: Error | string): false Inside a route middleware handler, `abortNavigation()` will abort navigation, and throw an error if one is set as a parameter. +## Examples + +The example below shows how you can use `abortNavigation` in route middleware to prevent unauthorised route access. + +```jsx +// middleware/auth.ts +export default defineNuxtRouteMiddleware((to, from) => { + const user = useState('user') + if (!user.value.isAuthorized) { + abortNavigation() + } + return navigateTo('/edit-post') +}) +``` + +### `err` as a string + +You can pass the error as a `string`. + +```ts [middleware/auth.ts] +export default defineNuxtRouteMiddleware((to, from) => { + const auth = useState('auth') + if (!user.value.isAuthorized) { + abortNavigation('This feature requires special permission.') + } +}) +``` + +### `err` as an Error object + +You can pass the error as an `Error` object that includes the error code and a message. + +```ts [middleware/auth.ts] +export default defineNuxtRouteMiddleware((to, from) => { + const auth = useState('auth') + if (to.params.id === '1') { + abortNavigation({ + statusCode: 401, + statusMessage: "This feature requires special permission." + }) + } +}) +``` + ::ReadMore{link="/guide/features/routing"} :: From 492a6ab8a1ff5c3fd6b2243ba2dc677b9b6b0a49 Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Thu, 25 Aug 2022 11:53:31 +0100 Subject: [PATCH 2/4] style: spacing --- docs/content/3.api/3.utils/abort-navigation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/3.api/3.utils/abort-navigation.md b/docs/content/3.api/3.utils/abort-navigation.md index 23cefa57fde..225136d8912 100644 --- a/docs/content/3.api/3.utils/abort-navigation.md +++ b/docs/content/3.api/3.utils/abort-navigation.md @@ -56,8 +56,8 @@ export default defineNuxtRouteMiddleware((to, from) => { if (to.params.id === '1') { abortNavigation({ statusCode: 401, - statusMessage: "This feature requires special permission." - }) + statusMessage: 'This feature requires special permission.' + }) } }) ``` From 6f8b2be1a6815b5eda2308871131b0a649cd183c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damian=20G=C5=82owala?= <48835293+DamianGlowala@users.noreply.github.com> Date: Thu, 25 Aug 2022 19:11:28 +0200 Subject: [PATCH 3/4] Update abort-navigation.md --- .../content/3.api/3.utils/abort-navigation.md | 56 ++++++++++--------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/docs/content/3.api/3.utils/abort-navigation.md b/docs/content/3.api/3.utils/abort-navigation.md index 225136d8912..d347903b99c 100644 --- a/docs/content/3.api/3.utils/abort-navigation.md +++ b/docs/content/3.api/3.utils/abort-navigation.md @@ -1,63 +1,65 @@ # `abortNavigation` -`abortNavigation` is a helper function that prevents the navigation from taking place. +`abortNavigation` is a helper function that prevents navigation from taking place and throws an error if one is set as a parameter. -## Usage +::alert{type="warning"} +`abortNavigation` is only usable inside a [route middleware handler](/guide/directory-structure/middleware). +:: + +## Type ```ts abortNavigation(err?: Error | string): false ``` -`abortNavigation` takes one optional argument which can be of type `string` or an `Error` object. +## Parameters -- **err**: Optional error to be thrown by `abortNavigation()`. +### `err` -::alert{type="warning"} -`abortNavigation()` is only usable inside a [route middleware handler](/guide/directory-structure/middleware). -:: +- **Type**: [`Error`](https://developer.mozilla.org/pl/docs/Web/JavaScript/Reference/Global_Objects/Error) | `string` -Inside a route middleware handler, `abortNavigation()` will abort navigation, and throw an error if one is set as a parameter. + Optional error to be thrown by `abortNavigation`. ## Examples -The example below shows how you can use `abortNavigation` in route middleware to prevent unauthorised route access. +The example below shows how you can use `abortNavigation` in a route middleware to prevent unauthorized route access: -```jsx -// middleware/auth.ts +```ts [middleware/auth.ts] export default defineNuxtRouteMiddleware((to, from) => { - const user = useState('user') - if (!user.value.isAuthorized) { + const user = useState('user') + + if (!user.value.isAuthorized) { abortNavigation() } - return navigateTo('/edit-post') + + return navigateTo('/edit-post') }) ``` -### `err` as a string +### `err` as a String -You can pass the error as a `string`. +You can pass the error as a string: ```ts [middleware/auth.ts] export default defineNuxtRouteMiddleware((to, from) => { - const auth = useState('auth') - if (!user.value.isAuthorized) { - abortNavigation('This feature requires special permission.') + const auth = useState('auth') + + if (!user.value.isAuthorized) { + abortNavigation('Insufficient permissions.') } }) ``` -### `err` as an Error object +### `err` as an Error Object -You can pass the error as an `Error` object that includes the error code and a message. +You can pass the error as an [`Error`](https://developer.mozilla.org/pl/docs/Web/JavaScript/Reference/Global_Objects/Error) object, e.g. caught by the `catch`-block: ```ts [middleware/auth.ts] export default defineNuxtRouteMiddleware((to, from) => { - const auth = useState('auth') - if (to.params.id === '1') { - abortNavigation({ - statusCode: 401, - statusMessage: 'This feature requires special permission.' - }) + try { + /* code that might throw an error */ + } catch (err) { + abortNavigation(err) } }) ``` From 237d3fb0f4ad0a3bb30698b78e529cda7588846a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damian=20G=C5=82owala?= <48835293+DamianGlowala@users.noreply.github.com> Date: Thu, 25 Aug 2022 19:37:01 +0200 Subject: [PATCH 4/4] Update docs/content/3.api/3.utils/abort-navigation.md --- docs/content/3.api/3.utils/abort-navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/3.utils/abort-navigation.md b/docs/content/3.api/3.utils/abort-navigation.md index d347903b99c..9b636c5ab13 100644 --- a/docs/content/3.api/3.utils/abort-navigation.md +++ b/docs/content/3.api/3.utils/abort-navigation.md @@ -29,7 +29,7 @@ export default defineNuxtRouteMiddleware((to, from) => { const user = useState('user') if (!user.value.isAuthorized) { - abortNavigation() + return abortNavigation() } return navigateTo('/edit-post')