type-plus 6.8.1 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "type-plus",
-  "version": "6.8.1",
+  "version": "7.0.0",
   "description": "Provides additional types for TypeScript.",
   "homepage": "https://github.com/unional/type-plus",
   "bugs": {

package/ts/array/{array.ts → array.at.ts}

@@ -1,3 +1,5 @@
+import type { IsStrictNumber } from '../number/strict_number_type.js'
+import type { TupleType } from '../tuple/tuple_type.js'
 import type { IndexAt } from './array_index.js'
 
 /**
@@ -13,21 +15,14 @@ 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<A, N, Fail> extends infer I
+export type At<A extends unknown[], N extends number, Fail = never> = IndexAt<
+	A,
+	N,
+	Fail,
+	Fail,
+	Fail
+> extends infer I
 	? I extends number
-		? A[I]
+		? TupleType<A, IsStrictNumber<I, A[I] | undefined, A[I]>, A[I] | undefined>
 		: Fail
 	: never
-
-/**
- * Concats two arrays.
- *
- * alias of: `[...A, ...B]`
- *
- * @alias ArrayPlus.Concat
- *
- * ```ts
- * type R = Concat<[1], [2, 3]> // [1, 2, 3]
- * ```
- */
-export type Concat<A extends unknown[], B extends unknown[]> = [...A, ...B]

package/ts/array/array.concat.ts

@@ -0,0 +1,12 @@
+/**
+ * Concats two arrays or tuples.
+ *
+ * alias of: `[...A, ...B]`
+ *
+ * @alias ArrayPlus.Concat
+ *
+ * ```ts
+ * type R = Concat<[1], [2, 3]> // [1, 2, 3]
+ * ```
+ */
+export type Concat<A extends unknown[], B extends unknown[]> = [...A, ...B]

package/ts/array/array.entries.ts

@@ -0,0 +1,24 @@
+import type { IsTuple } from '../tuple/tuple_type.js'
+/**
+ * Returns an array of key-value pairs for every entry in the array or tuple.
+ *
+ * Note that this is not the same as `Array.entries(A)`,
+ * which returns an iterable interator.
+ *
+ * @example
+ * ```ts
+ * ArrayPlus.Entries<Array<string | number>> // Array<[number, string | number]>
+ * ArrayPlus.Entries<[1, 2, 3]> // [[0, 1], [1, 2], [2, 3]]
+ * ```
+ */
+export type Entries<A extends unknown[]> = IsTuple<
+	A,
+	Device<A, []>,
+	A extends Array<infer T> ? Array<[number, T]> : never
+>
+
+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

package/ts/array/array.find.ts

@@ -0,0 +1,32 @@
+import type { TupleType } from '../tuple/tuple_type.js'
+
+/**
+ * Returns the first type in the array or tuple that matches the `Criteria`.
+ *
+ * If the `Criteria` is not met, it will return `never'.
+ *
+ * For `Array<T>`, it will return `T | undefined` if `T` satisfies `Criteria`.
+ *
+ * @example
+ * ```ts
+ * ArrayPlus.Find<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
+ *
+ * ArrayPlus.Find<[true, 1, 'x', 3], string> // 'x'
+ * ```
+ */
+export type FindFirst<A extends unknown[], Criteria> = TupleType<
+	A,
+	A['length'] extends 0
+		? never
+		: A extends [infer Head, ...infer Tail]
+		? Head extends Criteria
+			? Head
+			: FindFirst<Tail, Criteria>
+		: never,
+	A extends Array<infer T> ? (T extends Criteria ? T | undefined : never) : never
+>
+
+/**
+ * @deprecated use FindFirst
+ */
+export type First<A extends any[], Criteria> = FindFirst<A, Criteria>

package/ts/array/array.find_last.ts

@@ -0,0 +1,27 @@
+import type { TupleType } from '../tuple/tuple_type.js'
+
+/**
+ * Returns the last type in the array or tuple that matches the `Criteria`.
+ *
+ * If the `Criteria` is not met, it will return `never'.
+ *
+ * For `Array<T>`, it will return `T | undefined` if `T` satisfies `Criteria`.
+ *
+ * @example
+ * ```ts
+ * ArrayPlus.Find<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
+ *
+ * ArrayPlus.Find<[true, 123, 'x', 321], number> // 321
+ * ```
+ */
+export type FindLast<A extends Array<any>, Criteria> = TupleType<
+	A,
+	A['length'] extends 0
+		? never
+		: A extends [...infer Heads, infer Last]
+		? Last extends Criteria
+			? Last
+			: FindLast<Heads, Criteria>
+		: never,
+	A extends Array<infer T> ? (T extends Criteria ? T | undefined : never) : never
+>

package/ts/array/array.reverse.ts

@@ -0,0 +1,16 @@
+/*
+ * Reverses the order of elements in the array or tuple.
+ *
+ * @example
+ * ```ts
+ * Reverse<Array<string | number>> // Array<string | number>
+ *
+ * Reverse<[1, 2, 3]> // [3, 2, 1]
+ * ```
+ *
+ * @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

package/ts/array/array.some.ts

@@ -0,0 +1,53 @@
+import type { IsEqual } from '../equal/equal.js'
+import type { CanAssign } from '../index.js'
+import type { Tail } from './tail.js'
+import type { UnionOfValues } from './union_of_values.js'
+
+/**
+ * Determines whether the array type `A` contains any elements that satisfies the specified `Criteria` type.
+ *
+ * It operates in `loose` mode by default,
+ * which means literal types satisfies their widened counterparts.
+ *
+ * You can also change it to `strict` mode.
+ *
+ * @example
+ * ```ts
+ * Some<string[], string> // true
+ * Some<['a', boolean], boolean> // true
+ * Some<['a', true], boolean> //true
+ *
+ * Some<['a', true], boolean, 'strict'> // false
+ * ```
+ */
+export type Some<
+	A extends any[],
+	Criteria,
+	Mode extends 'strict' | 'loose' = 'loose',
+	Then = true,
+	Else = false
+> = 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']
+		? IsEqual<UnionOfValues<A>, Criteria> extends true
+			? Then
+			: Else
+		: StrictTuple<A, Criteria, Then, Else>
+
+	export type StrictTuple<A extends unknown[], Criteria, Then, Else> = A['length'] extends 0
+		? 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']
+		? CanAssign<UnionOfValues<A>, Criteria, Then, Else>
+		: LooseTuple<A, Criteria, Then, Else>
+
+	export type LooseTuple<A extends unknown[], Criteria, Then, Else> = A['length'] extends 0
+		? Else
+		: A[0] extends Criteria
+		? Then
+		: LooseTuple<Tail<A>, Criteria, Then, Else>
+}

