type-plus 8.0.0-beta.0 → 8.0.0-beta.2

package/src/array/array_plus.index_at.ts

@@ -0,0 +1,169 @@
+import type { IsAny } from '../any/is_any.js'
+import type { IsEqual } from '../equal/equal.js'
+import type { Abs } from '../math/abs.js'
+import type { GreaterThan } from '../math/greater_than.js'
+import type { Subtract } from '../math/subtract.js'
+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*
+ *
+ * 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
+ *
+ * type R = IndexAt<['a', 'b', 'c'], 3> // never
+ * type R = IndexAt<['a', 'b', 'c'], -4> // never
+ * ```
+ */
+export type IndexAt<
+	A extends readonly unknown[],
+	N extends number,
+	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
+
+export namespace IndexAt {
+	export type _<
+		A extends readonly unknown[],
+		N extends number,
+		Fail = never,
+		Upper = A['length'],
+		Lower = 0
+	> = IsEqual<
+		A['length'],
+		0,
+		Fail,
+		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,
+				// 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
+					}
+				>
+			}
+		>
+	>
+}
+
+
+// import type { IsAny } from '../any/is_any.js'
+// import type { IsEqual } from '../equal/equal.js'
+// import type { Abs } from '../math/abs.js'
+// import type { GreaterThan } from '../math/greater_than.js'
+// import type { Subtract } from '../math/subtract.js'
+// import type { IsNever } from '../never/is_never.js'
+// import type { IsStrictNumber } from '../number/is_strict_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*
+//  *
+//  * 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
+//  *
+//  * type R = IndexAt<['a', 'b', 'c'], 3> // never
+//  * type R = IndexAt<['a', 'b', 'c'], -4> // never
+//  * ```
+//  */
+// export type IndexAt<
+// 	A extends readonly unknown[],
+// 	N extends number,
+// 	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
+
+// export namespace IndexAt {
+// 	export type _<
+// 		A extends readonly unknown[],
+// 		N extends number,
+// 		Fail = never,
+// 		Upper = A['length'],
+// 		Lower = 0
+// 	> = IsEqual<
+// 		A['length'],
+// 		0,
+// 		Fail,
+// 		IsInteger<
+// 			N,
+// 			IsInteger.$Branch
+// 		> extends infer R
+// 		? R extends $Then
+// 		? IsStrictNumber<
+// 			A['length'],
+// 			IsStrictNumber.$Branch
+// 		> extends infer R
+// 		// A: array
+// 		? R extends $Then ? N
+// 		// A: tuple
+// 		: R extends $Else ? IsNegative<
+// 			N,
+// 			IsNegative.$Branch
+// 		> extends infer R
+// 		? R extends $Then ? GreaterThan<Abs<N>, A['length']> extends true ? Lower : Subtract<A['length'], Abs<N>>
+// 		: GreaterThan<A['length'], N> extends true ? N : Upper
+// 		: never
+// 		: never : never
+// 		// N: number or float
+// 		: IsAny<
+// 			N,
+// 			{
+// 				$then: number,
+// 				$else: IsStrictNumber<
+// 					N,
+// 					IsStrictNumber.$Branch
+// 				> extends infer R
+// 				? R extends $Then ? N : never : never
+// 			}
+// 		>
+// 		: never
+// 	>
+// }

package/src/array/array_plus.is_index_out_of_bound.ts

@@ -0,0 +1,24 @@
+import type { IsNever } from '../never/is_never.js'
+import type { IndexAt } from './array_plus.index_at.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * 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: Then,
+		$else: Else
+	}
+>

package/src/array/array_plus.is_readonly.ts

