From e61d38d9b6b5bf1a659d0ffdd4b685d751ec0abf Mon Sep 17 00:00:00 2001
From: unional <homawong@gmail.com>
Date: Sun, 24 Sep 2023 01:58:39 -0700
Subject: [PATCH] feat: merge NeverType to IsNever

---
 type-plus/ts/any/is_any.ts                 | 12 ++-
 type-plus/ts/any/is_not_any.ts             | 20 ++++-
 type-plus/ts/any/readme.md                 | 92 ++++++---------------
 type-plus/ts/index.ts                      |  2 -
 type-plus/ts/never/is_never.spec.ts        | 45 ++++++++++-
 type-plus/ts/never/is_never.ts             | 55 +++++++++++--
 type-plus/ts/never/is_not_never.spec.ts    | 42 +++++++++-
 type-plus/ts/never/is_not_never.ts         | 58 +++++++++++--
 type-plus/ts/never/never_type.spec.ts      | 55 -------------
 type-plus/ts/never/never_type.ts           | 36 ---------
 type-plus/ts/never/not_never_type.spec.ts  | 47 -----------
 type-plus/ts/never/not_never_type.ts       | 37 ---------
 type-plus/ts/never/readme.md               | 94 +++++++++++++---------
 type-plus/ts/object/merge.ts               | 32 +++++---
 type-plus/ts/type_plus/branch/selection.ts |  1 +
 15 files changed, 312 insertions(+), 316 deletions(-)
 delete mode 100644 type-plus/ts/never/never_type.spec.ts
 delete mode 100644 type-plus/ts/never/never_type.ts
 delete mode 100644 type-plus/ts/never/not_never_type.spec.ts
 delete mode 100644 type-plus/ts/never/not_never_type.ts

