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 `${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 = {[Index in keyof Segments]: ToIndex}; /** 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`. 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>`. 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>`. 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>; //=> ['name'] | ['tags'] | ['address'] | ['tags', number] | ['address', 'city'] declare function getField(path: Path): Get; const city = getField(['address', 'city']); //=> string const tag = getField(['tags', 0]); //=> string | undefined ``` @category Array @category Template literal */ export type ParsePath = IsAny extends true ? Array // 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> : never; // Read the primitive path before testing its width or parsing its segments. type ParsePathImplementation = // 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 ? Array : ToIndexes>>; export {};