@@ -0,0 +1,50 @@
+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'
+
+/**
+ * 🎭 *predicate*
+ * 🔢 *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 ?
+	IsNever<
+		A,
+		{
+			$then: O['$never'],
+			$else: A extends any ?
+			LooseArrayType<A,
+				Readonly<A> extends A ? O['$then'] : O['$else'],
+				O['$notArray']
+			> : never
+		}
+	>
+	: never
+
+export namespace IsReadonly {
+	export interface Options
+		extends $Never.$Options, $SelectionOptions, TypePlusOptions.NotArray { }
+
+	export interface DefaultOptions {
+		$then: true,
+		$else: false,
+		$never: false,
+		$notArray: false
+	}
+}

package/src/array/array_plus.split_at.ts

@@ -0,0 +1,79 @@
+import type { IsNever } from '../never/is_never.js'
+import type { IsTuple } from '../tuple/is_tuple.js'
+import type { IndexAt } from './array_plus.index_at.js'
+import type { IsArray } from './is_array.js'
+
+/**
+ * ⚗️ *transform*
+ *
+ * Splits array or tuple `A` into two at the specified `Index`.
+ *
+ * If the `Index` is out of bounds,
+ * it will set to the boundary value.
+ *
+ * It is the type level `splice()`.
+ *
+ * @example
+ * ```ts
+ * SplitAt<[1, 2, 3, 4, 5], 2> // [[1, 2], [3, 4, 5]]
+ * SplitAt<[1, 2, 3, 4, 5], -3> // [[1, 2], [3, 4, 5]]
+ *
+ * SplitAt<[1, 2, 3, 4, 5], 2, 2> // [[1, 2, 5], [3, 4]]
+ *
+ * SplitAt<[1, 2, 3, 4, 5], 2, 2, ['a', 'b']> // [[1, 2, 'a', 'b', 5], [3, 4]]
+ *
+ * // out of bound resets to boundary
+ * SplitAt<[1, 2, 3, 4, 5], 6> // [[1, 2, 3, 4, 5], []]
+ * SplitAt<[1, 2, 3, 4, 5], -6> // [[], [1, 2, 3, 4, 5]]
+ * ```
+ */
+export type SplitAt<
+	A extends readonly unknown[],
+	Index extends number,
+	DeleteCount extends number | never = never,
+	Insert extends readonly unknown[] | never = never
+> = IsArray<
+	A,
+	{
+		exact: true,
+		$then: [A, A],
+		$else: SplitAt._<A, [], [], IndexAt._<A, Index>, DeleteCount, Insert>
+	}
+>
+
+export namespace SplitAt {
+	export type _<
+		A extends readonly unknown[],
+		B extends readonly unknown[],
+		C extends readonly unknown[],
+		Index extends number,
+		DeleteCount,
+		Insert extends readonly unknown[],
+	> = 0 extends A['length']
+		? IsTuple<Insert, { $then: [[...Insert, ...B], C], $else: [B, C] }>
+		: (Index extends B['length']
+			? IsNever<
+				DeleteCount,
+				{
+					$then: [B, A],
+					$else: _D<A, B, C, DeleteCount, Insert>
+				}>
+			: (A extends readonly [infer Head, ...infer Tail]
+				? _<Tail, [...B, Head], [], Index, DeleteCount, Insert>
+				: 'unexpected: A does not extends [Head, ...Tail]'))
+
+	export type _D<
+		A extends readonly unknown[],
+		B extends readonly unknown[],
+		C extends readonly unknown[],
+		DeleteCount,
+		Insert extends readonly unknown[],
+	> = DeleteCount extends C['length']
+		? IsTuple<Insert, { $then: [[...B, ...Insert, ...A], C], $else: [[...B, ...A], C] }>
+		: (A extends readonly [infer Head, ...infer Tail]
+			? _D<Tail, B, [...C, Head], DeleteCount, Insert>
+			: IsTuple<Insert, { $then: [[...Insert, ...B], C], $else: [B, C] }>
+		)
+
+}
+

package/src/array/find_first.ts

