type-plus 7.3.1 → 7.4.0

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,

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/readme.md

@@ -9,11 +9,11 @@ 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)
 
-`assertType<T>(subject)`:
+`assertType<T>(subject)`
 
-✔️ `immediate`
+💥 `immediate`
 
 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.
 	 */

package/ts/index.ts

@@ -1,10 +1,22 @@
 export type { AnyType, IsAny, IsNotAny, NotAnyType } from './any/any_type.js'
 export type { At } from './array/array.at.js'
-export type { Concat } from './array/array.concat.js'
+export type { FindFirst } from './array/array.find.js'
+export type { FindLast } from './array/array.find_last.js'
+export type { Some } from './array/array.some.js'
+export type { Concat } from './array/array_plus.concat.js'
 export * as ArrayPlus from './array/array_plus.js'
 export type { ArrayType, IsArray, IsNotArray, NotArrayType } from './array/array_type.js'
-export * from './array/index.js'
-export * from './assertion/assert_type.js'
+export type { Filter, KeepMatch } from './array/filter.js'
+export type { Head } from './array/head.js'
+export type { IntersectOfProps, MapToProp } from './array/intersect_of_props.js'
+export type { Last } from './array/last.js'
+export { literalArray } from './array/literal_array.js'
+export type { PadStart } from './array/pad_start.js'
+export { reduceWhile } from './array/reduce_while.js'
+export type { Reverse } from './array/reverse.js'
+export type { PropUnion, UnionOfProps } from './array/union_of_props.js'
+export type { UnionOfValues } from './array/union_of_values.js'
+export { assertType } from './assertion/assert_type.js'
 export type { BigintType, IsBigint, IsNotBigint, NotBigintType } from './bigint/bigint_type.js'
 export type { StringToBigint } from './bigint/cast.js'
 export type {
@@ -82,7 +94,11 @@ export type { IsNotString, IsString, NotStringType, StringType } from './string/
 export type { IsNotSymbol, IsSymbol, NotSymbolType, SymbolType } from './symbol/symbol_type.js'
 export * from './testing/stub.js'
 export * from './testing/test_type.js'
+export type { CommonPropKeys } from './tuple/common_prop_keys.js'
 export * from './tuple/create_tuple.js'
+export { drop } from './tuple/drop.js'
+export type { DropFirst, DropLast, DropMatch, DropNull, DropNullable, DropUndefined } from './tuple/drop.js'
+export type { Tail } from './tuple/tail.js'
 export * as TuplePlus from './tuple/tuple_plus.js'
 export type { IsNotTuple, IsTuple, NotTupleType, TupleType } from './tuple/tuple_type.js'
 export * from './type-guard/is_type.js'
@@ -100,3 +116,6 @@ export * from './unpartial.js'
 export * from './utils/index.js'
 export type { IsNotVoid, IsVoid, NotVoidType, VoidType } from './void/void_type.js'
 
+
+
+

package/ts/math/numeric_struct.ts

@@ -1,4 +1,4 @@
-import type { Tail } from '../array/tail.js'
+import type { Tail } from '../tuple/tail.js'
 import type { PadStart } from '../tuple/tuple_plus.pad_start.js'
 import type { Add as NumericAdd } from './add.js'
 import type { ToNegative } from './math_plus.to_negative.js'
@@ -631,14 +631,14 @@ export namespace Digit {
 	][A][B]
 
 	export type Plus10 = { [k in number]: number } & {
-		'-1': 9
-		'-2': 8
-		'-3': 7
-		'-4': 6
-		'-5': 5
-		'-6': 4
-		'-7': 3
-		'-8': 2
+		'-1': 9,
+		'-2': 8,
+		'-3': 7,
+		'-4': 6,
+		'-5': 5,
+		'-6': 4,
+		'-7': 3,
+		'-8': 2,
 		'-9': 1
 	}
 	export type Multiply<A extends number, B extends number> = [

package/ts/mix_types/any_or_never_type.ts

@@ -4,7 +4,7 @@ import type { NeverType } from '../never/never_type.js'
 /**
  * Parse `T` to ensure it is either exactly `any` or exactly `never`.
  *
- * 🐾 *parse*
+ * 🌪️ *filter*
  * 🩳 *shortcut*
  *
  * @example

package/ts/mix_types/readme.md

@@ -6,7 +6,10 @@ This folder contains types and utilities that work across multiple types.
 
 `AnyOrNeverType<T, Then = T, Else = never>` 🎭 🩳
 
-Parse `T` to ensure it is either exactly `any` or exactly `never`.
+Filter `T` to ensure it is either exactly `any` or exactly `never`.
+
+🌪️ *filter*
+🩳 *shortcut*
 
 ```ts
 import type { AnyOrNeverType } from 'type-plus'
@@ -24,6 +27,9 @@ type R = AnyOrNeverType<unknown, 1, 2> // 2
 
 Validate if `T` is either exactly `any` or exactly `never`.
 
+🎭 *validate*
+🩳 *shortcut*
+
 ```ts
 import type { IsAnyOrNever } from 'type-plus'