type-plus 7.3.1 → 7.5.0

package/ts/array/head.ts

@@ -1 +1,40 @@
-export type Head<T extends any[]> = T['length'] extends 0 ? never : T[0]
+import type { NeverType } from '../never/never_type.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['caseNever'] 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 unknown[],
+	Options extends Head.Options = Head.DefaultOptions
+> = NeverType<
+	T,
+	Options['caseNever'],
+	T['length'] extends 0 ? Options['caseEmptyTuple'] : T[0]
+>
+
+export namespace Head {
+	export interface Options extends NeverType.Options {
+		caseEmptyTuple?: unknown
+	}
+
+	export interface DefaultOptions extends NeverType.DefaultOptions {
+		caseEmptyTuple: never
+	}
+}

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,38 @@
+import type { NeverType } from '../never/never_type.js'
+
 /**
- * Get the last type of an array or tuple.
+ * 🦴 *utilities*
+ *
+ * Gets the last entry in the tuple or the type of array `T`.
+ *
+ * @example
+ * ```ts
+ * type R = Last<[1, 2, 3]> // 3
+ * type R = Last<string[]> // string
+ *
+ * type R = Last<[]> // never
+ * ```
+ *
+ * @typeParam Options['caseNever'] Return type when `T` is `never`.
+ * Default to `never`.
+ *
+ * @typeParam Options['caseEmptyTuple'] Return type when `T` is `[]`.
+ * Default to `never`.
  */
-export type Last<T extends any[]> = T extends [...any[], infer R] ? R : T[0]
+export type Last<
+	T extends unknown[],
+	Options extends Last.Options = Last.DefaultOptions
+> = NeverType<T,
+	Options['caseNever'],
+	T['length'] extends 0 ? Options['caseEmptyTuple'] : T extends [...unknown[], infer R] ? R : T[0]
+>
+
+export namespace Last {
+	export interface Options extends NeverType.Options {
+		caseEmptyTuple?: unknown
+	}
+
+	export interface DefaultOptions extends NeverType.DefaultOptions {
+		caseEmptyTuple: never
+	}
+}

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,13 +1,26 @@
 # 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
 
 The `ArrayType<T>` and friends are used to check if a type is exactly `Array<T>` or not.
 
 They are strict type checks, meaning they match only the type `Array<T>`,
-and not [tuple], union, or intersection types.
+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
 
-> `ArrayPlus.At<A, N, Fail = never>`
+type R = NotArrayType<number> // number
+type R = NotArrayType<[1]> // [1]
+```
+
+### [IsNotArrayType](./array_type.ts#71)
+
+`IsNotArrayType<T, Then = true, Else = false>`
+
+🎭 *validate*
 
-Gets the type of the array or tuple `A` at index `N`.
+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#l20)
+
+`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`.
@@ -45,7 +97,7 @@ 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
+type R = ArrayPlus.At<A, 0> // string | number | undefined
 ```
 
 For tuple, it will return the type of the tuple value at index `N`.
@@ -53,17 +105,20 @@ 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
+type R = ArrayPlus.At<T, 0> // number
+type R = 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)
+## [`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,202 @@ It is added for completeness.
 
 You are encouraged to use `[...A, ...B]` directly.
 
