type-plus 6.3.0 → 6.4.0

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>

package/ts/function/readme.md

@@ -0,0 +1,84 @@
+# Function
+
+`Function` is a type to represent functions.
+
+## Type Checking
+
+The `FunctionType<T>` and friends are used to check if a type is `Function` or not.
+
+They are loose type checks, meaning they match `Function` and function signatures,
+function overloads, as well as intersection types.
+
+```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
+```
+
+- [`FunctionType<T, Then = T, Else = never>`](function_type.ts#L18): check if `T` is `Function` or Function literal.
+- [`IsFunction<T, Then = true, Else = false`](function_type.ts#L39): is `T` `Function`.
+- [`NotFunctionType<T, Then = T, Else = never>`](function_type.ts#L56): check if `T` is not `Function`.
+- [`IsNotFunction<T, Then = true, Else = false>`](function_type.ts#L72): is `T` not `Function`.
+
+---
+
+The `StrictFunctionType<T>` and friends are used to check if a type is exactly `Function` or not.
+
+They are strict type checks, meaning they match only the type `Function` only.
+
+```ts
+import type { StrictFunctionType } from 'type-plus'
+
+ * type R = StrictFunctionType<Function> // Function
+ *
+ * type R = StrictFunctionType<() => void> // never
+ * type R = StrictFunctionType<Function & { a: 1 }> // never
+```
+
+- [`StrictFunctionType<T, Then = T, Else = never>`](strict_function_type.ts#L15): check if `T` is exactly `Function`.
+- [`IsStrictFunction<T, Then = true, Else = false`](strict_function_type.ts#L33): is `T` exactly `Function`.
+- [`NotStrictFunctionType<T, Then = T, Else = never>`](strict_function_type.ts#L47): check if `T` is not exactly `Function`.
+- [`IsNotStrictFunction<T, Then = true, Else = false>`](strict_function_type.ts#L61): is `T` not exactly `Function`.
+
+---
+
+`AnyFunction` is a type to represent any function.
+
+You can also use it to build specific signatures.
+
+```ts
+import type { AnyFunction } from 'type-plus'
+
+type R = AnyFunction // (...args: any[]) => any
+type R = AnyFunction<[a: string, b: number], boolean> // (a: string, b: number) => boolean
+```
+
+---
+
+`ExtractFunction<T>` extracts the function type from a type.
+Note that it does not work with function overloads.
+
+```ts
+import type { ExtractFunction } from 'type-plus'
+
+type R = ExtractFunction<{
+  () => void
+  a: 1
+}> // () => void
+```
+
+---
+
+`extractFunction` is the function form of `ExtractFunction<T>`.
+
+## References
+
+- [mdn web docs: BigInt][mdn]
+
+[mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt

package/ts/function/strict_function_type.ts

@@ -0,0 +1,61 @@
+import type { IsAnyOrNever } from '../any/any_or_never.js'
+
+/**
+ * Check if `T` is exactly `Function`.
+ *
+ * ```ts
+ * import type { StrictFunctionType } from 'type-plus'
+ *
+ * type R = StrictFunctionType<Function> // Function
+ *
+ * type R = StrictFunctionType<() => void> // never
+ * type R = StrictFunctionType<Function & { a: 1 }> // never
+ * ```
+ */
+export type StrictFunctionType<T, Then = T, Else = never> = IsAnyOrNever<
+	T,
+	Else,
+	[T, Function] extends [Function, T] ? Then : Else
+>
+
+/**
+ * Check if `T` is not exactly `Function`.
+ *
+ * ```ts
+ * import type { NotStrictFunctionType } from 'type-plus'
+ *
+ * type R = NotStrictFunctionType<Function> // never
+ * type R = NotStrictFunctionType<() => void> // () => void
+ *
+ * type R = NotStrictFunctionType<Function & { a: 1 }> // Function & { a: 1 }
+ * ```
+ */
+export type NotStrictFunctionType<T, Then = T, Else = never> = StrictFunctionType<T, Else, Then>
+
+/**
+ * Is `T` exactly `Function`.
+ *
+ * ```ts
+ * import type { IsStrictFunction } from 'type-plus'
+ *
+ * type R = IsStrictFunction<Function> // true
+ *
+ * type R = IsStrictFunction<() => void> // false
+ * type R = IsStrictFunction<(() => void) & { a: 1 }> // false
+ * ```
+ */
+export type IsStrictFunction<T, Then = true, Else = false> = StrictFunctionType<T, Then, Else>
+
+/**
+ * Is `T` not exactly `Function`.
+ *
+ * ```ts
+ * import type { IsNotStrictFunction } from 'type-plus'
+ *
+ * type R = IsNotStrictFunction<Function> // false
+ *
+ * type R = IsNotStrictFunction<() => void> // true
+ * type R = IsNotStrictFunction<(() => void) & { a: 1 }> // true
+ * ```
+ */
+export type IsNotStrictFunction<T, Then = true, Else = false> = StrictFunctionType<T, Else, Then>

package/ts/functional/Maybe.ts

@@ -1,5 +1,5 @@
-import type { Brand } from '../nominal-types/index.js'
-import type { Equal } from '../predicates/index.js'
+import type { Brand } from '../nominal/index.js'
+import type { Equal } from '../equal/equal.js'
 import type { Widen } from '../utils/index.js'
 
 export type Maybe<T> = Just<T> | None<T>

package/ts/functional/compose.ts

@@ -1,5 +1,5 @@
-import type { Head, Last } from '../array_plus/index.js'
-import type { AnyFunction } from '../function/AnyFunction.js'
+import type { Head, Last } from '../array/index.js'
+import type { AnyFunction } from '../function/any_function.js'
 
 /**
  * Compose functions to produce a new function.