type-plus 7.4.0 → 7.6.0

package/ts/array/array_index.ts

@@ -25,35 +25,45 @@ export type IndexAt<
 	Fail = never,
 	Upper = A['length'],
 	Lower = 0
-> = IsEqual<
-	A['length'],
-	0,
-	Fail,
-	Integer<
-		N,
-		StrictNumberType<
-			A['length'],
-			// A: array
-			N,
-			// A: tuple
-			Negative<
-				N,
-				GreaterThan<Abs<N>, A['length']> extends true ? Lower : Subtract<A['length'], Abs<N>>,
-				GreaterThan<A['length'], N> extends true ? N : Upper
-			>
-		>,
-		// N: number or float
-		IsAny<
+> = IsNever<A, Fail, IndexAt._<A, N, Fail, Upper, Lower>>
+
+export namespace IndexAt {
+	export type _<
+		A extends Array<unknown>,
+		N extends number,
+		Fail = never,
+		Upper = A['length'],
+		Lower = 0
+	> = IsEqual<
+		A['length'],
+		0,
+		Fail,
+		Integer<
 			N,
-			number,
 			StrictNumberType<
+				A['length'],
+				// A: array
+				N,
+				// A: tuple
+				Negative<
+					N,
+					GreaterThan<Abs<N>, A['length']> extends true ? Lower : Subtract<A['length'], Abs<N>>,
+					GreaterThan<A['length'], N> extends true ? N : Upper
+				>
+			>,
+			// N: number or float
+			IsAny<
 				N,
-				// TODO: handle tuple to union of indexes
-				N
+				number,
+				StrictNumberType<
+					N,
+					// TODO: handle tuple to union of indexes
+					N
+				>
 			>
 		>
 	>
->
+}
 
 /**
  * Is N an out of bound index of A.

package/ts/array/array_plus.common_prop_keys.ts

@@ -0,0 +1,35 @@
+import type { NeverType } from '../never/never_type.js'
+import type { KeyTypes } from '../object/KeyTypes.js'
+
+/**
+ * ⚗️ *transform*
+ * 🔢 *customization*
+ *
+ * Gets the common keys of the record types in the array `A`.
+ *
+ * @example
+ * ```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'
+ * ```
+ *
+ * @typeParam Options['caseNever'] Return type when `T` is `never`.
+ * Default to `never`.
+ */
+export type CommonPropKeys<
+	A extends Record<KeyTypes, unknown>[],
+	Options extends CommonPropKeys.Options = CommonPropKeys.DefaultOptions
+> = NeverType<A,
+	Options['caseNever'],
+	A extends Array<infer R extends Record<KeyTypes, unknown>> ? keyof R : never
+>
+
+export namespace CommonPropKeys {
+	export interface Options extends NeverType.Options {
+	}
+
+	export interface DefaultOptions extends NeverType.DefaultOptions {
+	}
+}

package/ts/array/array_plus.drop_match.ts

@@ -0,0 +1,16 @@
+import type { NonNull } from '../utils/NonNull.js'
+import type { NonUndefined } from '../utils/NonUndefined.js'
+
+export type DropMatch<A extends Readonly<Array<unknown>>, Criteria> = A[0] extends Criteria
+	? 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>>))))

package/ts/array/array_plus.element_match.ts

@@ -0,0 +1,61 @@
+import type { IsNever } from '../never/never_type.js'
+import type { IsUnion } from '../union/union.js'
+import type { MergeOptions } from '../utils/options.js'
+
+/**
+ * 🦴 *utilities*
+ * 🔢 *customizable*
+ *
+ * Filter the element `T` in an array or tuple to match `Criteria`.
+ *
+ * @typeParam Options['widen'] Allow using narrow type to match widen type.
+ * e.g. `number, 1` -> `1 | undefined`.
+ * Default to `true`.
+ *
+ * @typeParam Options['caseNotMatch'] Return value when `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * @typeParam Options['caseWiden'] Return value when `widen` is true.
+ * Default to `Criteria | undefined`.
+ *
+ * @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.
+ * e.g. `ElementMatch<1 | 2, 1>` -> `1 | undefined`
+ */
+export type ElementMatch<
+	T,
+	Criteria,
+	Options extends ElementMatch.Options = ElementMatch.DefaultOptions<Criteria>
+> = [T] extends [Criteria]
+	? T
+	: (MergeOptions<Options, ElementMatch.DefaultOptions<Criteria>> extends infer C extends Record<keyof ElementMatch.Options, unknown>
+		? ((T extends Criteria
+			? T
+			: (C['widen'] extends true
+				? (Criteria extends T
+					? C['caseWiden']
+					: C['caseNotMatch'])
+				: C['caseNotMatch'])) extends infer R
+			? IsUnion<T, IsNever<R, R, R | C['caseUnionNotMatch']>, R>
+			: C['caseNotMatch'])
+		: never)
+
+export namespace ElementMatch {
+	export interface Options {
+		widen?: boolean | undefined,
+		caseNotMatch?: unknown,
+		caseWiden?: unknown,
+		caseUnionNotMatch?: unknown
+	}
+	export interface DefaultOptions<Criteria> {
+		widen: true,
+		caseNotMatch: never,
+		caseWiden: Criteria | undefined,
+		caseUnionNotMatch: never
+	}
+}

