type-plus 7.4.0 → 7.6.0

package/ts/array/readme.md

@@ -12,7 +12,7 @@ and each element has the same type `T`.
 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)
 
@@ -83,7 +83,7 @@ type R = IsNotArrayType<number> // true
 type R = IsNotArrayType<[1]> // true
 ```
 
-## [At](./array.at.ts)
+## [At](./array.at.ts#l20)
 
 `At<A, N, Fail = never>`
 
@@ -97,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`.
@@ -105,8 +105,8 @@ 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,
@@ -127,9 +127,41 @@ It is added for completeness.
 
 You are encouraged to use `[...A, ...B]` directly.
 
-## [`FindFirst`](./array.find.ts)
+## [`FindFirst`](./find_first.ts#l52)
 
-## [`FineLast`](./array.find_last.ts)
+`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)
 
@@ -164,42 +196,52 @@ type R = KeepMatch<[1, 2, '3'], number> // [1, 2]
 type R = KeepMatch<Array<string | undefined>, string> // string[]
 ```
 
-## [`Head`](./head.ts#l14)
+## [`Head`](./head.ts#l23)
 
-`Head<T, Cases = { empty_tuple }>`
+`Head<T, Options = { caseNever, caseEmptyTuple }>`
 
 🦴 *utilities*
+🔢 *customizable*
 
-Gets the first entry in the tuple or the type of array.
+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
 
-type R = Head<[]> // 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)
+## [`Last`](./last.ts#l23)
 
-`Last<T, Cases = { empty_tuple }>`
+`Last<T, Options = { caseNever, caseEmptyTuple }>`
 
 🦴 *utilities*
+🔢 *customizable*
 
-Gets the last entry in the tuple or the type of array.
+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
 
-type R = Last<[]> // never
+// customization
+type R = Last<never, { caseNever: 1 }> // 1
+type R = Last<[], { caseEmptyTuple: undefined }> // undefined
 ```
 
 ## [`literalArray`](./literal_array.ts)
@@ -231,12 +273,56 @@ please check [`TuplePlus`](../tuple/readme.md#TuplePlus).
 
 Alias of [At](#at).
 
-### [`ArrayPlus.Concat`](./array.concat.ts#L12)
+## [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>`
@@ -247,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<A, Criteria>
+### [`ArrayPlus.Find`](./array_plus.find.ts#l49)
 
-Returns the first type in the array or tuple that matches the `Criteria`.
+`ArrayPlus.Find<A, Criteria, Options { widen, caseNever, caseNotMatch, caseTuple, caseWiden, caseUnionNotMatch }>`
 
-If the `Criteria` is not met, it will return `never'.
+🦴 *utilities*
+🔢 *customizable*
 
-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)
@@ -295,12 +394,28 @@ ArrayPlus.Reverse<[1, 2, 3]> // [3, 2, 1]
 
 ### [`ArrayPlus.SplitAt`](./array_plus.split_at.ts#L22)
 
-> `ArrayPlus.SplitAt<A, Index>`
+`ArrayPlus.SplitAt<A, Index>`
+
+⚗️ *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.
 
-Splits the array or tuple at `Index`.
+It is the type level `splice()`.
 
 ```ts
-ArrayPlus.SplitAt<[1, 2, 3], 1> // [[1, 2], [3]]
+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]]
 ```
 
 ### [`ArrayPlus.Some`](./array.some.ts#L23)
@@ -339,7 +454,11 @@ 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.
+
+✅ means it is implemented.
+✴️ means it is implemented with reduced functionality
+🧬 means there is a built-in mechanism or type for it.
 
 - ✅ `at`: [`ArrayPlus.At`](#arrayplusat)
 - ✅ `concat`: [`Concat` | `ArrayPlus.Concat`](#arrayplusconcat) (`[...A, ...B]`)
@@ -365,7 +484,7 @@ Here are the list of array methods and their corresponding type-level functions,
 - 🚧 `slice`:
 - ✴️ `some`: [`Some` | `ArrayPlus.Some`](#arrayplussome)
 - 🚧 `sort`:
-- 🚧 `splice`:
+- ✴️ `splice`: [`ArrayPlus.SplitAt`](#arrayplussplitat)
 - 🧬 `unshift`: `[T, ...A]`
 - 🧬 `values`: `keyof A`
 
@@ -375,3 +494,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/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](./assert_type.ts)
+## [assertType](./assert_type.ts#l10)
 
 `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/index.ts

@@ -1,12 +1,12 @@
 export type { AnyType, IsAny, IsNotAny, NotAnyType } from './any/any_type.js'
 export type { At } from './array/array.at.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 type { Filter, KeepMatch } from './array/filter.js'
+export type { FindFirst } from './array/find_first.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'
@@ -77,6 +77,7 @@ export type {
 	Zero
 } from './numeric/numeric_type.js'
 export type { IsNotPositive, IsPositive, NonPositive, Positive } from './numeric/positive.js'
+export type { Required, RequiredExcept, RequiredPick } from './object/Required.js'
 export * from './object/index.js'
 export type { IsNotObject, IsObject, NotObjectType, ObjectType } from './object/object_type.js'
 export * from './predicates/index.js'
@@ -94,7 +95,7 @@ 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 type { CommonKeys, 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'
@@ -110,12 +111,11 @@ export type {
 	NotUndefinedType,
 	UndefinedType
 } from './undefined/undefined_type.js'
+export type { IsUnion, UnionType } from './union/union.js'
 export type { UnionKeys } from './union_keys.js'
 export type { IsNotUnknown, IsUnknown, NotUnknownType, UnknownType } from './unknown/unknown_type.js'
 export * from './unpartial.js'
 export * from './utils/index.js'
+export type { MergeOptions as MergeCases } from './utils/options.js'
 export type { IsNotVoid, IsVoid, NotVoidType, VoidType } from './void/void_type.js'
 
-
-
-

package/ts/never/never_type.ts

@@ -55,3 +55,16 @@ export type IsNever<T, Then = true, Else = false> = NeverType<T, Then, Else>
  * type R = IsNotNever<never> // false
  */
 export type IsNotNever<T, Then = true, Else = false> = NeverType<T, Else, Then>
+
+export namespace NeverType {
+	/**
+	 * Type options when input type is `never`.
+	 */
+	export interface Options {
+		caseNever?: unknown
+	}
+
+	export interface DefaultOptions {
+		caseNever: never
+	}
+}

package/ts/object/index.ts

@@ -12,7 +12,6 @@ export type { Partial, PartialExcept, PartialOmit, PartialPick } from './Partial
 export type * from './optional_key.js'
 export type { RecursiveIntersect } from './RecursiveIntersect.js'
 export type { RecursiveRequired } from './RecursiveRequired.js'
-export type { RequiredExcept, RequiredPick } from './Required.js'
 export type { RequiredKeys } from './RequiredKeys.js'
 export type { SpreadRecord } from './SpreadRecord.js'
 export type { ValueOf } from './ValueOf.js'