@@ -0,0 +1,73 @@
+import type { IsTuple } from '../tuple/is_tuple.js'
+import type { Find as TupleFind } from '../tuple/tuple_plus.find.js'
+import type { Find as ArrayFind } from './array_plus.find.js'
+
+/**
+ * 🦴 *utilities*
+ * 🔢 *customizable*
+ *
+ * Find the first type in the array or tuple `A` that matches `Criteria`.
+ *
+ * If the `Criteria` is not met, it will return `never'.
+ *
+ * @example
+ * ```ts
+ * type R = FindFirst<[true, 1, 'x', 3], string> // 'x'
+ * type R = FindFirst<[true, 1, 'x', 3], number> // 1
+ * type R = FindFirst<[string, number, 1], 1> // widen: 1 | undefined
+ * type R = FindFirst<[true, number | string], string> // unionMiss: string | undefined
+ * type R = FindFirst<Array<string>, string> // string
+ * type R = FindFirst<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
+ * type R = FindFirst<Array<string | number>, number | string> // string | number
+ * type R = FindFirst<Array<number>, 1> // widen: 1 | undefined
+ * type R = FindFirst<Array<string | number>, number> // unionMiss: number | undefined
+ *
+ * type R = FindFirst<[true, 1, 'x'], 2> // never
+ * type R = FindFirst<string[], number> // never
+ * ```
+ *
+ * @typeParam Options['widen'] performs widen match.
+ * Default to `true`.
+ * 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['$widen']`
+ *
+ * @typeParam Options['caseEmptyTuple'] return type when `A` is an empty tuple.
+ * Default to `never`.
+ *
+ * @typeParam Options['$never'] return type when `A` is `never`. Default to `never`.
+ *
+ * @typeParam Options['$noMatch'] Return value when `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * @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['$unionMiss'] Return value when a branch of the union `T` does not match `Criteria`.
+ * Default to `undefined`.
+ * Since it is a union, the result will be join to the matched branch as union.
+ */
+export type FindFirst<
+	A extends readonly unknown[],
+	Criteria, Options extends FindFirst.Options = FindFirst.DefaultOptions<Criteria>
+> = IsTuple<
+	A,
+	{
+		$then: TupleFind<A, Criteria, Options>,
+		$else: ArrayFind<A, Criteria, Options>
+	}
+>
+
+export namespace FindFirst {
+	export interface Options extends ArrayFind.Options, TupleFind.Options { }
+	export interface DefaultOptions<Criteria>
+		extends ArrayFind.DefaultOptions<Criteria>, TupleFind.DefaultOptions<Criteria> { }
+}
+
+
+/**
+ * @deprecated use FindFirst
+ */
+export type First<A extends any[], Criteria> = FindFirst<A, Criteria>

package/src/array/head.ts

@@ -0,0 +1,45 @@
+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*
+ * 🔢 *customizable*
+ *
+ * Gets the first entry in the tuple or the type of array `T`.
+ *
+ * @example
+ * ```ts
+ * type R = Head<[1, 2, 3]> // 1
+ * type R = Head<string[]> // string
+ *
+ * type R = Head<[]> // never
+ * ```
+ *
+ * @typeParam Options['$never'] Return type when `T` is `never`.
+ * Default to `never`.
+ *
+ * @typeParam Options['caseEmptyTuple'] Return type when `T` is `[]`.
+ * Default to `never`.
+ */
+export type Head<
+	T extends readonly unknown[],
+	Options extends Head.Options = Head.DefaultOptions
+> = IsNever<
+	T,
+	$SelectionBranch
+> extends infer R
+	? R extends $Then ? Options['$never']
+	: R extends $Else ? T['length'] extends 0 ? Options['caseEmptyTuple'] : T[0]
+	: never : never
+
+
+export namespace Head {
+	export interface Options extends $Never.$Options {
+		caseEmptyTuple?: unknown
+	}
+
+	export interface DefaultOptions extends $Never.$Default {
+		caseEmptyTuple: never
+	}
+}

package/src/array/is_array.ts

