type-plus 7.4.0 → 7.5.0

package/ts/tuple/drop.ts

@@ -1,13 +1,14 @@
-import type { IsEqual } from '../equal/equal.js'
-import type { NonNull, NonUndefined } from '../utils/index.js'
+import type { DropMatch as ArrayDropMatch } from '../array/array_plus.drop_match.js'
+import type { DropMatch as TupleDropMatch } from './tuple_plus.drop_match.js'
 
 /**
+ * ⚗️ *transform*
+ * 🔢 *customizable*
+ *
  * Drops the first entry in the tuple `T`.
  *
  * If the type is an array, the same array will be returned.
  *
- * ⚗️ *transform*
- *
  * @example
  * ```ts
  * type R = DropFirst<[1, 2, 3]> // [2, 3]
@@ -15,30 +16,45 @@ import type { NonNull, NonUndefined } from '../utils/index.js'
  * type R = DropFirst<[]> // []
  * type R = DropFirst<string[]> // string[]
  * ```
+ *
+ * @typeParam Options['caseArray'] Return type when `T` is `Array`.
+ * Default to `T`.
+ *
+ * @typeParam Options['caseEmptyTuple'] Return type when `T` is an empty tuple.
+ * Default to `[]`.
  */
-export type DropFirst<T extends unknown[], Cases extends {
-	'array'?: unknown,
-	'empty_tuple'?: unknown,
-} = {
-	'array': T,
-	'empty_tuple': [],
-}> = number extends T['length']
-	? Cases['array']
+export type DropFirst<
+	T extends unknown[],
+	Options extends DropFirst.Options = DropFirst.DefaultOptions<T>
+> = number extends T['length']
+	? Options['caseArray']
 	: T['length'] extends 0
-	? Cases['empty_tuple']
+	? Options['caseEmptyTuple']
 	: T['length'] extends 1
 	? []
 	: T extends [any, ...infer Tail]
 	? Tail
 	: never
 
+export namespace DropFirst {
+	export interface Options {
+		caseArray?: unknown,
+		caseEmptyTuple?: unknown,
+	}
+	export interface DefaultOptions<T> {
+		caseArray: T,
+		caseEmptyTuple: []
+	}
+}
+
 /**
+ * ⚗️ *transform*
+ * 🔢 *customizable*
+ *
  * Drops the last entry in the tuple `T`.
  *
  * If the type is an array, the same array will be returned.
  *
- * ⚗️ *transform*
- *
  * @example
  * ```ts
  * type R = DropLast<[1, 2, 3]> // [2, 3]
@@ -46,30 +62,44 @@ export type DropFirst<T extends unknown[], Cases extends {
  * type R = DropLast<[]> // []
  * type R = DropLast<string[]> // string[]
  * ```
+ *
+ * @typeParam Options['caseArray'] Return type when `T` is `Array`.
+ * Default to `T`.
+ *
+ * @typeParam Options['caseEmptyTuple'] Return type when `T` is an empty tuple.
+ * Default to `[]`.
  */
-export type DropLast<T extends unknown[], Cases extends {
-	'array'?: unknown,
-	'empty_tuple'?: unknown,
-} = {
-	'array': T,
-	'empty_tuple': [],
-}> = number extends T['length']
-	? Cases['array']
+export type DropLast<
+	T extends unknown[],
+	Cases extends DropLast.Options = DropLast.DefaultOptions<T>
+> = number extends T['length']
+	? Cases['caseArray']
 	: T['length'] extends 0
-	? Cases['empty_tuple']
+	? Cases['caseEmptyTuple']
 	: T['length'] extends 1
 	? []
 	: T extends [...infer Heads, any]
 	? Heads
 	: never
 
-type ExcludeUnionOfEmptyTuple<A> = IsEqual<A, []> extends true ? A : Exclude<A, []>
+
+export namespace DropLast {
+	export interface Options {
+		caseArray?: unknown,
+		caseEmptyTuple?: unknown,
+	}
+	export interface DefaultOptions<T> {
+		caseArray: T,
+		caseEmptyTuple: []
+	}
+}
+
 
 /**
- * drops entries matching `Criteria` in array or tuple `A`.
- *
  * ⚗️ *transform*
  *
+ * Drops entries matching `Criteria` in array or tuple `A`.
+ *
  * @example
  * ```ts
  * type R = DropMatch<Array<string | undefined>, undefined> // string[]
@@ -77,38 +107,9 @@ type ExcludeUnionOfEmptyTuple<A> = IsEqual<A, []> extends true ? A : Exclude<A,
  * type R = DropMatch<Array<1 | 2>, number> // never[]
  * ```
  */
