type-plus 7.6.2 → 8.0.0-beta.2

package/src/tuple/drop.ts

@@ -0,0 +1,125 @@
+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.
+ *
+ * @example
+ * ```ts
+ * type R = DropFirst<[1, 2, 3]> // [2, 3]
+ * type R = DropFirst<[string]> // []
+ * type R = DropFirst<[]> // []
+ * type R = DropFirst<string[]> // string[]
+ * ```
+ *
+ * @typeParam Options['$array'] 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[],
+	Options extends DropFirst.Options = DropFirst.DefaultOptions<T>
+> = number extends T['length']
+	? Options['$array']
+	: T['length'] extends 0
+	? Options['caseEmptyTuple']
+	: T['length'] extends 1
+	? []
+	: T extends [any, ...infer Tail]
+	? Tail
+	: never
+
+export namespace DropFirst {
+	export interface Options {
+		$array?: unknown,
+		caseEmptyTuple?: unknown,
+	}
+	export interface DefaultOptions<T> {
+		$array: T,
+		caseEmptyTuple: []
+	}
+}
+
+/**
+ * ⚗️ *transform*
+ * 🔢 *customizable*
+ *
+ * Drops the last entry in the tuple `T`.
+ *
+ * If the type is an array, the same array will be returned.
+ *
+ * @example
+ * ```ts
+ * type R = DropLast<[1, 2, 3]> // [2, 3]
+ * type R = DropLast<[string]> // []
+ * type R = DropLast<[]> // []
+ * type R = DropLast<string[]> // string[]
+ * ```
+ *
+ * @typeParam Options['$array'] 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 DropLast.Options = DropLast.DefaultOptions<T>
+> = number extends T['length']
+	? Cases['$array']
+	: T['length'] extends 0
+	? Cases['caseEmptyTuple']
+	: T['length'] extends 1
+	? []
+	: T extends [...infer Heads, any]
+	? Heads
+	: never
+
+
+export namespace DropLast {
+	export interface Options {
+		$array?: unknown,
+		caseEmptyTuple?: unknown,
+	}
+	export interface DefaultOptions<T> {
+		$array: T,
+		caseEmptyTuple: []
+	}
+}
+
+
+/**
+ * ⚗️ *transform*
+ *
+ * Drops entries matching `Criteria` in array or tuple `A`.
+ *
+ * @example
+ * ```ts
+ * type R = DropMatch<Array<string | undefined>, undefined> // string[]
+ * type R = DropMatch<Array<string>, string> // never[]
+ * type R = DropMatch<Array<1 | 2>, number> // 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>
+export type DropUndefined<A extends Array<any>> = DropMatch<A, undefined>
+
+/**
+ * drop a particular value from an array.
+ *
+ * 💀 *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> {
+	return array.filter(v => v !== value) as DropMatch<A, C>
+}

package/src/tuple/is_not_tuple.ts

@@ -0,0 +1,101 @@
+import type { NotAssignable } from '../predicates/not_assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $IsDistributive } from '../type_plus/branch/$is_distributive.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $Then } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate that `T` is not a tuple, excluding array.
+ *
+ * ```ts
+ * type R = IsNotTuple<[]>       // false
+ * type R = IsNotTuple<[1]>      // false
+ *
+ * type R = IsNotTuple<number[]> // true
+ * type R = IsNotTuple<string>   // true
+ * type R = IsNotTuple<never>    // true
+ * type R = IsNotTuple<unknown>  // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not a `tuple`, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotTuple<[], { selection: 'filter' }> // never
+ * type R = IsNotTuple<[1], { selection: 'filter' }> // never
+ *
+ * type R = IsNotTuple<never, { selection: 'filter' }> // never
+ * type R = IsNotTuple<unknown, { selection: 'filter' }> // unknown
+ * type R = IsNotTuple<[] | boolean, { selection: 'filter' }> // boolean
+ * type R = IsNotTuple<[1] | bigint> // bigint
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = IsNotTuple<[] | 1> // boolean
+ * type R = IsNotTuple<[] | 1, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotTuple<bigint, IsNotTuple.$Branch> // $Then
+ * type R = IsNotTuple<[], IsNotTuple.$Branch> // $Else
+ * ```
+ */
+export type IsNotTuple<
+	T,
+	$O extends IsNotTuple.$Options = {}
+> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Then]>,
+			$else: IsNotTuple.$<T, $O>
+		}
+	>
+>
+
+export namespace IsNotTuple {
+	export type $Options = $Equality.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+	// export type $Default = $Select.$Default
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is `bigint` or `bigint` literals.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> = $IsDistributive<$O, {
+		$then: T extends readonly any[]
+		? (
+			number extends T['length']
+			? $ResolveBranch<T, $O, [$Then]>
+			: $ResolveBranch<T, $O, [$Else]>
+		)
+		: $ResolveBranch<T, $O, [$Then]>,
+		$else: [T] extends [readonly any[]]
+		? (
+			number extends T['length']
+			? $ResolveBranch<T, $O, [$Then]>
+			: $ResolveBranch<T, $O, [$Else]>
+		)
+		: $ResolveBranch<T, $O, [$Then]>
+	}>
+
+	export type $UtilOptions = NotAssignable.$UtilOptions
+}

