import type {UnknownCollection} from './unknown-collection.d.ts'; import type {NonRecursiveType} from './internal/type.d.ts'; import type {ApplyDefaultOptions} from './apply-default-options.d.ts'; import type {IsAny} from './is-any.d.ts'; import type {IsOptionalKeyOf} from './is-optional-key-of.d.ts'; import type {GreaterThan} from './greater-than.d.ts'; import type {Sum} from './sum.d.ts'; import type {UnknownArray} from './unknown-array.d.ts'; /** Options for the `OptionalPaths` type. @see {@link OptionalPaths} */ export type OptionalPathsOptions = { /** The maximum depth to recurse when searching for optional paths. Range: 0 ~ 10. @default 5 @example ``` import type {OptionalPaths} from 'type-fest'; type Recursive = {foo?: Recursive}; type A = OptionalPaths; //=> 'foo' | 'foo.foo' | 'foo.foo.foo' | 'foo.foo.foo.foo' | 'foo.foo.foo.foo.foo' | 'foo.foo.foo.foo.foo.foo' type B = OptionalPaths; //=> 'foo' | 'foo.foo' | 'foo.foo.foo' | 'foo.foo.foo.foo' type C = OptionalPaths; //=> 'foo' ``` */ maxRecursionDepth?: number; }; type DefaultOptionalPathsOptions = { maxRecursionDepth: 5; }; /** Get a union of all paths to optional properties in the given object. Use-cases: - Can be used in conjunction with `PickDeep`/`OmitDeep` to select/remove all optional properties from an object. For a union, a path is included when the property is optional in any member. @example ``` import type {OptionalPaths} from 'type-fest'; type A = OptionalPaths<{a: {b?: string; c: number}; d?: boolean}>; //=> 'a.b' | 'd' type B = OptionalPaths<[string, number?]>; //=> '1' type C = OptionalPaths<{[x: string]: string; a?: string; b: string}>; //=> 'a' ``` @example ``` import type {OptionalPaths, PickDeep, OmitDeep} from 'type-fest'; type UserFields = { id: string; avatarUrl?: string; role?: string; preferences: { theme: string; alerts?: boolean; }; }; type OptionalUserFields = PickDeep>; //=> { // avatarUrl?: string; // role?: string; // preferences: { // alerts?: boolean; // }; // } type RequiredUserFields = OmitDeep>; //=> {id: string; preferences: {theme: string}} ``` @see {@link OptionalPathsOptions} @category Object @category Array */ export type OptionalPaths = // The paths are always strings. The intersection tells TypeScript so for a generic `BaseType`, which makes `OmitDeep>` valid. _OptionalPaths> & string; type _OptionalPaths, Accumulator extends string = '', CurrentDepth extends number = 0> = BaseType extends Exclude | Exclude // Also, distributes `BaseType` ? never : IsAny extends true ? never : BaseType extends object ? RetrieveOptionalPaths> : never; type ComputeOptionalPaths, Accumulator extends string = '', CurrentDepth extends number = 0> = { [Key in keyof BaseType]-?: // Only string paths are produced, not number keys like `Paths` does, so the result can always be passed to `PickDeep` and `OmitDeep`. | (IsOptionalKeyOf extends true ? `${Accumulator}${Key & (string | number)}` : never) | (GreaterThan extends true // Limit the depth to prevent infinite recursion. ? _OptionalPaths> : never) }; type RetrieveOptionalPaths = PathsObject extends UnknownArray ? PathsObject[number] // Object returned from `ComputeOptionalPaths` for index signatures might look like `{[x: string]: never; a: 'a'}`, // and here if we simply index with `keyof PathsObject`, we would lose the `'a'` path, and just get back `never`. // So, we alias all the keys to `string` creating a union of all the value types and then retrieve the union by indexing with `string`. : {[Key in keyof PathsObject as string]: PathsObject[Key]}[keyof PathsObject extends never ? never : string]; // If `PathsObject` is an empty object, indexing with `string` will produce incorrect result, hence we index conditionally. export {};