diff --git a/type-plus/ts/any/is_any.ts b/type-plus/ts/any/is_any.ts
index 2e1e5637fd..80cf2f7e93 100644
--- a/type-plus/ts/any/is_any.ts
+++ b/type-plus/ts/any/is_any.ts
@@ -2,10 +2,10 @@ import type { $Else, $ResolveSelection, $SelectionOptions, $Then } from '../type
 
 /**
  * 🎭 *predicate*
- * 🔢 *customize*
  *
  * Validate if `T` is exactly `any`.
  *
+ * @example
  * ```ts
  * type R = IsAny<any> // true
  *
@@ -14,8 +14,11 @@ import type { $Else, $ResolveSelection, $SelectionOptions, $Then } from '../type
  * type R = IsAny<string | boolean> // false
  * ```
  *
- * 🔢 *customize*: filter
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is exactly `any`.
  *
+ * @example
  * ```ts
  * type R = IsAny<any, { selection: 'filter' }> // any
  *
@@ -24,8 +27,11 @@ import type { $Else, $ResolveSelection, $SelectionOptions, $Then } from '../type
  * type R = IsAny<string | boolean, { selection: 'filter' }> // never
  * ```
  *
- * 🔢 *customize*: branching
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
  *
+ * @example
  * ```ts
  * type R = IsAny<any, $SelectionBranch> // $Then
  * type R = IsAny<string, $SelectionBranch> // $Else
diff --git a/type-plus/ts/any/is_not_any.ts b/type-plus/ts/any/is_not_any.ts
index fff7b71bde..13809ce3cc 100644
--- a/type-plus/ts/any/is_not_any.ts
+++ b/type-plus/ts/any/is_not_any.ts
@@ -3,10 +3,10 @@ import type { IsAny } from './is_any.js'
 
 /**
  * 🎭 *predicate*
- * 🔢 *customize*
  *
  * Validate if `T` is not exactly `any`.
  *
+ * @example
  * ```ts
  * type R = IsNotAny<any> // false
  *
@@ -15,8 +15,24 @@ import type { IsAny } from './is_any.js'
  * type R = IsNotAny<string | boolean> // true
  * ```
  *
- * 🔢 *customize*: branching
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not exactly `any`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotAny<any, { selection: 'filter' }> // never
+ *
+ * type R = IsNotAny<never, { selection: 'filter' }> // never
+ * type R = IsNotAny<unknown, { selection: 'filter' }> // unknown
+ * type R = IsNotAny<string | boolean, { selection: 'filter' }> // string | boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
  *
+ * @example
  * ```ts
  * type R = IsNotAny<any, $SelectionBranch> // $Else
  * type R = IsNotAny<string, $SelectionBranch> // $Then
diff --git a/type-plus/ts/any/readme.md b/type-plus/ts/any/readme.md
index 627c60062f..901a7d2f32 100644
--- a/type-plus/ts/any/readme.md
+++ b/type-plus/ts/any/readme.md
@@ -4,74 +4,11 @@
 It is a supertype of all types.
 It is a way to opt-out of type checking and let the values pass through compile-time checks.
 
-## [AnyType](./any_type.ts)
-
-`AnyType<T, $O = { $then: T, $else: never }>`
-
-🌪️ *filter*
-🔢 *customize*
-
-Filter to ensure `T` is exactly `any`.
-
-```ts
-type R = AnyType<any> // any
-
-type R = AnyType<never> // never
-type R = AnyType<unknown> // never
-type R = AnyType<string | boolean> // never
-```
-
-🔢 *customize*: as predicate/validate (= `IsAny`)
-
-```ts
-type R = AnyType<any, $SelectionPredicate> // true
-type R = AnyType<string, $SelectionPredicate> // false
-```
-
-🔢 *customize*: branching
-
-```ts
-type R = AnyType<any, $SelectionBranch> // $Then
-type R = AnyType<string, $SelectionBranch> // $Else
-```
-
-## [NotAnyType](./not_any_type.ts)
-
-`NotAnyType<T, $O = { $then: T, $else: never }>`
-
-🌪️ *filter*
-🔢 *customize*
-
-Filter to ensure `T` is not exactly `any`.
-
-```ts
-type R = NotAnyType<any> // never
-
-type R = NotAnyType<never> // never
-type R = NotAnyType<unknown> // unknown
-type R = NotAnyType<string | boolean> // string | boolean
-```
-
-🔢 *customize*: as predicate/validate (= `IsNotAny`)
-
-```ts
-type R = NotAnyType<string, $SelectionPredicate> // true
-type R = NotAnyType<any, $SelectionPredicate> // false
-```
-
-🔢 *customize*: branching
-
-```ts
-type R = NotAnyType<string, $SelectionBranch> // $Then
-type R = NotAnyType<any, $SelectionBranch> // $Else
-```
-
 ## [IsAny](./is_any.ts)
 
-`IsAny<T, $O = { $then: true, $else: false }>`
+`IsAny<T, $O = { selection: 'predicate' | 'filter', $then: true, $else: false }>`
 
 🎭 *predicate*
-🔢 *customize*
 
 Validate if `T` is exactly `any`.
 
@@ -83,7 +20,9 @@ type R = IsAny<unknown> // false
 type R = IsAny<string | boolean> // false
 ```
 
-🔢 *customize*: filter
+🔢 *customize*
+
+Filter to ensure `T` is exactly `any`.
 
 ```ts
 type R = IsAny<any, { selection: 'filter' }> // any
@@ -93,7 +32,9 @@ type R = IsAny<unknown, { selection: 'filter' }> // never
 type R = IsAny<string | boolean, { selection: 'filter' }> // never
 ```
 
-🔢 *customize*: branching
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
 
 ```ts
 type R = IsAny<any, $SelectionBranch> // $Then
@@ -102,10 +43,9 @@ type R = IsAny<string, $SelectionBranch> // $Else
 
 ### [IsNotAny](./is_not_any.ts)
 
-`IsNotAny<T, $O = { $then: true, $else: false }>`
+`IsNotAny<T, $O = { selection: 'predicate' | 'filter', $then: true, $else: false }>`
 
 🎭 *predicate*
-🔢 *customize*
 
 Validate if `T` is not exactly `any`.
 
@@ -117,7 +57,21 @@ type R = IsNotAny<unknown> // true
 type R = IsNotAny<string | boolean> // true
 ```
 
-🔢 *customize*: branching
+🔢 *customize*
+
+Filter to ensure `T` is not exactly `any`.
+
+```ts
+type R = IsNotAny<any, { selection: 'filter' }> // never
+
+type R = IsNotAny<never, { selection: 'filter' }> // never
+type R = IsNotAny<unknown, { selection: 'filter' }> // unknown
+type R = IsNotAny<string | boolean, { selection: 'filter' }> // string | boolean
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
 
 ```ts
 type R = IsNotAny<any, $SelectionBranch> // $Else
diff --git a/type-plus/ts/index.ts b/type-plus/ts/index.ts
index 856948e8e9..7435516b73 100644
--- a/type-plus/ts/index.ts
+++ b/type-plus/ts/index.ts
@@ -63,8 +63,6 @@ export * from './mix_types/merge.js'
 export type * from './never/is_never.js'
 export type * from './never/is_not_never.js'
 export type * from './never/never.js'
-export type * from './never/never_type.js'
-export type * from './never/not_never_type.js'
 export * from './nodejs/index.js'
 export * from './nominal/index.js'
 export type * from './null/non_null.js'
diff --git a/type-plus/ts/never/is_never.spec.ts b/type-plus/ts/never/is_never.spec.ts
index 863b2230b3..cd056ca491 100644
--- a/type-plus/ts/never/is_never.spec.ts
+++ b/type-plus/ts/never/is_never.spec.ts
@@ -1,6 +1,7 @@
 import { it } from '@jest/globals'
 // never intersect with any type is never
-import { testType, type IsNever } from '../index.js'
+import { describe } from 'node:test'
+import { testType, type $NotNever, type IsNever } from '../index.js'
 
 it('returns true for never', () => {
 	testType.true<IsNever<never>>(true)
@@ -48,3 +49,45 @@ it('can override Then/Else', () => {
 	testType.equal<IsNever<unknown, { $then: 1, $else: 2 }>, 2>(true)
 	testType.equal<IsNever<void, { $then: 1, $else: 2 }>, 2>(true)
 })
+
+describe('filter', () => {
+
+	it('returns never if T is never', () => {
+		testType.equal<IsNever<never, { selection: 'filter' }>, never>(true)
+	})
+
+	it('returns $NotNever for other special types', () => {
+		testType.equal<IsNever<unknown, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<void, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<any, { selection: 'filter' }>, $NotNever>(true)
+	})
+
+	it('returns $NotNever for other types', () => {
+		testType.equal<IsNever<undefined, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<null, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<number, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<boolean, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<true, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<false, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<string, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<'', { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<symbol, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<bigint, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<{}, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<string[], { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<[], { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<Function, { selection: 'filter' }>, $NotNever>(true)
+		testType.equal<IsNever<() => void, { selection: 'filter' }>, $NotNever>(true)
+	})
+
+	it('returns $NotNever for union type', () => {
+		testType.equal<IsNever<never | 1, { selection: 'filter' }>, $NotNever>(true)
+	})
+
+	it('returns never for intersection type', () => {
+		// TypeScript resolve this to `never` automatically,
+		// so `IsNever<>` actually does not do anthing in this case.
+		testType.never<never & { a: 1 }>(true)
+		testType.never<IsNever<never & { a: 1 }, { selection: 'filter' }>>(true)
+	})
+})
diff --git a/type-plus/ts/never/is_never.ts b/type-plus/ts/never/is_never.ts
index 19e981b0d4..025cdb68f5 100644
--- a/type-plus/ts/never/is_never.ts
+++ b/type-plus/ts/never/is_never.ts
@@ -1,20 +1,48 @@
-import type { $SelectionOptions, $SelectionPredicate } from '../type_plus/branch/selection.js'
+import type { $SelectionOptions } from '../type_plus/branch/selection.js'
 import type { $ResolveOptions } from '../type_plus/resolve_options.js'
+import type { $NotNever } from './never.js'
 
 /**
  * 🎭 *predicate*
- * 🔢 *customize*
  *
  * Validate if `T` is `never`.
  *
+ * @example
  * ```ts
  * type R = IsNever<never> // true
  *
  * type R = IsNever<1> // false
  * ```
  *
- * 🔢 *customize*: branching
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is `never`, otherwise returns `$NotNever`.
+ *
+ * Filter normally returns `never` in the `$else` clause.
+ * But since we are checking for `never` here,
+ * we have to return `$NotNever` instead.
+ *
+ * @example
+ * ```ts
+ * type R = IsNever<never, { selection: 'filter' }> // never
+ *
+ * type R = IsNever<1, { selection: 'filter' }> // $NotNever
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is `never`, otherwise returns `unknown`.
  *
+ * @example
+ * ```ts
+ * type R = IsNever<1, { selection: 'filter-unknown' }> // unknown
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
  * ```ts
  * type R = IsNever<never, $SelectionBranch> // $Then
  * type R = IsNever<1, $SelectionBranch> // $Else
@@ -22,8 +50,23 @@ import type { $ResolveOptions } from '../type_plus/resolve_options.js'
  */
 export type IsNever<
 	T,
