type-plus 6.3.0 → 6.5.0

package/ts/bigint/strict_bigint_type.ts

@@ -0,0 +1,69 @@
+import type { IsAnyOrNever } from '../any/any_or_never.js'
+
+/**
+ * Check if the type `T` is exactly `bigint`.
+ *
+ * ```
+ * import type { StrictBigintType } from 'type-plus'
+ *
+ * type R = StrictBigintType<bigint> // bigint
+ *
+ * type R = StrictBigintType<1n> // never
+ * type R = StrictBigintType<number> // never
+ * type R = StrictBigintType<bigint | boolean> // never
+ * type R = StrictBigintType<unknown> // never
+ * ```
+ */
+export type StrictBigintType<T, Then = T, Else = never> = IsAnyOrNever<
+	T,
+	Else,
+	[bigint] extends [T] ? ([T] extends [bigint] ? (`${T}` extends `${number}` ? Else : Then) : Else) : Else
+>
+
+/**
+ * Is the type `T` exactly `bigint`.
+ *
+ * ```
+ * import type { IsStrictBigint } from 'type-plus'
+ *
+ * type R = IsStrictBigint<bigint> // true
+ *
+ * type R = IsStrictBigint<1n> // false
+ * type R = IsStrictBigint<number> // false
+ * type R = IsStrictBigint<bigint | boolean> // false
+ * type R = IsStrictBigint<unknown> // false
+ * ```
+ */
+export type IsStrictBigint<T, Then = true, Else = false> = StrictBigintType<T, Then, Else>
+
+/**
+ * Check if the type `T` is not exactly `bigint`.
+ *
+ * ```
+ * import type { NotStrictBigintType } from 'type-plus'
+ *
+ * type R = NotStrictBigintType<bigint> // never
+ *
+ * type R = NotStrictBigintType<1n> // 1n
+ * type R = NotStrictBigintType<number> // number
+ * type R = NotStrictBigintType<bigint | boolean> // string | boolean
+ * type R = NotStrictBigintType<unknown> // unknown
+ * ```
+ */
+export type NotStrictBigintType<T, Then = T, Else = never> = StrictBigintType<T, Else, Then>
+
+/**
+ * Is the type `T` not exactly `bigint`.
+ *
+ * ```
+ * import type { IsNotStrictBigint } from 'type-plus'
+ *
+ * type R = IsNotStrictBigint<bigint> // false
+ *
+ * type R = IsNotStrictBigint<1n> // true
+ * type R = IsNotStrictBigint<number> // true
+ * type R = IsNotStrictBigint<bigint | boolean> // true
+ * type R = IsNotStrictBigint<unknown> // true
+ * ```
+ */
+export type IsNotStrictBigint<T, Then = true, Else = false> = StrictBigintType<T, Else, Then>

package/ts/boolean/boolean_type.ts