-export type DropMatch<A extends Readonly<Array<unknown>>, Criteria> = number extends A['length']
-	? // array
-	A[0] extends Criteria
-	? // criteria matches: DropAll<string[], string>
-	never[]
-	: undefined extends Criteria
-	? null extends Criteria
-	? Array<NonNullable<A[0]>>
-	: Array<NonUndefined<A[0]>>
-	: null extends Criteria
-	? Array<NonNull<A[0]>>
-	: Criteria extends A[0]
-	? Array<Exclude<A[0], Criteria>>
-	: A[0] extends Criteria
-	? A
-	: Array<Exclude<A[0], Criteria>>
-	: DropMatchTuple<A, Criteria>
-
-type DropMatchTuple<A extends Readonly<Array<any>>, Criteria> = A['length'] extends 0
-	? // empty tuple
-	A
-	: A extends readonly [infer Head, ...infer Tail]
-	? Tail['length'] extends 0
-	? // single element tuple
-	undefined extends Criteria
-	? ExcludeUnionOfEmptyTuple<Head extends Criteria ? [] : [Head]>
-	: ExcludeUnionOfEmptyTuple<Head extends Criteria ? [] : [Head]>
-	: // multiple elements
-	Exclude<Head, Criteria> extends never
-	? DropMatch<Tail, Criteria>
-	: [Exclude<Head, Criteria>, ...DropMatch<Tail, Criteria>]
-	: never[]
+export type DropMatch<A extends Readonly<Array<unknown>>, Criteria> =	number extends A['length']
+	? ArrayDropMatch<A, Criteria>
+	: TupleDropMatch<A, Criteria>
 
 export type DropNull<A extends Array<any>> = DropMatch<A, null>
 export type DropNullable<A extends Array<any>> = DropMatch<A, null | undefined>
@@ -119,6 +120,6 @@ export type DropUndefined<A extends Array<any>> = DropMatch<A, undefined>
  *
  * 💀 *deprecated* the type does not sufficiently cover the use cases.
  */
