type-plus 8.0.0-beta.6 → 8.0.0-beta.8

package/src/$type/special/$special.ts

@@ -0,0 +1,40 @@
+import type { $BranchOptions } from '../branch/$branch.js'
+import type { $InputOptions } from '../branch/$input_options.js'
+import type { $ResolveBranch } from '../branch/$resolve_branch.js'
+import type { $Else, $Selection, $Then } from '../branch/$selection.js'
+import type { $Any } from './$any.js'
+import type { $Never } from './$never.js'
+import type { $Unknown } from './$unknown.js'
+import type { $Void } from './$void.js'
+
+/**
+ * A type to handle special types: `any`, `unknown`, `never`, and `void`.
+ *
+ * @example
+ * ```ts
+ * type YourType<T, $Options extends $Special.Options> = Special<T,
+ * {
+ *   $any: $ResolveBranch<$Options, [$Any, ...], T>
+ *   $unknown: $ResolveBranch<$Options, [$Unknown, ...], T>
+ *   $never: $ResolveBranch<$Options, [$Never, ...], T>
+ *   $void: $ResolveBranch<$Options, [$Void, ...], T>
+ *   $then: $ResolveBranch<$Options, [...], T>
+ *   $else: $ResolveBranch<$Options, [...], T>
+ * }>
+ *
+ * @since 🏷️ 8.0.0
+ */
+export type $Special<T, $O extends $Special.Options = {}> = 0 extends 1 & T
+	? $ResolveBranch<$O, [$Any, $Then], T>
+	: [T, unknown] extends [unknown, T]
+		? $ResolveBranch<$O, [$Unknown, $Then], T>
+		: [T, never] extends [never, T]
+			? $ResolveBranch<$O, [$Never, $Then], T>
+			: [T, void] extends [void, T]
+				? $ResolveBranch<$O, [$Void, $Then], T>
+				: $ResolveBranch<$O, [$Else]>
+
+export namespace $Special {
+	export type Options = $Selection.Options & $InputOptions<$Any | $Unknown | $Never | $Void>
+	export type Branch = $Selection.Branch & $BranchOptions<$Any | $Unknown | $Never | $Void>
+}

package/src/$type/special/$unknown.ts

@@ -0,0 +1,35 @@
+import type { $Branch } from '../branch/$branch.js'
+
+/**
+ * Branch selector for type `unknown`.
+ */
+export type $Unknown = $Branch<'$unknown'>
+
+declare const $unknown: '$unknown'
+
+export namespace $Unknown {
+	export type $Key = '$unknown'
+	/**
+	 * Options to specifically handles the `unknown` type.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<T, $Options extends $Unknown.$Options> = ...
+	 * ```
+	 */
+	export type $Options = { [$unknown]?: unknown }
+
+	/**
+	 * Branch option to specifically handles the `unknown` type.
+	 *
+	 * Use this to finely customize the behavior of your type.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<T, $Options $Unknown.$Options> = ...
+	 *
+	 * type R = YourType<T, $Unknown.$Branch> extends $Unknown ? HandleUnknown : HandleOthers
+	 * ```
+	 */
+	export type $Branch = { [$unknown]: $Unknown }
+}

package/src/$type/special/$void.ts

@@ -0,0 +1,44 @@
+import type { $Branch } from '../branch/$branch.js'
+
+/**
+ * Branch selector for type `void`.
+ */
+export type $Void = $Branch<'$void'>
+
+declare const $void: '$void'
+
+export namespace $Void {
+	export type $Key = '$void'
+
+	/**
+	 * Options to specifically handles the `void` type.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<T, $Options extends $Void.$Options> = ...
+	 * ```
+	 */
+	export type $Options = { [$void]?: unknown }
+
+	/**
+	 * Branch option to specifically handles the `void` type.
+	 *
+	 * Use this to finely customize the behavior of your type.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<T, $Options $Void.$Options> = ...
+	 *
+	 * type R = YourType<T, $Void.$Branch> extends $Void ? HandleNever : HandleOthers
+
+	 * ```
+	 */
+	export type $Branch = { [$void]: $Void }
+
+	/**
+	 * Default option for the `$void` branch.
+	 *
+	 * Unsurprisingly, defaulting `$void` to `void`.
+	 */
+	export type $Default = { [$void]: void }
+}

