UNPKG

type-fest

Version:

A collection of essential TypeScript types

495 lines (393 loc) • 17.2 kB
import type {UnknownCollection} from './unknown-collection.d.ts'; import type {NonRecursiveType, KeyToString, CountExactInArray} from './internal/index.d.ts'; import type {IsNumberLike} from './is-number-like.d.ts'; import type {ApplyDefaultOptions} from './apply-default-options.d.ts'; import type {IsAny} from './is-any.d.ts'; import type {UnknownArray} from './unknown-array.d.ts'; import type {GreaterThan} from './greater-than.d.ts'; import type {IsNever} from './is-never.d.ts'; import type {ExtendsStrict} from './extends-strict.d.ts'; import type {Sum} from './sum.d.ts'; import type {And} from './and.d.ts'; import type {OptionalKeysOf} from './optional-keys-of.d.ts'; import type {OptionalPaths} from './optional-paths.d.ts'; // For `@link` import type {NonNullableDeep} from './non-nullable-deep.d.ts'; // For `@link` import type {ConditionalKeys} from './conditional-keys.d.ts'; // For `@link` /** Options for the `Paths` type. @see {@link Paths} */ export type PathsOptions = { /** The maximum depth to recurse when searching for paths. Range: 0 ~ 10. @default 5 */ maxRecursionDepth?: number; /** The maximum number of times to recurse into a circular reference, like a `parent` property that points back to its own type. Use it to limit large self-referencing types without lowering {@link PathsOptions.maxRecursionDepth | `maxRecursionDepth`} for the rest of the type. With `0`, the circular property is included, but `Paths` does not go into it. `maxRecursionDepth` still applies. When {@link PathsOptions.leavesOnly | `leavesOnly`} is `true`, a path that stops at this limit counts as a leaf. @default number @example ``` import type {Paths} from 'type-fest'; type Node = { value: string; parent: Node; }; type A = Paths<Node, {maxCircularDepth: 0}>; //=> 'value' | 'parent' type B = Paths<Node, {maxCircularDepth: 1}>; //=> 'value' | 'parent' | 'parent.value' | 'parent.parent' ``` */ maxCircularDepth?: number; /** Use bracket notation for array indices and numeric object keys. @default false @example ``` import type {Paths} from 'type-fest'; type ArrayExample = { array: ['foo']; }; type A = Paths<ArrayExample, {bracketNotation: false}>; //=> 'array' | 'array.0' type B = Paths<ArrayExample, {bracketNotation: true}>; //=> 'array' | 'array[0]' ``` @example ``` import type {Paths} from 'type-fest'; type NumberKeyExample = { 1: ['foo']; }; type A = Paths<NumberKeyExample, {bracketNotation: false}>; //=> 1 | '1' | '1.0' type B = Paths<NumberKeyExample, {bracketNotation: true}>; //=> '[1]' | '[1][0]' ``` */ bracketNotation?: boolean; /** Only include leaf paths in the output. A path whose value can be `null` or `undefined` is also a leaf, even if the value can be an object too. An optional property (`?`) is not a leaf because of its implicit `undefined`, but explicitly including `undefined` in the property type makes it a leaf. To leave out such paths, remove `null` and `undefined` first with {@link NonNullableDeep}. @default false @example ``` import type {Paths} from 'type-fest'; type Post = { id: number; author: { id: number; name: { first: string; last: string; }; }; }; type AllPaths = Paths<Post, {leavesOnly: false}>; //=> 'id' | 'author' | 'author.id' | 'author.name' | 'author.name.first' | 'author.name.last' type LeafPaths = Paths<Post, {leavesOnly: true}>; //=> 'id' | 'author.id' | 'author.name.first' | 'author.name.last' ``` @example ``` import type {Paths} from 'type-fest'; type ArrayExample = { array: Array<{foo: string}>; tuple: [string, {bar: string}]; }; type AllPaths = Paths<ArrayExample, {leavesOnly: false}>; //=> 'array' | 'tuple' | `array.${number}` | `array.${number}.foo` | 'tuple.0' | 'tuple.1' | 'tuple.1.bar' type LeafPaths = Paths<ArrayExample, {leavesOnly: true}>; //=> `array.${number}.foo` | 'tuple.0' | 'tuple.1.bar' ``` @example ``` import type {NonNullableDeep, Paths} from 'type-fest'; type User = { name: string; address: {city: string} | null; }; type LeafPaths = Paths<User, {leavesOnly: true}>; //=> 'name' | 'address' | 'address.city' type NonNullableLeafPaths = Paths<NonNullableDeep<User>, {leavesOnly: true}>; //=> 'name' | 'address.city' ``` */ leavesOnly?: boolean; /** Only include paths at the specified depth. By default all paths up to {@link PathsOptions.maxRecursionDepth | `maxRecursionDepth`} are included. Note: Depth starts at `0` for root properties. @default number @example ``` import type {Paths} from 'type-fest'; type Post = { id: number; author: { id: number; name: { first: string; last: string; }; }; }; type DepthZero = Paths<Post, {depth: 0}>; //=> 'id' | 'author' type DepthOne = Paths<Post, {depth: 1}>; //=> 'author.id' | 'author.name' type DepthTwo = Paths<Post, {depth: 2}>; //=> 'author.name.first' | 'author.name.last' type LeavesAtDepthOne = Paths<Post, {leavesOnly: true; depth: 1}>; //=> 'author.id' ``` */ depth?: number; /** Include paths to the elements of arrays and tuples. When `false`, the path to an array or tuple is still included, but the paths to its elements are not. With {@link PathsOptions.leavesOnly | `leavesOnly`}, the path to an array or tuple then counts as a leaf. If the given type is itself an array or tuple, the result is `never`. Use-case: The paths are used with an API that cannot address array elements, like Firestore field paths. @default true @example ``` import type {Paths} from 'type-fest'; type Project = { filename: string; listA: string[]; listB: [{filename: string}]; folder: { name: string; }; }; type AllPaths = Paths<Project, {recurseIntoArrays: true}>; //=> 'filename' | 'listA' | 'listB' | 'folder' | `listA.${number}` | 'listB.0' | 'listB.0.filename' | 'folder.name' type WithoutArrayPaths = Paths<Project, {recurseIntoArrays: false}>; //=> 'filename' | 'listA' | 'listB' | 'folder' | 'folder.name' type LeafPaths = Paths<Project, {recurseIntoArrays: false; leavesOnly: true}>; //=> 'filename' | 'listA' | 'listB' | 'folder.name' ``` */ recurseIntoArrays?: boolean; /** Only include paths that do not go through an optional key. A key is optional when it has the `?` modifier, so a required key whose type includes `undefined` is still included. Index signatures are not optional, and neither is the `number` index of an array or of a tuple with a rest element. For a union, each member is checked separately, so a key that is optional in one member but required in another is included. With {@link PathsOptions.leavesOnly | `leavesOnly`}, an object whose keys are all optional, or a tuple whose elements are all optional, counts as a leaf, like an empty object. Use-case: Get the paths to the properties that must be present, like the required fields of a config. To get the paths to optional keys instead, use {@link OptionalPaths}. @default false @example ``` import type {Paths} from 'type-fest'; type Project = { filename: string; size?: number; options: { timeout?: number; }; folder: { name: string; subfolder?: { filename: string; }; }; }; type RequiredPaths = Paths<Project, {requiredOnly: true}>; //=> 'filename' | 'options' | 'folder' | 'folder.name' type RequiredLeafPaths = Paths<Project, {requiredOnly: true; leavesOnly: true}>; //=> 'filename' | 'options' | 'folder.name' ``` */ requiredOnly?: boolean; /** Only include paths whose value type is assignable to this type. The checked value is what reading the path gives, so an optional property includes `undefined`: `{name?: string}` matches `string | undefined`, not `string`. A union value is checked as a whole, so `{a: string | number}` does not match `string`. For a single object, these are the matching rules of {@link ConditionalKeys}. Only the value at the end of the path is checked, so a path can still go through an optional property. Add {@link PathsOptions.requiredOnly | `requiredOnly`} to leave those out. Use-case: You want a type-safe way to refer only to the paths that hold a specific kind of value, like every `string` path in a translation object. The default, `unknown`, includes every path. @default unknown @example ``` import type {Paths} from 'type-fest'; type Project = { id: number; title: string; tags: string[]; scores: [number, number]; owner: { name: string; age: number; }; }; type StringPaths = Paths<Project, {valueType: string}>; //=> 'title' | `tags.${number}` | 'owner.name' type NumberPaths = Paths<Project, {valueType: number}>; //=> 'id' | 'scores.0' | 'scores.1' | 'owner.age' ``` @example ``` import type {Paths} from 'type-fest'; // Reading an optional property can give `undefined`, so the matcher needs it. type A = Paths<{name?: string; age: number}, {valueType: string}>; //=> never type B = Paths<{name?: string; age: number}, {valueType: string | undefined}>; //=> 'name' // A union value is checked as a whole. type C = Paths<{value: string | number; name: string}, {valueType: string}>; //=> 'name' ``` */ valueType?: unknown; }; type DefaultPathsOptions = { maxRecursionDepth: 5; maxCircularDepth: number; bracketNotation: false; leavesOnly: false; depth: number; recurseIntoArrays: true; requiredOnly: false; valueType: unknown; }; /** The types that `Paths` does not recurse into. */ type NonRecursivePathsType<Options extends Required<PathsOptions>> = | NonRecursiveType | Exclude<UnknownCollection, UnknownArray> | (Options['recurseIntoArrays'] extends false ? UnknownArray : never); /** The optional keys of the given object, which `Paths` leaves out with `requiredOnly`. */ type KeysToSkip<T extends object, Options extends Required<PathsOptions>> = Options['requiredOnly'] extends true ? OptionalKeysOf<T> : never; /** Whether every key of the given object, or every element of the given tuple, is optional. Symbol keys are ignored, because `Paths` leaves them out. */ type HasOnlyOptionalKeys<Value> = Value extends UnknownArray ? number extends Value['length'] // A non-tuple array or a tuple with a rest element has an index that is not optional. ? false : [] extends Value ? true : false : Value extends object ? IsNever<Exclude<keyof Value & (string | number), OptionalKeysOf<Value>>> : false; /** Generate a union of all possible paths to properties in the given object. It also works with arrays. Use-case: You want a type-safe way to access deeply nested properties in an object. Note: With a `string` index signature at the top level, the result is `string`, because TypeScript merges the other paths, like `` `${string}.a` ``, into `string`. Use {@link PathsOptions.leavesOnly | `leavesOnly`} or {@link PathsOptions.depth | `depth`} to get the nested paths. Note: A key that contains a dot gives a path that reads like a nested path, because every `.` separates two keys. `Paths<{'a.b': {c: number}}>` includes `'a.b.c'`, which `Get`, `PickDeep`, and the other path types read as `a` → `b` → `c`. To read such a key, use the array form of `Get`: `Get<{'a.b': {c: number}}, ['a.b', 'c']>` is `number`. Note: In a generic function, use concrete option values before relying on bracket notation. While any option is generic, TypeScript can read the result as if the default options were used. @example ``` import type {Paths} from 'type-fest'; type Project = { filename: string; listA: string[]; listB: [{filename: string}]; folder: { subfolder: { filename: string; }; }; }; type ProjectPaths = Paths<Project>; //=> 'filename' | 'listA' | 'listB' | 'folder' | `listA.${number}` | 'listB.0' | 'listB.0.filename' | 'folder.subfolder' | 'folder.subfolder.filename' declare function open<Path extends ProjectPaths>(path: Path): void; open('filename'); // Pass open('folder.subfolder'); // Pass open('folder.subfolder.filename'); // Pass // @ts-expect-error open('foo'); // TypeError // Also works with arrays open('listA.1'); // Pass open('listB.0'); // Pass // @ts-expect-error open('listB.1'); // TypeError. Because listB only has one element. ``` @example ``` import type {Paths} from 'type-fest'; type Users = Record<string, {name: string}>; type AllPaths = Paths<Users>; //=> string type LeafPaths = Paths<Users, {leavesOnly: true}>; //=> `${string}.name` ``` @category Object @category Array */ export type Paths<T, Options extends PathsOptions = {}> = // Resolving the options in a conditional type defers it for generic options, so declaration emit keeps this alias instead of expanding the result. ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, Options> extends infer ResolvedOptions extends Required<PathsOptions> ? _Paths<T, ResolvedOptions> : never; type _Paths<T, Options extends Required<PathsOptions>, CurrentDepth extends number = 0, Seen extends unknown[] = []> = T extends NonRecursivePathsType<Options> ? never : IsAny<T> extends true ? never : T extends object // Numeric enum members also accept `number`, so compare printed values to recognize finite limits. ? `${number}` extends `${Options['maxCircularDepth']}` // No limit, so skip tracking the seen types, which would prevent TypeScript from reusing instantiations ? InternalPaths<T, Options, CurrentDepth, Seen, KeysToSkip<T, Options>> : GreaterThan<CountExactInArray<Seen, T>, Options['maxCircularDepth']> extends true // Limit the depth of circular references ? never : InternalPaths<T, Options, CurrentDepth, [...Seen, T], KeysToSkip<T, Options>> : never; // The key map removes optional modifiers from the generated paths, while each value is read from its own required property. type InternalPaths<T, Options extends Required<PathsOptions>, CurrentDepth extends number, Seen extends unknown[], SkippedKey> = {[Key in keyof T]-?: Key extends SkippedKey ? never : Key extends string | number // Leave out the keys in `SkippedKey`, and limit `Key` to `string | number` ? ( And<Options['bracketNotation'], IsNumberLike<Key>> extends true ? `[${Key}]` : CurrentDepth extends 0 // Return both `Key` and `KeyToString<Key>` because for number keys, like `1`, both `1` and `'1'` are valid keys. ? Key | KeyToString<Key> : `.${Key}` ) extends infer TransformedKey extends string | number ? ((Options['leavesOnly'] extends true ? Options['maxRecursionDepth'] extends CurrentDepth ? TransformedKey : IsNever<PathValue<T, Key>> extends true ? TransformedKey : PathValue<T, Key> extends infer Value // For distributing the declared property value ? (Value extends readonly [] | NonRecursivePathsType<Options> ? TransformedKey : IsNever<keyof Value & (string | number)> extends true // Check for empty object & `unknown`, because `keyof unknown` is `never`. Symbol keys are ignored, because they have no paths. ? TransformedKey : (Options['requiredOnly'] extends true ? HasOnlyOptionalKeys<Value> : false) extends true // With `requiredOnly`, a value whose keys are all optional has no paths, so it counts as a leaf like an empty object. ? TransformedKey // Like `_Paths`, skip circular checks when there is no limit and `Seen` is not tracked. : `${number}` extends `${Options['maxCircularDepth']}` ? never : GreaterThan<CountExactInArray<Seen, Value>, Options['maxCircularDepth']> extends true // The path terminates at the circular reference limit, just like it does at `maxRecursionDepth`. ? TransformedKey : never) : never // Should never happen : TransformedKey ) extends infer _TransformedKey // If `depth` is provided, the condition becomes truthy only when it matches `CurrentDepth`. // Otherwise, since `depth` defaults to `number`, the condition is always truthy, returning paths at all depths. ? CurrentDepth extends Options['depth'] // The value is read as a property, so an optional key carries its `undefined`, like `ConditionalKeys`. // The default matcher accepts every value. This branch is required, not just faster: reading `T[Key]` for a generic `T` makes the result irreducible, which breaks constraints like `ParsePath<Paths<T>>`. ? unknown extends Options['valueType'] ? _TransformedKey // An `any` value matches every matcher, like with `ConditionalKeys`. : ExtendsStrict<T[Key], Options['valueType'], {strictAny: false}> extends true ? _TransformedKey : never : never : never) // Recursively generate paths for the current key | (GreaterThan<Options['maxRecursionDepth'], CurrentDepth> extends true // Limit the depth to prevent infinite recursion ? `${TransformedKey}${_Paths<PathValue<T, Key>, Options, Sum<CurrentDepth, 1>, Seen> & (string | number)}` : never) : never : never }[keyof T & (T extends UnknownArray ? number : unknown)]; // Reading one required property removes implicit absence without transforming array elements. type PathValue<Type, Key extends keyof Type> = Required<Pick<Type, Key>>[Key]; export {};