type-fest
Version:
A collection of essential TypeScript types
89 lines (74 loc) • 4.36 kB
TypeScript
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 {};