package/ts/array/array_index.ts

@@ -1,12 +1,12 @@
 import type { IsAny } from '../any/any_type.js'
-import type { Equal } from '../equal/equal.js'
-import type { Abs } from '../math/Abs.js'
-import type { GreaterThan } from '../math/GreaterThan.js'
-import type { Subtract } from '../math/Subtract.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/never_type.js'
-import type { Integer } from '../number/integer.js'
-import type { Negative } from '../number/negative.js'
 import type { StrictNumberType } from '../number/strict_number_type.js'
+import type { Integer } from '../numeric/integer.js'
+import type { Negative } from '../numeric/negative.js'
 
 /**
  * Gets the normalized index to access the element of an array or tuple.
@@ -19,7 +19,13 @@ import type { StrictNumberType } from '../number/strict_number_type.js'
  * type R = IndexAt<['a', 'b', 'c'], -4> // never
  * ```
  */
-export type IndexAt<A extends Array<unknown>, N extends number, Fail = never> = Equal<
+export type IndexAt<
+	A extends Array<unknown>,
+	N extends number,
+	Fail = never,
+	Upper = A['length'],
+	Lower = 0
+> = IsEqual<
 	A['length'],
 	0,
 	Fail,
@@ -32,8 +38,8 @@ export type IndexAt<A extends Array<unknown>, N extends number, Fail = never> =
 			// A: tuple
 			Negative<
 				N,