-	$O extends $SelectionOptions = $SelectionPredicate
+	$O extends IsNever.$Options = {}
 > = [T, never] extends [never, T]
-	? $ResolveOptions<[$O['$then'], true]>
-	: $ResolveOptions<[$O['$else'], false]>
+	? $ResolveOptions<[$O['$then'], $O['selection'] extends 'filter' | 'filter-unknown' ? T : true]>
+	: $ResolveOptions<[$O['$else'], $O['selection'] extends 'filter'
+		? $NotNever
+		: $O['selection'] extends 'filter-unknown' ? unknown : false]>
+
 
+export namespace IsNever {
+	export type $Options = Omit<$SelectionOptions, 'selection'> & {
+		/**
+		 * On top of `selection` values from `$SelectionOptions`,
+		 *
+		 * it also support:
+		 *
+		 * `filter-unknown` which returns `unknown` when `T` is `never`
+		 */
+		selection?: 'predicate' | 'filter' | 'filter-unknown' | undefined
+	}
+}
diff --git a/type-plus/ts/never/is_not_never.spec.ts b/type-plus/ts/never/is_not_never.spec.ts
index cdfb19ccb7..0b64452d93 100644
--- a/type-plus/ts/never/is_not_never.spec.ts
+++ b/type-plus/ts/never/is_not_never.spec.ts
@@ -1,5 +1,6 @@
 import { it } from '@jest/globals'