package/src/$type/special/readme.md

@@ -0,0 +1,51 @@
+# Special Types Handling
+
+"Special types" in TypeScript are `any`, `unknown`, `never`, and `void`.
+They serve as the top and bottom types of the type system,
+and not corresponding to a specific type in JavaScript.
+
+In type-level programming, in many cases we want to handle these types specially.
+
+## [`$Special`](./$special.ts)
+
+🏷️ **since 8.0.0**
+
+`$Special` is a type to handle special types in TypeScript.
+
+🎭 **predicate**
+By default, it acts as a predicate type:
+
+```ts
+type A = $Special<any> // true
+type A = $Special<unknown> // true
+type A = $Special<never> // true
+type A = $Special<void> // true
+type A = $Special<number> // false
+```
+
+🔢 **customize**
+
+`$Special` can be used as a `filter`:
+
+```ts
+type A = $Special<any, { selection: 'filter' }> // any
+type A = $Special<unknown, { selection: 'filter' }> // unknown
+type A = $Special<never, { selection: 'filter' }> // never
+type A = $Special<void, { selection: 'filter' }> // void
+type A = $Special<number, { selection: 'filter' }> // never
+```
+
+🔱 **branching**
+
+Most of the time, `$Special` is used with branching to handle special types.
+
+```ts
+type A<T> = $Special<T, {
+	$any: ...,
+	$unknown: ...,
+	$never: ...,
+	$void: ...,
+	$then: ...,
+	$else: ...,
+}>
+```

package/src/$type/utils/$merge_options.ts

@@ -0,0 +1,11 @@
+/**
+ * Merge type options.
+ *
+ * This is used in the type to merge the user provided options with the default options.
+ *
+ * @typeparam $O - The type of the options, typically provided by the user.
+ * @typeparam $P - The type of the default options.
+ */
+export type $MergeOptions<$O extends Record<string, any>, $P extends { [k in keyof $O]?: unknown }> = {
+	[k in Exclude<keyof $O, keyof $P>]: $O[k]
+} & $P

package/src/$type/utils/readme.md

@@ -0,0 +1,10 @@
+# Type-level utilities
+
+This folder contains utility types for the types in type-level programming.
+
+## [`$MergeOptions`](./merge_options.ts)
+
+🏷️ **since 8.0.0**
+
+`$MergeOptions<$O, $P>` merges two options types `$O` and `$P`.
+This is used in the type to merge the user provided options with the default options.

package/src/any/is_any.ts