+## [`FindFirst`](./find_first.ts#l52)
+
+`FindFirst<A, Criteria, Options = { widen, caseEmptyTuple, caseNever, caseNoMatch, caseWiden, caseUnionMiss }>`
+
+🦴 *utilities*
+🔢 *customizable*
+
+Find the first type in the array or tuple `A` that matches `Criteria`.
+
+```ts
+import type { FindFirst } from 'type-plus'
+
+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> // unionNotMatch: string
+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> // unionNotMatch: number
+
+type R = FindFirst<[true, 1, 'x'], 2> // never
+type R = FindFirst<string[], number> // never
+
+// customization
+type R = FindFirst<[number], 1, { widen: false }> // never
+type R = FindFirst<[number], 1, { caseWiden: never }> // never
+type R = FindFirst<[], 1, { caseEmptyTuple: 2 }> // 2
+type R = FindFirst<never, 1, { caseNever: 2 }> // 2
+type R = FindFirst<[string], number, { caseNotMatch: 2 }> // 2
+type R = FindFirst<[string | number], number, { caseUnionNotMatch: undefined }> // number | undefined
+```
+
+## [`FindLast`](./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#l23)
+
+`Head<T, Options = { caseNever, caseEmptyTuple }>`
+
+🦴 *utilities*
+🔢 *customizable*
+
+Gets the first entry in the tuple or the type of array `T`.
+
+```ts
+import type { Head } from 'type-plus'
+
+type R = Head<[1, 2, 3]> // 1
+type R = Head<string[]> // string
+type R = Head<never> // caseNever: never
+type R = Head<[]> // caseEmptyTuple: never
+
+// customization
+type R = Head<never, { caseNever: 1 }> // 1
+type R = Head<[], { caseEmptyTuple: undefined }> // undefined
+```
+
+## [`IntersectOfProps`](./intersect_of_props.ts)
+
+## [`MapToProp`](./intersect_of_props.ts)
+
+## [`Last`](./last.ts#l23)
+
+`Last<T, Options = { caseNever, caseEmptyTuple }>`
+
+🦴 *utilities*
+🔢 *customizable*
+
+Gets the last entry in the tuple or the type of array `T`.
+
+```ts
+import type { Last } from 'type-plus'
+
+type R = Last<[1, 2, 3]> // 3
+type R = Last<string[]> // string
+type R = Last<never> // caseNever: never
+type R = Last<[]> // caseEmptyTuple: never
+
+// customization
+type R = Last<never, { caseNever: 1 }> // 1
+type R = Last<[], { caseEmptyTuple: undefined }> // undefined
+```
+
+## [`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.CommonPropKeys](./array_plus.common_prop_keys.ts#l21)
+
+`ArrayPlus.CommonPropKeys<T extends Record[], Options = { caseNever }>`
+
+⚗️ *transform*
+🔢 *customizable*
+
+Gets the common property keys of the elements in array `A`.
+
+```ts
+import { type ArrayPlus } from 'type-plus'
+
+type R = ArrayPlus.CommonPropKeys<Array<{ a: 1 }>> // 'a'
+type R = ArrayPlus.CommonPropKeys<Array<{ a: 1, b: 1 } | { a: 1, c: 1 }>> // 'a'
+
+// customization
+type R = ArrayPlus.CommonPropKeys<never, { caseNever: 1 }> // 1
+```
+
+### [`ArrayPlus.Concat`](./array.concat.ts#l12)
+
+`ArrayPlus.Concat<A, B>`
+
+Alias of [Concat](#concat).
+
+### [`ArrayPlus.ElementMatch`](./array_plus.element_match.ts#l30)
+
+`ArrayPlus.ElementMatch<T, Criteria, Options = { widen, caseNotMatch, caseWiden, caseUnionNotMatch }>`
+
+🌪️ *filter*
+🔢 *customizable*
+
+Filter the element `T` in an array or tuple to match `Criteria`.
+
+```ts
+import type { ArrayPlus } from 'type-plus'
+
+type R = ArrayPlus.ElementMatch<number, number> // number
+type R = ArrayPlus.ElementMatch<1, number> // 1
+type R = ArrayPlus.ElementMatch<number, string> // notMatch: never
+type R = ArrayPlus.ElementMatch<number, 1> // widen: 1
+type R = ArrayPlus.ElementMatch<number | string, number> // unionNotMatch: number
+
+// customization
+type R = ArrayPlus.ElementMatch<number, string, { caseNotMatch: 1 }> // 1
+type R = ArrayPlus.ElementMatch<number, 1, { widen: false }> // never
+type R = ArrayPlus.ElementMatch<number, 1, { caseWiden: never }> // never
+type R = ArrayPlus.ElementMatch<number | string, number, { caseUnionNotMatch: undefined }> // number | undefined
+```
+
 ### [`ArrayPlus.Entries`](./array.entries.ts#L14)
 
 > `ArrayPlus.Entries<A>`
@@ -82,24 +333,37 @@ 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]]
+type R = ArrayPlus.Entries<Array<string | number>> // Array<[number, string | number]>
+type R = ArrayPlus.Entries<[1, 2, 3]> // [[0, 1], [1, 2], [2, 3]]
 ```
 
-### [`ArrayPlus.Find`](./array.find.ts#L17)
+### [`ArrayPlus.Find`](./array_plus.find.ts#l49)
 
-> `ArrayPlus.Find<A, Criteria>
+`ArrayPlus.Find<A, Criteria, Options { widen, caseNever, caseNotMatch, caseTuple, caseWiden, caseUnionNotMatch }>`
 
-Returns the first type in the array or tuple that matches the `Criteria`.
+🦴 *utilities*
+🔢 *customizable*
 
