type-plus 8.0.0-beta.0 → 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 = { $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/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['$never'] 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['$never'],
-	(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.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 { TypePlusOptions } 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['$widen']`
- *
- * @typeParam Options['$array'] 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['$never'] return type when `A` is `never`. Default to `never`.
- *
- * @typeParam Options['$notMatch'] Return value when `T` does not match `Criteria`.
- * Default to `never`.
- *
- * @typeParam Options['$widen'] 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['$unionNotMatch'] 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 readonly unknown[],
-	Criteria,
-	Options extends Find.Options = Find.DefaultOptions<Criteria>
-> = TypePlusOptions.Merge<Options, Find.DefaultOptions<Criteria>> extends infer O extends Find.Options
-	? TupleType<
-		A,
-		A['length'] extends 0
-		? O['$emptyTuple']
-		: Find.Device<A, Criteria, O>,
-		O['$array'],
-		O
-	>
-	: never
-export namespace Find {
-	export type Device<
-		A extends readonly unknown[],
-		Criteria,
-		Options extends Find.Options
-	> = A['length'] extends 0
-		? Options['$notMatch']
-		: (A extends readonly [infer Head, ...infer Tail]
-			? ElementMatch<
-				Head,
-				Criteria,
-				TypePlusOptions.Merge<{ $notMatch: Device<Tail, Criteria, Options> }, Options>
-			>
-			: never)
-	export interface Options extends ElementMatch.Options, NeverType.Options {
-		$array?: unknown,
-		$emptyTuple?: unknown,
-	}
-
-	export interface DefaultOptions<Criteria> extends ElementMatch.DefaultOptions<Criteria>, NeverType.DefaultOptions {
-		$array: 'does not support array. Please use `FindFirst` or `ArrayPlus.Find` instead.',
-		$emptyTuple: never,
-	}
-}

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['$never'],
-	[T] extends [readonly any[]] ? (number extends T['length'] ? Else : Then) : Else
->
-
-export namespace TupleType {
-	export interface Options extends NeverType.Options {
-	}
-
-	export interface DefaultOptions<Else> {
-		$never: 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>() {}

package/ts/type_plus/cases.ts

@@ -1,14 +0,0 @@
-const $then = Symbol('then')
-export type $Then = typeof $then
-
-const $else = Symbol('else')
-export type $Else = typeof $else
-
-const $never = Symbol('never')
-export type $Never = typeof $never
-
-const $error = Symbol('error')
-export interface $Error<M extends string> {
-	type: typeof $error,
-	message: M
-}

package/ts/undefined/readme.md

@@ -1,18 +0,0 @@
-# undefined
-
-## Type Checking
-
-The `UndefinedType<T>` and friends are used to check if a type is `undefined` or not.
-
-```ts
-import type { UndefinedType } from 'type-plus'
-
-type R = UndefinedType<undefined> // undefined
-
-type R = UndefinedType<1> // never
-```
-
-- [`UndefinedType<T, Then = T, Else = never>`](undefined_type.ts#L16): check if `T` is `undefined`.
-- [`IsUndefined<T, Then = true, Else = false`](undefined_type.ts#L35): is `T` `undefined`.
-- [`NotUndefinedType<T, Then = T, Else = never>`](undefined_type.ts#L50): check if `T` is not `undefined`.
-- [`IsNotUndefined<T, Then = true, Else = false>`](undefined_type.ts#L65): is `T` not `undefined`.

package/ts/undefined/undefined_type.ts

@@ -1,57 +0,0 @@
-import type { IsAny } from '../any/any_type.js'
-
-/**
- * Check if the type `T` is exactly `undefined`.
- *
- * ```ts
- * type R = UndefinedType<undefined> // undefined
- *
- * type R = UndefinedType<never> // never
- * type R = UndefinedType<unknown> // never
- * type R = UndefinedType<string | boolean> // never
- * ```
- */
-export type UndefinedType<T, Then = T, Else = never> = IsAny<
-	T,
-	Else,
-	[T, undefined] extends [undefined, T] ? Then : Else
->
-
-/**
- * Is the type `T` exactly `undefined`.
- *
- * ```ts
- * type R = IsUndefined<undefined> // true
- *
- * type R = IsUndefined<never> // false
- * type R = IsUndefined<unknown> // false
- * type R = IsUndefined<string | boolean> // false
- * ```
- */
-export type IsUndefined<T, Then = true, Else = false> = UndefinedType<T, Then, Else>
-
-/**
- * Check if the type `T` is not `undefined`.
- *
- * ```ts
- * type R = NotUndefinedType<undefined> // never
- *
- * type R = NotUndefinedType<never> // never
- * type R = NotUndefinedType<unknown> // unknown
- * type R = NotUndefinedType<string | boolean> // string | boolean
- * ```
- */
-export type NotUndefinedType<T, Then = T, Else = never> = UndefinedType<T, Else, Then>
-
-/**
- * Is the type `T` not `undefined`.
- *
- * ```ts
- * type R = IsNotUndefined<undefined> // false
- *
- * type R = IsNotUndefined<never> // true
- * type R = IsNotUndefined<unknown> // true
- * type R = IsNotUndefined<string | boolean> // true
- * ```
- */
-export type IsNotUndefined<T, Then = true, Else = false> = UndefinedType<T, Else, Then>