type-fest
Version:
A collection of essential TypeScript types
107 lines (89 loc) • 4.66 kB
TypeScript
import type {IsArrayOfUnknownLength, NonRecursiveType} from './internal/index.d.ts';
import type {IsEqual} from './is-equal.d.ts';
import type {LiteralToPrimitive} from './literal-to-primitive.d.ts';
import type {Primitive} from './primitive.d.ts';
import type {UnknownArray} from './unknown-array.d.ts';
/**
Like `LiteralToPrimitive` except it converts literal types inside an object or array deeply.
For example, given a constant object, it returns a new object type with the same keys but with all the values converted to primitives.
@see {@link LiteralToPrimitive}
Use-case: Deal with data that is imported from a JSON file.
Note: A type that recurses only through a tuple, such as `type List = null | readonly [string, List]`, hits the instantiation depth limit, because a tuple is converted element by element. Recursion through an object property or an array of unknown length, such as `JsonValue`, is fine.
@example
```
import type {LiteralToPrimitiveDeep} from 'type-fest';
const config = {
appName: 'MyApp',
version: '1.0.0',
maxRetries: 3,
enableLogging: true,
apiUrl: 'https://api.myapp.com/v1',
} as const;
declare function updateConfig(newConfig: typeof config): void;
updateConfig({
// @ts-expect-error
appName: 'MyUpdatedApp',
// Error: Type '"MyUpdatedApp"' is not assignable to type '"MyApp"'.
// @ts-expect-error
version: '2.0.0',
// Error: Type '"2.0.0"' is not assignable to type '"1.0.0"'.
// @ts-expect-error
maxRetries: 1,
// Error: Type '1' is not assignable to type '3'.
// @ts-expect-error
enableLogging: false,
// Error: Type 'false' is not assignable to type 'true'.
// @ts-expect-error
apiUrl: 'https://api.myapp.com/v2',
// Error: Type '"https://api.myapp.com/v2"' is not assignable to type '"https://api.myapp.com/v1"'.
});
declare function updateConfigFixed(newConfig: LiteralToPrimitiveDeep<typeof config>): void;
updateConfigFixed({
appName: 'MyUpdatedApp',
version: '2.0.0',
maxRetries: 1,
enableLogging: false,
apiUrl: 'https://api.myapp.com/v2',
});
```
@category Type
@category Object
*/
export type LiteralToPrimitiveDeep<T> =
// `undefined` and `null` are handed back as is rather than through `LiteralToPrimitive`. For an optional key, the `undefined` that its `?` contributes then stays the one TypeScript removes from the result, instead of becoming a new `undefined` that it keeps.
T extends null | undefined
? T
// `unknown` and `any` are not literals, so there is nothing to convert. Checked per union member, because a union such as `'x' | {} | null | undefined` is as wide as `unknown` as a whole.
: unknown extends T
? T
// A branded or tagged primitive is still a primitive, so it is collapsed before the object branches, which would otherwise map over the string methods.
: T extends Primitive
? LiteralToPrimitive<T>
// `void`, functions, class constructors and the other single-value built-ins are kept as is.
: T extends NonRecursiveType
? T
// `object` is not a literal either, and mapping over it would turn it into `{}`, which accepts a string.
: IsEqual<T, object> extends true
? T
: T extends UnknownArray
? IsArrayOfUnknownLength<T> extends false
// A homomorphic mapped type keeps the length, the optional elements, the rest element and `readonly`, without a recursion step per element.
? {[Key in keyof T]: LiteralToPrimitiveDeep<T[Key]>}
// An array of unknown length is rebuilt directly, because mapping it makes a recursive element type, such as `JsonValue`, infinitely deep.
: T extends unknown[]
? Array<LiteralToPrimitiveDeep<T[number]>>
: ReadonlyArray<LiteralToPrimitiveDeep<T[number]>>
: T extends Map<infer KeyType, infer ValueType>
? Map<LiteralToPrimitiveDeep<KeyType>, LiteralToPrimitiveDeep<ValueType>>
: T extends ReadonlyMap<infer KeyType, infer ValueType>
? ReadonlyMap<LiteralToPrimitiveDeep<KeyType>, LiteralToPrimitiveDeep<ValueType>>
: T extends Set<infer ItemType>
? Set<LiteralToPrimitiveDeep<ItemType>>
: T extends ReadonlySet<infer ItemType>
? ReadonlySet<LiteralToPrimitiveDeep<ItemType>>
// A weak collection is kept as is, because its key must be a weak reference. It is matched after `Map` and `Set`, because a `Map` or `Set` of objects is assignable to it.
: T extends WeakMap<WeakKey, unknown> | WeakSet<WeakKey>
? T
// A homomorphic map preserves named keys, index signatures and their modifiers in one pass.
: {[Key in keyof T]: LiteralToPrimitiveDeep<T[Key]>} & {};
export {};