-				GreaterThan<Abs<N>, A['length']> extends true ? Fail : Subtract<A['length'], Abs<N>>,
-				GreaterThan<A['length'], N> extends true ? N : Fail
+				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
@@ -61,7 +67,7 @@ export type IndexAt<A extends Array<unknown>, N extends number, Fail = never> =
  * ```
  */
 export type IsIndexOutOfBound<A extends unknown[], N extends number, Then = true, Else = false> = IsNever<
-	IndexAt<A, N>,
+	IndexAt<A, N, never, never, never>,
 	Then,
 	Else
 >

package/ts/array/array_plus.split_at.ts

@@ -0,0 +1,47 @@
+import type { IndexAt } from './array_index.js'
+import { ArrayType } from './array_type.js'
+
+/**
+ * Splits an array into two at the specified `Index`.
+ *
+ * If the `Index` is out of bounds,
+ * it will set to the boundary value, similar to `array.splice()`.
+ *
+ * @example
+ * ```ts
+ * SplitAt<[1, 2, 3, 4, 5], 0> // [[], [1, 2, 3, 4, 5]]
+ * SplitAt<[1, 2, 3, 4, 5], -5> // [[], [1, 2, 3, 4, 5]]
+ *
+ * SplitAt<[1, 2, 3, 4, 5], 2> // [[1, 2], [3, 4, 5]]
+ *
+ * SplitAt<[1, 2, 3, 4, 5], 4> // [[1, 2, 3, 4], [5]]
+ * SplitAt<[1, 2, 3, 4, 5], -1> // [[1, 2, 3, 4], [5]]
+ *
+ * SplitAt<[1, 2, 3, 4, 5], 5> // [[1, 2, 3, 4, 5], []]
+ *
+ * // 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 unknown[], Index extends number> = ArrayType<
+	A,
+	[A, A],
+	ArraySplitAtDevice<A, [], IndexAt<A, Index>>
+>
+
+/**
+ * Splits an array into two at the specified `Index`.
+ * The device does not work on negative index nor out of bound index.
+ *
+ * @internal
+ */
+export type ArraySplitAtDevice<
+	A extends unknown[],
+	B extends unknown[],
+	Index extends number
+> = Index extends B['length']
+	? [B, A]
+	: A extends [infer Head, ...infer Tail]
+	? ArraySplitAtDevice<Tail, [...B, Head], Index>
+	: never

package/ts/array/array_plus.ts

@@ -1,2 +1,10 @@
-export type { At, Concat } from './array.js'
+export type { At } from './array.at.js'
+export type { Concat } from './array.concat.js'
+export type { Entries } from './array.entries.js'
+export type { FindFirst as Find } from './array.find.js'
+export type { FindLast } from './array.find_last.js'
+export type { Reverse } from './array.reverse.js'
+export type { Some } from './array.some.js'
 export type { IndexAt, IsIndexOutOfBound } from './array_index.js'
+export type { SplitAt } from './array_plus.split_at.js'
+export type { PadStart } from './pad_start.js'

package/ts/array/drop.ts

@@ -1,4 +1,4 @@
-import type { Equal } from '../equal/equal.js'
+import type { IsEqual } from '../equal/equal.js'
 import type { NonNull, NonUndefined } from '../utils/index.js'
 
 export type DropFirst<A extends any[]> = number extends A['length']
@@ -21,7 +21,7 @@ export type DropLast<A extends any[]> = number extends A['length']
 	? Heads
 	: never
 
