UNPKG

type-fest

Version:

A collection of essential TypeScript types

189 lines (146 loc) • 7.27 kB
import type {HasMultipleCallSignatures} from './has-multiple-call-signatures.d.ts'; import type {CallSignatureOf, IsArrayOfUnknownLength, NonRecursiveLeaf, NonRecursiveType} from './internal/index.d.ts'; import type {ApplyDefaultOptions} from './apply-default-options.d.ts'; import type {IsNever} from './is-never.d.ts'; import type {ReadonlyDate} from './readonly-date.d.ts'; /** @see {@link ReadonlyDeep} */ export type ReadonlyDeepOptions = { /** The types to keep as is, instead of making deeply readonly. A kept type is left untouched at every depth, including everything inside it. Matching uses assignability. @default never @example ``` import type {ReadonlyDeep} from 'type-fest'; type Color = {red: number}; type Settings = {name: string; color: Color}; type ReadonlySettings = ReadonlyDeep<Settings, {keep: Color}>; //=> {readonly name: string; readonly color: Color} ``` */ readonly keep?: unknown; }; /** Create a deeply immutable version of another type. This is useful when a deeply nested structure needs to be exposed as completely immutable, for example, an imported JSON module or when receiving an API response that is passed around. Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/13923) if you want to have this type as a built-in in TypeScript. Use [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) if you only need one level deep. @example ``` import type {ReadonlyDeep} from 'type-fest'; declare const foo: { a: string; b: {c: number}; d: Array<{e: number}>; }; foo.a = 'bar'; // Allowed foo.b = {c: 3}; // Allowed foo.b.c = 4; // Allowed foo.d = [{e: 5}]; // Allowed foo.d.push({e: 6}); // Allowed const last = foo.d.at(-1); if (last) { last.e = 7; // Allowed } declare const readonlyFoo: ReadonlyDeep<typeof foo>; // @ts-expect-error readonlyFoo.a = 'bar'; // Error: Cannot assign to 'a' because it is a read-only property. // @ts-expect-error readonlyFoo.b = {c: 3}; // Error: Cannot assign to 'b' because it is a read-only property. // @ts-expect-error readonlyFoo.b.c = 4; // Error: Cannot assign to 'c' because it is a read-only property. // @ts-expect-error readonlyFoo.d = [{e: 5}]; // Error: Cannot assign to 'd' because it is a read-only property. // @ts-expect-error readonlyFoo.d.push({e: 6}); // Error: Property 'push' does not exist on type 'ReadonlyArray<{readonly e: number}>'. const readonlyLast = readonlyFoo.d.at(-1); if (readonlyLast) { // @ts-expect-error readonlyLast.e = 8; // Error: Cannot assign to 'e' because it is a read-only property. } ``` Pass the types to keep as is through the `keep` option to leave matching types untouched at every depth, like a class instance whose properties and methods should not be made readonly. Matching uses assignability, so a plain object type that structurally matches a kept type is kept too, and a wide type, like `object`, keeps every object: @example ``` import type {ReadonlyDeep} from 'type-fest'; class Color { r = 0; g = 0; } declare const theme: { name: string; background: Color; }; declare const readonlyTheme: ReadonlyDeep<typeof theme, {keep: Color}>; // @ts-expect-error readonlyTheme.name = 'solarized'; // Error: Cannot assign to 'name' because it is a read-only property. readonlyTheme.background.r = 3; // OK: `Color` is kept as is, so its properties stay writable ``` Overloaded functions, including their properties, are kept as is due to a [TypeScript limitation](https://github.com/microsoft/TypeScript/issues/29732). See {@link HasMultipleCallSignatures} for overload detection limitations. A `Date` becomes a {@link ReadonlyDate}, which has no `set*` methods. A subclass of `Date` or a tagged `Date` becomes a plain `ReadonlyDate` too. Use the `keep` option to keep dates as is. Note that the methods of an array, such as `join`, can still be reassigned, because TypeScript treats `Readonly<ReadonlyArray<T>>` the same as `ReadonlyArray<T>`. The methods of a `Map` or a `Set` are made readonly. @see {@link ReadonlyDeepOptions} @category Object @category Array @category Set @category Map */ export type ReadonlyDeep<Value, Options extends ReadonlyDeepOptions = {}> = _ReadonlyDeep<Value, ApplyDefaultOptions<ReadonlyDeepOptions, {keep: never}, Options>['keep']>; /** Internal helper for {@link ReadonlyDeep}. */ type _ReadonlyDeep<Value, Keep> = // A kept type is returned as is, including everything inside it. It is matched before everything else, so a kept `Map` or `Set` is not rebuilt either. Value extends Keep ? Value : Value extends NonRecursiveLeaf ? Value extends Date ? ReadonlyDate : Value : Value extends (...arguments_: any[]) => unknown ? IsNever<keyof Value> extends true // For functions with no properties ? Value : HasMultipleCallSignatures<Value> extends true ? Value : CallSignatureOf<Value> & _ReadonlyObjectDeep<Value, Keep> : Value extends ReadonlyMap<infer KeyType, infer ValueType> ? ReadonlyMapDeep<KeyType, ValueType, Keep> : Value extends ReadonlySet<infer ItemType> ? ReadonlySetDeep<ItemType, Keep> : Value extends readonly unknown[] ? IsArrayOfUnknownLength<Value> extends false // A homomorphic mapped type keeps the length, the optional elements and the rest element, without a recursion step per element. ? {readonly [Key in keyof Value]: _ReadonlyDeep<Value[Key], Keep>} // An array of unknown length is rebuilt directly, because mapping it makes a recursive element type, such as `JsonValue`, infinitely deep. : ReadonlyArray<_ReadonlyDeep<Value[number], Keep>> : Value extends NonRecursiveType | WeakMap<WeakKey, unknown> | WeakSet<WeakKey> ? Value // These are a single value rather than a structure to recurse into, so their methods are not made readonly. The weak collections are separate because they are rebuilt rather than skipped by the sibling types. : Value extends object ? _ReadonlyObjectDeep<Value, Keep> : unknown; /** Same as `ReadonlyDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `ReadonlyDeep`. The `ReadonlyMap` is wrapped in `Readonly` so that its methods are readonly too. A `ReadonlyMap` only leaves out the methods that change the map, and the methods it has can still be reassigned, so linters such as the `prefer-readonly-parameter-types` rule of typescript-eslint do not see it as readonly. See https://github.com/sindresorhus/type-fest/issues/357 */ type ReadonlyMapDeep<KeyType, ValueType, Keep> = {} & Readonly<ReadonlyMap<_ReadonlyDeep<KeyType, Keep>, _ReadonlyDeep<ValueType, Keep>>>; /** Same as `ReadonlyDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `ReadonlyDeep`. See the note on {@link ReadonlyMapDeep `ReadonlyMapDeep`} for why the built-in is wrapped in `Readonly`. */ type ReadonlySetDeep<ItemType, Keep> = {} & Readonly<ReadonlySet<_ReadonlyDeep<ItemType, Keep>>>; /** Same as `ReadonlyDeep`, but accepts only `object`s as inputs. Internal helper for `ReadonlyDeep`. */ export type _ReadonlyObjectDeep<ObjectType extends object, Keep = never> = { readonly [KeyType in keyof ObjectType]: _ReadonlyDeep<ObjectType[KeyType], Keep> }; export {};