package/ts/array/array_plus.find.ts

@@ -0,0 +1,71 @@
+import type { NeverType } from '../never/never_type.js'
+import type { TupleType } from '../tuple/tuple_type.js'
+import type { MergeOptions } from '../utils/options.js'
+import type { ElementMatch } from './array_plus.element_match.js'
+
+/**
+ * 🦴 *utilities*
+ * 🔢 *customizable*
+ *
+ * Finds the type in array `A` that matches `Criteria`.
+ *
+ * @example
+ * ```ts
+ * 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<Array<number>, 1> // widen: 1 | undefined
+ * type R = ArrayPlus.Find<Array<string | number>, number> // unionMiss: number | undefined
+ *
+ * type R = ArrayPlus.Find<string[], number> // 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['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['caseTuple'] return type when `A` is a tuple. Default to `not supported` message.
+ *
+ * @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,
+		O['caseTuple'],
+		A extends Array<infer T> ? ElementMatch<T, Criteria, O> : never,
+		O
+	>
+	: never
+
+export namespace Find {
+	export interface Options extends ElementMatch.Options, NeverType.Options {
+		caseTuple?: unknown,
+	}
+
+	export interface DefaultOptions<Criteria> extends ElementMatch.DefaultOptions<Criteria>, NeverType.DefaultOptions {
+		caseTuple: 'does not support tuple. Please use `FindFirst` or `TuplePlus.Find` instead.',
+	}
+}

package/ts/array/array_plus.split_at.ts

@@ -1,45 +1,74 @@
+import type { NeverType } from '../never/never_type.js'
+import type { IsTuple } from '../tuple/tuple_type.js'
 import type { IndexAt } from './array_index.js'
 import type { ArrayType } from './array_type.js'
 
 /**
- * Splits an array into two at the specified `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, similar to `array.splice()`.
+ * it will set to the boundary value.
+ *
+ * It is the type level `splice()`.
  *
  * @example
  * ```ts
- * SplitAt<[1, 2, 3, 4, 5], 0> // [[], [1, 2, 3, 4, 5]]
- * SplitAt<[1, 2, 3, 4, 5], -5> // [[], [1, 2, 3, 4, 5]]
- *
  * 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], 4> // [[1, 2, 3, 4], [5]]
- * SplitAt<[1, 2, 3, 4, 5], -1> // [[1, 2, 3, 4], [5]]
+ * SplitAt<[1, 2, 3, 4, 5], 2, 2> // [[1, 2, 5], [3, 4]]
  *
- * SplitAt<[1, 2, 3, 4, 5], 5> // [[1, 2, 3, 4, 5], []]
+ * 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]]
  * ```
  */
-export type SplitAt<A extends unknown[], Index extends number> = ArrayType<
+export type SplitAt<
+	A extends unknown[],
+	Index extends number,
+	DeleteCount extends number | never = never,
+	Insert extends unknown[] | never = never
+> = ArrayType<
 	A,
 	[A, A],
-	ArraySplitAtDevice<A, [], IndexAt<A, Index>>
+	SplitAt._<A, [], [], IndexAt._<A, Index>, DeleteCount, Insert>
 >
 
