UNPKG

type-fest

Version:

A collection of essential TypeScript types

89 lines (74 loc) • 4.36 kB
import type {If} from './if.d.ts'; import type {IsAny} from './is-any.d.ts'; import type {IsLiteral} from './is-literal.d.ts'; import type {MatchingKey} from './matching-key.d.ts'; import type {WithKeyAliases} from './internal/index.d.ts'; import type {UnwrapBrandedPrimitive} from './unwrap-branded-primitive.d.ts'; import type {Tagged} from './tagged.d.ts'; // For `@link` import type {TupleToObject} from './tuple-to-object.d.ts'; // For `@link` /** Transforms an array of objects into a record keyed by one of their properties. When all key values are literals, each key maps to the element it comes from, so a property that only one element has stays available under that element's key. Elements that share a key value are merged into a union under that key. `Object.fromEntries` keeps only the last of them at runtime, so the union is wider than the value you get back. If any key value is not a literal, every key maps to the union of all elements, since their key domains may overlap. Use-cases: - Type a lookup table built from a static list, such as routes by path or commands by name. - Type the result of `Object.fromEntries(items.map(item => [item[key], item]))` without turning every element into the same type. @example ``` import type {ArrayToRecord} from 'type-fest'; const animals = [ {name: 'Shadow', species: 'dog'}, {name: 'Sassy', species: 'cat'}, {name: 'Jake the Dog', species: 'dog', isMagical: true}, ] as const; type Animals = ArrayToRecord<typeof animals, 'name'>; //=> { // Shadow: { // readonly name: 'Shadow'; // readonly species: 'dog'; // }; // Sassy: { // readonly name: 'Sassy'; // readonly species: 'cat'; // }; // 'Jake the Dog': { // readonly name: 'Jake the Dog'; // readonly species: 'dog'; // readonly isMagical: true; // }; // } const animalsByName = Object.fromEntries(animals.map(animal => [animal.name, animal])) as Animals; type IsMagical = Animals['Jake the Dog']['isMagical']; //=> true // A key property that holds a wide `string` gives an index signature type AnyAnimalByName = ArrayToRecord<Array<{name: string; species: string}>, 'name'>; //=> {[x: string]: {name: string; species: string}} ``` Note: Every element must have the key property, and it must hold a `string` or a `number`; any other value type gives `never`. An `any` key value is valid and gives a string index signature, unless another element's key value is invalid, which makes the whole record `never`. A `never` key value gives no key. The key values must be literal to get a key per element, so use `as const` or a `const` type parameter; a wide `string` gives a string index signature, a wide `number` gives a numeric one, and mixing the two gives both. A number and its string spelling, like `1` and `'1'`, are the same key. A branded key value is unwrapped first, so a {@link Tagged} `'a'` gives the key `a`. @see {@link TupleToObject} @category Array */ // The element's key value names its property. `UnwrapBrandedPrimitive` stops a branded value from erasing the key, and `& (string | number)` keeps the mapped key a valid property key for the compiler. Validate each element before combining its key values, so `any` cannot hide another element's invalid key type. export type ArrayToRecord< ArrayType extends readonly object[], KeyProperty extends keyof ArrayType[number] | keyof WithKeyAliases<ArrayType[number]>, > = If<IsAny<ArrayType>, any, false extends HasValidKey<ArrayType[number], KeyProperty> ? never : UnwrapBrandedPrimitive<KeyValues<ArrayType[number], KeyProperty>> & (string | number) extends infer Keys extends string | number ? IsLiteral<Keys> extends true ? {[Item in ArrayType[number] as UnwrapBrandedPrimitive<Item[MatchingKey<Item, KeyProperty>]> & (string | number)]: Item} : Record<Keys, ArrayType[number]> : never>; /** Checks each element separately so an `any` key value cannot erase invalid key values on other elements. */ type HasValidKey<Item extends object, KeyProperty extends PropertyKey> = Item extends unknown ? [Item[MatchingKey<Item, KeyProperty>]] extends [string | number] ? true : false : never; /** Reads the selected property on each element before combining its values. */ type KeyValues<Item extends object, KeyProperty extends PropertyKey> = Item extends unknown ? Item[MatchingKey<Item, KeyProperty>] : never; export {};