UNPKG

type-fest

Version:

A collection of essential TypeScript types

81 lines (65 loc) • 4.26 kB
import type {SimplifyObject} from './internal/object.d.ts'; import type {RequiredKeysOf} from './required-keys-of.d.ts'; import type {_Merge} from './merge.d.ts'; import type {IsAny} from './is-any.d.ts'; import type {If} from './if.d.ts'; import type {IsNever} from './is-never.d.ts'; import type {MatchingKey} from './matching-key.d.ts'; import type {DefaultsFor} from './defaults-for.d.ts'; // For `@link` /** Apply default options to specified options, preserving literal types. Useful for authors of configurable utility types. `Defaults` must give every optional option a default and must not give a default for a required option. Each default must be assignable to its option type. `SpecifiedOptions` must satisfy `Options`, including its required properties. Use {@link DefaultsFor} to define a defaults object. The resolution is shallow, so a nested object is replaced as a whole. A specified option overrides its default. An optional or `undefined`-including specified option uses the default when the declared type does not admit `undefined`, and still overrides when the declared type admits `undefined`, such as `unknown` or `string | undefined`. A numeric key can use either spelling, so `0` and `'0'` name the same option. Every option declared in `Options` is required, and its `readonly` modifier comes from the chosen default or override. @example ``` import type {ApplyDefaultOptions} from 'type-fest'; type FormatOptions = { uppercase?: boolean; prefix?: string; }; type DefaultFormatOptions = { uppercase: false; prefix: ''; }; type Format<Value extends string, Options extends FormatOptions = {}> = FormatWithOptions<Value, ApplyDefaultOptions<FormatOptions, DefaultFormatOptions, Options>>; type FormatWithOptions<Value extends string, Options extends Required<FormatOptions>> = `${Options['prefix']}${Options['uppercase'] extends true ? Uppercase<Value> : Value}`; type Plain = Format<'hello'>; //=> 'hello' type Heading = Format<'hello', {uppercase: true; prefix: '# '}>; //=> '# HELLO' type Resolved = ApplyDefaultOptions<FormatOptions, DefaultFormatOptions, {uppercase?: true}>; //=> {uppercase: false; prefix: ''} ``` Known limitations: - Intended for an object with named properties. Arrays, tuples, and functions are not supported. A string index signature on `Options` blocks defaults for its named options. - A union of option types or a union-valued option uses one resolution, usually the defaults. A `never` option value is not supported. - Extra properties are allowed: an extra specified property is kept unless it can be `undefined`, and extra `Defaults` keys are kept. - With `any` or `never` as `SpecifiedOptions`, the defaults are used, or `never` if `Options` has a required property. - This does not model runtime object spread, so TypeScript may require concrete specified options instead of unresolved generics. @see {@link DefaultsFor} @category Object */ export type ApplyDefaultOptions< Options extends object, Defaults extends SimplifyObject<Omit<Required<Options>, RequiredKeysOf<Options>> & Partial<Record<RequiredKeysOf<Options>, never>>>, SpecifiedOptions extends Options, > = // Keep the resolved type assignable to `Required<Options>` without inferring a result that can widen a specified generic value to its constraint. _ApplyDefaultOptions<Options, Defaults, SpecifiedOptions> extends Required<Options> ? _ApplyDefaultOptions<Options, Defaults, SpecifiedOptions> : never; type _ApplyDefaultOptions< Options extends object, Defaults, SpecifiedOptions, > = If<IsAny<SpecifiedOptions>, Defaults, If<IsNever<SpecifiedOptions>, Defaults, // The overrides are already an object map, so skip `Merge`'s array and equality dispatch. _Merge<Defaults, { // The first `as` branch keeps the key of an option whose declared type admits `undefined`, like `unknown`, because `undefined` is one of its valid values. `-?` then strips the optional modifier, so an unnarrowed options type still resolves instead of failing the `Required<Options>` guard above. [Key in keyof SpecifiedOptions as undefined extends Required<Options>[MatchingKey<Options, Key>] ? Key : undefined extends SpecifiedOptions[Key] ? never : Key ]-?: SpecifiedOptions[Key] }>>>; export {};