-/**
- * Splits an array into two at the specified `Index`.
- * The device does not work on negative index nor out of bound index.
- */
-export type ArraySplitAtDevice<
-	A extends unknown[],
-	B extends unknown[],
-	Index extends number
-> = Index extends B['length']
-	? [B, A]
-	: A extends [infer Head, ...infer Tail]
-	? ArraySplitAtDevice<Tail, [...B, Head], Index>
-	: never
+export namespace SplitAt {
+	export type _<
+		A extends unknown[],
+		B extends unknown[],
+		C extends unknown[],
+		Index extends number,
+		DeleteCount,
+		Insert extends unknown[],
+	> = 0 extends A['length']
+		? IsTuple<Insert, [[...Insert, ...B], C], [B, C]>
+		: (Index extends B['length']
+			? _D<A, B, C, DeleteCount, Insert>
+			: (A extends [infer Head, ...infer Tail]
+				? _<Tail, [...B, Head], [], Index, DeleteCount, Insert>
+				: 'unexpected: A does not extends [Head, ...Tail]'))
+
+	export type _D<
+		A extends unknown[],
+		B extends unknown[],
+		C extends unknown[],
+		DeleteCount,
+		Insert extends unknown[],
+	> = NeverType<
+		DeleteCount,
+		[B, A],
+		DeleteCount extends C['length']
+		? IsTuple<Insert, [[...B, ...Insert, ...A], C], [[...B, ...A], C]>
+		: (A extends [infer Head, ...infer Tail]
+			? _D<Tail, B, [...C, Head], DeleteCount, Insert>
+			: IsTuple<Insert, [[...Insert, ...B], C], [B, C]>
+		)
+	>
+}
+

package/ts/array/array_plus.ts

@@ -1,11 +1,14 @@
 export type { At } from './array.at.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 { CommonPropKeys } from './array_plus.common_prop_keys.js'
+export type { Concat } from './array_plus.concat.js'
+export type { DropMatch } from './array_plus.drop_match.js'
+export type { ElementMatch } from './array_plus.element_match.js'
 export type { Filter } from './array_plus.filter.js'
-export type { SplitAt } from './array_plus.split_at.js'
+export type { Find } from './array_plus.find.js'
 export type { PadStart } from './array_plus.pad_start.js'
+export type { SplitAt } from './array_plus.split_at.js'

package/ts/array/find_first.ts

@@ -0,0 +1,71 @@
+import type { TupleType } from '../tuple/tuple_type.js'
+import type { Find as TupleFind } from '../tuple/tuple_plus.find.js'
+import type { Find as ArrayFind } from './array_plus.find.js'
+
+/**
+ * 🦴 *utilities*
+ * 🔢 *customizable*
+ *
+ * Find the first type in the array or tuple `A` that matches `Criteria`.
+ *
+ * If the `Criteria` is not met, it will return `never'.
+ *
+ * @example
+ * ```ts
+ * 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> // unionMiss: string | undefined
+ * 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> // unionMiss: number | undefined
+ *
+ * type R = FindFirst<[true, 1, 'x'], 2> // never
+ * type R = FindFirst<string[], number> // 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['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['caseNoMatch'] 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['caseUnionMiss'] Return value when a branch of the union `T` does not match `Criteria`.
+ * Default to `undefined`.
+ * Since it is a union, the result will be join to the matched branch as union.
+ */
+export type FindFirst<
+	A extends unknown[],
+	Criteria, Options extends FindFirst.Options = FindFirst.DefaultOptions<Criteria>
+> = TupleType<
+	A,
+	TupleFind<A, Criteria, Options>,
+	ArrayFind<A, Criteria, Options>
+>
+
+export namespace FindFirst {
+	export interface Options extends ArrayFind.Options, TupleFind.Options { }
+	export interface DefaultOptions<Criteria>
+		extends ArrayFind.DefaultOptions<Criteria>, TupleFind.DefaultOptions<Criteria> { }
+}
+
+
+/**
+ * @deprecated use FindFirst
+ */
+export type First<A extends any[], Criteria> = FindFirst<A, Criteria>

package/ts/array/head.ts

@@ -1,7 +1,10 @@
+import type { NeverType } from '../never/never_type.js'
+
 /**
  * 🦴 *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`.
  *
  * @example
  * ```ts
@@ -10,9 +13,28 @@
  *
  * 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 any[], Cases extends {
-	empty_tuple?: unknown
-} = {
-	empty_tuple: never
-}> = T['length'] extends 0 ? Cases['empty_tuple'] : T[0]
+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/last.ts

@@ -1,7 +1,9 @@
+import type { NeverType } from '../never/never_type.js'
+
 /**
  * 🦴 *utilities*
  *
- * 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`.
  *
  * @example
  * ```ts
@@ -10,9 +12,27 @@
  *
  * 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 unknown[], Cases extends {
-	empty_tuple?: unknown
-} = {
-	empty_tuple: never
-}> = T['length'] extends 0 ? Cases['empty_tuple'] : T extends [...unknown[], 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
+	}
+}