@@ -1,13 +1,13 @@
-import type { $Never } from '../never/never.js'
-import type { $SpecialType } from '../type_plus/$special_type.js'
-import type { $InputOptions } from '../type_plus/branch/$input_options.js'
-import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
-import type { $Else, $SelectionBranch, $Then } from '../type_plus/branch/$selection.js'
-import type { $SelectionOptions } from '../type_plus/branch/$selection_options.js'
-import type { $Unknown } from '../unknown/unknown.js'
+import type { $InputOptions } from '../$type/branch/$input_options.js'
+import type { $ResolveBranch } from '../$type/branch/$resolve_branch.js'
+import type { $Else, $Selection, $Then } from '../$type/branch/$selection.js'
+import type { $Never } from '../$type/special/$never.js'
+import type { $Special } from '../$type/special/$special.js'
+import type { $Unknown } from '../$type/special/$unknown.js'
+import type { $Void } from '../$type/special/$void.js'
 
 /**
- * 🎭 *predicate*
+ * 🎭 **predicate**
  *
  * Validate if `T` is `any`.
  *
@@ -20,40 +20,43 @@ import type { $Unknown } from '../unknown/unknown.js'
  * type R = IsAny<string | boolean> // false
  * ```
  *
- * 🔢 *customize*
+ * 🌪️ **filter**
  *
  * Filter to ensure `T` is `any`.
  *
  * @example
  * ```ts
  * type R = IsAny<any, { selection: 'filter' }> // any
- *
  * type R = IsAny<never, { selection: 'filter' }> // never
  * type R = IsAny<unknown, { selection: 'filter' }> // never
  * type R = IsAny<string | boolean, { selection: 'filter' }> // never
  * ```
  *
- * 🔢 *customize*
+ * 🔱 **branching**
  *
  * 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
+ * type R = IsAny<any, $Selection.Branch> // $Then
+ * type R = IsAny<string, $Selection.Branch> // $Else
+ * type R = IsAny<unknown, IsAny.$Branch> // $Unknown
+ * type R = IsAny<never, IsAny.$Branch> // $Never
+ * type R = IsAny<void, IsAny.$Branch> // $Void
  * ```
  */
-export type IsAny<T, $O extends IsAny.$Options = {}> = $SpecialType<
+export type IsAny<T, $O extends IsAny.$Options = {}> = $Special<
 	T,
 	{
-		$any: $ResolveBranch<T, $O, [$Then]>
-		$unknown: $ResolveBranch<T, $O, [$Unknown, $Else]>
-		$never: $ResolveBranch<T, $O, [$Never, $Else]>
-		$else: $ResolveBranch<T, $O, [$Else]>
+		$any: $ResolveBranch<$O, [$Then], T>
+		$unknown: $ResolveBranch<$O, [$Unknown, $Else]>
+		$never: $ResolveBranch<$O, [$Never, $Else]>
+		$void: $ResolveBranch<$O, [$Void, $Else]>
+		$else: $ResolveBranch<$O, [$Else]>
 	}
 >
 
 export namespace IsAny {
-	export type $Options = $SelectionOptions & $InputOptions<$Unknown | $Never>
-	export type $Branch = $SelectionBranch
+	export type $Options = $Selection.Options & $InputOptions<$Unknown | $Never | $Void>
+	export type $Branch = $Selection.Branch & $Unknown.$Branch & $Never.$Branch & $Void.$Branch
 }

package/src/any/is_not_any.ts

@@ -1,10 +1,10 @@
-import type { $Never } from '../never/never.js'
-import type { $SpecialType } from '../type_plus/$special_type.js'
-import type { $InputOptions } from '../type_plus/branch/$input_options.js'
-import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
-import type { $Else, $SelectionBranch, $Then } from '../type_plus/branch/$selection.js'
-import type { $SelectionOptions } from '../type_plus/branch/$selection_options.js'
-import type { $Unknown } from '../unknown/unknown.js'
+import type { $InputOptions } from '../$type/branch/$input_options.js'
+import type { $ResolveBranch } from '../$type/branch/$resolve_branch.js'
+import type { $Else, $Selection, $Then } from '../$type/branch/$selection.js'
+import type { $Never } from '../$type/special/$never.js'
+import type { $Special } from '../$type/special/$special.js'
+import type { $Unknown } from '../$type/special/$unknown.js'
+import type { $Void } from '../$type/special/$void.js'
 
 /**
  * 🎭 *predicate*
@@ -43,17 +43,18 @@ import type { $Unknown } from '../unknown/unknown.js'
  * type R = IsNotAny<string, $SelectionBranch> // $Then
  * ```
  */
