From: Eduardo San Martin Morote Date: Fri, 10 Jun 2022 14:57:49 +0000 (+0200) Subject: chore: types housekeeping X-Git-Tag: v4.1.0~31 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f6f61bf2b93647d626c286e1dd59de004331963d;p=thirdparty%2Fvuejs%2Frouter.git chore: types housekeeping --- diff --git a/packages/router/src/errors.ts b/packages/router/src/errors.ts index c466f9a3..afae094a 100644 --- a/packages/router/src/errors.ts +++ b/packages/router/src/errors.ts @@ -7,7 +7,10 @@ import { import { assign } from './utils' /** - * Flags so we can combine them when checking for multiple errors + * Flags so we can combine them when checking for multiple errors. This is the internal version of + * {@link NavigationFailureType}. + * + * @internal */ export const enum ErrorTypes { // they must be literals to be used as values so we can't write @@ -70,6 +73,11 @@ export interface NavigationFailure extends Error { to: RouteLocationNormalized } +/** + * Internal error used to detect a redirection. + * + * @internal + */ export interface NavigationRedirectError extends Omit { type: ErrorTypes.NAVIGATION_GUARD_REDIRECT diff --git a/packages/router/src/history/common.ts b/packages/router/src/history/common.ts index b203f17b..3476777a 100644 --- a/packages/router/src/history/common.ts +++ b/packages/router/src/history/common.ts @@ -2,12 +2,14 @@ import { isBrowser } from '../utils' import { removeTrailingSlash } from '../location' export type HistoryLocation = string -// pushState clones the state passed and do not accept everything -// it doesn't accept symbols, nor functions as values. It also ignores Symbols as keys /** - * Allowed variables in HTML5 history state + * Allowed variables in HTML5 history state. Note that pushState clones the state + * passed and does not accept everything: e.g it doesn't accept symbols, nor + * functions as values. It also ignores Symbols as keys. + * + * @internal */ -type HistoryStateValue = +export type HistoryStateValue = | string | number | boolean @@ -23,7 +25,13 @@ export interface HistoryState { [x: number]: HistoryStateValue [x: string]: HistoryStateValue } -interface HistoryStateArray extends Array {} + +/** + * Allowed arrays for history.state. + * + * @internal + */ +export interface HistoryStateArray extends Array {} export enum NavigationType { pop = 'pop', diff --git a/packages/router/src/history/hash.ts b/packages/router/src/history/hash.ts index 522b6c9e..f1cedefd 100644 --- a/packages/router/src/history/hash.ts +++ b/packages/router/src/history/hash.ts @@ -3,15 +3,13 @@ import { createWebHistory } from './html5' import { warn } from '../warning' /** - * Creates a hash history. Useful for web applications with no host (e.g. - * `file://`) or when configuring a server to handle any URL is not possible. + * Creates a hash history. Useful for web applications with no host (e.g. `file://`) or when configuring a server to + * handle any URL is not possible. * - * @param base - optional base to provide. Defaults to `location.pathname + - * location.search` If there is a `` tag in the `head`, its value will be - * ignored in favor of this parameter **but note it affects all the - * history.pushState() calls**, meaning that if you use a `` tag, it's - * `href` value **has to match this parameter** (ignoring anything after the - * `#`). + * @param base - optional base to provide. Defaults to `location.pathname + location.search` If there is a `` tag + * in the `head`, its value will be ignored in favor of this parameter **but note it affects all the history.pushState() + * calls**, meaning that if you use a `` tag, it's `href` value **has to match this parameter** (ignoring anything + * after the `#`). * * @example * ```js diff --git a/packages/router/src/index.ts b/packages/router/src/index.ts index 9e978d7f..8624db20 100644 --- a/packages/router/src/index.ts +++ b/packages/router/src/index.ts @@ -44,6 +44,9 @@ export type { RouteParamsRaw, RouteParamValue, RouteParamValueRaw, + RouteLocationNamedRaw, + RouteLocationPathRaw, + RouteLocationString, RouteLocationMatched, RouteLocationOptions, RouteRecordRedirectOption, @@ -65,15 +68,26 @@ export type { _RemoveRegexpFromParam, _RemoveUntilClosingPar, _JoinPath as JoinPath, + _ParamDelimiter, + _ParamModifier, } from './types/paths' -export type { RouteNamedMap } from './types/named' +export type { + RouteNamedMap, + RouteStaticPathMap, + RouteNamedInfo, + _RouteRecordNamedBaseInfo, +} from './types/named' export type { Config, RouterTyped } from './typedRouter' export { createRouter } from './router' export type { Router, RouterOptions, RouterScrollBehavior } from './router' export { NavigationFailureType, isNavigationFailure } from './errors' -export type { NavigationFailure } from './errors' +export type { + NavigationFailure, + ErrorTypes, + NavigationRedirectError, +} from './errors' export { onBeforeRouteLeave, diff --git a/packages/router/src/matcher/types.ts b/packages/router/src/matcher/types.ts index cf8e0d2e..f48c7522 100644 --- a/packages/router/src/matcher/types.ts +++ b/packages/router/src/matcher/types.ts @@ -10,7 +10,7 @@ import { ComponentPublicInstance } from 'vue' // normalize component/components into components and make every property always present /** - * Normalized version of a {@link RouteRecord route record} + * Normalized version of a {@link RouteRecord | route record}. */ export interface RouteRecordNormalized { /** diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts index 72d4534f..d6002898 100644 --- a/packages/router/src/router.ts +++ b/packages/router/src/router.ts @@ -149,7 +149,7 @@ export interface RouterOptions extends PathParserOptions { * {@link RouterOptions.stringifyQuery}. * * @example - * Let's say you want to use the package {@link https://github.com/ljharb/qs | qs} + * Let's say you want to use the [qs package](https://github.com/ljharb/qs) * to parse queries, you can provide both `parseQuery` and `stringifyQuery`: * ```js * import qs from 'qs' @@ -207,14 +207,14 @@ export interface Router { listening: boolean /** - * Add a new {@link RouteRecordRaw route record} as the child of an existing route. + * Add a new {@link RouteRecordRaw | route record} as the child of an existing route. * * @param parentName - Parent Route Record where `route` should be appended at * @param route - Route Record to add */ addRoute(parentName: RouteRecordName, route: RouteRecordRaw): () => void /** - * Add a new {@link RouteRecordRaw route record} to the router. + * Add a new {@link RouteRecordRaw | route record} to the router. * * @param route - Route Record to add */ @@ -232,13 +232,13 @@ export interface Router { */ hasRoute(name: RouteRecordName): boolean /** - * Get a full list of all the {@link RouteRecord route records}. + * Get a full list of all the {@link RouteRecord | route records}. */ getRoutes(): RouteRecord[] /** - * Returns the {@link RouteLocation normalized version} of a - * {@link RouteLocationRaw route location}. Also includes an `href` property + * Returns the {@link RouteLocation | normalized version} of a + * {@link RouteLocationRaw | route location}. Also includes an `href` property * that includes any existing `base`. By default the `currentLocation` used is * `route.currentRoute` and should only be overridden in advanced use cases. * diff --git a/packages/router/src/types/named.ts b/packages/router/src/types/named.ts index d343262f..a662969f 100644 --- a/packages/router/src/types/named.ts +++ b/packages/router/src/types/named.ts @@ -148,6 +148,7 @@ export type RouteStaticPathMapGeneric = Record< /** * Relevant information about a named route record to deduce its params. + * * @internal */ export interface RouteNamedInfo< diff --git a/packages/router/src/types/paths.ts b/packages/router/src/types/paths.ts index e1888fa2..e2318e34 100644 --- a/packages/router/src/types/paths.ts +++ b/packages/router/src/types/paths.ts @@ -41,7 +41,7 @@ export type _ParamModifier = '+' | '?' | '*' * * @internal */ -type _ParamDelimiter = +export type _ParamDelimiter = | '-' | '/' | '%' @@ -153,7 +153,7 @@ export type _ParamToObject< * Takes the custom regex (and everything after) of a param and strips it off. * * @example - * - `\\d+(?:inner-group\\)-end)/:rest-of-url` -> `/:rest-of-url` + * - `\\d+(?:inner-group\\)-end)/:rest-of-url` becomes `/:rest-of-url` * * @internal */ @@ -260,7 +260,7 @@ type _PossibleModifierValue = | readonly never[] /** - * Recursively builds a path from a {param} based path + * Recursively builds a path from a param based path with curly braces (e.g. `\{id\}`). * * @internal */