Add OmitIndexSignature and PickIndexSignature types (#453)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

Author: skarab42

index.d.ts

@@ -13,7 +13,14 @@ export type {MergeExclusive} from './source/merge-exclusive';
 export type {RequireAtLeastOne} from './source/require-at-least-one';
 export type {RequireExactlyOne} from './source/require-exactly-one';
 export type {RequireAllOrNone} from './source/require-all-or-none';
-export type {RemoveIndexSignature} from './source/remove-index-signature';
+export type {
+	OmitIndexSignature,
+	/**
+	@deprecated Renamed to {@link OmitIndexSignature}.
+	*/
+	OmitIndexSignature as RemoveIndexSignature,
+} from './source/omit-index-signature';
+export type {PickIndexSignature} from './source/pick-index-signature';
 export type {PartialDeep, PartialDeepOptions} from './source/partial-deep';
 export type {PartialOnUndefinedDeep, PartialOnUndefinedDeepOptions} from './source/partial-on-undefined-deep';
 export type {ReadonlyDeep} from './source/readonly-deep';

readme.md

@@ -134,7 +134,8 @@ Click the type names for complete docs.
 - [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys.
 - [`RequireExactlyOne`](source/require-exactly-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
 - [`RequireAllOrNone`](source/require-all-or-none.d.ts) - Create a type that requires all of the given keys or none of the given keys.
-- [`RemoveIndexSignature`](source/remove-index-signature.d.ts) - Create a type that only has explicitly defined properties, absent of any index signatures.
+- [`OmitIndexSignature`](source/omit-index-signature.d.ts) - Omit any index signatures from the given object type, leaving only explicitly defined properties.
+- [`PickIndexSignature`](source/pick-index-signature.d.ts) - Pick only index signatures from the given object type, leaving out all explicitly defined properties.
 - [`PartialDeep`](source/partial-deep.d.ts) - Create a deeply optional version of another type. Use [`Partial<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) if you only need one level deep.
 - [`PartialOnUndefinedDeep`](source/partial-on-undefined-deep.d.ts) - Create a deep version of another type where all keys accepting `undefined` type are set to optional.
 - [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) if you only need one level deep.

source/remove-index-signature.d.ts source/omit-index-signature.d.ts

@@ -1,5 +1,7 @@
 /**
-Remove any index signatures from the given object type, so that only explicitly defined properties remain.
+Omit any index signatures from the given object type, leaving only explicitly defined properties.
+
+This is the counterpart of `PickIndexSignature`.
 
 Use-cases:
 - Remove overly permissive signatures from third-party types.
@@ -34,20 +36,20 @@ type Keyed = {} extends Record<'foo' | 'bar', unknown>
 Using a [mapped type](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#further-exploration), you can then check for each `KeyType` of `ObjectType`...
 
 ```
-import type {RemoveIndexSignature} from 'type-fest';
+import type {OmitIndexSignature} from 'type-fest';
 
-type RemoveIndexSignature<ObjectType> = {
+type OmitIndexSignature<ObjectType> = {
 	[KeyType in keyof ObjectType // Map each key of `ObjectType`...
-	]: ObjectType[KeyType]; // ...to its original value, i.e. `RemoveIndexSignature<Foo> == Foo`.
+	]: ObjectType[KeyType]; // ...to its original value, i.e. `OmitIndexSignature<Foo> == Foo`.
 };
 ```
 
 ...whether an empty object (`{}`) would be assignable to an object with that `KeyType` (`Record<KeyType, unknown>`)...
 
 ```
-import type {RemoveIndexSignature} from 'type-fest';
+import type {OmitIndexSignature} from 'type-fest';
 
-type RemoveIndexSignature<ObjectType> = {
+type OmitIndexSignature<ObjectType> = {
 	[KeyType in keyof ObjectType
 		// Is `{}` assignable to `Record<KeyType, unknown>`?
 		as {} extends Record<KeyType, unknown>
@@ -60,9 +62,9 @@ type RemoveIndexSignature<ObjectType> = {
 If `{}` is assignable, it means that `KeyType` is an index signature and we want to remove it. If it is not assignable, `KeyType` is a "real" key and we want to keep it.
 
 ```
-import type {RemoveIndexSignature} from 'type-fest';
+import type {OmitIndexSignature} from 'type-fest';
 
-type RemoveIndexSignature<ObjectType> = {
+type OmitIndexSignature<ObjectType> = {
 	[KeyType in keyof ObjectType
 		as {} extends Record<KeyType, unknown>
 			? never // => Remove this `KeyType`.
@@ -73,7 +75,7 @@ type RemoveIndexSignature<ObjectType> = {
 
 @example
 ```
-import type {RemoveIndexSignature} from 'type-fest';
+import type {OmitIndexSignature} from 'type-fest';
 
 interface Example {
 	// These index signatures will be removed.
@@ -91,13 +93,14 @@ interface Example {
 	qux?: 'baz';
 }
 
-type ExampleWithoutIndexSignatures = RemoveIndexSignature<Example>;
+type ExampleWithoutIndexSignatures = OmitIndexSignature<Example>;
 // => { foo: 'bar'; qux?: 'baz' | undefined; }
 ```
 
+@see PickIndexSignature
 @category Object
 */
-export type RemoveIndexSignature<ObjectType> = {
+export type OmitIndexSignature<ObjectType> = {
 	[KeyType in keyof ObjectType as {} extends Record<KeyType, unknown>
 		? never
 		: KeyType]: ObjectType[KeyType];

source/pick-index-signature.d.ts

@@ -0,0 +1,102 @@
+/**
+Pick only index signatures from the given object type, leaving out all explicitly defined properties.
+
+This is the counterpart of `OmitIndexSignature`.
+
+When you use a type that will iterate through an object that has indexed keys and explicitly defined keys you end up with a type where only the indexed keys are kept. This is because `keyof` of an indexed type always returns `string | number | symbol`, because every key is possible in that object. With this type, you can save the indexed keys and reinject them later, like in the second example below.
+
+@example
+```
+import type {PickIndexSignature} from 'type-fest';
+
+declare const symbolKey: unique symbol;
+
+type Example = {
+	// These index signatures will remain.
+	[x: string]: unknown;
+	[x: number]: unknown;
+	[x: symbol]: unknown;
+	[x: `head-${string}`]: string;
+	[x: `${string}-tail`]: string;
+	[x: `head-${string}-tail`]: string;
+	[x: `${bigint}`]: string;
+	[x: `embedded-${number}`]: string;
+
+	// These explicitly defined keys will be removed.
+	['snake-case-key']: string;
+	[symbolKey]: string;
+	foo: 'bar';
+	qux?: 'baz';
+};
+
+type ExampleIndexSignature = PickIndexSignature<Example>;
+// {
+// 	[x: string]: unknown;
+// 	[x: number]: unknown;
+// 	[x: symbol]: unknown;
+// 	[x: `head-${string}`]: string;
+// 	[x: `${string}-tail`]: string;
+// 	[x: `head-${string}-tail`]: string;
+// 	[x: `${bigint}`]: string;
+// 	[x: `embedded-${number}`]: string;
+// }
+```
+
+@example
+```
+import type {OmitIndexSignature, PickIndexSignature, Simplify} from 'type-fest';
+
+type Foo = {
+	[x: string]: string;
+	foo: string;
+	bar: number;
+};
+
+// Imagine that you want a new type `Bar` that comes from `Foo`.
+// => {
+// 	[x: string]: string;
+// 	bar: number;
+// };
+
+type Bar = Omit<Foo, 'foo'>;
+// This is not working because `Omit` returns only indexed keys.
+// => {
+// 	[x: string]: string;
+// 	[x: number]: string;
+// }
+
+// One solution is to save the indexed signatures to new type.
+type FooIndexSignature = PickIndexSignature<Foo>;
+// => {
+// 	[x: string]: string;
+// }
+
+// Get a new type without index signatures.
+type FooWithoutIndexSignature = OmitIndexSignature<Foo>;
+// => {
+// 	foo: string;
+// 	bar: number;
+// }
+
+// At this point we can use Omit to get our new type.
+type BarWithoutIndexSignature = Omit<FooWithoutIndexSignature, 'foo'>;
+// => {
+// 	bar: number;
+// }
+
+// And finally we can merge back the indexed signatures.
+type BarWithIndexSignature = Simplify<BarWithoutIndexSignature & FooIndexSignature>;
+// => {
+// 	[x: string]: string;
+// 	bar: number;
+// }
+```
+
+@see OmitIndexSignature
+@category Object
+*/
+export type PickIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType as {} extends Record<KeyType, unknown>
+		? KeyType
+		: never]: ObjectType[KeyType];
+};

test-d/remove-index-signature.ts test-d/omit-index-signature.ts

@@ -1,5 +1,5 @@
 import {expectType} from 'tsd';
-import type {RemoveIndexSignature} from '../index';
+import type {OmitIndexSignature} from '../index';
 
 type ExampleInterface = {
 	// These index signatures will be removed.
@@ -24,13 +24,13 @@ type MappedType<ObjectType> = {
 	};
 };
 
-declare const exampleInterfaceKnownKeys: RemoveIndexSignature<ExampleInterface>;
+declare const exampleInterfaceKnownKeys: OmitIndexSignature<ExampleInterface>;
 expectType<{
 	foo: 'bar';
 	qux?: 'baz';
 }>(exampleInterfaceKnownKeys);
 
-declare const exampleMappedTypeKnownKeys: RemoveIndexSignature<
+declare const exampleMappedTypeKnownKeys: OmitIndexSignature<
 MappedType<ExampleInterface>
 >;
 expectType<{

test-d/pick-index-signature.ts

@@ -0,0 +1,28 @@
+import {expectType} from 'tsd';
+import type {PickIndexSignature, Simplify} from '../index';
+
+declare const symbolKey: unique symbol;
+
+type Foo = {
+	[x: string]: unknown;
+	[x: number]: unknown;
+	[x: symbol]: unknown;
+	[x: `head-${string}`]: string;
+	[x: `${string}-tail`]: string;
+	[x: `head-${string}-tail`]: string;
+	[x: `${bigint}`]: string;
+	[x: `embedded-${number}`]: string;
+};
+
+type Bar = {
+	['snake-case-key']: string;
+	[symbolKey]: string;
+	foo: 'bar';
+	qux?: 'baz';
+};
+
+type FooBar = Simplify<Foo & Bar>;
+
+declare const indexSignature: PickIndexSignature<FooBar>;
+
+expectType<Foo>(indexSignature);