@@ -0,0 +1,116 @@
+import type { Assignable } from '../predicates/assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $Exact } from '../type_plus/branch/$exact.js'
+import type { $IsDistributive } from '../type_plus/branch/$is_distributive.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $Then } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate that `T` is an array.
+ *
+ * @example
+ * ```ts
+ * type R = IsArray<number[]> // true
+ * type R = IsArray<[1]> // true
+ *
+ * type R = IsArray<number> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is an array, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsArray<number[], { selection: 'filter' }> // number[]
+ * type R = IsArray<number, { selection: 'filter' }> // never
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Disable distribution of union types.
+ *
+ * @example
+ * ```ts
+ * type R = IsArray<number[] | 1> // boolean
+ * type R = IsArray<number[] | 1, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Check if `T` is exactly an array, excluding tuple.
+ *
+ * @example
+ * ```ts
+ * type R = IsArray<[]> // true
+ * type R = IsArray<[], { exact: true }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsArray<number[], IsArray.$Branch> // $Then
+ * type R = IsArray<number, IsArray.$Branch> // $Else
+ * ```
+ */
+export type IsArray<
+	T,
+	$O extends IsArray.$Options = {}
+> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Else]>,
+			$else: IsArray.$<T, $O>
+		}
+	>
+>
+
+export namespace IsArray {
+	export type $Options = $Equality.$Options & $Exact.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is an array.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> =
+		$Exact.$IsExact<$O, {
+			$then: $IsDistributive<$O, {
+				$then: T extends readonly any[]
+				? (
+					number extends T['length']
+					? $ResolveBranch<T, $O, [$Then]>
+					: $ResolveBranch<T, $O, [$Else]>
+				)
+				: $ResolveBranch<T, $O, [$Else]>,
+				$else: [T] extends [readonly any[]]
+				? (
+					number extends T['length']
+					? $ResolveBranch<T, $O, [$Then]>
+					: $ResolveBranch<T, $O, [$Else]>
+				)
+				: $ResolveBranch<T, $O, [$Else]>
+			}>,
+			$else: $IsDistributive<$O, {
+				$then: T extends readonly any[]
+				? $ResolveBranch<T, $O, [$Then]>
+				: $ResolveBranch<T, $O, [$Else]>,
+				$else: [T] extends readonly [any[]]
+				? $ResolveBranch<T, $O, [$Then]>
+				: $ResolveBranch<T, $O, [$Else]>
+			}>
+		}>
+
+	export type $UtilOptions = Assignable.$UtilOptions & $Exact.$Options
+}

package/src/array/is_not_array.ts

@@ -0,0 +1,114 @@
+import type { NotAssignable } from '../predicates/not_assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $Exact } from '../type_plus/branch/$exact.js'
+import type { $IsDistributive } from '../type_plus/branch/$is_distributive.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $Then } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate that `T` is not an array.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotArray<number[]> // false
+ * type R = IsNotArray<[1]> // false
+ *
+ * type R = IsNotArray<number> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not an array, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotArray<number[], { selection: 'filter' }> // never
+ * type R = IsNotArray<number, { selection: 'filter' }> // number
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Disable distribution of union types.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotArray<number[] | 1> // boolean
+ * type R = IsNotArray<number[] | 1, { distributive: false }> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Check if `T` is not exactly an array, including tuple.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotArray<[]> // false
+ * type R = IsNotArray<[], { exact: true }> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotArray<number[], IsNotArray.$Branch> // $Else
+ * type R = IsNotArray<number, IsNotArray.$Branch> // $Then
+ * ```
+ */
+export type IsNotArray<T,
+	$O extends IsNotArray.$Options = {}
+> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Then]>,
+			$else: IsNotArray.$<T, $O>
+		}
+	>
+>
+export namespace IsNotArray {
+	export type $Options = $Equality.$Options & $Exact.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is not an array.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> =
+		$Exact.$IsExact<$O, {
+			$then: $IsDistributive<$O, {
+				$then: T extends readonly any[]
+				? (
+					number extends T['length']
+					? $ResolveBranch<T, $O, [$Else]>
+					: $ResolveBranch<T, $O, [$Then]>
+				)
+				: $ResolveBranch<T, $O, [$Then]>,
+				$else: [T] extends [readonly any[]]
+				? (
+					number extends T['length']
+					? $ResolveBranch<T, $O, [$Else]>
+					: $ResolveBranch<T, $O, [$Then]>
+				)
+				: $ResolveBranch<T, $O, [$Then]>
+			}>,
+			$else: $IsDistributive<$O, {
+				$then: T extends readonly any[]
+				? $ResolveBranch<T, $O, [$Else]>
+				: $ResolveBranch<T, $O, [$Then]>,
+				$else: [T] extends readonly [any[]]
+				? $ResolveBranch<T, $O, [$Else]>
+				: $ResolveBranch<T, $O, [$Then]>
+			}>
+		}>
+
+	export type $UtilOptions = NotAssignable.$UtilOptions & $Exact.$Options
+}