package/src/tuple/is_tuple.ts

@@ -0,0 +1,99 @@
+import type { Assignable } from '../predicates/assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $IsDistributive } from '../type_plus/branch/$is_distributive.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $Then } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate that `T` is a tuple, excluding array.
+ *
+ * ```ts
+ * type R = IsTuple<[]>       // true
+ *
+ * type R = IsTuple<number[]> // false
+ * type R = IsTuple<string>   // false
+ * type R = IsTuple<never>    // false
+ * type R = IsTuple<unknown>  // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is a `tuple`, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsTuple<[], { selection: 'filter' }> // []
+ * type R = IsTuple<[1], { selection: 'filter' }> // [1]
+ *
+ * type R = IsTuple<never, { selection: 'filter' }> // never
+ * type R = IsTuple<unknown, { selection: 'filter' }> // never
+ * type R = IsTuple<[] | boolean, { selection: 'filter' }> // []
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = IsTuple<[1] | 1> // boolean
+ * type R = IsTuple<[] | 1, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsTuple<[], IsTuple.$Branch> // $Then
+ * type R = IsTuple<string, IsTuple.$Branch> // $Else
+ * ```
+ */
+export type IsTuple<
+	T,
+	$O extends IsTuple.$Options = {}
+> =
+	$SpecialType<T,
+		$MergeOptions<$O,
+			{
+				$then: $ResolveBranch<T, $O, [$Else]>,
+				$else: IsTuple.$<T, $O>
+			}
+		>
+	>
+
+export namespace IsTuple {
+	export type $Options = $Equality.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is `tuple`.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> = $IsDistributive<$O, {
+		$then: T extends readonly any[]
+		? (
+			number extends T['length']
+			? $ResolveBranch<T, $O, [$Else]>
+			: $ResolveBranch<T, $O, [$Then]>
+		)
+		: $ResolveBranch<T, $O, [$Else]>,
+		$else: [T] extends [readonly any[]]
+		? (
+			number extends T['length']
+			? $ResolveBranch<T, $O, [$Else]>
+			: $ResolveBranch<T, $O, [$Then]>
+		)
+		: $ResolveBranch<T, $O, [$Else]>
+	}>
+
+	export type $UtilOptions = Assignable.$UtilOptions
+}

package/src/tuple/readme.md

