Add ExtractStrict type (#1119)

Co-authored-by: Som Shekhar Mukherjee <[email protected]>

Author: nigeltroy

index.d.ts

@@ -176,3 +176,6 @@ export type {LastArrayElement} from './source/last-array-element';
 export type {GlobalThis} from './source/global-this';
 export type {PackageJson} from './source/package-json';
 export type {TsConfigJson} from './source/tsconfig-json';
+
+// Improved built-in
+export type {ExtractStrict} from './source/extract-strict';

readme.md

@@ -333,6 +333,10 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). It also includes support for [TypeScript Declaration Files](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html).
 - [`TsConfigJson`](source/tsconfig-json.d.ts) - Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
 
+### Improved built-in
+
+- [`ExtractStrict`](source/extract-strict.d.ts) - A stricter version of `Extract<T, U>` that ensures every member of `U` can successfully extract something from `T`.
+
 ## Declined types
 
 *If we decline a type addition, we will make sure to document the better solution here.*

source/extract-strict.d.ts

@@ -0,0 +1,45 @@
+/**
+A stricter version of {@link Extract<T, U>} that ensures every member of `U` can successfully extract something from `T`.
+
+For example, `StrictExtract<string | number | boolean, number | bigint>` will error because `bigint` cannot extract anything from `string | number | boolean`.
+
+@example
+```
+// Valid Examples
+
+type Example1 = ExtractStrict<{status: 'success'; data: string[]} | {status: 'error'; error: string}, {status: 'success'}>;
+//=> {status: 'success'; data: string[]}
+
+type Example2 = ExtractStrict<'xs' | 's' | 'm' | 'l' | 'xl', 'xs' | 's'>;
+//=> 'xs' | 's'
+
+type Example3 = ExtractStrict<{x: number; y: number} | [number, number], unknown[]>;
+//=> [number, number]
+```
+
+@example
+```
+// Invalid Examples
+
+// `'xxl'` cannot extract anything from `'xs' | 's' | 'm' | 'l' | 'xl'`
+type Example1 = ExtractStrict<'xs' | 's' | 'm' | 'l' | 'xl', 'xl' | 'xxl'>;
+//                                                           ~~~~~~~~~~~~
+// Error: Type "'xl' | 'xxl'" does not satisfy the constraint 'never'.
+
+// `unknown[]` cannot extract anything from `{x: number; y: number} | {x: string; y: string}`
+type Example2 = ExtractStrict<{x: number; y: number} | {x: string; y: string}, unknown[]>;
+//                                                                             ~~~~~~~~~
+// Error: Type 'unknown[]' does not satisfy the constraint 'never'.
+```
+
+@category Improved Built-in
+*/
+export type ExtractStrict<
+	T,
+	U extends [U] extends [
+		// Ensure every member of `U` extracts something from `T`
+		U extends unknown ? (Extract<T, U> extends never ? never : U) : never,
+	]
+		? unknown
+		: never,
+> = Extract<T, U>;

test-d/extract-strict.ts

@@ -0,0 +1,101 @@
+import {expectType} from 'tsd';
+import type {ExtractStrict} from '../source/extract-strict';
+
+// Primitive union tests
+
+type ShirtSize = 'xxxl' | 'xxl' | 'xl' | 'l' | 'm' | 's' | 'xs' | 'xxs';
+type LargeShirtSize = 'xxxl' | 'xxl' | 'xl' | 'l';
+type SmallShirtSize = 's' | 'xs' | 'xxs';
+
+declare const largeShirtSizes: ExtractStrict<ShirtSize, LargeShirtSize>;
+expectType<LargeShirtSize>(largeShirtSizes);
+
+declare const smallShirtSizes: ExtractStrict<ShirtSize, SmallShirtSize>;
+expectType<SmallShirtSize>(smallShirtSizes);
+
+// @ts-expect-error
+declare const allInvalidShirtSizes: ExtractStrict<ShirtSize, 'skyscraper-large' | 'atom-small'>;
+
+// @ts-expect-error
+declare const someInvalidShirtSizes: ExtractStrict<ShirtSize, 'm' | 'atom-small'>;
+
+// Object union tests
+
+type Foo = {
+	kind: 'foo';
+	a: string;
+	b: string;
+};
+
+type Bar = {
+	kind: 'bar';
+	a: string;
+	b: number;
+	c: boolean;
+};
+
+type Foobar = Foo | Bar;
+
+declare const foobarByA: ExtractStrict<Foobar, {a: string}>;
+expectType<Foobar>(foobarByA);
+
+declare const onlyFooByKind: ExtractStrict<Foobar, {kind: 'foo'}>;
+expectType<Foo>(onlyFooByKind);
+
+declare const onlyFooByB: ExtractStrict<Foobar, {b: string}>;
+expectType<Foo>(onlyFooByB);
+
+declare const onlyBarByC: ExtractStrict<Foobar, {c: boolean}>;
+expectType<Bar>(onlyBarByC);
+
+declare const foobarByUnionBC: ExtractStrict<Foobar, {b: string} | {c: boolean}>;
+expectType<Foobar>(foobarByUnionBC);
+
+// @ts-expect-error
+declare const invalidLoneField: ExtractStrict<Foobar, {d: string}>;
+
+// @ts-expect-error
+declare const invalidMixedFields: ExtractStrict<Foobar, {kind: 'foo'; d: string}>;
+
+// @ts-expect-error
+declare const undefinedField: ExtractStrict<Foobar, undefined>;
+
+// Primitives
+expectType<number>({} as ExtractStrict<string | number, number>);
+expectType<number | bigint>({} as ExtractStrict<string | number | bigint, number | bigint>);
+expectType<'bar' | 'baz'>({} as ExtractStrict<'foo' | 'bar' | 'baz', `b${string}`>);
+
+// @ts-expect-error
+type invalid1 = ExtractStrict<string | number | boolean, number | bigint>;
+// @ts-expect-error
+type invalid2 = ExtractStrict<string, Uppercase<string>>;
+
+// Optional and readonly modifiers
+expectType<{a: string; b: number}>({} as ExtractStrict<{a: string; b: number}, {a?: string}>);
+expectType<string[]>({} as ExtractStrict<string[], readonly string[]>);
+
+// @ts-expect-error
+type invalid3 = ExtractStrict<{a?: string; b: number}, {a: string}>;
+// @ts-expect-error
+type invalid4 = ExtractStrict<readonly string[], string[]>;
+
+// Index signatures
+expectType<{c: true; d: false}>(
+	{} as ExtractStrict<{a: string; b: number} | {c: true; d: false}, Record<string, boolean>>,
+);
+
+// @ts-expect-error
+type invalid5 = ExtractStrict<{a: string; b: number} | {c: true; d: false}, Record<string, string>>;
+
+// `any` and `never`
+expectType<string | {a: string; b: number} | string[]>(
+	{} as ExtractStrict<string | {a: string; b: number} | string[], any>,
+);
+expectType<never>(
+	{} as ExtractStrict<string | {a: string; b: number} | string[], never>,
+);
+
+// Miscellaneous
+expectType<[number, number]>({} as ExtractStrict<[number, number] | {x: number; y: number}, unknown[]>);
+expectType<[number, number]>({} as ExtractStrict<[number, number] | [number, number, number], {length: 2}>);
+expectType<{data: string | string[]}>({} as ExtractStrict<string | string[] | {data: string | string[]}, {data: unknown}>);