-If the `Criteria` is not met, it will return `never'.
-
-For `Array<T>`, it will return `T | undefined` if `T` satisfies `Criteria`.
+Finds the type in array `A` that matches `Criteria`.
 
 ```ts
-ArrayPlus.Find<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
-
-ArrayPlus.Find<[true, 1, 'x', 3], string> // 'x'
+import type { ArrayPlus } from 'type-plus'
+
+type R = ArrayPlus.Find<Array<string>, string> // string
+type R = ArrayPlus.Find<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
+type R = ArrayPlus.Find<Array<string | number>, number | string> // string | number
+type R = ArrayPlus.Find<number[], 1> // widen: 1 | undefined
+type R = ArrayPlus.Find<Array<string | number>, number> // unionNotMatch: number
+
+type R = ArrayPlus.Find<string[], number> // never
+
+// customization
+type R = ArrayPlus.Find<number[], 1, { widen: false }> // never
+type R = ArrayPlus.Find<number[], 1, { caseWiden: never }> // never
+type R = ArrayPlus.Find<never, 1, { caseNever: 2 }> // 2
+type R = ArrayPlus.Find<string[], number, { caseNotMatch: 2 }> // 2
+type R = ArrayPlus.Find<[], 1, { caseTuple: 2 }> // 2
+type R = ArrayPlus.Find<Array<string | number>, number, { caseUnionNotMatch: undefined }> // number | undefined
 ```
 
 ### [`ArrayPlus.FindLast`](./array.find_last.ts#L17)
@@ -174,7 +438,7 @@ 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
+Here are the list of array methods and their corresponding type-level functions, if available.
 
 - ✅ `at`: [`ArrayPlus.At`](#arrayplusat)
 - ✅ `concat`: [`Concat` | `ArrayPlus.Concat`](#arrayplusconcat) (`[...A, ...B]`)
@@ -210,3 +474,4 @@ Here are the list of array methods and their corresponding type-level functions,
 
 [handbook]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#arrays
 [tuple]: ../tuple/readme.md
+[union]: ../union/readme.md

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,

package/ts/array/reverse.ts

@@ -1,3 +1,8 @@
+/**
+ * ⚗️ *transform*
+ *
+ * reverses the order of `A`.
+ */
 export type Reverse<A extends unknown[]> = number extends A['length']
 	? A
 	: A['length'] extends 0

package/ts/array/union_of_props.ts

@@ -1,5 +1,5 @@
 import type { KeyTypes } from '../object/index.js'
-import type { Tail } from './tail.js'
+import type { Tail } from '../tuple/tail.js'
 
 /**
  * Gets the union of properties of the elements in `A`

package/ts/assertion/assert_type.ts

@@ -3,7 +3,10 @@ import { isConstructor, type AnyConstructor } from '../class/index.js'
 import { type AnyFunction } from '../function/any_function.js'
 
 /**
- * assert the subject satisfies the specified type T
+ * 💥 *immediate*
+ * 🚦 *assertion*
+ *
+ * Assert the subject satisfies the specified type T
  * @type T the type to check against.
  */
 export function assertType<T>(subject: T): asserts subject is T

package/ts/assertion/readme.md

@@ -9,11 +9,12 @@ They throw an error if the condition is not met, and return nothing otherwise.
 These assertion functions are typically used in runtime,
 so that that type of the value can be narrowed down.
 
-## assertType
+## [assertType](./assert_type.ts#l10)
 
-`assertType<T>(subject)`:
+`assertType<T>(subject)`
 
-✔️ `immediate`
+💥 *immediate*
+🚦 *assertion*
 
 It ensures `subject` satisfies `T`.
 It is similar to `const x: T = subject` without introducing an unused variable.

package/ts/functional/compose.ts

@@ -1,4 +1,5 @@
-import type { Head, Last } from '../array/index.js'
+import type { Head } from '../array/head.js'
+import type { Last } from '../array/last.js'
 import type { AnyFunction } from '../function/any_function.js'
 
 /**

package/ts/functional/context.ts

@@ -27,7 +27,7 @@ export type ContextBuilder<Init extends ContextBaseShape, Ctx extends ContextBas
 	 */
 	extend<Additional extends ContextBaseShape = ContextBaseShape>(
 		extender: ContextExtender<Ctx, Additional>
-	): ContextBuilder<Init, LeftJoin<Ctx, Additional>>
+	): ContextBuilder<Init, LeftJoin<Ctx, Additional>>,
 	/**
 	 * Build and return the context.
 	 */