type-fest
Version:
A collection of essential TypeScript types
102 lines (79 loc) • 4.63 kB
TypeScript
import type {ParsePathToStringSegments, KeyToString, UnwrapPathBrand} from './internal/index.d.ts';
import type {IsAny} from './is-any.d.ts';
import type {Get} from './get.d.ts'; // For `@link`
import type {Paths} from './paths.d.ts'; // For `@link`
/**
Convert a path segment that is an array index, like `'0'`, into a number.
*/
type ToIndex<Segment extends string> =
Segment extends `${infer Index extends number}`
// The round trip keeps segments like `'01'` and `'0x10'` as strings, because they are not array indices. It also turns `${number}` into `number`. Negative numbers and exponent forms like `'1e-7'` survive the round trip, but are not array indices either.
? `${Index}` extends Segment
? Segment extends `-${string}` | `${string}e${string}` ? Segment : Index
: Segment
: Segment;
/**
Convert each array index in the given path segments into a number.
*/
type ToIndexes<Segments extends string[]> = {[Index in keyof Segments]: ToIndex<Segments[Index]>};
/**
Convert a property path into a tuple of keys, with numeric indices.
It splits a path like {@link Get} does, with dot notation (`'users.0.name'`) and bracket notation (`'users[0].name'`).
- A key that is a non-negative integer, like `'0'` or `'42'`, becomes a number, and so does `${number}`.
- Other keys stay strings, like `'01'`, `'-1'`, `'1e3'`, and `'9007199254740993'` (which a number cannot hold exactly).
- A number path is read as its string form, so `ParsePath<1.5>` is `[1, 5]`.
- A placeholder in a template literal path, like `${string}`, is read as one key.
- A `string` or `any` path gives `Array<string | number>`. This also applies to the `string` member of `LiteralUnion<'a', string>`.
- A union of paths gives a union of tuples; `never` gives `never`. Path brands are removed before parsing.
Use-cases:
- Type the path for an API that takes an array of keys, like the `name` of an Ant Design form field, or `_.get(object, ['users', 0, 'name'])`.
- Get the paths from {@link Paths} as tuples with `ParsePath<Paths<BaseType>>`.
For a parameter constrained to the result, use a `const` type parameter to preserve literal indices and infer the value at the selected path.
The result is a mutable tuple. To also accept a readonly path, constrain the parameter to `Readonly<ParsePath<…>>`.
This type splits paths without validating their syntax or checking whether the keys exist. Empty keys are preserved, so `ParsePath<''>` is `['']`. Quotes and backslashes are literal characters, so `ParsePath<'a["b"]'>` is `['a', '"b"']`. Escapes like `\.` are not supported. To access keys that contain dots or brackets, pass a tuple directly to `Get`.
@example
```
import type {ParsePath} from 'type-fest';
type A = ParsePath<'users[0].name'>;
//=> ['users', 0, 'name']
type B = ParsePath<'users.0.name'>;
//=> ['users', 0, 'name']
type C = ParsePath<`users.${number}.name`>;
//=> ['users', number, 'name']
```
@example
```
import type {Get, ParsePath, Paths} from 'type-fest';
type FormValues = {
name: string;
tags: string[];
address: {
city: string;
};
};
type FieldPath = ParsePath<Paths<FormValues>>;
//=> ['name'] | ['tags'] | ['address'] | ['tags', number] | ['address', 'city']
declare function getField<const Path extends FieldPath>(path: Path): Get<FormValues, Path>;
const city = getField(['address', 'city']);
//=> string
const tag = getField(['tags', 0]);
//=> string | undefined
```
@category Array
@category Template literal
*/
export type ParsePath<Path extends string | number> =
IsAny<Path> extends true
? Array<string | number>
// Distribute here, inside the `IsAny` check, so a union of paths shows as a union of tuples. Without distribution, it shows as `ToIndexes<…>`, and with distribution at the top level, it shows as `ParsePath<…>`. Without distribution, a function parameter constrained to the result also widens string literals when it is not `const`.
: Path extends unknown
// Normalize each path without collapsing the literal alternatives of `LiteralUnion`.
? ParsePathImplementation<UnwrapPathBrand<Path>>
: never;
// Read the primitive path before testing its width or parsing its segments.
type ParsePathImplementation<Path extends string | number> =
// Check `Path` for the `string & {}` of `LiteralUnion`, because its string form is not `string`. Also check the string form, because checking only `Path` stops a function parameter constrained to the result from inferring string literals when it is not `const`.
string extends Path | KeyToString<Path>
? Array<string | number>
: ToIndexes<ParsePathToStringSegments<KeyToString<Path>>>;
export {};