-type ExcludeUnionOfEmptyTuple<A> = Equal<A, []> extends true ? A : Exclude<A, []>
+type ExcludeUnionOfEmptyTuple<A> = IsEqual<A, []> extends true ? A : Exclude<A, []>
 
 /**
  * drops entries matching `Criteria` in array or tuple `A`.

package/ts/array/index.ts

@@ -1,17 +1,16 @@
 export * from './common_prop_keys.js'
-export * from './create_tuple.js'
 export * from './drop.js'
 export * from './filter.js'
-export * from './find_first.js'
-export * from './find_last.js'
+export * from './array.find.js'
+export * from './array.find_last.js'
 export * from './head.js'
 export * from './intersect_of_props.js'
 export * from './last.js'
 export * from './literal_array.js'
-export * from './pad_left.js'
+export * from './pad_start.js'
 export * from './reduce_while.js'
 export * from './reverse.js'
-export * from './some.js'
+export * from './array.some.js'
 export * from './tail.js'
 export * from './union_of_props.js'
 export * from './union_of_values.js'

package/ts/array/pad_start.ts

@@ -0,0 +1,43 @@
+import type { CanAssign } from '../index.js'
+import type { CreateTuple } from '../tuple/create_tuple.js'
+import type { PadStart as TuplePadStart } from '../tuple/tuple_plus.pad_start.js'
+import type { UnionOfValues } from './union_of_values.js'
+
+/**
+ * Pads the start of an array or tuple with `PadWith`.
+ *
+ * @example
+ * ```ts
+ * // Padding array
+ * PadStart<number[], 1, string> // [string, ...number[]]
+ *
+ * // Ignore if the type is compatible
+ * PadStart<number[], 2, number> // number[]
+ * PadStart<number[], 3, 1> // number[]
+ *
+ * // Padding tuple
+ * PadStart<[1, 2, 3], 5, 0> // [0, 0, 1, 2, 3]
+ *
+ * // Ignore if MaxLength is less than the length of the tuple
+ * PadStart<[1, 2, 3], 5, 0> // [0, 0, 1, 2, 3]
+ *
+ * // Default to unknown
+ * PadStart<[1, 2, 3], 5> // [unknown, unknown, 1, 2, 3]
+ * ```
+ */
+export type PadStart<
+	A extends unknown[],
+	MaxLength extends number,
+	PadWith = unknown
+> = number extends A['length']
+	? MaxLength extends 0
+		? A
+		: CanAssign<PadWith, UnionOfValues<A>> extends true
+		? A
+		: PadStart<[...CreateTuple<MaxLength, PadWith>, ...A], MaxLength, PadWith>
+	: TuplePadStart<A, MaxLength, PadWith>
+
+/**
+ * @deprecated use PadStart instead
+ */
+export type PadLeft<A extends any[], Total extends number, PadWith = any> = PadStart<A, Total, PadWith>

package/ts/array/readme.md