-export type IsNotAny<T, $O extends IsNotAny.$Options = {}> = $SpecialType<
+export type IsNotAny<T, $O extends IsNotAny.$Options = {}> = $Special<
 	T,
 	{
-		$any: $ResolveBranch<T, $O, [$Else]>
-		$unknown: $ResolveBranch<T, $O, [$Unknown, $Then]>
-		$never: $ResolveBranch<T, $O, [$Never, $Then]>
-		$else: $ResolveBranch<T, $O, [$Then]>
+		$any: $ResolveBranch<$O, [$Else]>
+		$never: $ResolveBranch<$O, [$Never, $Then], T>
+		$unknown: $ResolveBranch<$O, [$Unknown, $Then], T>
+		$void: $ResolveBranch<$O, [$Void, $Then], T>
+		$else: $ResolveBranch<$O, [$Then], T>
 	}
 >
 
 export namespace IsNotAny {
-	export type $Options = $SelectionOptions & $InputOptions<$Unknown | $Never>
-	export type $Branch = $SelectionBranch
+	export type $Options = $Selection.Options & $InputOptions<$Unknown | $Never | $Void>
+	export type $Branch = $Selection.Branch & $Unknown.$Branch & $Never.$Branch & $Void.$Branch
 }

package/src/any/readme.md

@@ -1,16 +1,25 @@
-# Any
+# `any`
 
-`any` is one of the two top types in TypeScript.
-It is a supertype of all types.
+The `any` type is one of the two top types in TypeScript.
+It is a super-type of all types.
 It is a way to opt-out of type checking and let the values pass through compile-time checks.
 
-## [IsAny](./is_any.ts)
+## [`IsAny`](./is_any.ts)
 
-`IsAny<T, $O = { selection: 'predicate' | 'filter', $then: true, $else: false }>`
+```ts
+IsAny<T, $O = {
+	selection: 'predicate' | 'filter' = 'predicate',
+	$then: unknown = true,
+	$else: unknown = false,
+	$unknown: unknown,
+	$never: unknown,
+	$void: unknown
+}>
+```
 
-🎭 *predicate*
+🎭 **predicate**
 
-Validate if `T` is exactly `any`.
+Validate if `T` is `any`.
 
 ```ts
 type R = IsAny<any> // true
@@ -20,32 +29,34 @@ type R = IsAny<unknown> // false
 type R = IsAny<string | boolean> // false
 ```
 
-🔢 *customize*
+🌪️ **filter**
 
-Filter to ensure `T` is exactly `any`.
+Filter to ensure `T` is `any`.
 
 ```ts
 type R = IsAny<any, { selection: 'filter' }> // any
-
 type R = IsAny<never, { selection: 'filter' }> // never
 type R = IsAny<unknown, { selection: 'filter' }> // never
 type R = IsAny<string | boolean, { selection: 'filter' }> // never
 ```
 
-🔢 *customize*
+🔱 **branching**
 
 Use unique branch identifiers to allow precise processing of the result.
 
 ```ts
-type R = IsAny<any, $SelectionBranch> // $Then
-type R = IsAny<string, $SelectionBranch> // $Else
+type R = IsAny<any, $Selection.Branch> // $Then
+type R = IsAny<string, $Selection.Branch> // $Else
+type R = IsAny<unknown, IsAny.$Branch> // $Unknown
+type R = IsAny<never, IsAny.$Branch> // $Never
+type R = IsAny<void, IsAny.$Branch> // $Void
 ```
 
-### [IsNotAny](./is_not_any.ts)
+### [`IsNotAny`](./is_not_any.ts)
 
 `IsNotAny<T, $O = { selection: 'predicate' | 'filter', $then: true, $else: false }>`
 
-🎭 *predicate*
+🎭 **predicate**
 
 Validate if `T` is not exactly `any`.
 
@@ -57,7 +68,7 @@ type R = IsNotAny<unknown> // true
 type R = IsNotAny<string | boolean> // true
 ```
 
-🔢 *customize*
+🌪️ **filter**
 
 Filter to ensure `T` is not exactly `any`.
 
@@ -69,7 +80,7 @@ type R = IsNotAny<unknown, { selection: 'filter' }> // unknown
 type R = IsNotAny<string | boolean, { selection: 'filter' }> // string | boolean
 ```
 
