import type {MatchingKey} from './matching-key.d.ts'; import type {PropertyValue} from './property-value.d.ts'; import type {IsRecordLike} from './is-record-like.d.ts'; import type {Not} from './not.d.ts'; import type {IsAny} from './is-any.d.ts'; import type {IsEqual} from './is-equal.d.ts'; import type {IsNever} from './is-never.d.ts'; import type {MergeDeep, MergeDeepOptions} from './merge-deep.d.ts'; import type {OverrideProperties} from './override-properties.d.ts'; // For `@link` import type {SetProperty} from './set-property.d.ts'; // For `@link` import type {UnknownArray} from './unknown-array.d.ts'; /** Override existing properties of the given type deeply. Similar to {@link MergeDeep}, but requires overridden keys to exist at every level. Use-cases: - Correcting deeply nested values from an external source, such as an API response, while keeping the shape of the original type. - Catching a property rename or removal in a generated type before a hand-written override silently goes stale. Unlike {@link MergeDeep}, an `Override` key that does not exist in `Original`, or in the original value at the same path, is a type error, unless its value is `never` or the original is an array. Value types can change freely. An override of a record-like object is merged, so keys you do not mention keep their original value. The `Options` parameter is passed to {@link MergeDeep} and does not change which keys are checked. See {@link MergeDeepOptions}. To change the type of a single deeply-nested property using a key path, use {@link SetProperty} instead. It does not require the key to exist. @example ``` import type {OverridePropertiesDeep} from 'type-fest'; type ApiResponse = { id: string; author: { name: string; email: string; }; }; type Corrected = OverridePropertiesDeep; //=> {id: number; author: {name: string; email: `${string}@${string}`}} ``` @example ``` import type {OverridePropertiesDeep} from 'type-fest'; type ApiResponse = { author: { email: string; }; }; // @ts-expect-error `emailAddress` does not exist on `ApiResponse['author']` type Invalid = OverridePropertiesDeep; ``` A key is valid when it is declared on the original, covered by an index signature, or a canonical string or number spelling of a numeric key, such as `0` and `'0'`. Plain strings cannot select declared string enum keys. Keys are checked recursively through values classified by {@link IsRecordLike}, including ordinary class instances, and a missing key is reported at its full path, for example `author.emailAddress`. Known limitations: - Only record-like object values are checked. Arrays, maps, sets, dates, functions, the bare `object` type, and unions containing an excluded value are opaque. An optional value's `undefined` part is ignored. Array elements are never checked, even with `recurseIntoArrays`, which can merge in keys the original lacks. - For a union of record-like objects, only the keys common to every member can be overridden; a union of arrays is opaque. A union `Override` is checked member by member, but a member with an extra key can match another member's check. - Only key existence is checked, not value types. - An unresolved generic in `Original` or `Override` cannot be checked. This also applies to {@link OverrideProperties}. - An `unknown` original only accepts `never`-valued keys (`{}` works), while an `any` original or override gives `any`. A key with a `never` value bypasses the check even when it does not exist, as in {@link OverrideProperties}. - At the root, an `object` rejects every key and a `Map`, `Set`, or `Date` merges to `never`. A root array is opaque, so a non-array override is accepted but merges to `never`. @see {@link OverrideProperties} @see {@link SetProperty} @see {@link MergeDeep} @see {@link MergeDeepOptions} @category Object */ export type OverridePropertiesDeep< Original, Override extends OverridePropertiesDeepCheck, Options extends MergeDeepOptions = {}, > = MergeDeep; /** The constraint for {@link OverridePropertiesDeep}. Every key of `Override` must exist in `Original`, unless its value is `never` or the original is an array, and every record-like object value is checked against the original value at the same path. The mapped type is deliberately not recursive. TypeScript reports a circular constraint when a type parameter's constraint refers to itself through a recursive mapped type, but two aliases that call each other are accepted. The recursion therefore goes through {@link OverridePropertyDeepValue}. */ type OverridePropertiesDeepCheck = { // A `never`, `any`, or array original is opaque, so its keys are not checked. [Key in keyof Override]: [Original] extends [never] | [UnknownArray] ? Override[Key] : IsKnownPropertyKey extends true ? OverridePropertyDeepValue, Override[Key]> : never; }; /** Find the declared key of `Original` that `Key` names, including a canonical numeric spelling of a numeric key and a key covered by an index signature. Returns `never` when `Original` has no such key. */ type DeclaredKeyOf = [Original] extends [object] ? MatchingKey : never; /** Test whether `Key` names a property of `Original`. See {@link DeclaredKeyOf} for the accepted spellings. */ type IsKnownPropertyKey = Not>>; /** Get the value of `Key` in `Original`, matching the spellings described in {@link DeclaredKeyOf}. */ type OriginalPropertyValue = PropertyValue; /** Test whether the original value is a record-like object whose keys can be checked. An `any` original is not checked, and an `object` original has no declared keys. */ type IsCheckableObject = IsAny extends true ? false : IsEqual, object> extends true ? false : IsRecordLike>; /** Check an override value against the original value at the same path. A value that is not a record-like object is returned as it is, because only object keys are checked. The distribution over `Override` checks the object part of an optional property separately from `undefined`. */ type OverridePropertyDeepValue = Override extends unknown ? IsAny extends true ? unknown : IsRecordLike extends true ? IsCheckableObject extends true ? OverridePropertiesDeepCheck, Override> : Override : Override : never; export {};