type-fest
Version:
A collection of essential TypeScript types
130 lines (103 loc) • 6.4 kB
TypeScript
import type {AsciiPunctuationCharacter} from './ascii-punctuation-character.d.ts';
import type {WhitespaceCharacter} from './whitespace-character.d.ts';
import type {Alphanumeric, LowercaseLetter, UppercaseLetter} from './characters.d.ts';
import type {IsAny} from './is-any.d.ts';
import type {IsStringLiteral} from './is-string-literal.d.ts';
import type {Simplify} from './simplify.d.ts';
import type {UnwrapPathBrand} from './internal/index.d.ts';
/**
Consume ASCII identifier characters. Other ASCII punctuation or whitespace ends the name, while unsupported name characters make the entire pattern fall back.
*/
type ScanParameterName<Segment extends string, Name extends string> =
Segment extends `${infer Character}${infer Rest}`
? Character extends Alphanumeric | '$' | '_'
? ScanParameterName<Rest, `${Name}${Character}`>
: Character extends AsciiPunctuationCharacter | WhitespaceCharacter
? FinishParameter<Segment, Name>
: never
: {[Key in Name]: string};
/**
Apply a modifier only at the end of a slash-separated segment; otherwise continue scanning literal text and parameters.
*/
type FinishParameter<Segment extends string, Name extends string> =
Segment extends '?' | '*'
? {[Key in Name]?: string | undefined}
: Segment extends '+'
? {[Key in Name]: string}
: {[Key in Name]: string} & SegmentParameters<Segment>;
/**
Read named parameters and literal text in a flat segment. Unsupported syntax returns `never` so the entire pattern can fall back.
*/
type SegmentParameters<Segment extends string> =
Segment extends `:${infer FirstCharacter}${infer Rest}`
? FirstCharacter extends LowercaseLetter | UppercaseLetter | '$' | '_'
? ScanParameterName<Rest, FirstCharacter>
: never
: Segment extends `${infer Character}${infer Rest}`
? Character extends ':' | '?' | '*' | '+' | '(' | '{' | '}' | '\\' | '#'
? never
: SegmentParameters<Rest>
: {};
/**
Collect parameters from slash-separated segments. An unsupported segment makes the whole result `never`, rather than retaining partially extracted parameters.
*/
type ExtractRouteParameters<Pattern extends string, Parameters = {}> =
Pattern extends `${infer Segment}/${infer Rest}`
? ExtractRouteParameters<Rest, Parameters & SegmentParameters<Segment>>
: Parameters & SegmentParameters<Pattern>;
/**
Extract the named parameters from a URL route pattern, like `/users/:id`.
Supports a flat subset of the [URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) pathname syntax: literal text and named parameters, including multiple parameters in one segment like `/flights/:from-:to`. Parameter names must start with an ASCII letter, `$`, or `_`, followed by ASCII letters, digits, `$`, or `_`. Other ASCII punctuation or whitespace ends a name, so `/:id.json` captures `id`.
- `:id` requires the key `id`, with a `string` value.
- `:id?` and `:path*` make the key optional, with a `string | undefined` value. A `*` parameter is conservatively optional even when a zero-length match captures the empty string.
- `:path+` requires the key, with a `string` value. Repeated parameters follow URLPattern semantics and are strings, not arrays.
- A union of literal patterns gives a union of parameter objects.
Modifiers are supported only at the end of a slash-separated segment, including after a literal prefix like `/files/prefix-:path*`. A modifier inside a segment, like `/:id?-suffix`, is unsupported.
Unsupported syntax makes the entire pattern fall back to `Record<string, string | undefined>`, without partially extracting parameters. This includes Unicode parameter names, regular expression groups (`/:id(\\d+)`), brace groups (`/users{/:id}?`), escapes, bare wildcards (`/files/*`), full URLs, search strings, and fragments. For example, `/users/:id/*` falls back without retaining `id`. Use a named catchall like `/files/:path*` instead of a bare wildcard.
The route syntaxes of other routers, like `/blog/[slug]` in Next.js or `/posts/$id` in TanStack Router, are literal text in this syntax, so they give `{}`.
Non-literal patterns, including `string`, `any`, and template literal patterns containing placeholders like `` `${string}` ``, also fall back to `Record<string, string | undefined>`. A `LiteralUnion` preserves its literal members alongside that fallback. This type does not validate patterns at runtime or diagnose every invalid pattern. Validate patterns with `new URLPattern({pathname: pattern})` when needed.
Use-cases:
- Type the `params` that a router passes to a route, from a route pattern constant.
- Type the arguments for building a URL from a pattern.
@example
```
import type {RouteParameters} from 'type-fest';
type A = RouteParameters<'/users/:id'>;
//=> {id: string}
type B = RouteParameters<'/users/:id?'>;
//=> {id?: string | undefined}
type C = RouteParameters<'/users/:id/files/:fileId?'>;
//=> {id: string; fileId?: string | undefined}
type D = RouteParameters<'/files/:folderId/:path*'>;
//=> {folderId: string; path?: string | undefined}
type E = RouteParameters<'/flights/:from-:to'>;
//=> {from: string; to: string}
type F = RouteParameters<'/files/:file.:ext?'>;
//=> {file: string; ext?: string | undefined}
```
@example
```
import type {RouteParameters} from 'type-fest';
declare function createRoute<Pattern extends string>(pattern: Pattern, handler: (parameters: RouteParameters<Pattern>) => Promise<Response>): void;
createRoute('/users/:userId/posts/:postId', ({userId, postId}) => fetch(`/users/${userId}/posts/${postId}`));
createRoute('/about', () => fetch('/about'));
```
@category Template literal
*/
export type RouteParameters<Pattern extends string> =
IsAny<Pattern> extends true
? Record<string, string | undefined>
// Distribute here, inside the `IsAny` check, so a union of patterns shows as a union of parameter objects.
: Pattern extends unknown
? RouteParametersImplementation<UnwrapPathBrand<Pattern>>
: never;
// The brand is unwrapped before checking whether the pattern is a literal or extracting its parameters.
type RouteParametersImplementation<Pattern extends string> =
IsStringLiteral<Pattern> extends true
? ExtractRouteParameters<Pattern> extends infer Parameters
? [Parameters] extends [never]
? Record<string, string | undefined>
: Simplify<Parameters>
: never
: Record<string, string | undefined>;
export {};