-🔢 *customize*
+🔱 **branching**
 
 Use unique branch identifiers to allow precise processing of the result.
 
@@ -85,8 +96,8 @@ type R = IsNotAny<string, $SelectionBranch> // $Then
 Well, yeah:
 
 ```ts
-type A = any extends unknown ? 1 : 2 // 1
-type B = unknown extends any ? 1 : 2 // 1
+type A = any extends unknown ? true : false // true
+type B = unknown extends any ? true : false // true
 ```
 
 > Aren't using `any` is bad?

package/src/array/array.reverse.ts

@@ -13,11 +13,8 @@ import type { IsReadonly } from './array_plus.is_readonly.js'
  * @param T The array type to reverse.
  * @returns The reversed array type.
  */
-export type Reverse<A extends readonly unknown[]> = Reverse._<A> extends infer R
-	? IsReadonly<A> extends true
-		? Readonly<R>
-		: R
-	: never
+export type Reverse<A extends readonly unknown[]> =
+	Reverse._<A> extends infer R ? (IsReadonly<A> extends true ? Readonly<R> : R) : never
 
 export namespace Reverse {
 	export type _<A extends readonly unknown[]> = A extends readonly [infer First, ...infer Rest]

package/src/array/array.some.ts

@@ -1,4 +1,4 @@
-import type { IsEqual } from '../equal/equal.js'
+import type { IsEqual } from '../equal/is_equal.js'
 import type { CanAssign } from '../index.js'
 import type { Tail } from '../tuple/tail.js'
 import type { UnionOfValues } from './union_of_values.js'

package/src/array/array_plus.common_prop_keys.ts

@@ -1,5 +1,5 @@
+import type { $Never } from '../$type/special/$never.js'
 import type { IsNever } from '../never/is_never.js'
-import type { $Never } from '../never/never.js'
 import type { KeyTypes } from '../object/KeyTypes.js'
 
 /**

package/src/array/array_plus.filter.ts

@@ -5,9 +5,9 @@
 //  */
 // export type Filter<A extends readonly unknown[], Criteria = true> = Filter._<A, Criteria, []>
 
-import type { IsEqual } from '../equal/equal.js'
+import type { $Never } from '../$type/special/$never.js'
+import type { IsEqual } from '../equal/is_equal.js'
 import type { IsNever } from '../never/is_never.js'
-import type { $Never } from '../never/never.js'
 import type { TypePlusOptions } from '../utils/options.js'
 
 /**

package/src/array/array_plus.find.ts

@@ -1,6 +1,6 @@
-import type { $Never } from '../never/never.js'
+import type { $ResolveOptions } from '../$type/$resolve_options.js'
+import type { $Never } from '../$type/special/$never.js'
 import type { IsTuple } from '../tuple/is_tuple.js'
-import type { $ResolveOptions } from '../type_plus/$resolve_options.js'
 import type { ElementMatch } from './array_plus.element_match.js'
 
 /**

package/src/array/array_plus.index_at.ts

@@ -1,5 +1,5 @@
 import type { IsAny } from '../any/is_any.js'
-import type { IsEqual } from '../equal/equal.js'
+import type { IsEqual } from '../equal/is_equal.js'
 import type { Abs } from '../math/abs.js'
 import type { GreaterThan } from '../math/greater_than.js'
 import type { Subtract } from '../math/subtract.js'
@@ -7,7 +7,6 @@ import type { IsNever } from '../never/is_never.js'
 import type { IsNumber } from '../number/is_number.js'
 import type { IsInteger } from '../numeric/is_integer.js'
 import type { IsNegative } from '../numeric/is_negative.js'
-import type { $Else, $SelectionBranch, $Then } from '../type_plus/branch/$selection.js'
 
 /**
  * 🦴 *utilities*
@@ -29,13 +28,13 @@ export type IndexAt<
 	Fail = never,
 	Upper = A['length'],
 	Lower = 0,
-> = IsNever<A, $SelectionBranch> extends infer R
-	? R extends $Then
-		? Fail
-		: R extends $Else
-			? IndexAt._<A, N, Fail, Upper, Lower>
-			: never
-	: never
+> = IsNever<
+	A,
+	{
+		$then: Fail
+		$else: IndexAt._<A, N, Fail, Upper, Lower>
+	}
+>
 
 export namespace IndexAt {
 	export type _<A extends readonly unknown[], N extends number, Fail = never, Upper = A['length'], Lower = 0> = IsEqual<
@@ -45,31 +44,26 @@ export namespace IndexAt {
 		IsInteger<
 			N,
 			{
-				$then: IsNumber<A['length'], IsNumber.$Branch<{ exact: true }>> extends infer R
-					? // A: array
-						R extends $Then
-						? N
-						: // A: tuple
-							R extends $Else
-							? IsNegative<
-									N,
-									{
-										$then: GreaterThan<Abs<N>, A['length']> extends true ? Lower : Subtract<A['length'], Abs<N>>
-										$else: GreaterThan<A['length'], N> extends true ? N : Upper
-									}
-								>
-							: never
-					: never
+				$then: IsNumber<
+					A['length'],
+					{
+						exact: true
+						$then: N
+						$else: IsNegative<
+							N,
+							{
+								$then: GreaterThan<Abs<N>, A['length']> extends true ? Lower : Subtract<A['length'], Abs<N>>
+								$else: GreaterThan<A['length'], N> extends true ? N : Upper
+							}
+						>
+					}
+				>
 				// N: number or float
 				$else: IsAny<
 					N,
 					{
 						$then: number
-						$else: IsNumber<N, IsNumber.$Branch<{ exact: true }>> extends infer R
-							? R extends $Then
-								? N
-								: never
-							: never
+						$else: IsNumber<N, { exact: true; $then: N; $else: never }>
 					}
 				>
 			}

package/src/array/array_plus.is_readonly.ts

@@ -1,6 +1,6 @@
+import type { $Selection } from '../$type/branch/$selection.js'
+import type { $Never } from '../$type/special/$never.js'
 import type { IsNever } from '../never/is_never.js'
-import type { $Never } from '../never/never.js'
-import type { $SelectionOptions } from '../type_plus/branch/$selection_options.js'
 import type { TypePlusOptions } from '../utils/options.js'
 import type { LooseArrayType } from './loose_array_type.js'
 
@@ -35,7 +35,7 @@ export type IsReadonly<A, $Options extends IsReadonly.Options = IsReadonly.Defau
 	: never
 
 export namespace IsReadonly {
-	export interface Options extends $Never.$Options, $SelectionOptions, TypePlusOptions.NotArray {}
+	export interface Options extends $Never.$Options, $Selection.Options, TypePlusOptions.NotArray {}
 
 	export interface DefaultOptions {
 		$then: true

package/src/array/head.ts

@@ -1,6 +1,6 @@
+import type { $Else, $Selection, $Then } from '../$type/branch/$selection.js'
+import type { $Never } from '../$type/special/$never.js'
 import type { IsNever } from '../never/is_never.js'
-import type { $Never } from '../never/never.js'
-import type { $Else, $SelectionBranch, $Then } from '../type_plus/branch/$selection.js'
 
 /**
  * 🦴 *utilities*
@@ -24,7 +24,7 @@ import type { $Else, $SelectionBranch, $Then } from '../type_plus/branch/$select
  */
 export type Head<T extends readonly unknown[], Options extends Head.Options = Head.DefaultOptions> = IsNever<
 	T,
-	$SelectionBranch
+	$Selection.Branch
 > extends infer R
 	? R extends $Then
 		? Options['$never']