UNPKG

type-fest

Version:

A collection of essential TypeScript types

87 lines (64 loc) • 3.07 kB
import type {MatchingKey} from './matching-key.d.ts'; // For `@link` import type {Get} from './get.d.ts'; // For `@link` import type {ValueOf} from './value-of.d.ts'; // For `@link` /** Get the type of a property, or `never` if the key does not exist. Useful for safe indexed access in a generic type, where `BaseType[Key]` is an error because the key may not exist. `BaseType` can be any type, including primitives and `unknown`. A numeric key matches in both its number and string form, like in {@link MatchingKey}. For example, `'0'` reads a `0` key, but `'00'` does not. The type of an optional property includes `undefined`. A union of keys returns a union of the values, and keys that do not exist are ignored. For a union of base types, the key must exist in every member with the same spelling, otherwise the result is `never`. Use {@link ValueOf} to read a key that exists in only some members, and {@link Get} for key paths. An `any` base type returns `any`. A `never`, `unknown`, `null`, `undefined`, or `void` base type returns `never`. A `never` key always returns `never`. Note: An index outside the bounds of a fixed-length tuple returns `undefined`, not `never`. @example ``` import type {PropertyValue} from 'type-fest'; type ErrorCode<ErrorType> = PropertyValue<ErrorType, 'code'>; type A = ErrorCode<{code: 'ENOENT'; message: string}>; //=> 'ENOENT' type B = ErrorCode<Error>; //=> never type StatusMessages = { 200: 'OK'; '404': 'Not found'; }; type C = PropertyValue<StatusMessages, '200'>; //=> 'OK' type D = PropertyValue<StatusMessages, 404 | 500>; //=> 'Not found' ``` @example ``` import type {PropertyValue, ValueOf} from 'type-fest'; type ApiResponse = {status: 'ok'; data: string[]} | {status: 'error'; message: string}; type Status = PropertyValue<ApiResponse, 'status'>; //=> 'ok' | 'error' type Data = PropertyValue<ApiResponse, 'data'>; //=> never // Read a property from only the union members that have it. type SuccessData = ValueOf<ApiResponse, 'data'>; //=> string[] ``` @see {@link MatchingKey} @see {@link ValueOf} @see {@link Get} @category Object */ export type PropertyValue<BaseType, Key extends PropertyKey> = Key extends keyof BaseType ? PropertyValueOfUnion<BaseType, Key> : Key extends number ? `${Key}` extends keyof BaseType ? PropertyValueOfUnion<BaseType, `${Key}`> : never : Key extends `${infer NumberKey extends number}` // A numeric-looking string names a number key only when its spelling survives the conversion. ? `${NumberKey}` extends Key ? NumberKey extends keyof BaseType ? PropertyValueOfUnion<BaseType, NumberKey> : never : never : never; /** Read `Key` from each member of a `BaseType` union. `Key` is resolved against the whole union, so it exists in every member. An undistributed read can widen a declared symbol property's value to `unknown` when another member has a symbol index signature. */ type PropertyValueOfUnion<BaseType, Key extends keyof BaseType> = BaseType extends unknown ? BaseType[Key] : never; export {};