type-plus 7.6.2 → 8.0.0-beta.2

package/ts/tuple/readme.md

@@ -1,282 +0,0 @@
-# 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 }>`
-
-🎭 *validate*
-
-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 }>`
-
-🎭 *validate*
-
-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 = { 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>`
-
-⚗️ *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 = { 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>`
-
-⚗️ *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.
-
-```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/ts/tuple/tail.ts

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

package/ts/tuple/tuple_plus.common_prop_keys.ts

@@ -1,47 +0,0 @@
-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.filter.ts

@@ -1,29 +0,0 @@
-/**
- * ⚗️ *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 unknown[], Criteria> = T['length'] extends 0
-	? []
-	: (
-		T extends [infer Head, ...infer Tail]
-		? (
-			Tail['length'] extends 0
-			? (
-				Head extends Criteria
-				? [Head]
-				: [])
-			: (
-				Head extends Criteria
-				? [Head, ...Filter<Tail, Criteria>]
-				: Filter<Tail, Criteria>
-			)
-		)
-		: never
-	)

package/ts/tuple/tuple_plus.find.ts

@@ -1,88 +0,0 @@
-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,
-	}
-}

package/ts/tuple/tuple_plus.pad_start.ts

@@ -1,58 +0,0 @@
-/**
- * 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*
- *
- * @example
- * ```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]
- * ```
- */
-export type PadStart<Tuple extends unknown[], MaxLength extends number, PadWith = unknown> = PadStart.Device<
-	Tuple,
-	MaxLength,
-	PadWith,
-	[]
->
-
-export namespace PadStart {
-	export type Device<
-		Source extends unknown[],
-		MaxLength extends number,
-		PadWith,
-		Result extends unknown[]
-	> =
-		Result['length'] extends MaxLength
-		? (
-			Source extends []
-			? Result
-			: (
-				Source extends [...infer Head, infer Tail]
-				? (
-					[Tail, ...Result] extends infer R extends unknown[]
-					? Device<Head, R['length'], PadWith, R>
-					: never
-				)
-				: never
-			)
-		)
-		: (
-			Source extends []
-			? Device<Source, MaxLength, PadWith, [PadWith, ...Result]>
-			: (
-				Source extends [...infer Head, infer Tail]
-				? Device<Head, MaxLength, PadWith, [Tail, ...Result]>
-				: Source
-			)
-		)
-
-}

package/ts/tuple/tuple_type.ts

@@ -1,106 +0,0 @@
-import type { IsNever, NeverType } from '../never/never_type.js'
-
-/**
- * 🌪️ *filter*
- *
- * Filter `T` to ensure it is a tuple, excluding array.
- *
- * @typeParam Cases['never'] Return type when `T` is `never`. Default to `Else`.
- *
- * @example
- * ```ts
- * 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
- * ```
- */
-export type TupleType<
-	T,
-	Then = T,
-	Else = never,
-	Options extends TupleType.Options = TupleType.DefaultOptions<Else>
-> = IsNever<
-	T,
-	Options['caseNever'],
-	[T] extends [any[]] ? (number extends T['length'] ? Else : Then) : Else
->
-
-export namespace TupleType {
-	export interface Options extends NeverType.Options {
-	}
-
-	export interface DefaultOptions<Else> {
-		caseNever: Else
-	}
-}
-
-
-/**
- * 🎭 *validate*
- *
- * 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
- * ```
- */
-export type IsTuple<
-	T,
-	Then = true,
-	Else = false,
-	Options extends TupleType.Options = TupleType.DefaultOptions<Else>
-> = TupleType<T, Then, Else, Options>
-
-
-/**
- * 🌪️ *filter*
- *
- * Filter `T` to ensure it is not an tuple, excluding array.
- *
- * ```ts
- * 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
- * ```
- */
-export type NotTupleType<
-	T,
-	Then = T,
-	Else = never,
-	Options extends TupleType.Options = TupleType.DefaultOptions<Then>
-> = TupleType<T, Else, Then, Options>
-
-/**
- * 🎭 *validate*
- *
- * 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
- * ```
- */
-export type IsNotTuple<
-	T,
-	Then = true,
-	Else = false,
-	Options extends TupleType.Options = TupleType.DefaultOptions<Then>
-> = TupleType<T, Else, Then, Options>

package/ts/type/no_infer.ts

@@ -1,27 +0,0 @@
-import type { IsNull } from '../null/null_type.js'
-import type { Or } from '../predicates/logical.js'
-import type { IsUndefined } from '../undefined/undefined_type.js'
-
-/**
- * Prevents inference of a type parameter `T`.
- *
- * 🦴 *utilities*
- *
- * @ajafff original version author
- * @see https://github.com/microsoft/TypeScript/issues/14829#issuecomment-298425341
- *
- * @example
- * ```ts
- * function assertEqual<T>(a: T, b: NoInfer<T>) {
- *   return a === b
- * }
- *
- * assertEqual(123, 324) // OK
- * assertEqual(123, 'abc') // Error
- * assertEqual({ x: 1 }, { x: 1, y: 2 }) // Error
- * ```
- *
- * A build-in `NoInfer` is coming soon.
- * @see https://github.com/microsoft/TypeScript/pull/52968
- */
-export type NoInfer<T> = Or<IsNull<T>, IsUndefined<T>, T, T & {}>

package/ts/type-guard/is_type.ts

@@ -1,52 +0,0 @@
-import type { IsEqual } from '../equal/equal.js'
-
-/**
- * Is the subject of type T
- */
-export function isType<T>(subject: T): subject is T
-/**
- * Is the subject of type T, satisfying the supplied validator
- */
-export function isType<T>(subject: unknown, validator: (s: T) => unknown): subject is T
-export function isType(subject: unknown, validator?: (s: unknown) => unknown) {
-	return validator ? !!validator(subject) : true
-}
-
-/**
- * @deprecated use `isType<T>()` or `testType.true<T>()` instead
- */
-isType.t = function <T extends true>(subject?: T) {
-	return subject === undefined || subject === true
-}
-
-/**
- * @deprecated use `isType<T>()` or `testType.false<T>()` instead
- */
-isType.f = function <T extends false>(subject?: T) {
-	return subject === undefined || subject === false
-}
-
-/**
- * Check is the type `never`
- * @deprecated use `isType<T>()` or `testType.never<T>()` instead
- */
-function isNever<S extends never>(): unknown
-/**
- * Check is the value is type `never`
- * @deprecated use `isType<T>()` or `testType.never<T>()` instead
- */
-function isNever(subject: never): subject is never
-function isNever(_subject?: unknown): _subject is never {
-	return true
-}
-
-isType.never = isNever
-
-/**
- * Are types A and B equals/not equals.
- * Easier to use than `isType.t<>()` and `isType.f<>()`,
- * when doing type level only equality comparison as you don't have to import `Equal<>`.
- *
- * @deprecated use `testType.equal()` instead
- */
-isType.equal = function <_C extends IsEqual<A, B>, A, B>() {}