-export function drop<A extends Readonly<unknown[]>, const C> (array: A, value: C): DropMatch < A, C > {
+export function drop<A extends Readonly<unknown[]>, const C>(array: A, value: C): DropMatch<A, C> {
 	return array.filter(v => v !== value) as DropMatch<A, C>
 }

package/ts/tuple/readme.md

@@ -9,87 +9,175 @@ Each entry in the *tuple* is specified explicitly.
 
 The `TupleType<T>` and friends are used to check if `T` is a tuple, excluding array.
 
+### [TupleType](./tuple_type.ts#l21)
+
+`TupleType<T, Then = T, Else = never, Cases = { never }>`
+
+🌪️ *filter*
+
+Filter `T` to ensure it is a tuple, excluding array.
+
 ```ts
 import type { TupleType } from 'type-plus'
 
-type R = TupleType<[]> // []
-type R = TupleType<[1]> // [1]
+ type R = TupleType<[]>       // []
+ type R = TupleType<[1]>      // [1]
 
-type R = TupleType<number[]> // never
-type R = TupleType<number> // never
+ type R = TupleType<number[]> // never
+ type R = TupleType<string>   // never
+ type R = TupleType<never>    // never
+ type R = TupleType<unknown>  // never
 ```
 
-- [`TupleType<T, Then = T, Else = never>`](tuple_type.ts#L16): check if `T` is a *tuple*.
-- [`IsTuple<T, Then = true, Else = false`](tuple_type.ts#L35): is `T` *tuple*.
-- [`NotTupleType<T, Then = T, Else = never>`](tuple_type.ts#L50): check if `T` is not *tuple*.
-- [`IsNotTuple<T, Then = true, Else = false>`](tuple_type.ts#L65): is `T` not *tuple*.
+Overridable cases:
 
-## [CommonPropKeys](./common_prop_keys.ts)
+- `never`: if `T` is `never`, it returns `Else`.
 
-`CommonPropKeys<T extends Record[], Cases = { array, no_common_keys }>`
+### [IsTuple](./array_type.ts#l47)
 
-⚗️ *transform*
+`IsTuple<T, Then = true, Else = false, Cases = { never }>`
 
-Gets the common property keys of the elements in tuple `T`.
+🎭 *validate*
+
+Validate that `T` is a tuple, excluding array.
 
 ```ts
-import { CommonPropKeys } from 'type-plus'
+import type { IsTuple } from 'type-plus'
 
-type R = CommonPropKeys<[{ a: number }, { b: number }]> // never
-type R = CommonPropKeys<[{ a: number, c: 1 }, { b: number, c: 2 }]> // 'c'
+type R = IsTuple<[]>       // true
+
+type R = IsTuple<number[]> // false
+type R = IsTuple<string>   // false
+type R = IsTuple<never>    // false
+type R = IsTuple<unknown>  // false
 ```
 
 Overridable cases:
 
-- `array`: if `T` is array, it returns the key of the record type in the array.
-- `no_common_keys`: if there are no common keys, it returns `never`.
+- `never`: if `T` is `never`, it returns `Else`.
 
-## [DropFirst](./drop.ts)
+### [NotTupleType](./tuple_type.ts#l70)
 
-`DropFirst<T extends unknown[], Cases = { array, empty_tuple }>`
+`NotArrayType<T, Then = T, Else = never, Cases = { never }>`
 
-Drops the first entry in the tuple `T`.
+🌪️ *filter*
 
-⚗️ *transform*
+Filter `T` to ensure it is not an tuple, excluding array.
 
 ```ts
-import { DropFirst } from 'type-plus'
+import type { NotArrayType } from 'type-plus'
 
-type R = DropFirst<[1, 2, 3]> // [2, 3]
+type R = NotTupleType<[]>       // never
+type R = NotTupleType<[1]>      // never
+
+type R = NotTupleType<number[]> // number[]
+type R = NotTupleType<string>   // string
+type R = NotTupleType<never>    // never
+type R = NotTupleType<unknown>  // unknown
 ```
 
 Overridable cases:
 
-- `array`: if `T` is array, it returns `T`.
-- `empty_tuple`: if `T` is `[]`, it returns `[]`.
+- `never`: if `T` is `never`, it returns `Else`.
 
-## [DropLast](./drop.ts)
+### [IsNotTupleType](./tuple_type.ts#l92)
 
-`DropLast<T extends unknown[], Cases = { array, empty_tuple }>`
+`IsNotTupleType<T, Then = true, Else = false, Cases = { never }>`
 
-Drops the last entry in the tuple `T`.
+🎭 *validate*
 
-⚗️ *transform*
+Validate that `T` is not a tuple, excluding array.
 
 ```ts
-import { DropLast } from 'type-plus'
+import type { IsNotTupleType } from 'type-plus'
+
+type R = IsNotTuple<[]>       // false
+type R = IsNotTuple<[1]>      // false
 
-type R = DropLast<[1, 2, 3]> // [1, 2]
+type R = IsNotTuple<number[]> // true
+type R = IsNotTuple<string>   // true
+type R = IsNotTuple<never>    // true
+type R = IsNotTuple<unknown>  // true
 ```
 
 Overridable cases:
 
-- `array`: if `T` is array, it returns `T`.
-- `empty_tuple`: if `T` is `[]`, it returns `[]`.
+- `never`: if `T` is `never`, it returns `Else`.
+
+## [CommonPropKeys](./common_prop_keys.ts#l22)
+
+`CommonPropKeys<T extends Record[], Options = { caseNever }>`
+
+⚗️ *transform*
+🔢 *customizable*
+
+Gets the common property keys of the elements in tuple or array `T`.
+
+```ts
+import { CommonPropKeys } from 'type-plus'
+
+type R = CommonPropKeys<[{ a: 1, c: 1 }, { b: 1, c: 2 }]> // 'c'
+type R = CommonPropKeys<[{ a: 1 }, { b: 1 }]> // never
+type R = CommonPropKeys<Array<{ a: 1, b: 1 } | { a: 1, c: 1 }>> // 'a'
+type R = CommonPropKeys<[{ a: 1 }, { b: 1 }]> // never
+type R = CommonPropKeys<never> // caseNever: never
+
+// customization
+type R = CommonPropKeys<never, { caseNever: 1 }> // 1
+```
+
+## [DropFirst](./drop.ts#l26)
+
+`DropFirst<T extends unknown[], Options = { caseArray, caseEmptyTuple }>`
+
+⚗️ *transform*
+🔢 *customizable*
+
+Drops the first entry in the tuple `T`.
+
+```ts
+import { DropFirst } from 'type-plus'
+
+type R = DropFirst<[1, 2, 3]> // [2, 3]
+type R = DropFirst<[string]> // []
+type R = DropFirst<string[]> // caseArray: string[]
+type R = DropFirst<[]> // caseEmptyTuple: []
+
+// customization
+type R = DropFirst<string[], { caseArray: 1 }> // 1
+type R = DropFirst<[], { caseEmptyTuple: 1 }> // 1
+```
+
+## [DropLast](./drop.ts#l72)
+
+`DropLast<T extends unknown[], Options = { array, empty_tuple }>`
+
+⚗️ *transform*
+🔢 *customizable*
+
+Drops the last entry in the tuple `T`.
+
+```ts
+import { DropLast } from 'type-plus'
+
+type R = DropLast<[1, 2, 3]> // [2, 3]
+type R = DropLast<[string]> // []
+type R = DropLast<string[]> // caseArray: string[]
+type R = DropLast<[]> // caseEmptyTuple: []
+
+// customization
+type R = DropLast<string[], { caseArray: 1 }> // 1
+type R = DropLast<[], { caseEmptyTuple: 1 }> // 1
+```
 
 ## [DropMatch](./drop.ts)
 
 `DropMatch<A extends Readonly<Array<unknown>>, Criteria>`
 
-Drops entries matching `Criteria` in array or tuple `A`.
-
 ⚗️ *transform*
 
+Drops entries matching `Criteria` in array or tuple `A`.
+
 ```ts
 type R = DropMatch<Array<string | undefined>, undefined> // string[]
 type R = DropMatch<Array<string>, string> // never[]
@@ -101,31 +189,82 @@ type R = DropMatch<Array<1 | 2>, number> // never[]
 `TuplePlus` contains type utilities specific for *tuple*.
 The input type are not checked and assumed to be *tuple*.
 
+## [TuplePlus.CommonPropKeys](./tuple_plus.common_prop_keys.ts#l22)
+
+`TuplePlus.CommonPropKeys<T extends Record[], Options = { caseNever }>`
+
+⚗️ *transform*
+🔢 *customizable*
+
+Gets the common property keys of the elements in tuple `T`.
+
+```ts
+import { type TuplePlus } from 'type-plus'
+
+type R = TuplePlus.CommonPropKeys<[{ a: 1, c: 1 }, { b: 1, c: 2 }]> // 'c'
+type R = TuplePlus.CommonPropKeys<[{ a: 1 }, { b: 1 }]> // never
+type R = TuplePlus.CommonPropKeys<Array<{ a: 1, b: 1 } | { a: 1, c: 1 }>> // 'a'
+type R = TuplePlus.CommonPropKeys<[{ a: 1 }, { b: 1 }]> // never
+type R = TuplePlus.CommonPropKeys<never> // caseNever: never
+
+// customization
+type R = TuplePlus.CommonPropKeys<never, { caseNever: 1 }> // 1
+```
+
 ### [TuplePlus.Filter](./tuple_plus.filter.ts)
 
 `TuplePlus.Filter<T, Criteria>`
 
-Filter entries matching `Criteria` in tuple `T`.
-
 ⚗️ *transform*
 
+Filter entries matching `Criteria` in tuple `T`.
+
 ```ts
 import { TuplePlus } from 'type-plus'
 
 type R = TuplePlus.Filter<[1, 2, '3'], number> // [1, 2]
 ```
 
+### [`TuplePlus.Find`](./tuple_plus.find.ts#l51)
+
+`TuplePlus.Find<A, Criteria, Options { widen, caseArray, caseEmptyTuple, caseNever, caseNotMatch, caseWiden, caseUnionNotMatch }>`
+
+🦴 *utilities*
+🔢 *customizable*
+
+Finds the type in tuple `A` that matches `Criteria`.
+
+```ts
+import type { TuplePlus } from 'type-plus'
+
+type R = TuplePlus.Find<[true, 1, 'x', 3], string> // 'x'
+type R = TuplePlus.Find<[true, 1, 'x', 3], number> // 1
+type R = TuplePlus.Find<[string, number, 1], 1> // widen: 1 | undefined
+type R = TuplePlus.Find<[true, number | string], string> // unionNotMatch: string
+
+type R = TuplePlus.Find<[true, 1, 'x'], 2> // never
+
+// customization
+type R = TuplePlus.Find<[number], 1, { widen: false }> // never
+type R = TuplePlus.Find<[number], 1, { caseWiden: never }> // never
+type R = TuplePlus.Find<string[], 1, { caseArray: 2 }> // 2
+type R = TuplePlus.Find<[], 1, { caseEmptyTuple: 2 }> // 2
+type R = TuplePlus.Find<never, 1, { caseNever: 2 }> // 2
+type R = TuplePlus.Find<[string], number, { caseNotMatch: 2 }> // 2
+type R = TuplePlus.Find<[string | number], number, { caseUnionNotMatch: undefined }> // number | undefined
+```
+
 ### [TuplePlus.PadStart](./tuple_plus.pad_start.ts)
 
 `TuplePlus.PadStart<T, MaxLength, PadWith>`
 
+⚗️ *transform*
+
 Pad `T` with `PadWith` at the start of the tuple.
 
 If the `MaxLength` is less than the length of the tuple,
 the `Tuple` will be returned unchanged.
 
-⚗️ *transform*
-
 ```ts
 PadStart<[1, 2, 3], 5, 0> // [0, 0, 1, 2, 3]
 

package/ts/tuple/tuple_plus.common_prop_keys.ts

@@ -0,0 +1,47 @@
+import type { NeverType } from '../never/never_type.js'
+import type { KeyTypes } from '../object/KeyTypes.js'
+import type { Tail } from './tail.js'
+
+/**
+ * ⚗️ *transform*
+ * 🔢 *customization*
+ *
+ * Gets the common property keys of the elements in tuple `T`.
+ *
+ * @example
+ * ```ts
+ * import { type TuplePlus } from 'type-plus'
+ *
+ * type R = TuplePlus.CommonPropKeys<[{ a: number }, { b: number }]> // never
+ * type R = TuplePlus.CommonPropKeys<[{ a: number, c: 1 }, { b: number, c: 2 }]> // 'c'
+ * ```
+ *
+ * @typeParam Options['caseNever'] Return type when `T` is `never`.
+ * Default to `never`.
+ */
+export type CommonPropKeys<
+	T extends Record<KeyTypes, unknown>[],
+	Options extends CommonPropKeys.Options = CommonPropKeys.DefaultOptions
+> = NeverType<
+	T,
+	Options['caseNever'],
+	(T['length'] extends 0
+		? never
+		: (
+			T['length'] extends 1
+			? keyof T[0]
+			: (
+				T['length'] extends 2
+				? keyof T[0] & keyof T[1]
+				: keyof T[0] & keyof T[1] & CommonPropKeys<Tail<Tail<T>>>
+			)
+		))
+>
+
+export namespace CommonPropKeys {
+	export interface Options extends NeverType.Options {
+	}
+
+	export interface DefaultOptions extends NeverType.DefaultOptions {
+	}
+}

package/ts/tuple/tuple_plus.drop_match.ts

@@ -0,0 +1,20 @@
+import type { IsEqual } from '../equal/equal.js'
+
+export type DropMatch<A extends Readonly<Array<unknown>>, Criteria> = A['length'] extends 0
+	? // empty tuple
+	A
+	: A extends readonly [infer Head, ...infer Tail]
+	? Tail['length'] extends 0
+	? // single element tuple
+	undefined extends Criteria
+	? DropMatch.ExcludeUnionOfEmptyTuple<Head extends Criteria ? [] : [Head]>
+	: DropMatch.ExcludeUnionOfEmptyTuple<Head extends Criteria ? [] : [Head]>
+	: // multiple elements
+	Exclude<Head, Criteria> extends never
+	? DropMatch<Tail, Criteria>
+	: [Exclude<Head, Criteria>, ...DropMatch<Tail, Criteria>]
+	: never[]
+
+export namespace DropMatch {
+	export type ExcludeUnionOfEmptyTuple<A> = IsEqual<A, []> extends true ? A : Exclude<A, []>
+}

package/ts/tuple/tuple_plus.filter.ts

@@ -1,8 +1,8 @@
 /**
- * Filter entries matching `Criteria` in tuple `T`.
- *
  * ⚗️ *transform*
  *
+ * Filter entries matching `Criteria` in tuple `T`.
+ *
  * @example
  * ```ts
  * type R = Filter<[1, 2, '3'], number> // [1, 2]

package/ts/tuple/tuple_plus.find.ts

@@ -0,0 +1,88 @@
+import type { ElementMatch } from '../array/array_plus.element_match.js'
+import type { NeverType } from '../never/never_type.js'
+import type { MergeOptions } from '../utils/options.js'
+import type { TupleType } from './tuple_type.js'
+
+/**
+ * 🦴 *utilities*
+ * 🔢 *customizable*
+ *
+ * Find the first type in tuple `A` that matches `Criteria`.
+ *
+ * @example
+ * ```ts
+ * type R = TuplePlus.Find<[true, 1, 'x', 3], string> // 'x'
+ * type R = TuplePlus.Find<[true, 1, 'x', 3], number> // 1
+ * type R = TuplePlus.Find<[string, number, 1], 1> // widen: 1 | undefined
+ * type R = TuplePlus.Find<[true, number | string], string> // unionMiss: string | undefined
+ *
+ * type R = TuplePlus.Find<[true, 1, 'x'], 2> // never
+ * ```
+ *
+ * @typeParam Options['widen'] performs widen match.
+ * Default to `true`.
+ * With widen match, a narrowed type will match its widen type.
+ * e.g. matching `1` against `number` yields `1 | undefined`
+ *
+ * The widen behavior can be customized by `Options['caseWiden']`
+ *
+ * @typeParam Options['caseArray'] return type when `A` is an array. Default to `not supported` message.
+ *
+ * @typeParam Options['caseEmptyTuple'] return type when `A` is an empty tuple.
+ * Default to `never`.
+ *
+ * @typeParam Options['caseNever'] return type when `A` is `never`. Default to `never`.
+ *
+ * @typeParam Options['caseNotMatch'] Return value when `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * @typeParam Options['caseWiden'] return type when `T` in `A` is a widen type of `Criteria`.
+ * Default to `Criteria | undefined`.
+ * Set it to `never` for a more type-centric behavior
+ *
+ * @typeParam Options['caseUnionNotMatch'] Return value when a branch of the union `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * If you want the type to behave more like JavaScript,
+ * you can override it to return `undefined`.
+ *
+ * Since it is a union, the result will be joined to the matched branch as union.
+ */
+export type Find<
+	A extends unknown[],
+	Criteria,
+	Options extends Find.Options = Find.DefaultOptions<Criteria>
+> = MergeOptions<Options, Find.DefaultOptions<Criteria>> extends infer O extends Find.Options
+	? TupleType<
+		A,
+		A['length'] extends 0
+		? O['caseEmptyTuple']
+		: Find.Device<A, Criteria, O>,
+		O['caseArray'],
+		O
+	>
+	: never
+export namespace Find {
+	export type Device<
+		A extends unknown[],
+		Criteria,
+		Options extends Find.Options
+	> = A['length'] extends 0
+		? Options['caseNotMatch']
+		: (A extends [infer Head, ...infer Tail]
+			? ElementMatch<
+				Head,
+				Criteria,
+				MergeOptions<{ caseNotMatch: Device<Tail, Criteria, Options> }, Options>
+			>
+			: never)
+	export interface Options extends ElementMatch.Options, NeverType.Options {
+		caseArray?: unknown,
+		caseEmptyTuple?: unknown,
+	}
+
+	export interface DefaultOptions<Criteria> extends ElementMatch.DefaultOptions<Criteria>, NeverType.DefaultOptions {
+		caseArray: 'does not support array. Please use `FindFirst` or `ArrayPlus.Find` instead.',
+		caseEmptyTuple: never,
+	}
+}