-import { testType, type IsNotNever } from '../index.js'
+import { testType, type IsNotNever, type $Never } from '../index.js'
+import { describe } from 'node:test'
 
 it('returns false for never', () => {
 	testType.false<IsNotNever<never>>(true)
@@ -47,3 +48,42 @@ it('can override Then/Else', () => {
 	testType.equal<IsNotNever<unknown, { $then: 1, $else: 2 }>, 1>(true)
 	testType.equal<IsNotNever<void, { $then: 1, $else: 2 }>, 1>(true)
 })
+
+describe('filter', () => {
+
+	it('returns `is_never` if T is never', () => {
+		testType.equal<IsNotNever<never, { selection: 'filter' }>, $Never>(true)
+	})
+
+	it('returns T for other special types', () => {
+		testType.equal<IsNotNever<unknown, { selection: 'filter' }>, unknown>(true)
+		testType.equal<IsNotNever<void, { selection: 'filter' }>, void>(true)
+		testType.equal<IsNotNever<any, { selection: 'filter' }>, any>(true)
+	})
+
+	it('returns T for other types', () => {
+		testType.equal<IsNotNever<undefined, { selection: 'filter' }>, undefined>(true)
+		testType.equal<IsNotNever<null, { selection: 'filter' }>, null>(true)
+		testType.equal<IsNotNever<number, { selection: 'filter' }>, number>(true)
+		testType.equal<IsNotNever<boolean, { selection: 'filter' }>, boolean>(true)
+		testType.equal<IsNotNever<true, { selection: 'filter' }>, true>(true)
+		testType.equal<IsNotNever<false, { selection: 'filter' }>, false>(true)
+		testType.equal<IsNotNever<string, { selection: 'filter' }>, string>(true)
+		testType.equal<IsNotNever<'', { selection: 'filter' }>, ''>(true)
+		testType.equal<IsNotNever<symbol, { selection: 'filter' }>, symbol>(true)
+		testType.equal<IsNotNever<bigint, { selection: 'filter' }>, bigint>(true)
+		testType.equal<IsNotNever<{}, { selection: 'filter' }>, {}>(true)
+		testType.equal<IsNotNever<string[], { selection: 'filter' }>, string[]>(true)
+		testType.equal<IsNotNever<[], { selection: 'filter' }>, []>(true)
+		testType.equal<IsNotNever<Function, { selection: 'filter' }>, Function>(true)
+		testType.equal<IsNotNever<() => void, { selection: 'filter' }>, () => void>(true)
+	})
+
+	it('returns T for union type', () => {
+		testType.equal<IsNotNever<never | 1, { selection: 'filter' }>, 1>(true)
+	})
+
+	it('returns $Never for intersection type', () => {
+		testType.equal<IsNotNever<never & { a: 1 }, { selection: 'filter' }>, $Never>(true)
+	})
+})
diff --git a/type-plus/ts/never/is_not_never.ts b/type-plus/ts/never/is_not_never.ts
index aac00f2e6c..3f61a11837 100644
--- a/type-plus/ts/never/is_not_never.ts
+++ b/type-plus/ts/never/is_not_never.ts
@@ -1,20 +1,48 @@
-import type { $FlipSelection, $SelectionOptions, $SelectionPredicate } from '../type_plus/branch/selection.js'
-import type { IsNever } from './is_never.js'
+import type { $SelectionOptions } from '../type_plus/branch/selection.js'
+import type { $ResolveOptions } from '../type_plus/resolve_options.js'
+import type { $Never } from './never.js'
 
 /**
  * 🎭 *predicate*
- * 🔢 *customize*
  *
  * Validate if `T` not `never`.
  *
+ * @example
  * ```ts
  * type R = IsNotNever<1> // true
  *
  * type R = IsNotNever<never> // false
  * ```
  *
- * 🔢 *customize*: branching
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not `never`, otherwise returns `$Never`.
  *
+ * Filter normally returns `never` in the `$else` clause.
+ * But since we are checking for `never` here,
+ * we have to return `$Never` instead.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNever<1, { selection: 'filter' }> // 1
+ *
+ * type R = IsNotNever<never, { selection: 'filter' }> // $Never
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is `never`, otherwise returns `unknown`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNever<never, { selection: 'filter-unknown' }> // unknown
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
  * ```ts
  * type R = IsNotNever<never, $SelectionBranch> // $Else
  * type R = IsNotNever<1, $SelectionBranch> // $Then
@@ -22,5 +50,23 @@ import type { IsNever } from './is_never.js'
  */
 export type IsNotNever<
 	T,
-	$Options extends $SelectionOptions = $SelectionPredicate
-> = IsNever<T, $FlipSelection<$Options>>
+	$O extends IsNotNever.$Options = {}
+> = [T, never] extends [never, T]
+	? $ResolveOptions<[$O['$else'], $O['selection'] extends 'filter'
+		? $Never
+		: $O['selection'] extends 'filter-unknown' ? unknown : false]>
+	: $ResolveOptions<[$O['$then'], $O['selection'] extends 'filter' | 'filter-unknown' ? T : true]>
+
+
+export namespace IsNotNever {
+	export type $Options = Omit<$SelectionOptions, 'selection'> & {
+		/**
+		 * On top of `selection` values from `$SelectionOptions`,
+		 *
+		 * it also support:
+		 *
+		 * `filter-unknown` which returns `unknown` when `T` is `never`
+		 */
+		selection?: 'predicate' | 'filter' | 'filter-unknown' | undefined
+	}
+}
diff --git a/type-plus/ts/never/never_type.spec.ts b/type-plus/ts/never/never_type.spec.ts
deleted file mode 100644
index ef747dc2b3..0000000000
--- a/type-plus/ts/never/never_type.spec.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-import { it } from '@jest/globals'
-import { testType, type $NotNever, type NeverType } from '../index.js'
-
-it('returns never if T is never', () => {
-	testType.equal<NeverType<never>, never>(true)
-})
-
-it('returns $NotNever for other special types', () => {
-	testType.equal<NeverType<unknown>, $NotNever>(true)
-	testType.equal<NeverType<void>, $NotNever>(true)
-	testType.equal<NeverType<any>, $NotNever>(true)
-})
-
-it('returns $NotNever for other types', () => {
-	testType.equal<NeverType<undefined>, $NotNever>(true)
-	testType.equal<NeverType<null>, $NotNever>(true)
-	testType.equal<NeverType<number>, $NotNever>(true)
-	testType.equal<NeverType<boolean>, $NotNever>(true)
-	testType.equal<NeverType<true>, $NotNever>(true)
-	testType.equal<NeverType<false>, $NotNever>(true)
-	testType.equal<NeverType<string>, $NotNever>(true)
-	testType.equal<NeverType<''>, $NotNever>(true)
-	testType.equal<NeverType<symbol>, $NotNever>(true)
-	testType.equal<NeverType<bigint>, $NotNever>(true)
-	testType.equal<NeverType<{}>, $NotNever>(true)
-	testType.equal<NeverType<string[]>, $NotNever>(true)
-	testType.equal<NeverType<[]>, $NotNever>(true)
-	testType.equal<NeverType<Function>, $NotNever>(true)
-	testType.equal<NeverType<() => void>, $NotNever>(true)
-})
-
-it('returns $NotNever for union type', () => {
-	testType.equal<NeverType<never | 1>, $NotNever>(true)
-})
-
-it('returns never for intersection type', () => {
-	// TypeScript resolve this to `never` automatically,
-	// so `NeverType<>` actually does not do anthing in this case.
-	testType.never<never & { a: 1 }>(true)
-	testType.never<NeverType<never & { a: 1 }>>(true)
-})
-
-it('can override Then/Else', () => {
-	testType.equal<NeverType<never, { $then: 1, $else: 2 }>, 1>(true)
-	testType.equal<NeverType<0, { $then: 1, $else: 2 }>, 2>(true)
-
-	testType.equal<NeverType<any, { $then: 1, $else: 2 }>, 2>(true)
-	testType.equal<NeverType<unknown, { $then: 1, $else: 2 }>, 2>(true)
-	testType.equal<NeverType<void, { $then: 1, $else: 2 }>, 2>(true)
-})
-
-it('supports partial customization', () => {
-	testType.equal<NeverType<never, { $else: 2 }>, never>(true)
-	testType.equal<NeverType<0, { $then: 1 }>, $NotNever>(true)
-})
diff --git a/type-plus/ts/never/never_type.ts b/type-plus/ts/never/never_type.ts
deleted file mode 100644
index 025a2ec74f..0000000000
--- a/type-plus/ts/never/never_type.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import type { $SelectionOptions } from '../type_plus/branch/selection.js'
-import type { $ResolveOptions } from '../type_plus/resolve_options.js'
-import type { $NotNever } from './never.js'
-
-/**
- * 🌪️ *filter*
- * 🔢 *customize*
- *
- * Filter to ensure `T` is `never`, otherwise returns `$NotNever`.
- *
- * ```ts
- * type R = NeverType<never> // never
- *
- * type R = NeverType<1> // $NotNever
- * ```
- *
- * 🔢 *customize*: as predicate/validate (= `IsNever`)
- *
- * ```ts
- * type R = NeverType<never, $SelectionPredicate> // true
- * type R = NeverType<1, $SelectionPredicate> // false
- * ```
- *
- * 🔢 *customize*: branching
- *
- * ```ts
- * type R = NeverType<never, $SelectionBranch> // $Then
- * type R = NeverType<1, $SelectionBranch> // $Else
- * ```
- */
-export type NeverType<
-	T,
-	$O extends $SelectionOptions = { $then: T, $else: $NotNever }
-> = [T, never] extends [never, T]
-? $ResolveOptions<[$O['$then'], T]>
-: $ResolveOptions<[$O['$else'], $NotNever]>
diff --git a/type-plus/ts/never/not_never_type.spec.ts b/type-plus/ts/never/not_never_type.spec.ts
deleted file mode 100644
index 7cec16dde5..0000000000
--- a/type-plus/ts/never/not_never_type.spec.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { it } from '@jest/globals'
-import { testType, type $Never, type NotNeverType } from '../index.js'
-
-it('returns `is_never` if T is never', () => {
-	testType.equal<NotNeverType<never>, $Never>(true)
-})
-
-it('returns T for other special types', () => {
-	testType.equal<NotNeverType<unknown>, unknown>(true)
-	testType.equal<NotNeverType<void>, void>(true)
-	testType.equal<NotNeverType<any>, any>(true)
-})
-
-it('returns T for other types', () => {
-	testType.equal<NotNeverType<undefined>, undefined>(true)
-	testType.equal<NotNeverType<null>, null>(true)
-	testType.equal<NotNeverType<number>, number>(true)
-	testType.equal<NotNeverType<boolean>, boolean>(true)
-	testType.equal<NotNeverType<true>, true>(true)
-	testType.equal<NotNeverType<false>, false>(true)
-	testType.equal<NotNeverType<string>, string>(true)
-	testType.equal<NotNeverType<''>, ''>(true)
-	testType.equal<NotNeverType<symbol>, symbol>(true)
-	testType.equal<NotNeverType<bigint>, bigint>(true)
-	testType.equal<NotNeverType<{}>, {}>(true)
-	testType.equal<NotNeverType<string[]>, string[]>(true)
-	testType.equal<NotNeverType<[]>, []>(true)
-	testType.equal<NotNeverType<Function>, Function>(true)
-	testType.equal<NotNeverType<() => void>, () => void>(true)
-})
-
-it('returns T for union type', () => {
-	testType.equal<NotNeverType<never | 1>, 1>(true)
-})
-
-it('returns $Never for intersection type', () => {
-	testType.equal<NotNeverType<never & { a: 1 }>, $Never>(true)
-})
-
-it('can override Then/Else', () => {
-	testType.equal<NotNeverType<never, { $then: 1, $else: 2 }>, 2>(true)
-	testType.equal<NotNeverType<0, { $then: 1, $else: 2 }>, 1>(true)
-
-	testType.equal<NotNeverType<any, { $then: 1, $else: 2 }>, 1>(true)
-	testType.equal<NotNeverType<unknown, { $then: 1, $else: 2 }>, 1>(true)
-	testType.equal<NotNeverType<void, { $then: 1, $else: 2 }>, 1>(true)
-})
diff --git a/type-plus/ts/never/not_never_type.ts b/type-plus/ts/never/not_never_type.ts
deleted file mode 100644
index 461af073e1..0000000000
--- a/type-plus/ts/never/not_never_type.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import type { $Else, $SelectionBranch, $SelectionOptions, $Then } from '../type_plus/branch/selection.js'
-import type { IsNever } from './is_never.js'
-import type { $Never } from './never.js'
-
-/**
- * 🌪️ *filter*
- * 🔢 *customize*
- *
- * Filter to ensure `T` is not `never`, otherwise returns `$Never`.
- *
- * ```ts
- * type R = NotNeverType<1> // 1
- *
- * type R = NotNeverType<never> // $Never
- * ```
- *
- * 🔢 *customize*: as predicate/validate (= `IsNotNever`)
- *
- * ```ts
- * type R = NotNeverType<1, $SelectionPredicate> // true
- * type R = NotNeverType<never, $SelectionPredicate> // false
- * ```
- *
- * 🔢 *customize*: branching
- *
- * ```ts
- * type R = NotNeverType<never, $SelectionBranch> // $Else
- * type R = NotNeverType<1, $SelectionBranch> // $Then
- * ```
- */
-export type NotNeverType<
-	T,
-	$Options extends $SelectionOptions = { $then: T, $else: $Never }
-> = IsNever<T, $SelectionBranch> extends infer R
-	? R extends $Then ? $Options['$else']
-	: R extends $Else ? $Options['$then']
-	: never : never
diff --git a/type-plus/ts/never/readme.md b/type-plus/ts/never/readme.md
index 774d697fec..592cd7eaaf 100644
--- a/type-plus/ts/never/readme.md
+++ b/type-plus/ts/never/readme.md
@@ -3,87 +3,101 @@
 `never` is a bottom type in TypeScript.
 That means it is a subtype of all other types.
 
-## Type Checking
+## [IsNever](./is_never.ts)
 
-The `NeverType<T>` and friends are used to check if a type is exactly `never`.
+`IsNever<T, $Options = { selection: 'predicate' | 'filter' | 'filter-unknown', $then: true, $else: false }>`
 
-Filter normally returns `never` in the `$else` clause.
-But since we are checking for `never` here,
-they have to return something other than `never`.
+🎭 *predicate*
 
-Therefore, `NeverType<T>` will return the `$NotNever` when `T` is not `never`,
-and `NotNeverType<T>` will return the `$Never` symbol when `T` is `never`.
+Validate if `T` is `never`.
 
-### [NeverType](./never_type.ts)
+```ts
+type R = IsNever<never> // true
 
-`NeverType<T, $Options = { $then: T, $else: $NotNever }>`
+type R = IsNever<1> // false
+```
 
-🌪️ *filter*
 🔢 *customize*
 
-Filter to ensure `T` is exactly `never`.
+Filter to ensure `T` is `never`, otherwise returns `$NotNever`.
 
-If it is not, returns `$NotNever`.
+Filter normally returns `never` in the `$else` clause.
+But since we are checking for `never` here,
+we have to return `$NotNever` instead.
 
 ```ts
-import type { NeverType } from 'type-plus'
-
-type R = NeverType<never> // never
+type R = IsNever<never, { selection: 'filter' }> // never
 
-type R = NeverType<true> // $NotNever
-type R = NeverType<false> // $NotNever
+type R = IsNever<1, { selection: 'filter' }> // $NotNever
 ```
 
-### [IsNever](./is_never.ts)
+🔢 *customize*
 
-`IsNever<T, $Options = { $then: true, $else: false }>`
+Filter to ensure `T` is `never`, otherwise returns `unknown`.
+
+```ts
+type R = IsNever<1, { selection: 'filter-unknown' }> // unknown
+```
 
-🎭 *predicate*
 🔢 *customize*
 
-Validate if `T` is exactly `never`.
+Use unique branch identifiers to allow precise processing of the result.
 
 ```ts
-import type { IsNever } from 'type-plus'
+type R = IsNever<never, $SelectionBranch> // $Then
+type R = IsNever<1, $SelectionBranch> // $Else
+```
 
-type R = IsNever<never> // true
+### [IsNotNever](./is_not_never.ts)
 
-type R = IsNever<true> // false
-type R = IsNever<false> // false
-```
+`IsNotNever<T, $Options = { selection: 'predicate' | 'filter' | 'filter-unknown', $then: true, $else: false }>`
 
-### [NotNeverType](./not_never_type.ts)
+🎭 *predicate*
+
+Validate if `T` not `never`.
 
-`NotNeverType<T, $Options = { $then: T, $else: $Never }>`
+```ts
+type R = IsNotNever<1> // true
+
+type R = IsNotNever<never> // false
+```
 
-🌪️ *filter*
 🔢 *customize*
 
-Filter `T` to ensure it is not exactly `never`.
+Filter to ensure `T` is not `never`, otherwise returns `$Never`.
 
-### [IsNotNever](./is_not_never.ts)
+Filter normally returns `never` in the `$else` clause.
+But since we are checking for `never` here,
+we have to return `$Never` instead.
 
-`IsNotNever<T, $Options = { $then: true, $else: false }>`
+```ts
+type R = IsNotNever<1, { selection: 'filter' }> // 1
+
+type R = IsNotNever<never, { selection: 'filter' }> // $Never
+```
 
-🎭 *predicate*
 🔢 *customize*
 
-Validate if `T` is not exactly `never`.
+Filter to ensure `T` is `never`, otherwise returns `unknown`.
 
 ```ts
-import type { IsNotNever } from 'type-plus'
+type R = IsNotNever<never, { selection: 'filter-unknown' }> // unknown
+```
 
-type R = IsNotNever<true> // true
-type R = IsNotNever<false> // true
+🔢 *customize*
 
-type R = IsNotNever<never> // false
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsNotNever<never, $SelectionBranch> // $Else
+type R = IsNotNever<1, $SelectionBranch> // $Then
 ```
 
 ## [$Never](./never.ts)
 
 `$Never` is a special branch type to indicate the type is `never`.
 
-It is used in [`NotNeverType`](#notnevertype).
+It is used in [`IsNotNever`](#isnotnever).
 
 ## [$NeverOptions](./never.ts)
 
@@ -139,7 +153,7 @@ Unsurprisingly, defaulting `$never` to `never`.
 
 `$NotNever` is a special branch type to indicate the type is not `never`.
 
-It is used in [`NeverType`](#nevertype).
+It is used in [`IsNever`](#isnever).
 
 ## References
 
diff --git a/type-plus/ts/object/merge.ts b/type-plus/ts/object/merge.ts
index 91f1351aa4..3f1d28ded6 100644
--- a/type-plus/ts/object/merge.ts
+++ b/type-plus/ts/object/merge.ts
@@ -1,8 +1,8 @@
 import type { IsAny } from '../any/is_any.js'
 import type { NonComposableTypes } from '../composable_types.js'
 import type { IsNever } from '../never/is_never.js'
+import type { IsNotNever } from '../never/is_not_never.js'
 import type { $Never } from '../never/never.js'
-import type { NotNeverType } from '../never/not_never_type.js'
 import type { IsLiteral } from '../predicates/literal.js'
 import type { Or } from '../predicates/logical.js'
 import type { IsDisjoint } from './IsDisjoint.js'
@@ -37,56 +37,63 @@ export type Merge<A extends AnyRecord, B extends AnyRecord, Options = Merge.Defa
 					? ([OptionalKeys<A>, OptionalKeys<B>] extends [infer PKA extends KeyTypes, infer PKB extends KeyTypes]
 						?
 						// property is optional when both A[k] and B[k] are optional
-						NotNeverType<
+						IsNotNever<
 							PKA & PKB,
 							{
+								selection: 'filter-unknown',
 								$then: { [k in PKA & PKB]?: A[k] | B[k] },
 								$else: unknown
 							}
 						> &
 						// properties only in A excluding partials is A[k]
-						NotNeverType<
+						IsNotNever<
 							Exclude<KA, PKA | KB>,
 							{
+								selection: 'filter-unknown',
 								$then: { [k in Exclude<KA, PKA | KB>]: A[k] },
 								$else: unknown
 							}
 						> &
 						// properties only in B excluding partials is B[k]
-						NotNeverType<
+						IsNotNever<
 							Exclude<KB, PKB>,
 							{
+								selection: 'filter-unknown',
 								$then: { [k in Exclude<KB, PKB>]: B[k] },
 								$else: unknown
 							}
 						> &
 						// properties is required in A but optional in B is unionized without undefined
-						NotNeverType<
+						IsNotNever<
 							Exclude<KA & PKB, PKA>,
 							{
+								selection: 'filter-unknown',
 								$then: { [k in Exclude<KA & PKB, PKA>]: A[k] | Exclude<B[k], undefined> },
 								$else: unknown
 							}
 						>
 						: never)
 					:
-					NotNeverType<
+					IsNotNever<
 						Exclude<KA, KA & KB>,
 						{
+							selection: 'filter-unknown',
 							$then: { [k in Exclude<KA, KA & KB>]: A[k] },
 							$else: unknown
 						}
 					> &
-					NotNeverType<
+					IsNotNever<
 						Exclude<KB, KA & KB>,
 						{
+							selection: 'filter-unknown',
 							$then: { [k in Exclude<KB, KA & KB>]: B[k] },
 							$else: unknown
 						}
 					> &
-					NotNeverType<
+					IsNotNever<
 						KA & KB,
 						{
+							selection: 'filter-unknown',
 							$then: { [k in KA & KB]: A[k] | B[k] },
 							$else: unknown
 						}
@@ -96,23 +103,26 @@ export type Merge<A extends AnyRecord, B extends AnyRecord, Options = Merge.Defa
 					IsLiteral<KB> extends true
 					? { [k in Exclude<KA, KB>]: A[k] } & { [k in keyof B]: B[k] }
 					:
-					NotNeverType<
+					IsNotNever<
 						Exclude<KA, KA & KB>,
 						{
+							selection: 'filter-unknown',
 							$then: { [k in Exclude<KA, KA & KB>]: A[k] },
 							$else: unknown
 						}
 					> &
-					NotNeverType<
+					IsNotNever<
 						Exclude<KB, KA & KB>,
 						{
+							selection: 'filter-unknown',
 							$then: { [k in Exclude<KB, KA & KB>]: B[k] },
 							$else: unknown
 						}
 					> &
-					NotNeverType<
+					IsNotNever<
 						KA & KB,
 						{
+							selection: 'filter-unknown',
 							$then: { [k in KA & KB]: A[k] | B[k] },
 							$else: unknown
 						}
diff --git a/type-plus/ts/type_plus/branch/selection.ts b/type-plus/ts/type_plus/branch/selection.ts
index 49cb7385fc..8c8cbec1d4 100644
--- a/type-plus/ts/type_plus/branch/selection.ts
+++ b/type-plus/ts/type_plus/branch/selection.ts
@@ -63,6 +63,7 @@ export type $InvertSelection<Branch extends $Then | $Else> =
  *
  * This encourage consumer of your type to use conditional type to avoid performance issues.
  *
+ * @example
  * ```ts
  * type YourType<
  *   T,