@@ -0,0 +1,69 @@
+import type { IsAnyOrNever } from '../any/any_or_never.js'
+
+/**
+ * Check if the type `T` is `boolean`, including `true` and `false`.
+ *
+ * ```ts
+ * import type { BooleanType } from 'type-plus'
+ *
+ * type R = BooleanType<boolean> // boolean
+ * type R = BooleanType<true> // true
+ * type R = BooleanType<false> // false
+ *
+ * type R = BooleanType<number> // never
+ * type R = BooleanType<unknown> // never
+ * ```
+ */
+export type BooleanType<T, Then = T, Else = never> = IsAnyOrNever<
+	T,
+	Else,
+	[T] extends [boolean] ? Then : Else
+>
+
+/**
+ * Check if the type `T` is not `boolean`, including `true` and `false`.
+ *
+ * ```ts
+ * import type { NotBooleanType } from 'type-plus'
+ *
+ * type R = NotBooleanType<boolean> // never
+ * type R = NotBooleanType<true> // never
+ * type R = NotBooleanType<false> // never
+ *
+ * type R = NotBooleanType<number> // number
+ * type R = NotBooleanType<unknown> // unknown
+ * ```
+ */
+export type NotBooleanType<T, Then = T, Else = never> = BooleanType<T, Else, Then>
+
+/**
+ * Is the type `T` `boolean`, including `true` and `false`.
+ *
+ * ```ts
+ * import type { IsBoolean } from 'type-plus'
+ *
+ * type R = IsBoolean<boolean> // true
+ * type R = IsBoolean<true> // true
+ * type R = IsBoolean<false> // true
+ *
+ * type R = IsBoolean<number> // false
+ * type R = IsBoolean<unknown> // false
+ * ```
+ */
+export type IsBoolean<T, Then = true, Else = false> = BooleanType<T, Then, Else>
+
+/**
+ * Is the type `T` not `boolean`, including `true` and `false`.
+ *
+ * ```ts
+ * import type { IsNotBoolean } from 'type-plus'
+ *
+ * type R = IsNotBoolean<boolean> // false
+ * type R = IsNotBoolean<true> // false
+ * type R = IsNotBoolean<false> // false
+ *
+ * type R = IsNotBoolean<number> // true
+ * type R = IsNotBoolean<unknown> // true
+ * ```
+ */
+export type IsNotBoolean<T, Then = true, Else = false> = BooleanType<T, Else, Then>

package/ts/boolean/false_type.ts

@@ -0,0 +1,61 @@
+import type { IsAnyOrNever } from '../any/any_or_never.js'
+
+/**
+ * Check if the type `T` is exactly `false`.
+ *
+ * ```ts
+ * import type { FalseType } from 'type-plus'
+ *
+ * type R = FalseType<false> // false
+ *
+ * type R = FalseType<true> // never
+ * type R = FalseType<unknown> // never
+ * ```
+ */
+export type FalseType<T, Then = T, Else = never> = IsAnyOrNever<
+	T,
+	Else,
+	[T, false] extends [false, T] ? Then : Else
+>
+
+/**
+ * Check if the type `T` is not exactly `false`.
+ *
+ * ```ts
+ * import type { NotFalseType } from 'type-plus'
+ *
+ * type R = NotFalseType<false> // never
+ *
+ * type R = NotFalseType<true> // true
+ * type R = NotFalseType<unknown> // unknown
+ * ```
+ */
+export type NotFalseType<T, Then = T, Else = never> = FalseType<T, Else, Then>
+
+/**
+ * Is the type `T` exactly `false`.
+ *
+ * ```ts
+ * import type { IsFalse } from 'type-plus'
+ *
+ * type R = IsFalse<false> // true
+ *
+ * type R = IsFalse<true> // false
+ * type R = IsFalse<unknown> // false
+ * ```
+ */
+export type IsFalse<T, Then = true, Else = false> = FalseType<T, Then, Else>
+
+/**
+ * Is the type `T` not exactly `false`.
+ *
+ * ```ts
+ * import type { IsNotFalse } from 'type-plus'
+ *
+ * type R = IsNotFalse<false> // false
+ *
+ * type R = IsNotFalse<true> // true
+ * type R = IsNotFalse<unknown> // true
+ * ```
+ */
+export type IsNotFalse<T, Then = true, Else = false> = FalseType<T, Else, Then>

package/ts/boolean/readme.md