@@ -0,0 +1,282 @@
+# Tuple
+
+In TypeScript, the type of an JavaScript array can be an [array](../array/readme.md) or a [tuple](#tuple).
+
+A *tuple type* is an array with fixed number of entries.
+Each entry in the *tuple* is specified explicitly.
+
+## Type Checking
+
+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<number[]> // never
+ type R = TupleType<string>   // never
+ type R = TupleType<never>    // never
+ type R = TupleType<unknown>  // never
+```
+
+Overridable cases:
+
+- `never`: if `T` is `never`, it returns `Else`.
+
+### [IsTuple](./array_type.ts#l47)
+
+`IsTuple<T, Then = true, Else = false, Cases = { never }>`
+
+🎭 *predicate*
+
+Validate that `T` is a tuple, excluding array.
+
+```ts
+import type { IsTuple } from 'type-plus'
+
+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:
+
+- `never`: if `T` is `never`, it returns `Else`.
+
+### [NotTupleType](./tuple_type.ts#l70)
+
+`NotArrayType<T, Then = T, Else = never, Cases = { never }>`
+
+🌪️ *filter*
+
+Filter `T` to ensure it is not an tuple, excluding array.
+
+```ts
+import type { NotArrayType } from 'type-plus'
+
+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:
+
+- `never`: if `T` is `never`, it returns `Else`.
+
+### [IsNotTupleType](./tuple_type.ts#l92)
+
+`IsNotTupleType<T, Then = true, Else = false, Cases = { never }>`
+
+🎭 *predicate*
+
+Validate that `T` is not a tuple, excluding array.
+
+```ts
+import type { IsNotTupleType } from 'type-plus'
+
+type R = IsNotTuple<[]>       // false
+type R = IsNotTuple<[1]>      // false
+
+type R = IsNotTuple<number[]> // true
+type R = IsNotTuple<string>   // true
+type R = IsNotTuple<never>    // true
+type R = IsNotTuple<unknown>  // true
+```
+
+Overridable cases:
+
+- `never`: if `T` is `never`, it returns `Else`.
+
+## [CommonPropKeys](./common_prop_keys.ts#l22)
+
+`CommonPropKeys<T extends Record[], Options = { $never }>`
+
+⚗️ *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> // $never: never
+
+// customization
+type R = CommonPropKeys<never, { $never: 1 }> // 1
+```
+
+## [DropFirst](./drop.ts#l26)
+
+`DropFirst<T extends unknown[], Options = { $array, 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[]> // $array: string[]
+type R = DropFirst<[]> // caseEmptyTuple: []
+
+// customization
+type R = DropFirst<string[], { $array: 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[]> // $array: string[]
+type R = DropLast<[]> // caseEmptyTuple: []
+
+// customization
+type R = DropLast<string[], { $array: 1 }> // 1
+type R = DropLast<[], { caseEmptyTuple: 1 }> // 1
+```
+
+## [DropMatch](./drop.ts)
+
+`DropMatch<A extends Readonly<Array<unknown>>, Criteria>`
+
+⚗️ *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[]
+type R = DropMatch<Array<1 | 2>, number> // never[]
+```
+
+## [TuplePlus](./tuple_plus.ts)
+
+`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 = { $never }>`
+
+⚗️ *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> // $never: never
+
+// customization
+type R = TuplePlus.CommonPropKeys<never, { $never: 1 }> // 1
+```
+
+### [TuplePlus.Filter](./tuple_plus.filter.ts)
+
+`TuplePlus.Filter<T, Criteria>`
+
+⚗️ *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, $array, caseEmptyTuple, $never, $notMatch, $widen, $unionNotMatch }>`
+
+🦴 *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, { $widen: never }> // never
+type R = TuplePlus.Find<string[], 1, { $array: 2 }> // 2
+type R = TuplePlus.Find<[], 1, { caseEmptyTuple: 2 }> // 2
+type R = TuplePlus.Find<never, 1, { $never: 2 }> // 2
+type R = TuplePlus.Find<[string], number, { $notMatch: 2 }> // 2
+type R = TuplePlus.Find<[string | number], number, { $unionNotMatch: 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.
+
+```ts
+PadStart<[1, 2, 3], 5, 0> // [0, 0, 1, 2, 3]
+
+// Ignore if MaxLength is less than the length of the tuple
+PadStart<[1, 2, 3], 2> // [1, 2, 3]
+
+// Default to unknown
+PadStart<[1, 2, 3], 5> // [unknown, unknown, 1, 2, 3]
+```
+
+## References
+
+- [Handbook]
+
+[handbook]: https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types

package/src/tuple/tail.ts

@@ -0,0 +1,10 @@
+import type { UnionOfValues } from '../array/union_of_values.js'
+
+/**
+ * Gets the types of a tuple except the first entry.
+ */
+export type Tail<T extends readonly unknown[]> = T['length'] extends 0
+	? never
+	: (T extends readonly [any, ...infer Tail]
+		? Tail extends UnionOfValues<T>[] ? Tail : never
+		: T)

package/src/tuple/tuple_plus.common_prop_keys.ts

@@ -0,0 +1,50 @@
+import type { IsNever } from '../never/is_never.js'
+import type { $Never } from '../never/never.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['$never'] Return type when `T` is `never`.
+ * Default to `never`.
+ */
+export type CommonPropKeys<
+	T extends Record<KeyTypes, unknown>[],
+	Options extends CommonPropKeys.Options = CommonPropKeys.DefaultOptions
+> = IsNever<
+	T,
+	{
+		$then: Options['$never'],
+		$else: (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 $Never.$Options {
+	}
+
+	export interface DefaultOptions extends $Never.$Default {
+	}
+}

package/src/tuple/tuple_plus.filter.ts

@@ -0,0 +1,29 @@
+/**
+ * ⚗️ *transform*
+ *
+ * Filter entries matching `Criteria` in tuple `T`.
+ *
+ * @example
+ * ```ts
+ * type R = Filter<[1, 2, '3'], number> // [1, 2]
+ * type R = Filter<[1, 2, '3'], true> // []
+ * ```
+ */
+export type Filter<T extends readonly unknown[], Criteria = true> = T['length'] extends 0
+	? []
+	: (
+		T extends readonly [infer Head, ...infer Tail]
+		? (
+			Tail['length'] extends 0
+			? (
+				Head extends Criteria
+				? [Head]
+				: [])
+			: (
+				Head extends Criteria
+				? [Head, ...Filter<Tail, Criteria>]
+				: Filter<Tail, Criteria>
+			)
+		)
+		: never
+	)