type-plus 7.3.0 → 7.4.0

package/ts/any/readme.md

@@ -1,6 +1,8 @@
 # Any
 
-`any` is one of the two top type in TypeScript. It is the supertype of all types. It is a way to opt-out of type checking and let the values pass through compile-time checks.
+`any` is one of the two top types in TypeScript.
+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.
 
 ## Type Checking
 
@@ -10,14 +12,96 @@ They are strict type checks, meaning they match only the type `any`.
 Union and intersections are not a factor here they are resolved to `any`,
 except `any & never` which is `never`.
 
-- [`AnyType<T, Then = T, Else = never>`](any_type.ts#L15): check if `T` is exactly `any`.
-- [`IsAny<T, Then = true, Else = false`](any_type.ts#L30): is `T` exactly `any`.
-- [`NotAnyType<T, Then = T, Else = never>`](any_type.ts#L45): check if `T` is not exactly `any`.
-- [`IsNotAny<T, Then = true, Else = false>`](any_type.ts#L60): is `T` not exactly `any`.
+### [AnyType](./any.spec.ts#15)
 
-## Type Utilities
+`AnyType<T, Then = T, Else = never>`
 
-- [`IsAnyOrNever<T, Then = true, Else = false>`](any_or_never.ts#L17)]: is `T` type `any` or `never`.
+🌪️ *filter*
+
+Filter `T` to ensure it is exactly `any`.
+
+```ts
+import type { AnyType } from 'type-plus'
+
+type R = AnyType<any> // any
+
+type R = AnyType<never> // never
+type R = AnyType<unknown> // never
+type R = AnyType<string | boolean> // never
+```
+
+### [IsAny](./any.spec.ts#31)
+
+`IsAny<T, Then = true, Else = false>`
+
+🎭 *validate*
+
+Validate if `T` is exactly `any`.
+
+```ts
+import type { IsAny } from 'type-plus'
+
+type R = IsAny<any> // true
+
+type R = IsAny<never> // false
+type R = IsAny<unknown> // false
+type R = IsAny<string | boolean> // false
+```
+
+### [NotAnyType](./any.spec.ts#47)
+
+`NotAnyType<T, Then = T, Else = never>`
+
+🌪️ *filter*
+
+Filter `T` to ensure it is not exactly `any`.
+
+```ts
+import type { NotAnyType } from 'type-plus'
+
+type R = NotAnyType<any> // never
+
+type R = NotAnyType<never> // never
+type R = NotAnyType<unknown> // never
+type R = NotAnyType<string | boolean> // string | boolean
+```
+
+### [IsNotAny](./any.spec.ts#65)
+
+`IsNotAny<T, Then = true, Else = false>`
+
+🎭 *validate*
+
+Validate if `T` is not exactly `any`.
+
+```ts
+import type { IsNotAny } from 'type-plus'
+
+type R = IsNotAny<any> // false
+
+type R = IsNotAny<never> // true
+type R = IsNotAny<unknown> // true
+type R = IsNotAny<string | boolean> // true
+```
+
+## Trivia
+
+> Both `any` and `unknown` are top types?
+
+Well, yeah:
+
+```ts
+type A = any extends unknown ? 1 : 2 // 1
+type B = unknown extends any ? 1 : 2 // 1
+```
+
+> Aren't using `any` is bad?
+
+If you use it to simply tell TypeScript to shut up because you are lazy, then yes.
+
+But it is ok to use `any` in many cases, as the type system of TypeScript is not sounded.
+
+There are many cases it is not possible to induce the type correctly.
 
 ## References
 

package/ts/array/array.at.ts

@@ -3,7 +3,9 @@ import type { TupleType } from '../tuple/tuple_type.js'
 import type { IndexAt } from './array_index.js'
 
 /**
- * Gets the type of the array or tuple at index `N`.
+ * 🦴 *utilities*
+ *
+ * Gets the type of the array or tuple at positive or negative index `N`.
  *
  * Like `Array.at()`, this type supports negative numbers.
  *

package/ts/array/array.find.ts

@@ -1,7 +1,9 @@
 import type { TupleType } from '../tuple/tuple_type.js'
 
 /**
- * Returns the first type in the array or tuple that matches the `Criteria`.
+ * 🦴 *utilities*
+ *
+ * Gets the first type in the array or tuple that matches the `Criteria`.
  *
  * If the `Criteria` is not met, it will return `never'.
  *

package/ts/array/array.find_last.ts

@@ -1,7 +1,9 @@
 import type { TupleType } from '../tuple/tuple_type.js'
 
 /**
- * Returns the last type in the array or tuple that matches the `Criteria`.
+ * 🦴 *utilities*
+ *
+ * Gets the last type in the array or tuple that matches the `Criteria`.
  *
  * If the `Criteria` is not met, it will return `never'.
  *

package/ts/array/array.some.ts

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

package/ts/array/{array.concat.ts → array_plus.concat.ts}

@@ -1,4 +1,7 @@
 /**
+ * 🦴 *utilities
+ * 💀 *deprecated* Will be available only as `ArrayPlus.Concat` in the next version
+ *
  * Concats two arrays or tuples.
  *
  * alias of: `[...A, ...B]`

package/ts/array/array_plus.filter.ts

@@ -0,0 +1,5 @@
+export type Filter<A extends unknown[], Criteria> = A[0] extends Criteria
+	? A
+	: Criteria extends A[0]
+	? Array<Criteria>
+	: never[]

package/ts/array/array_plus.pad_start.ts

@@ -0,0 +1,13 @@
+import type { CanAssign } from '../index.js'
+import type { CreateTuple } from '../tuple/create_tuple.js'
+import type { UnionOfValues } from './union_of_values.js'
+
+export type PadStart<
+	A extends unknown[],
+	MaxLength extends number,
+	PadWith = unknown
+> = MaxLength extends 0
+	? A
+	: CanAssign<PadWith, UnionOfValues<A>> extends true
+	? A
+	: PadStart<[...CreateTuple<MaxLength, PadWith>, ...A], MaxLength, PadWith>

package/ts/array/array_plus.ts

@@ -1,10 +1,11 @@
 export type { At } from './array.at.js'
-export type { Concat } from './array.concat.js'
+export type { Concat } from './array_plus.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 { Filter } from './array_plus.filter.js'
 export type { SplitAt } from './array_plus.split_at.js'
-export type { PadStart } from './pad_start.js'
+export type { PadStart } from './array_plus.pad_start.js'

package/ts/array/array_type.ts

@@ -2,12 +2,17 @@ import type { IsNever } from '../never/never_type.js'
 import type { StrictNumberType } from '../number/strict_number_type.js'
 
 /**
- * Check if the type `T` is an array and not a tuple.
+ * 🌪️ *filter*
  *
+ * Filter `T` to ensure it is an array, excluding tuple.
+ *
+ * @example
  * ```ts
  * type R = ArrayType<number[]> // number[]
  *
  * type R = ArrayType<[1]> // never
+ * type R = ArrayType<number[] | 1> // never
+ * type R = ArrayType<number[] & { a: 1 }> // never
  * ```
  */
 export type ArrayType<T, Then = T, Else = never> = IsNever<
@@ -17,32 +22,45 @@ export type ArrayType<T, Then = T, Else = never> = IsNever<
 >
 
 /**
- * Check if the type `T` is not an array.
+ * 🎭 *validate*
+ *
+ * Validate that `T` is an array, excluding tuple.
  *
+ * @example
  * ```ts
- * type R = NotArrayType<number[]> // never
+ * type R = IsArray<number[]> // true
  *
- * type R = NotArrayType<number> // number
- * type R = NotArrayType<[1]> // [1]
+ * type R = IsArray<number> // false
+ * type R = IsArray<[1]> // false
  * ```
  */
-export type NotArrayType<T, Then = T, Else = never> = ArrayType<T, Else, Then>
+export type IsArray<T, Then = true, Else = false> = ArrayType<T, Then, Else>
 
 /**
- * Is `T` an array?
+ * 🌪️ *filter*
+ *
+ * Filter `T` to ensure it is not an array, excluding tuple.
  *
+ * i.e. *tuple* will pass through this filter.
+ *
+ * @example
  * ```ts
- * type R = IsArray<number[]> // true
+ * type R = NotArrayType<number[]> // never
  *
- * type R = IsArray<number> // false
- * type R = IsArray<[1]> // false
+ * type R = NotArrayType<number> // number
+ * type R = NotArrayType<[1]> // [1]
  * ```
  */
-export type IsArray<T, Then = true, Else = false> = ArrayType<T, Then, Else>
+export type NotArrayType<T, Then = T, Else = never> = ArrayType<T, Else, Then>
 
 /**
- * Is `T` not an array?
+ * 🎭 *validate*
+ *
+ * Validate that `T` is not an array, excluding tuple.
+ *
+ * i.e. *tuple* will pass through this filter.
  *
+ * @example
  * ```ts
  * type R = IsNotArray<number[]> // false
  *

package/ts/array/filter.ts

@@ -1,27 +1,32 @@
+import type { Filter as FilterTuple } from '../tuple/tuple_plus.filter.js'
+import type { Filter as FilterArray } from './array_plus.filter.js'
+
 /**
- * filter the array or tuple `A`, keeping entries satisfying `Criteria`.
+ * ⚗️ *transform*
+ *
+ * Filter the array or tuple `A`, keeping entries satisfying `Criteria`.
+ *
+ * @example
+ * ```ts
+ * type R = Filter<[1, 2, '3'], number> // [1, 2]
+ * type R = Filter<Array<string | undefined>, string> // string[]
+ * ```
  */
-export type Filter<A extends Array<any>, Criteria> = number extends A['length']
-	? // array
-	  A[0] extends Criteria
-		? A
-		: Criteria extends A[0]
-		? Array<Criteria>
-		: never[]
-	: // tuple
-	A['length'] extends 0
-	? never
-	: A extends [infer Head, ...infer Tail]
-	? Tail['length'] extends 0
-		? Head extends Criteria
-			? [Head]
-			: never[]
-		: Head extends Criteria
-		? [Head, ...Filter<Tail, Criteria>]
-		: Filter<Tail, Criteria>
-	: never
+export type Filter<A extends unknown[], Criteria> = number extends A['length']
+	? FilterArray<A, Criteria>
+	: FilterTuple<A, Criteria>
 
 /**
- * keeps entries satisfying `Criteria` in array or tuple `A`.
+ * ⚗️ *transform*
+ * 👽 *alias*
+ *
+ * Keeps entries satisfying `Criteria` in array or tuple `A`.
+ *
+ * @alias of [Filter](./filter.ts)
+ * @example
+ * ```ts
+ * type R = KeepMatch<[1, 2, 3], number> // [1, 2]
+ * type R = KeepMatch<Array<string|undefined>, string> // string[]
+ * ```
  */
-export type KeepMatch<A extends Array<any>, Criteria> = Filter<A, Criteria>
+export type KeepMatch<A extends unknown[], Criteria> = Filter<A, Criteria>

package/ts/array/head.ts

@@ -1 +1,18 @@
-export type Head<T extends any[]> = T['length'] extends 0 ? never : T[0]
+/**
+ * 🦴 *utilities*
+ *
+ * Gets the first entry in the tuple or the type of array.
+ *
+ * @example
+ * ```ts
+ * type R = Head<[1, 2, 3]> // 1
+ * type R = Head<string[]> // string
+ *
+ * type R = Head<[]> // never
+ * ```
+ */
+export type Head<T extends any[], Cases extends {
+	empty_tuple?: unknown
+} = {
+	empty_tuple: never
+}> = T['length'] extends 0 ? Cases['empty_tuple'] : T[0]

package/ts/array/intersect_of_props.ts

@@ -1,10 +1,14 @@
 import type { KeyTypes } from '../object/index.js'
-import type { Tail } from './tail.js'
+import type { Tail } from '../tuple/tail.js'
 
 /**
- * Gets the intersect of properties of the elements in `A`
+ * 🦴 *utilities*
+ *
+ * Gets the intersect of properties of the elements in `A`.
  */
-export type IntersectOfProps<A extends Record<any, unknown>[], P extends KeyTypes> = A['length'] extends 0
+export type IntersectOfProps<A extends Record<any, unknown>[], P extends KeyTypes> = number extends A['length']
+	? A[0][P]
+	: A['length'] extends 0
 	? never
 	: A['length'] extends 1
 	? A[0][P]

package/ts/array/last.ts

@@ -1,4 +1,18 @@
 /**
- * Get the last type of an array or tuple.
+ * 🦴 *utilities*
+ *
+ * Gets the last entry in the tuple or the type of array.
+ *
+ * @example
+ * ```ts
+ * type R = Last<[1, 2, 3]> // 3
+ * type R = Last<string[]> // string
+ *
+ * type R = Last<[]> // never
+ * ```
  */
-export type Last<T extends any[]> = T extends [...any[], infer R] ? R : T[0]
+export type Last<T extends unknown[], Cases extends {
+	empty_tuple?: unknown
+} = {
+	empty_tuple: never
+}> = T['length'] extends 0 ? Cases['empty_tuple'] : T extends [...unknown[], infer R] ? R : T[0]

package/ts/array/literal_array.ts

@@ -1,5 +1,10 @@
 import type { KeyTypes } from '../object/index.js'
 
+/**
+ * 🦴 *utilities*
+ *
+ * return an array whose items are restricted to the provided literals.
+ */
 export function literalArray<T extends KeyTypes>(...entries: T[]): T[] {
 	return entries
 }

package/ts/array/pad_start.ts

@@ -1,11 +1,11 @@
-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'
+import type { PadStart as PadStartTuple } from '../tuple/tuple_plus.pad_start.js'
+import type { PadStart as PadStartArray } from './array_plus.pad_start.js'
 
 /**
  * Pads the start of an array or tuple with `PadWith`.
  *
+ * ⚗️ *transform*
+ *
  * @example
  * ```ts
  * // Padding array
@@ -30,12 +30,8 @@ export type PadStart<
 	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>
+	? PadStartArray<A, MaxLength, PadWith>
+	: PadStartTuple<A, MaxLength, PadWith>
 
 /**
  * @deprecated use PadStart instead

package/ts/array/readme.md

@@ -1,6 +1,11 @@
 # Array
 
-`Array<T>` or `T[]` is a type that represents an array of `T`.
+In TypeScript, the type of an JavaScript array can be an [array](#array) or a [tuple](../tuple/readme.md).
+
+`Array<T>` or `T[]` is a type that represents an array of `T`
+
+There is no length limitation to an `Array`,
+and each element has the same type `T`.
 
 ## Type Checking
 
@@ -9,6 +14,14 @@ The `ArrayType<T>` and friends are used to check if a type is exactly `Array<T>`
 They are strict type checks, meaning they match only the type `Array<T>`,
 and not [tuple], union, or intersection types.
 
+### [ArrayType](./array_type.ts#18)
+
+`ArrayType<T, Then = T, Else = never>`
+
+🌪️ *filter*
+
+Filter `T` to ensure it is an array, excluding tuple.
+
 ```ts
 import type { ArrayType } from 'type-plus'
 
@@ -19,25 +32,64 @@ 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 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).
+### [IsArray](./array_type.ts#37)
 
-## ArrayPlus
+`IsArray<T, Then = true, Else = false>`
 
-`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.
+🎭 *validate*
 
-For *tuple* specific types and type utilities,
-please check [`TuplePlus`](../tuple/readme.md#TuplePlus).
+Validate that `T` is an array, excluding tuple.
 
-### [`ArrayPlus.At`](./array.at.ts#L18)
+```ts
+import type { IsArray } from 'type-plus'
+
+type R = IsArray<number[]> // true
+
+type R = IsArray<number> // false
+type R = IsArray<[1]> // false
+```
+
+### [NotArrayType](./array_type.ts#54)
+
+`NotArrayType<T, Then = T, Else = never>`
+
+🌪️ *filter*
+
+Filter `T` to ensure it is not an array, excluding tuple.
+
+```ts
+import type { NotArrayType } from 'type-plus'
+
+type R = NotArrayType<number[]> // never
+
+type R = NotArrayType<number> // number
+type R = NotArrayType<[1]> // [1]
+```
 
-> `ArrayPlus.At<A, N, Fail = never>`
+### [IsNotArrayType](./array_type.ts#71)
 
-Gets the type of the array or tuple `A` at index `N`.
+`IsNotArrayType<T, Then = true, Else = false>`
+
+🎭 *validate*
+
+Validate that `T` is not an array, excluding tuple.
+
+```ts
+import type { IsNotArrayType } from 'type-plus'
+
+type R = IsNotArrayType<number[]> // false
+
+type R = IsNotArrayType<number> // true
+type R = IsNotArrayType<[1]> // true
+```
+
+## [At](./array.at.ts)
+
+`At<A, N, Fail = never>`
+
+🦴 *utilities*
+
+Gets the type of the array or tuple at positive or negative 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`.
@@ -61,9 +113,12 @@ 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)
+## [`Concat`](./array.concat.ts#L12)
+
+`Concat<A, B>`
 
-> `ArrayPlus.Concat<A, B>`
+🦴 *utilities*
+💀 *deprecated* Will be available only as `ArrayPlus.Concat` in the next version
 
 Concats two arrays or tuples.
 
@@ -72,6 +127,116 @@ It is added for completeness.
 
 You are encouraged to use `[...A, ...B]` directly.
 
+## [`FindFirst`](./array.find.ts)
+
+## [`FineLast`](./array.find_last.ts)
+
+## [`Some`](./array.some.ts)
+
+## [`Filter`](./filter.ts#l17)
+
+`Filter<A, Criteria>`
+
+⚗️ *transform*
+
+Filter the array or tuple `A`, keeping entries satisfying `Criteria`.
+
+```ts
+import type { Filter } from 'type-plus'
+
+type R = Filter<[1, 2, '3'], number> // [1, 2]
+type R = Filter<Array<string | undefined>, string> // string[]
+```
+
+## [`KeepMatch`](./filter.ts)
+
+`KeepMatch<A, Criteria>`
+
+⚗️ *transform*
+👽 *alias* of [`Filter`](#filter)
+
+Keeps entries satisfying `Criteria` in array or tuple `A`.
+
+```ts
+import type { KeepMatch } from 'type-plus'
+
+type R = KeepMatch<[1, 2, '3'], number> // [1, 2]
+type R = KeepMatch<Array<string | undefined>, string> // string[]
+```
+
+## [`Head`](./head.ts#l14)
+
+`Head<T, Cases = { empty_tuple }>`
+
+🦴 *utilities*
+
+Gets the first entry in the tuple or the type of array.
+
+```ts
+import type { Head } from 'type-plus'
+
+type R = Head<[1, 2, 3]> // 1
+type R = Head<string[]> // string
+
+type R = Head<[]> // never
+```
+
+## [`IntersectOfProps`](./intersect_of_props.ts)
+
+## [`MapToProp`](./intersect_of_props.ts)
+
+## [`Last`](./last.ts)
+
+`Last<T, Cases = { empty_tuple }>`
+
+🦴 *utilities*
+
+Gets the last entry in the tuple or the type of array.
+
+```ts
+import type { Last } from 'type-plus'
+
+type R = Last<[1, 2, 3]> // 3
+type R = Last<string[]> // string
+
+type R = Last<[]> // never
+```
+
+## [`literalArray`](./literal_array.ts)
+
+## [`PadStart`](./pad_start.ts)
+
+## [`reduceWhile`](./reduce_while.ts)
+
+## [`Reverse`](./reverse.ts)
+
+## [`PropUnion`](./union_of_props.ts)
+
+## [`UnionOfProps`](./union_of_props.ts)
+
+## [`UnionOfValues`](./union_of_values.ts)
+
+## 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>`
+
+Alias of [At](#at).
+
+### [`ArrayPlus.Concat`](./array.concat.ts#L12)
+
+`ArrayPlus.Concat<A, B>`
+
+Alias of [Concat](#concat).
+
 ### [`ArrayPlus.Entries`](./array.entries.ts#L14)
 
 > `ArrayPlus.Entries<A>`

package/ts/array/reduce_while.ts

@@ -1,3 +1,9 @@
+/**
+ * 🦴 *utilities*
+ *
+ * `reduce()` with predicate for early termination.
+ * A simple version of the same function in the `ramda` package.
+ */
 export function reduceWhile<T, R>(
 	predicate: (acc: R, currentValue: T) => boolean,
 	callbackfn: (previousValue: R, currentValue: T, currentIndex: number, array: T[]) => R,