Add .exclude and .extract helpers (#220)

* Add `.excluding` and `.extracting` helpers

* chore: change files

* Make naming less weird

* chore: change files

* Add more test cases

Co-authored-by: mmkal <mmkal@users.noreply.github.com>

Author: mmkal

common/changes/expect-type/exclude-extract_pr-220.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Add `.exclude` and `.extract` helpers (#220)",
+      "type": "minor",
+      "packageName": "expect-type"
+    }
+  ],
+  "packageName": "expect-type",
+  "email": "mmkal@users.noreply.github.com"
+}

packages/expect-type/readme.md

@@ -179,6 +179,43 @@ expectTypeOf(1).not.toBeUndefined()
 expectTypeOf(1).not.toBeNullable()
 ```
 
+Use `.extract` and `.exclude` to narrow down complex union types:
+
+```typescript
+type ResponsiveProp<T> = T | T[] | {xs?: T; sm?: T; md?: T}
+const getResponsiveProp = <T>(props: T): ResponsiveProp<T> => ({})
+type CSSProperties = {margin?: string; padding?: string}
+
+const cssProperties: CSSProperties = {margin: '1px', padding: '2px'}
+
+expectTypeOf(getResponsiveProp(cssProperties))
+  .exclude<unknown[]>()
+  .exclude<{xs?: unknown}>()
+  .toEqualTypeOf<CSSProperties>()
+
+expectTypeOf(getResponsiveProp(cssProperties))
+  .extract<unknown[]>()
+  .toEqualTypeOf<CSSProperties[]>()
+
+expectTypeOf(getResponsiveProp(cssProperties))
+  .extract<{xs?: any}>()
+  .toEqualTypeOf<{xs?: CSSProperties; sm?: CSSProperties; md?: CSSProperties}>()
+
+expectTypeOf<ResponsiveProp<number>>().exclude<number | number[]>().toHaveProperty('sm')
+expectTypeOf<ResponsiveProp<number>>().exclude<number | number[]>().not.toHaveProperty('xxl')
+```
+
+`.extract` and `.exclude` return never if no types remain after exclusion:
+
+```typescript
+type Person = {name: string; age: number}
+type Customer = Person & {customerId: string}
+type Employee = Person & {employeeId: string}
+
+expectTypeOf<Customer | Employee>().extract<{foo: string}>().toBeNever()
+expectTypeOf<Customer | Employee>().exclude<{name: string}>().toBeNever()
+```
+
 Make assertions about object properties:
 
 ```typescript

packages/expect-type/src/__tests__/index.test.ts

@@ -1,6 +1,8 @@
 /* eslint-disable @typescript-eslint/no-empty-function */
 import {expectTypeOf} from '..'
 
+/* eslint prettier/prettier: ["warn", { "singleQuote": true, "semi": false, "arrowParens": "avoid", "trailingComma": "es5", "bracketSpacing": false, "endOfLine": "auto", "printWidth": 100 }] */
+
 test("Check an object's type with `.toEqualTypeOf`", () => {
   expectTypeOf({a: 1}).toEqualTypeOf<{a: number}>()
 })
@@ -98,6 +100,39 @@ test('More `.not` examples', () => {
   expectTypeOf(1).not.toBeNullable()
 })
 
+test('Use `.extract` and `.exclude` to narrow down complex union types', () => {
+  type ResponsiveProp<T> = T | T[] | {xs?: T; sm?: T; md?: T}
+  const getResponsiveProp = <T>(props: T): ResponsiveProp<T> => ({})
+  type CSSProperties = {margin?: string; padding?: string}
+
+  const cssProperties: CSSProperties = {margin: '1px', padding: '2px'}
+
+  expectTypeOf(getResponsiveProp(cssProperties))
+    .exclude<unknown[]>()
+    .exclude<{xs?: unknown}>()
+    .toEqualTypeOf<CSSProperties>()
+
+  expectTypeOf(getResponsiveProp(cssProperties))
+    .extract<unknown[]>()
+    .toEqualTypeOf<CSSProperties[]>()
+
+  expectTypeOf(getResponsiveProp(cssProperties))
+    .extract<{xs?: any}>()
+    .toEqualTypeOf<{xs?: CSSProperties; sm?: CSSProperties; md?: CSSProperties}>()
+
+  expectTypeOf<ResponsiveProp<number>>().exclude<number | number[]>().toHaveProperty('sm')
+  expectTypeOf<ResponsiveProp<number>>().exclude<number | number[]>().not.toHaveProperty('xxl')
+})
+
+test('`.extract` and `.exclude` return never if no types remain after exclusion', () => {
+  type Person = {name: string; age: number}
+  type Customer = Person & {customerId: string}
+  type Employee = Person & {employeeId: string}
+
+  expectTypeOf<Customer | Employee>().extract<{foo: string}>().toBeNever()
+  expectTypeOf<Customer | Employee>().exclude<{name: string}>().toBeNever()
+})
+
 test('Make assertions about object properties', () => {
   const obj = {a: 1, b: ''}
 

packages/expect-type/src/index.ts

@@ -104,6 +104,8 @@ export interface ExpectTypeOf<Actual, B extends boolean> {
     key: K,
     ...MISMATCH: MismatchArgs<Extends<K, keyof Actual>, B>
   ) => K extends keyof Actual ? ExpectTypeOf<Actual[K], B> : true
+  extract: <V>(v?: V) => ExpectTypeOf<Extract<Actual, V>, B>
+  exclude: <V>(v?: V) => ExpectTypeOf<Exclude<Actual, V>, B>
   parameter: <K extends keyof Params<Actual>>(number: K) => ExpectTypeOf<Params<Actual>[K], B>
   parameters: ExpectTypeOf<Params<Actual>, B>
   constructorParameters: ExpectTypeOf<ConstructorParams<Actual>, B>
@@ -174,6 +176,8 @@ export const expectTypeOf: _ExpectTypeOf = <Actual>(actual?: Actual): ExpectType
     toEqualTypeOf: fn,
     toBeCallableWith: fn,
     toBeConstructibleWith: fn,
+    extract: expectTypeOf,
+    exclude: expectTypeOf,
     toHaveProperty: expectTypeOf,
     parameter: expectTypeOf,
   }