@@ -0,0 +1,85 @@
+# boolean
+
+`boolean` is a type that represents the two values: `true` and `false`.
+
+Unlike other types, `boolean` is a primitive union type.
+It is exactly equivalent to the union type `true | false`.
+
+## Type Checking
+
+The `BooleanType<T>` and friends are used to check if a type is `boolean` or not.
+
+It matches `boolean`, `true`, and `false`.
+
+```ts
+import type { BooleanType } from 'type-plus'
+
+type R = BooleanType<boolean> // boolean
+type R = BooleanType<true> // true
+type R = BooleanType<false> // false
+
+type R = BooleanType<1> // never
+```
+
+- [`BooleanType<T, Then = T, Else = never>`](boolean_type.ts#L17): check if `T` is `boolean`, `true`, or `false`.
+- [`IsBoolean<T, Then = true, Else = false`](boolean_type.ts#L37): is `T` `boolean`.
+- [`NotBooleanType<T, Then = T, Else = never>`](boolean_type.ts#L53): check if `T` is not `boolean`, `true`, nor `false`.
+- [`IsNotBoolean<T, Then = true, Else = false>`](boolean_type.ts#L69): is `T` not `boolean`.
+
+---
+
+The `StrictBooleanType<T>` and friends are used to check if a type is exactly `boolean` or not.
+
+It matches only the type `boolean`.
+
+```ts
+import type { StrictBooleanType } from 'type-plus'
+
+type R = StrictBooleanType<boolean> // boolean
+
+type R = StrictBooleanType<true> // never
+type R = StrictBooleanType<false> // never
+```
+
+- [`StrictBooleanType<T, Then = T, Else = never>`](strict_boolean_type.ts#L16): check if `T` is exactly `boolean`.
+- [`IsStrictBoolean<T, Then = true, Else = false`](strict_boolean_type.ts#L50): is `T` exactly `boolean`.
+- [`NotStrictBooleanType<T, Then = T, Else = never>`](strict_boolean_type.ts#L35): check if `T` is not exactly `boolean`.
+- [`IsNotStrictBoolean<T, Then = true, Else = false>`](strict_boolean_type.ts#L65): is `T` not exactly `boolean`.
+
+---
+
+The `TrueType<T>` and friends are used to check if a type is `true` or not.
+
+It matches only `true`.
+
+```ts
+import type { TrueType } from 'type-plus'
+
+type R = TrueType<true> // true
+
+type R = TrueType<boolean> // never
+```
+
+- [`TrueType<T, Then = T, Else = never>`](true_type.ts#L16): check if `T` is `true`.
+- [`IsTrue<T, Then = true, Else = false`](true_type.ts#L35): is `T` `true`.
+- [`NotTrueType<T, Then = T, Else = never>`](true_type.ts#L49): check if `T` is not `true`.
+- [`IsNotTrue<T, Then = true, Else = false>`](true_type.ts#L63): is `T` not `true`.
+
+---
+
+The `FalseType<T>` and friends are used to check if a type is `false` or not.
+
+It matches only `false`.
+
+```ts
+import type { FalseType } from 'type-plus'
+
+type R = FalseType<false> // false
+
+type R = FalseType<boolean> // never
+```
+
+- [`FalseType<T, Then = T, Else = never>`](false_type.ts#L16): check if `T` is `false`.
+- [`IsFalse<T, Then = true, Else = false`](false_type.ts#L35): is `T` `false`.
+- [`NotFalseType<T, Then = T, Else = never>`](false_type.ts#L49): check if `T` is not `false`.
+- [`IsNotFalse<T, Then = true, Else = false>`](false_type.ts#L63): is `T` not `false`.

package/ts/boolean/strict_boolean_type.ts

@@ -0,0 +1,65 @@
+import type { IsAnyOrNever } from '../any/any_or_never.js'
+
+/**
+ * Check if the type `T` is exactly `boolean`.
+ *
+ * ```ts
+ * import type { StrictBooleanType } from 'type-plus'
+ *
+ * type R = StrictBooleanType<boolean> // true
+ *
+ * type R = StrictBooleanType<true> // never
+ * type R = StrictBooleanType<false> // never
+ * type R = StrictBooleanType<unknown> // never
+ * ```
+ */
+export type StrictBooleanType<T, Then = T, Else = never> = IsAnyOrNever<
+	T,
+	Else,
+	[T, boolean] extends [boolean, T] ? Then : Else
+>
+
+/**
+ * Check if the type `T` is not exactly `boolean`.
+ *
+ * ```ts
+ * import type { NotStrictBooleanType } from 'type-plus'
+ *
+ * type R = NotStrictBooleanType<boolean> // never
+ *
+ * type R = NotStrictBooleanType<true> // true
+ * type R = NotStrictBooleanType<false> // false
+ * type R = NotStrictBooleanType<unknown> // unknown
+ * ```
+ */
+export type NotStrictBooleanType<T, Then = T, Else = never> = StrictBooleanType<T, Else, Then>
+
+/**
+ * Is the type `T` exactly `boolean`.
+ *
+ * ```ts
+ * import type { IsStrictBoolean } from 'type-plus'
+ *
+ * type R = IsStrictBoolean<boolean> // true
+ *
+ * type R = IsStrictBoolean<true> // false
+ * type R = IsStrictBoolean<false> // true
+ * type R = IsStrictBoolean<unknown> // false
+ * ```
+ */
+export type IsStrictBoolean<T, Then = true, Else = false> = StrictBooleanType<T, Then, Else>
+
+/**
+ * Is the type `T` not exactly `false`.
+ *
+ * ```ts
+ * import type { IsNotStrictBoolean } from 'type-plus'
+ *
+ * type R = IsNotStrictBoolean<boolean> // false
+ *
+ * type R = IsNotStrictBoolean<true> // true
+ * type R = IsNotStrictBoolean<false> // false
+ * type R = IsNotStrictBoolean<unknown> // true
+ * ```
+ */
+export type IsNotStrictBoolean<T, Then = true, Else = false> = StrictBooleanType<T, Else, Then>

package/ts/boolean/true_type.ts

@@ -0,0 +1,61 @@
+import type { IsAnyOrNever } from '../any/any_or_never.js'
+
+/**
+ * Check if the type `T` is exactly `true`.
+ *
+ * ```ts
+ * import type { TrueType } from 'type-plus'
+ *
+ * type R = TrueType<true> // true
+ *
+ * type R = TrueType<false> // never
+ * type R = TrueType<unknown> // never
+ * ```
+ */
+export type TrueType<T, Then = T, Else = never> = IsAnyOrNever<
+	T,
+	Else,
+	[T, true] extends [true, T] ? Then : Else
+>
+
+/**
+ * Check if the type `T` is not exactly `true`.
+ *
+ * ```ts
+ * import type { NotTrueType } from 'type-plus'
+ *
+ * type R = NotTrueType<true> // never
+ *
+ * type R = NotTrueType<false> // false
+ * type R = NotTrueType<unknown> // unknown
+ * ```
+ */
+export type NotTrueType<T, Then = T, Else = never> = TrueType<T, Else, Then>
+
+/**
+ * Is the type `T` exactly `true`.
+ *
+ * ```ts
+ * import type { IsTrue } from 'type-plus'
+ *
+ * type R = IsTrue<true> // true
+ *
+ * type R = IsTrue<false> // false
+ * type R = IsTrue<unknown> // false
+ * ```
+ */
+export type IsTrue<T, Then = true, Else = false> = TrueType<T, Then, Else>
+
+/**
+ * Is the type `T` not exactly `true`.
+ *
+ * ```ts
+ * import type { IsNotTrue } from 'type-plus'
+ *
+ * type R = IsNotTrue<true> // false
+ *
+ * type R = IsNotTrue<false> // true
+ * type R = IsNotTrue<unknown> // true
+ * ```
+ */
+export type IsNotTrue<T, Then = true, Else = false> = TrueType<T, Else, Then>

package/ts/composable_types.ts

@@ -0,0 +1,9 @@
+/**
+ * Types that can contain custom properties.
+ */
+export type ComposableTypes = object | Function
+
+/**
+ * Types that cannot contain custom properties.
+ */
+export type NonComposableTypes = boolean | number | string | symbol | bigint | undefined | null

package/ts/equal/equal.ts

@@ -0,0 +1,88 @@
+import type { IsAny } from '../any/any_type.js'
+import type { IsNever } from '../never/never_type.js'
+import type { IsObject } from '../object/object_type.js'
+import type { Properties } from '../object/properties.js'
+import type { And, Or } from '../predicates/logical.js'
+import type { IsSymbol } from '../symbol/symbol_type.js'
+
+type BothNever<A, B, Both, One, None> = And<
+	IsNever<A>,
+	IsNever<B>,
+	Both,
+	Or<IsNever<A>, IsNever<B>, One, None>
+>
+
+type BothAny<A, B, Both, One, None> = And<IsAny<A>, IsAny<B>, Both, Or<IsAny<A>, IsAny<B>, One, None>>
+
+type IdentityEqual<A, B, Then, Else> = (<_>() => _ extends (A & _) | _ ? 1 : 2) extends <_>() => _ extends
+	| (B & _)
+	| _
+	? 1
+	: 2
+	? Then
+	: Else
+
+/**
+ * Checks `A` and `B` are equal.
+ *
+ * ```ts
+ * import { type Equal } from 'type-plus'
+ *
+ * type R = Equal<1, 1> // true
+ * type R = Equal<any, any> // true
+ * type R = Equal<boolean, boolean> // true
+ * type R = Equal<true, true> // true
+ * type R = Equal<[1], [1]> // true
+ *
+ * type R = Equal<boolean, true> // false
+ * type R = Equal<any, 1> // false
+ * type R = Equal<[any], [1]> // false
+ * type R = Equal<{ a: 1 }, { a: 1; b: 2 }> // false
+ * ```
+ */
+export type Equal<A, B, Then = true, Else = false> = [A, B] extends [B, A]
+	? BothNever<
+			A,
+			B,
+			Then,
+			Else,
+			BothAny<
+				A,
+				B,
+				Then,
+				Else,
+				IdentityEqual<
+					A,
+					B,
+					Then,
+					And<
+						IsObject<A>,
+						IsObject<B>,
+						IdentityEqual<Properties<A>, Properties<B>, Then, Else>,
+						// `A` and `B` are narrowed, need to check again.
+						[A, B] extends [B, A] ? Then : Else
+					>
+				>
+			>
+	  >
+	: And<IsSymbol<A>, IsSymbol<B>, Then, Else>
+
+/**
+ * Checks `A` and `B` are not equal.
+ *
+ * ```ts
+ * import { type NotEqual } from 'type-plus'
+ *
+ * type R = NotEqual<1, 1> // false
+ * type R = NotEqual<any, any> // false
+ * type R = NotEqual<boolean, boolean> // false
+ * type R = NotEqual<true, true> // false
+ * type R = NotEqual<[1], [1]> // false
+ *
+ * type R = NotEqual<boolean, true> // true
+ * type R = NotEqual<any, 1> // true
+ * type R = NotEqual<[any], [1]> // true
+ * type R = NotEqual<{ a: 1 }, { a: 1; b: 2 }> // true
+ * ```
+ */
+export type NotEqual<A, B, Then = true, Else = false> = Equal<A, B, Else, Then>

package/ts/equal/readme.md

@@ -0,0 +1,31 @@
+# Equal
+
+`Equal<A, B>` and friends check if `A` and `B` are equal.
+
+It is a type-level version of `===`.
+It handles special types (`any`, `unknown`, `never`, `void`) correctly.
+
+```ts
+import { type Equal } from 'type-plus'
+
+type R = Equal<1, 1> // true
+type R = Equal<any, any> // true
+type R = Equal<boolean, boolean> // true
+type R = Equal<true, true> // true
+type R = Equal<[1], [1]> // true
+
+type R = Equal<boolean, true> // false
+type R = Equal<any, 1> // false
+type R = Equal<[any], [1]> // false
+type R = Equal<{ a: 1 }, { a: 1; b: 2 }> // false
+```
+
+- [`Equal<A, B, Then = true, Else = false>`](equal.ts#L27): check if `A` and `B` are equal.
+- [`NotEqual<A, B, Then = true, Else = false>`](equal.ts#L88): check if `A` and `B` are not equal.
+
+---
+
+[![Just Code: Equality is hard][equality-is-hard]][equality-is-hard-url]
+
+[equality-is-hard]: https://img.youtube.com/vi/VEqrFzCzo28/0.jpg
+[equality-is-hard-url]: https://www.youtube.com/watch?v=VEqrFzCzo28

package/ts/function/extract_function.ts

@@ -0,0 +1,29 @@
+import type { AnyFunction } from './any_function.js'
+
+/**
+ * Extract the function signature from a composite type T.
+ *
+ * It works with interact of functions, but not on function overloads and union.
+ * @note does not work with function overloads.
+ *
+ * ```ts
+ * import type { ExtractFunction } from 'type-plus'
+ *
+ * type R = ExtractFunction<{
+ *   () => void
+ *   a: 1
+ * }> // () => void
+ * ```
+ */
+export type ExtractFunction<T extends AnyFunction> = T extends AnyFunction<infer P, infer R>
+	? (...args: P) => R
+	: never
+
+/**
+ * Extract the function signature from a composite function.
+ *
+ * @note does not work with function overloads.
+ */
+export function extractFunction<T extends AnyFunction>(fn: T) {
+	return fn as unknown as ExtractFunction<T>
+}

package/ts/function/function_type.ts

@@ -0,0 +1,72 @@
+import type { IsAnyOrNever } from '../any/any_or_never.js'
+
+/**
+ * Check if `T` is a `Function`.
+ *
+ * ```ts
+ * import type { FunctionType } from 'type-plus'
+ *
+ * type R = FunctionType<Function> // Function
+ * type R = FunctionType<() => void> // () => void
+ * type R = FunctionType<(() => void) | { a: 1 }> // (() => void) | { a: 1 }
+ *
+ * type R = FunctionType<{ a: 1 }> // never
+ * type R = FunctionType<never> // never
+ * type R = FunctionType<unknown> // never
+ * ```
+ */
+export type FunctionType<T, Then = T, Else = never> = IsAnyOrNever<
+	T,
+	Else,
+	[T] extends [Function] ? Then : Else
+>
+
+/**
+ * Is `T` a `Function`.
+ *
+ * ```ts
+ * import type { IsFunction } from 'type-plus'
+ *
+ * type R = IsFunction<Function> // Function
+ * type R = IsFunction<() => void> // () => void
+ * type R = IsFunction<(() => void) | { a: 1 }> // (() => void) | { a: 1 }
+ *
+ * type R = IsFunction<{ a: 1 }> // never
+ * type R = IsFunction<never> // never
+ * type R = IsFunction<unknown> // never
+ * ```
+ */
+export type IsFunction<T, Then = true, Else = false> = FunctionType<T, Then, Else>
+
+/**
+ * Check if `T` is not a `Function`.
+ *
+ * ```ts
+ * import type { NotFunctionType } from 'type-plus'
+ *
+ * type R = NotFunctionType<Function> // never
+ * type R = NotFunctionType<() => void> // never
+ * type R = NotFunctionType<(() => void) | { a: 1 }> // never
+ *
+ * type R = NotFunctionType<{ a: 1 }> // { a: 1 }
+ * type R = NotFunctionType<never> // never
+ * type R = NotFunctionType<unknown> // unknown
+ * ```
+ */
+export type NotFunctionType<T, Then = T, Else = never> = FunctionType<T, Else, Then>
+
+/**
+ * Is `T` not a `Function`.
+ *
+ * ```ts
+ * import type { IsNotFunction } from 'type-plus'
+ *
+ * type R = IsNotFunction<Function> // false
+ * type R = IsNotFunction<() => void> // false
+ * type R = IsNotFunction<(() => void) | { a: 1 }> // false
+ *
+ * type R = IsNotFunction<{ a: 1 }> // true
+ * type R = IsNotFunction<never> // true
+ * ```
+ */
+export type IsNotFunction<T, Then = true, Else = false> = FunctionType<T, Else, Then>