type-plus 7.5.0 → 8.0.0-beta.0

package/{README.md → readme.md}

@@ -12,14 +12,16 @@ More than 200 type utilities for [TypeScript] for applications, library, and typ
 
 ## Table of Contents
 
-1. [What's in the package?](#whats-in-the-package)
+1. [Table of Contents](#table-of-contents)
+2. [Installation](#installation)
+3. [What's in the package?](#whats-in-the-package)
    1. [Update organization](#update-organization)
    2. [Update documentation](#update-documentation)
-2. [Assertion Function](#assertion-function)
+4. [Assertion Function](#assertion-function)
    1. [assertType](#asserttype)
-3. [Type Guard](#type-guard)
-4. [Type Utilities](#type-utilities)
-5. [Type Specific Utilities](#type-specific-utilities)
+5. [Type Guard](#type-guard)
+6. [Type Utilities](#type-utilities)
+7. [Type Specific Utilities](#type-specific-utilities)
    1. [any](#any)
    2. [Array](#array)
    3. [union](#union)
@@ -38,18 +40,19 @@ More than 200 type utilities for [TypeScript] for applications, library, and typ
    16. [undefined](#undefined)
    17. [unknown](#unknown)
    18. [void](#void)
-6. [Constant Types](#constant-types)
-7. [JSON Support](#json-support)
-8. [Type manipulation](#type-manipulation)
-9. [Type Predicates](#type-predicates)
-   1. [Logical](#logical)
-10. [Math](#math)
-11. [Utility Functions](#utility-functions)
-12. [Nominal Types](#nominal-types)
-13. [Functional Types](#functional-types)
-14. [Attribution](#attribution)
-15. [Useful Tips](#useful-tips)
-16. [Similar projects](#similar-projects)
+8. [Testing Utilities](#testing-utilities)
+9. [Constant Types](#constant-types)
+10. [JSON Support](#json-support)
+11. [Type manipulation](#type-manipulation)
+12. [Type Predicates](#type-predicates)
+    1. [Logical](#logical)
+13. [Math](#math)
+14. [Utility Functions](#utility-functions)
+15. [Nominal Types](#nominal-types)
+16. [Functional Types](#functional-types)
+17. [Attribution](#attribution)
+18. [Useful Tips](#useful-tips)
+19. [Similar projects](#similar-projects)
 
 ## Installation
 
@@ -844,6 +847,22 @@ You can learn more in their respective sections:
 
 ⭕ `predicate`: `T !== void`
 
+## Testing Utilities
+
+[type-plus](./README.md) privides some testing utilities to help you test your types.
+
+One of the key utilities is [`testType`](./ts/testing/readme.md#testtype).
+
+```ts
+import { testType } from 'type-plus'
+
+testType.any<T>(true) // T is `any`
+testType.equal<A, B>(true) // A is equal to B
+testType.never<T>(false) // T is not `never`
+```
+
+You can learn more about them in the [docs](./ts/testing/readme.md).
+
 ## Constant Types
 
 > `KeyTypes`

package/ts/array/array.at.ts

@@ -1,6 +1,6 @@
 import type { IsStrictNumber } from '../number/strict_number_type.js'
 import type { TupleType } from '../tuple/tuple_type.js'
-import type { IndexAt } from './array_index.js'
+import type { IndexAt } from './array_plus.index_at.js'
 
 /**
  * 🦴 *utilities*
@@ -17,7 +17,7 @@ import type { IndexAt } from './array_index.js'
  * type R = At<[1, 2, 3], -1> // 3
  * ```
  */
-export type At<A extends unknown[], N extends number, Fail = never> = IndexAt<
+export type At<A extends readonly unknown[], N extends number, Fail = never> = IndexAt<
 	A,
 	N,
 	Fail,

package/ts/array/array.entries.ts

@@ -11,16 +11,16 @@ import type { IsTuple } from '../tuple/tuple_type.js'
  * ArrayPlus.Entries<[1, 2, 3]> // [[0, 1], [1, 2], [2, 3]]
  * ```
  */
-export type Entries<A extends unknown[]> = IsTuple<
+export type Entries<A extends readonly unknown[]> = IsTuple<
 	A,
 	Entries.Device<A, []>,
 	A extends Array<infer T> ? Array<[number, T]> : never
 >
 
 export namespace Entries {
-	export type Device<A extends unknown[], R extends unknown[]> = A['length'] extends 0
-	? R
-	: A extends [...infer F, infer N]
-	? Device<F, [[F['length'], N], ...R]>
-	: never
+	export type Device<A extends readonly unknown[], R extends unknown[]> = A['length'] extends 0
+		? R
+		: (A extends readonly [...infer F, infer N]
+			? Device<F, [[F['length'], N], ...R]>
+			: never)
 }

package/ts/array/array.find_last.ts

@@ -16,14 +16,14 @@ import type { TupleType } from '../tuple/tuple_type.js'
  * ArrayPlus.Find<[true, 123, 'x', 321], number> // 321
  * ```
  */
-export type FindLast<A extends Array<any>, Criteria> = TupleType<
+export type FindLast<A extends readonly unknown[], Criteria> = TupleType<
 	A,
 	A['length'] extends 0
-		? never
-		: A extends [...infer Heads, infer Last]
-		? Last extends Criteria
+	? never
+	: (A extends readonly [...infer Heads, infer Last]
+		? (Last extends Criteria
 			? Last
-			: FindLast<Heads, Criteria>
-		: never,
-	A extends Array<infer T> ? (T extends Criteria ? T | undefined : never) : never
+			: FindLast<Heads, Criteria>)
+		: never),
+	A extends Readonly<Array<infer T>> ? (T extends Criteria ? T | undefined : never) : never
 >

package/ts/array/array.reverse.ts

@@ -1,3 +1,5 @@
+import type { IsReadonly } from './array_plus.is_readonly.js'
+
 /*
  * Reverses the order of elements in the array or tuple.
  *
@@ -11,6 +13,13 @@
  * @param T The array type to reverse.
  * @returns The reversed array type.
  */
-export type Reverse<A extends unknown[]> = A extends [infer First, ...infer Rest]
-	? [...Reverse<Rest>, First]
-	: A
+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]
+		? [..._<Rest>, First]
+		: A
+
+}

package/ts/array/array.some.ts

@@ -23,7 +23,7 @@ import type { UnionOfValues } from './union_of_values.js'
  * ```
  */
 export type Some<
-	A extends any[],
+	A extends readonly unknown[],
 	Criteria,
 	Mode extends 'strict' | 'loose' = 'loose',
 	Then = true,
@@ -31,37 +31,37 @@ export type Some<
 > = Mode extends 'strict' ? Some.Strict<A, Criteria, Then, Else> : Some.Loose<A, Criteria, Then, Else>
 
 export namespace Some {
-	export type Strict<A extends unknown[], Criteria, Then, Else> = number extends A['length']
+	export type Strict<A extends readonly unknown[], Criteria, Then, Else> = number extends A['length']
 		? StrictArray<A, Criteria, Then, Else>
 		: StrictTuple<A, Criteria, Then, Else>
 
-	export type StrictArray<A extends unknown[], Criteria, Then, Else> = IsEqual<
+	export type StrictArray<A extends readonly unknown[], Criteria, Then, Else> = IsEqual<
 		UnionOfValues<A>,
 		Criteria,
 		Then,
 		Else
 	>
 
-	export type StrictTuple<A extends unknown[], Criteria, Then, Else> = A['length'] extends 0
+	export type StrictTuple<A extends readonly unknown[], Criteria, Then, Else> = A['length'] extends 0
 		? Else
-		: IsEqual<A[0], Criteria> extends true
-		? Then
-		: StrictTuple<Tail<A>, Criteria, Then, Else>
+		: (IsEqual<A[0], Criteria> extends true
+			? Then
+			: StrictTuple<Tail<A>, Criteria, Then, Else>)
 
-	export type Loose<A extends unknown[], Criteria, Then, Else> = number extends A['length']
+	export type Loose<A extends readonly unknown[], Criteria, Then, Else> = number extends A['length']
 		? LooseArray<A, Criteria, Then, Else>
 		: LooseTuple<A, Criteria, Then, Else>
 
-	export type LooseArray<A extends unknown[], Criteria, Then, Else> = CanAssign<
+	export type LooseArray<A extends readonly unknown[], Criteria, Then, Else> = CanAssign<
 		UnionOfValues<A>,
 		Criteria,
 		Then,
 		Else
 	>
 
-	export type LooseTuple<A extends unknown[], Criteria, Then, Else> = A['length'] extends 0
+	export type LooseTuple<A extends readonly unknown[], Criteria, Then, Else> = A['length'] extends 0
 		? Else
-		: A[0] extends Criteria
-		? Then
-		: LooseTuple<Tail<A>, Criteria, Then, Else>
+		: (A[0] extends Criteria
+			? Then
+			: LooseTuple<Tail<A>, Criteria, Then, Else>)
 }

package/ts/array/array_plus.common_prop_keys.ts

@@ -15,15 +15,15 @@ import type { KeyTypes } from '../object/KeyTypes.js'
  * type R = ArrayPlus.CommonPropKeys<Array<{ a: 1, b: 1 } | { a: 1, c: 1 }>> // 'a'
  * ```
  *
- * @typeParam Options['caseNever'] Return type when `T` is `never`.
+ * @typeParam Options['$never'] Return type when `T` is `never`.
  * Default to `never`.
  */
 export type CommonPropKeys<
-	A extends Record<KeyTypes, unknown>[],
+	A extends readonly Record<KeyTypes, unknown>[],
 	Options extends CommonPropKeys.Options = CommonPropKeys.DefaultOptions
 > = NeverType<A,
-	Options['caseNever'],
-	A extends Array<infer R extends Record<KeyTypes, unknown>> ? keyof R : never
+	Options['$never'],
+	A extends Readonly<Array<infer R extends Record<KeyTypes, unknown>>> ? keyof R : never
 >
 
 export namespace CommonPropKeys {

package/ts/array/array_plus.concat.ts

@@ -12,4 +12,4 @@
  * type R = Concat<[1], [2, 3]> // [1, 2, 3]
  * ```
  */
-export type Concat<A extends unknown[], B extends unknown[]> = [...A, ...B]
+export type Concat<A extends Readonly<unknown[]>, B extends Readonly<unknown[]>> = [...A, ...B]

package/ts/array/array_plus.drop_match.ts

@@ -1,6 +1,9 @@
 import type { NonNull } from '../utils/NonNull.js'
 import type { NonUndefined } from '../utils/NonUndefined.js'
 
+/**
+ * ⚗️ *transform*
+ */
 export type DropMatch<A extends Readonly<Array<unknown>>, Criteria> = A[0] extends Criteria
 	? never[]
 	: (undefined extends Criteria

package/ts/array/array_plus.element_match.ts

@@ -1,6 +1,6 @@
 import type { IsNever } from '../never/never_type.js'
 import type { IsUnion } from '../union/union.js'
-import type { MergeOptions } from '../utils/options.js'
+import type { TypePlusOptions } from '../utils/options.js'
 
 /**
  * 🦴 *utilities*
@@ -12,13 +12,13 @@ import type { MergeOptions } from '../utils/options.js'
  * e.g. `number, 1` -> `1 | undefined`.
  * Default to `true`.
  *
- * @typeParam Options['caseNotMatch'] Return value when `T` does not match `Criteria`.
+ * @typeParam Options['$notMatch'] Return value when `T` does not match `Criteria`.
  * Default to `never`.
  *
- * @typeParam Options['caseWiden'] Return value when `widen` is true.
+ * @typeParam Options['$widen'] Return value when `widen` is true.
  * Default to `Criteria | undefined`.
  *
- * @typeParam Options['caseUnionNotMatch'] Return value when a branch of the union `T` does not match `Criteria`.
+ * @typeParam Options['$unionNotMatch'] Return value when a branch of the union `T` does not match `Criteria`.
  * Default to `never`.
  *
  * If you want the type to behave more like JavaScript,
@@ -33,29 +33,29 @@ export type ElementMatch<
 	Options extends ElementMatch.Options = ElementMatch.DefaultOptions<Criteria>
 > = [T] extends [Criteria]
 	? T
-	: (MergeOptions<Options, ElementMatch.DefaultOptions<Criteria>> extends infer C extends Record<keyof ElementMatch.Options, unknown>
+	: (TypePlusOptions.Merge<Options, ElementMatch.DefaultOptions<Criteria>> extends infer C extends Record<keyof ElementMatch.Options, unknown>
 		? ((T extends Criteria
 			? T
 			: (C['widen'] extends true
 				? (Criteria extends T
-					? C['caseWiden']
-					: C['caseNotMatch'])
-				: C['caseNotMatch'])) extends infer R
-			? IsUnion<T, IsNever<R, R, R | C['caseUnionNotMatch']>, R>
-			: C['caseNotMatch'])
+					? C['$widen']
+					: C['$notMatch'])
+				: C['$notMatch'])) extends infer R
+			? IsUnion<T, IsNever<R, R, R | C['$unionNotMatch']>, R>
+			: C['$notMatch'])
 		: never)
 
 export namespace ElementMatch {
 	export interface Options {
 		widen?: boolean | undefined,
-		caseNotMatch?: unknown,
-		caseWiden?: unknown,
-		caseUnionNotMatch?: unknown
+		$notMatch?: unknown,
+		$widen?: unknown,
+		$unionNotMatch?: unknown
 	}
 	export interface DefaultOptions<Criteria> {
 		widen: true,
-		caseNotMatch: never,
-		caseWiden: Criteria | undefined,
-		caseUnionNotMatch: never
+		$notMatch: never,
+		$widen: Criteria | undefined,
+		$unionNotMatch: never
 	}
 }

package/ts/array/array_plus.filter.ts

@@ -1,5 +1,49 @@
-export type Filter<A extends unknown[], Criteria> = A[0] extends Criteria
-	? A
-	: Criteria extends A[0]
-	? Array<Criteria>
-	: never[]
+// import type { IsEqual } from '../equal/equal.js'
+
+// /**
+//  * Filters an array or tuple based on criteria
+//  */
+// export type Filter<A extends readonly unknown[], Criteria = true> = Filter._<A, Criteria, []>
+
+import type { IsEqual } from '../equal/equal.js'
+import type { NeverType } from '../never/never_type.js'
+import type { TypePlusOptions } from '../utils/options.js'
+
+/**
+ * ⚗️ *transform*
+ * 🔢 *customizable*
+ *
+ * Filter the array `A`, keeping entries satisfying `Criteria`.
+ *
+ * @example
+ * ```ts
+ * type R = Filter<Array<string | undefined>, string> // string[]
+ * ```
+ */
+export type Filter<
+	A extends readonly unknown[],
+	Criteria = true,
+	Options extends Filter.Options = Filter.DefaultOptions
+> = TypePlusOptions.Merge<Options, Filter.DefaultOptions> extends infer O extends Filter.Options
+	? (NeverType<
+		A,
+		O['$never'],
+		(A[0] extends Criteria
+			? A
+			: Criteria extends A[0] ? Array<Criteria> : O['$notArray'])>)
+	: never
+
+export namespace Filter {
+	export interface Options extends TypePlusOptions.NotArray, NeverType.Options { }
+
+	export interface DefaultOptions {
+		$never: never,
+		$notArray: never[]
+	}
+
+	export type _<A extends readonly unknown[], Criteria, Result extends unknown[]> = A['length'] extends 0
+		? Result
+		: (A extends [infer H, ...infer Rest]
+			? IsEqual<H, Criteria, _<Rest, Criteria, [...Result, H]>, _<Rest, Criteria, Result>>
+			: never)
+}

package/ts/array/array_plus.find.ts

@@ -1,6 +1,6 @@
 import type { NeverType } from '../never/never_type.js'
 import type { TupleType } from '../tuple/tuple_type.js'
-import type { MergeOptions } from '../utils/options.js'
+import type { TypePlusOptions } from '../utils/options.js'
 import type { ElementMatch } from './array_plus.element_match.js'
 
 /**
@@ -25,20 +25,20 @@ import type { ElementMatch } from './array_plus.element_match.js'
  * With widen match, a narrowed type will match its widen type.
  * e.g. matching `1` against `number` yields `1 | undefined`
  *
- * The widen behavior can be customized by `Options['caseWiden']`
+ * The widen behavior can be customized by `Options['$widen']`
  *
- * @typeParam Options['caseNever'] return type when `A` is `never`. Default to `never`.
+ * @typeParam Options['$never'] return type when `A` is `never`. Default to `never`.
  *
- * @typeParam Options['caseNotMatch'] Return value when `T` does not match `Criteria`.
+ * @typeParam Options['$notMatch'] Return value when `T` does not match `Criteria`.
  * Default to `never`.
  *
- * @typeParam Options['caseTuple'] return type when `A` is a tuple. Default to `not supported` message.
+ * @typeParam Options['$tuple'] return type when `A` is a tuple. Default to `not supported` message.
  *
- * @typeParam Options['caseWiden'] return type when `T` in `A` is a widen type of `Criteria`.
+ * @typeParam Options['$widen'] return type when `T` in `A` is a widen type of `Criteria`.
  * Default to `Criteria | undefined`.
  * Set it to `never` for a more type-centric behavior
  *
- * @typeParam Options['caseUnionNotMatch'] Return value when a branch of the union `T` does not match `Criteria`.
+ * @typeParam Options['$unionNotMatch'] Return value when a branch of the union `T` does not match `Criteria`.
  * Default to `never`.
  *
  * If you want the type to behave more like JavaScript,
@@ -47,25 +47,25 @@ import type { ElementMatch } from './array_plus.element_match.js'
  * Since it is a union, the result will be joined to the matched branch as union.
  */
 export type Find<
-	A extends unknown[],
+	A extends readonly unknown[],
 	Criteria,
 	Options extends Find.Options = Find.DefaultOptions<Criteria>
 > =
-	MergeOptions<Options, Find.DefaultOptions<Criteria>> extends infer O extends Find.Options
+	TypePlusOptions.Merge<Options, Find.DefaultOptions<Criteria>> extends infer O extends Find.Options
 	? TupleType<
 		A,
-		O['caseTuple'],
-		A extends Array<infer T> ? ElementMatch<T, Criteria, O> : never,
+		O['$tuple'],
+		A extends Readonly<Array<infer T>> ? ElementMatch<T, Criteria, O> : never,
 		O
 	>
 	: never
 
 export namespace Find {
 	export interface Options extends ElementMatch.Options, NeverType.Options {
-		caseTuple?: unknown,
+		$tuple?: unknown,
 	}
 
 	export interface DefaultOptions<Criteria> extends ElementMatch.DefaultOptions<Criteria>, NeverType.DefaultOptions {
-		caseTuple: 'does not support tuple. Please use `FindFirst` or `TuplePlus.Find` instead.',
+		$tuple: 'does not support tuple. Please use `FindFirst` or `TuplePlus.Find` instead.',
 	}
 }

package/ts/array/{array_index.ts → array_plus.index_at.ts}

@@ -9,8 +9,11 @@ import type { Integer } from '../numeric/integer.js'
 import type { Negative } from '../numeric/negative.js'
 
 /**
+ * 🦴 *utilities*
+ *
  * Gets the normalized index to access the element of an array or tuple.
  *
+ * @example
  * ```ts
  * type R = IndexAt<['a', 'b', 'c'], 2> // 2
  * type R = IndexAt<['a', 'b', 'c'], -2> // 1
@@ -20,54 +23,47 @@ import type { Negative } from '../numeric/negative.js'
  * ```
  */
 export type IndexAt<
-	A extends Array<unknown>,
+	A extends readonly unknown[],
 	N extends number,
 	Fail = never,
 	Upper = A['length'],
 	Lower = 0
-> = IsEqual<
-	A['length'],
-	0,
-	Fail,
-	Integer<
-		N,
-		StrictNumberType<
-			A['length'],
-			// A: array
-			N,
-			// A: tuple
-			Negative<
-				N,
-				GreaterThan<Abs<N>, A['length']> extends true ? Lower : Subtract<A['length'], Abs<N>>,
-				GreaterThan<A['length'], N> extends true ? N : Upper
-			>
-		>,
-		// N: number or float
-		IsAny<
+> = IsNever<A, Fail, 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<
+		A['length'],
+		0,
+		Fail,
+		Integer<
 			N,
-			number,
 			StrictNumberType<
+				A['length'],
+				// A: array
+				N,
+				// A: tuple
+				Negative<
+					N,
+					GreaterThan<Abs<N>, A['length']> extends true ? Lower : Subtract<A['length'], Abs<N>>,
+					GreaterThan<A['length'], N> extends true ? N : Upper
+				>
+			>,
+			// N: number or float
+			IsAny<
 				N,
-				// TODO: handle tuple to union of indexes
-				N
+				number,
+				StrictNumberType<
+					N,
+					// TODO: handle tuple to union of indexes
+					N
+				>
 			>
 		>
 	>
->
-
-/**
- * Is N an out of bound index of A.
- *
- * ```ts
- * type R = IsIndexOutOfBound<[1], 0> // false
- * type R = IsIndexOutOfBound<[1], -1> // false
-
- * type R = IsIndexOutOfBound<[1], 1> // true
- * type R = IsIndexOutOfBound<[1], -2> // true
- * ```
- */
-export type IsIndexOutOfBound<A extends unknown[], N extends number, Then = true, Else = false> = IsNever<
-	IndexAt<A, N, never, never, never>,
-	Then,
-	Else
->
+}

package/ts/array/array_plus.is_index_out_of_bound.ts

@@ -0,0 +1,22 @@
+import type { IsNever } from '../never/never_type.js'
+import type { IndexAt } from './array_plus.index_at.js'
+
+/**
+ * 🎭 *validate*
+ *
+ * Is `N` an out of bound index of `A`.
+ *
+ * @example
+ * ```ts
+ * type R = IsIndexOutOfBound<[1], 0> // false
+ * type R = IsIndexOutOfBound<[1], -1> // false
+ *
+ * type R = IsIndexOutOfBound<[1], 1> // true
+ * type R = IsIndexOutOfBound<[1], -2> // true
+ * ```
+ */
+export type IsIndexOutOfBound<A extends readonly unknown[], N extends number, Then = true, Else = false> = IsNever<
+	IndexAt<A, N, never, never, never>,
+	Then,
+	Else
+>

package/ts/array/array_plus.is_readonly.ts

@@ -0,0 +1,46 @@
+import type { NeverType } from '../never/never_type.js'
+import type { TypePlusOptions } from '../utils/options.js'
+import type { LooseArrayType } from './loose_array_type.js'
+
+/**
+ * 🎭 *validate*
+ * 🔢 *customizable*
+ *
+ * Checks if `A` is a readonly array or tuple
+ *
+ * @example
+ * ```ts
+ * type R = IsReadonly<readonly string[]> // true
+ * type R = IsReadonly<readonly [1, 2, 3, 4, 5]> // true
+ *
+ * type R = IsReadonly<[1, 2, 3, 4, 5]> // false
+ * type R = IsReadonly<readonly string[] | number> // boolean
+ * ```
+ */
+export type IsReadonly<
+	A,
+	Options extends IsReadonly.Options = IsReadonly.DefaultOptions
+> =
+	TypePlusOptions.Merge<Options, IsReadonly.DefaultOptions> extends infer O extends IsReadonly.Options ?
+	NeverType<
+		A,
+		O['$never'],
+		A extends any ?
+		LooseArrayType<A,
+			Readonly<A> extends A ? O['$then'] : O['$else'],
+			O['$notArray']
+		> : never
+	>
+	: never
+
+export namespace IsReadonly {
+	export interface Options
+		extends NeverType.Options, TypePlusOptions.Selection, TypePlusOptions.NotArray { }
+
+	export interface DefaultOptions {
+		$then: true,
+		$else: false,
+		$never: false,
+		$notArray: false
+	}
+}

package/ts/array/array_plus.pad_start.ts

@@ -3,7 +3,7 @@ import type { CreateTuple } from '../tuple/create_tuple.js'
 import type { UnionOfValues } from './union_of_values.js'
 
 export type PadStart<
-	A extends unknown[],
+	A extends readonly unknown[],
 	MaxLength extends number,
 	PadWith = unknown
 > = MaxLength extends 0