UNPKG

type-fest

Version:

A collection of essential TypeScript types

210 lines (177 loc) • 8.21 kB
import type {MatchingKey} from './matching-key.d.ts'; import type {ArraySplice} from './array-splice.d.ts'; import type {Except} from './except.d.ts'; import type {NonRecursiveType, SetArrayAccess, KeyToString, UnwrapPathBrand} from './internal/index.d.ts'; import type {IsReadonlyArray} from './is-readonly-array.d.ts'; import type {OmitIndexSignature} from './omit-index-signature.d.ts'; import type {IsEqual} from './is-equal.d.ts'; import type {IsNever} from './is-never.d.ts'; import type {LiteralUnion} from './literal-union.d.ts'; import type {Paths} from './paths.d.ts'; import type {SimplifyDeep} from './simplify-deep.d.ts'; import type {UnionToTuple} from './union-to-tuple.d.ts'; import type {UnknownArray} from './unknown-array.d.ts'; /** Omit properties from a deeply-nested object. It supports recursing into arrays. It supports removing specific items from an array, replacing each removed item with unknown at the specified index. Use-case: Remove unneeded parts of complex objects. Use [`Omit<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) if you only need one level deep. @example ``` import type {OmitDeep} from 'type-fest'; type Info = { userInfo: { name: string; uselessInfo: { foo: string; }; }; }; type UsefulInfo = OmitDeep<Info, 'userInfo.uselessInfo'>; //=> {userInfo: {name: string}} // Supports removing multiple paths type Info1 = { userInfo: { name: string; uselessField: string; uselessInfo: { foo: string; }; }; }; type UsefulInfo1 = OmitDeep<Info1, 'userInfo.uselessInfo' | 'userInfo.uselessField'>; //=> {userInfo: {name: string}} // Supports array type A = OmitDeep<[1, 'foo', 2], '1'>; //=> [1, unknown, 2] // Supports recursing into array type Info2 = { address: [ { street: string; }, { street2: string; foo: string; }, ]; }; type AddressInfo = OmitDeep<Info2, 'address.1.foo'>; //=> {address: [{street: string}, {street2: string}]} ``` Note: An existing path that goes through an array or tuple element drops that element's `?` modifier and its `null`. Note: A path into a tuple intersected with an object type, such as a tagged tuple, loses the object type and some or all of the tuple elements. @category Object @category Array */ export type OmitDeep< T, // Autocomplete lists paths up to `a.b.c`, because listing deeper paths can take minutes for large union-heavy types. A generic `Paths<T>` can be a `number`, so any `number` is accepted, like any `string`. PathUnion extends LiteralUnion<Paths<T, {maxRecursionDepth: 2}>, string | number>, > = SimplifyDeep< OmitDeepHelper<T, UnionToTuple<UnwrapPathBrand<PathUnion>>>, UnknownArray>; /** Internal helper for {@link OmitDeep}. Recursively transforms `T` by applying {@link OmitDeepWithOnePath} for each path in `PathTuple`. */ type OmitDeepHelper<T, PathTuple extends UnknownArray> = PathTuple extends [infer Path, ...infer RestPaths] ? OmitDeepHelper<OmitDeepWithOnePath<T, Path & (string | number)>, RestPaths> : T; /** Omit one path from the given object/array. */ type OmitDeepWithOnePath<T, Path extends string | number> = T extends NonRecursiveType ? T // The array helper matches indexes as strings, so a number index is read as its string form. : T extends UnknownArray ? SetArrayAccess<OmitDeepArrayWithOnePath<T, KeyToString<Path>>, IsReadonlyArray<T>> : T extends object ? OmitDeepObjectWithOnePath<T, Path> : T; /** Omit one path from the given object. */ type OmitDeepObjectWithOnePath<ObjectT extends object, P extends string | number> = P extends `${infer RecordKeyInPath}.${infer SubPath}` ? { [Key in keyof ObjectT]: IsEqual<RecordKeyInPath, KeyToString<Key>> extends true ? OmitDeepWithOnePath<ObjectT[Key], SubPath> // `Paths` emits `${string}` for a signature, so matching segments transform its value type. Resolve the current key with `MatchingKey` to reject alternate numeric spellings. : RecordKeyInPath extends KeyToString<Key> & KeyToString<MatchingKey<Record<Key, unknown>, RecordKeyInPath>> // A member that names the key outright is what the key reads, so the signature is left alone. ? RecordKeyInPath extends KeyToString<keyof OmitIndexSignature<ObjectT>> ? ObjectT[Key] : OmitDeepWithOnePath<ObjectT[Key], SubPath> : ObjectT[Key] } // Match declared terminal keys by their spelling, including enums; leave index signatures to MatchingKey. : (MatchingKey<ObjectT, P> | keyof {[Key in keyof OmitIndexSignature<ObjectT> as IsEqual<KeyToString<Key>, KeyToString<P>> extends true ? Key : never]: never}) extends infer Key ? IsNever<Key> extends true ? ObjectT : Except<ObjectT, Extract<Key, keyof ObjectT>> // Keep unrelated declared fields covered by an index signature. : ObjectT; /** Omit one path from the given array. It replaces the item to `unknown` at the given index. @example ``` type A = OmitDeepArrayWithOnePath<[10, 20, 30, 40], '2'>; //=> [10, 20, unknown, 40] type B = OmitDeepArrayWithOnePath<[10, 20, 30, 40], '6'>; //=> [10, 20, 30, 40] ``` */ type OmitDeepArrayWithOnePath<ArrayType extends UnknownArray, P extends string | number> = // Handle paths that are `${number}.${string}` P extends `${infer ArrayIndex extends number}.${infer SubPath}` // A missing descendant leaves the element unchanged, so it must not create required array positions or discard nullish elements. ? IsEqual<OmitDeepWithOnePath<NonNullable<ArrayType[ArrayIndex]>, SubPath>, NonNullable<ArrayType[ArrayIndex]>> extends true ? ArrayType // If `ArrayIndex` is equal to `number`. Only the `${number}` segment itself is the wide index, since a segment that is not how JavaScript writes an index, such as `01`, is also inferred as `number`. : `${number}.${SubPath}` extends P // An array with nothing left to omit is kept empty. Omitting the whole array already removed every index, so a path that continues into one of those indices has nothing to recurse into, and reading the element type would yield `never`, which would collapse the array into `never[]` rather than leaving it empty. An empty tuple is kept as it is for the same reason, rather than keeping the `unknown` placeholder an element that does not exist would leave. ? ArrayType extends readonly [] ? ArrayType : Array<OmitDeepWithOnePath<NonNullable<ArrayType[number]>, SubPath>> // If `ArrayIndex` is a number literal, or `number` for a segment such as `01`. An array without that index is returned unchanged. : IsMissingArrayIndex<ArrayType, ArrayIndex> extends true ? ArrayType : ArraySplice<ArrayType, ArrayIndex, 1, [OmitDeepWithOnePath<NonNullable<ArrayType[ArrayIndex]>, SubPath>]> // If the path is equal to `number` : P extends `${infer ArrayIndex extends number}` // If the path is the `${number}` segment itself. A segment such as `01` is also inferred as `number`, but is not the wide index. ? `${number}` extends P ? [] // If `ArrayIndex` is a number literal, or `number` for a segment such as `01`. An array without that index is returned unchanged. : IsMissingArrayIndex<ArrayType, ArrayIndex> extends true ? ArrayType : ArraySplice<ArrayType, ArrayIndex, 1, [unknown]> : ArrayType; /** Whether `ArrayType` has no `Index` position, such as a negative index, or an index past the end of a fixed-length tuple. `Index` is `number` when the path segment is a number that is not how JavaScript writes an index, such as `01` or `-0`, which names a key no array has. A fixed-length tuple has a key for each of its positions, including optional ones. An array, or a tuple with a rest element, has no upper bound. @example ``` type A = IsMissingArrayIndex<[0, 1, 2], 3>; //=> true type B = IsMissingArrayIndex<number[], -1>; //=> true type C = IsMissingArrayIndex<[0, 1?], 1>; //=> false type D = IsMissingArrayIndex<[0, ...number[]], 5>; //=> false ``` */ type IsMissingArrayIndex<ArrayType extends UnknownArray, Index extends number> = number extends Index ? true : `${Index}` extends `-${string}` ? true : number extends ArrayType['length'] ? false : `${Index}` extends keyof ArrayType ? false : true; export {};