@@ -19,10 +19,190 @@ type R = ArrayType<number[] | 1> // never
 type R = ArrayType<number[] & { a: 1 }> // never
 ```
 
-- [`ArrayType<T, Then = T, Else = never>`](array_type.ts#L15): check if `T` is exactly `Array<X>`.
-- [`IsArray<T, Then = true, Else = false`](array_type.ts#L33): is `T` exactly `Array<X>`.
-- [`NotArrayType<T, Then = T, Else = never>`](array_type.ts#L47): check if `T` is not exactly `Array<X>`.
-- [`IsNotArray<T, Then = true, Else = false>`](array_type.ts#L61): is `T` not exactly `Array<X>`.
+- [`ArrayType<T, Then = T, Else = never>`](array_type.ts#L15): check if `T` is an array and not a tuple.
+- [`IsArray<T, Then = true, Else = false`](array_type.ts#L33): is `T` an array and not a tuple.
+- [`NotArrayType<T, Then = T, Else = never>`](array_type.ts#L47): check if `T` is not an array (can be a tuple).
+- [`IsNotArray<T, Then = true, Else = false>`](array_type.ts#L61): is `T` not an array (can be a tuple).
+
+## ArrayPlus
+
+`ArrayPlus` contains all types and type utilities related to array.
+Whenever possible, these types and type utilities also work with *tuples*,
+as *tuples* is a subset of array.
+
+For *tuple* specific types and type utilities,
+please check [`TuplePlus`](../tuple/readme.md#TuplePlus).
+
+### [`ArrayPlus.At`](./array.at.ts#L18)
+
+> `ArrayPlus.At<A, N, Fail = never>`
+
+Gets the type of the array or tuple `A` at index `N`.
+
+For array, it will return the union of the type of the array value and `undefined`,
+as there is no way to guarantee the array has value at `N`.
+
+```ts
+type A = Array<string | number>
+
+ArrayPlus.At<A, 0> // string | number | undefined
+```
+
+For tuple, it will return the type of the tuple value at index `N`.
+
+```ts
+type T = [number, string, 1, 2, 3]
+
+ArrayPlus.At<T, 0> // number
+ArrayPlus.At<T, -1> // 3
+```
+
+If the `N` is out of bound,
+or `N` is not a valid index,
+`ArrayPlus.At` will return the `Fail` case, which defaults to `never`.
+
+### [`ArrayPlus.Concat`](./array.concat.ts#L12)
+
+> `ArrayPlus.Concat<A, B>`
+
+Concats two arrays or tuples.
+
+It is just an alias of `[...A, ...B]`.
+It is added for completeness.
+
+You are encouraged to use `[...A, ...B]` directly.
+
+### [`ArrayPlus.Entries`](./array.entries.ts#L14)
+
+> `ArrayPlus.Entries<A>`
+
+Returns an array of key-value pairs for every entry in the array or tuple.
+
+Note that this is not the same as `Array.entries(A)`,
+which returns an iterable interator.
+
+```ts
+ArrayPlus.Entries<Array<string | number>> // Array<[number, string | number]>
+ArrayPlus.Entries<[1, 2, 3]> // [[0, 1], [1, 2], [2, 3]]
+```
+
+### [`ArrayPlus.Find`](./array.find.ts#L17)
+
+> `ArrayPlus.Find<A, Criteria>
+
+Returns the first type in the array or tuple that matches the `Criteria`.
+
+If the `Criteria` is not met, it will return `never'.
+
+For `Array<T>`, it will return `T | undefined` if `T` satisfies `Criteria`.
+
+```ts
+ArrayPlus.Find<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
+
+ArrayPlus.Find<[true, 1, 'x', 3], string> // 'x'
+```
+
+### [`ArrayPlus.FindLast`](./array.find_last.ts#L17)
+
+> `ArrayPlus.FindLast<A, Criteria>
+
+Returns the last type in the array or tuple that matches the `Criteria`.
+
+If the `Criteria` is not met, it will return `never'.
+
+For `Array<T>`, it will return `T | undefined` if `T` satisfies `Criteria`.
+
+```ts
+ArrayPlus.FindLast<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
+
+ArrayPlus.FindLast<[true, 123, 'x', 321], number> // 321
+```
+
+### [`ArrayPlus.Reverse`](./array.reverse.ts#L14)
+
+> `ArrayPlus.Reverse<A>`
+
+Reverses the order of the array or tuple.
+
+```ts
+ArrayPlus.Reverse<[1, 2, 3]> // [3, 2, 1]
+```
+
+### [`ArrayPlus.SplitAt`](./array_plus.split_at.ts#L22)
+
+> `ArrayPlus.SplitAt<A, Index>`
+
+Splits the array or tuple at `Index`.
+
+```ts
+ArrayPlus.SplitAt<[1, 2, 3], 1> // [[1, 2], [3]]
+```
+
+### [`ArrayPlus.Some`](./array.some.ts#L23)
+
+> `ArrayPlus.Some<A, Criteria, Mode, Then, Else>`
+
+Determines whether the array type `A` contains any elements that satisfies the specified `Criteria` type.
+
+It operates in `loose` mode by default,
+which means literal types satisfies their widened counterparts.
+You can also change it to `strict` mode.
+
+```ts
+Some<string[], string> // true
+Some<['a', boolean], boolean> // true
+Some<['a', true], boolean> //true
+
+Some<['a', true], boolean, 'strict'> // false
+```
+
+## Builtin array methods
+
+JavaScript has many builtin array methods.
+We will try to bring them to the type-level.
+
+Not all methods can be implemented in the type-level,
+or in the same way.
+
+For example, type-level does not support higher-level generics,
+i.e. it is not possible to pass in a generic type and "invoke" it.
+
+Therefore, methods like `map` and `reduce()` cannot be implemented generically.
+They have to be implemented separately for each specific use case,
+or with reduced capability.
+
+They are exposed under the `ArrayPlus` namespace,
+while some common ones are exposed at top-level.
+
+Here are the list of array methods and their corresponding type-level functions, if availableL
+
+- ✅ `at`: [`ArrayPlus.At`](#arrayplusat)
+- ✅ `concat`: [`Concat` | `ArrayPlus.Concat`](#arrayplusconcat) (`[...A, ...B]`)
+- 🚧 `copyWithin`:  `CopyWithin<A, Target, Start, End>`
+- ✴️ `entries`: [`ArrayPlus.Entries`](#arrayplusentries)
+- 🚧 `every`: `Every<A, Criteria, Then = A, Else = never>`
+- 🚧 `fill`: `Fill<A, V, Start, End>`
+- ✴️ `find`: [`FindFirst` | `ArrayPlus.Find`](#arrayplusfind)
+  - ✴️ [`FindLast` | `ArrayPlus.FindLast`](#arrayplusfindlast)
+- 🚧 `findIndex`: `FindIndex<A, Criteria> => number | number literal | never`
+- 🚧 `flat`: `Flat<A>`
+- 🚧 `flatMap`: `Flat<A, Criteria, R>`
+- 🚧 `includes`:
+- 🚧 `join`:
+- 🚧 `keys`: `Range<0, T['length']>`?
+- 🚧 `map`: `Map<A, Criteria, R>`
+- 🚧 `pop`: `Pop<A>`
+- 🧬 `push`: `[...A, T]`
+- 🚧 `reduce`:
+- 🚧 `reduceRight`:
+- ✅ `reverse`: [`ArrayPlus.Reverse`](#arrayplusreverse)
+- 🚧 `shift`:
+- 🚧 `slice`:
+- ✴️ `some`: [`Some` | `ArrayPlus.Some`](#arrayplussome)
+- 🚧 `sort`:
+- 🚧 `splice`:
+- 🧬 `unshift`: `[T, ...A]`
+- 🧬 `values`: `keyof A`
 
 ## References
 

package/ts/assertion/assert_type.ts

@@ -8,6 +8,9 @@ import { AnyFunction } from '../function/any_function.js'
  */
 export function assertType<T>(subject: T): asserts subject is T
 export function assertType<T>(subject: unknown, validator: (s: T) => boolean): asserts subject is T
+/**
+ * @deprecated this is not a failsafe test
+ */
 export function assertType<T extends new (...args: any) => any>(
 	subject: unknown,
 	constructor: T
@@ -78,6 +81,9 @@ assertType.noFunction = function <S>(subject: Exclude<S, AnyFunction>): void {
 	if (typeof subject === 'function') throw TypeError(`subject is function`)
 }
 
+/**
+ * @deprecated
+ */
 assertType.isConstructor = function (subject: AnyConstructor): asserts subject is AnyConstructor {
 	if (!isConstructor(subject)) throw TypeError(`subject is not a constructor`)
 }