type-plus 8.0.0-beta.0 → 8.0.0-beta.2

package/src/boolean/readme.md

@@ -0,0 +1,430 @@
+# 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`.
+
+## [IsBoolean](./is_boolean.ts)
+
+`IsBoolean<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is `boolean`, including `true` and `false`.
+
+```ts
+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
+type R = IsBoolean<string | boolean> // boolean
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is `boolean`, including `true` and `false`, otherwise returns `never`.
+
+```ts
+type R = IsBoolean<boolean, { selection: 'filter' }> // boolean
+type R = IsBoolean<true, { selection: 'filter' }> // true
+type R = IsBoolean<false, { selection: 'filter' }> // true
+
+type R = IsBoolean<number, { selection: 'filter' }> // never
+type R = IsBoolean<unknown, { selection: 'filter' }> // never
+type R = IsBoolean<never, { selection: 'filter' }> // never
+type R = IsBoolean<string | boolean, { selection: 'filter' }> // boolean
+```
+
+🔢 *customize*:
+
+Disable distribution of union types.
+
+```ts
+type R = IsBoolean<boolean | 1> // boolean
+type R = IsBoolean<boolean | 1, { distributive: false }> // false
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsBoolean<boolean, $SelectionBranch> // $Then
+type R = IsBoolean<string, $SelectionBranch> // $Else
+```
+
+## [IsTrue](./is_true.ts)
+
+`IsTrue<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is `true`.
+
+```ts
+type R = IsTrue<boolean> // boolean
+type R = IsTrue<true> // true
+type R = IsTrue<false> // false
+
+type R = IsTrue<number> // false
+type R = IsTrue<unknown> // false
+type R = IsTrue<string | boolean> // boolean
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is `true`, otherwise returns `never`.
+
+```ts
+type R = IsTrue<boolean, { selection: 'filter' }> // true
+type R = IsTrue<true, { selection: 'filter' }> // true
+type R = IsTrue<false, { selection: 'filter' }> // never
+
+type R = IsTrue<number, { selection: 'filter' }> // never
+type R = IsTrue<unknown, { selection: 'filter' }> // never
+type R = IsTrue<never, { selection: 'filter' }> // never
+type R = IsTrue<string | boolean, { selection: 'filter' }> // true
+```
+
+🔢 *customize*:
+
+Disable distribution of union types.
+
+```ts
+type R = IsTrue<true | 1> // boolean
+type R = IsTrue<boolean | 1> // boolean
+type R = IsTrue<true | 1, { distributive: false }> // false
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsTrue<true, $SelectionBranch> // $Then
+type R = IsTrue<boolean, $SelectionBranch> // $Then | $Else
+type R = IsTrue<string, $SelectionBranch> // $Else
+```
+
+## [IsFalse](./is_false.ts)
+
+`IsFalse<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is `false`.
+
+```ts
+type R = IsFalse<boolean> // boolean
+type R = IsFalse<true> // false
+type R = IsFalse<false> // true
+
+type R = IsFalse<number> // false
+type R = IsFalse<unknown> // false
+type R = IsFalse<string | boolean> // boolean
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is `false`, otherwise returns `never`.
+
+```ts
+type R = IsFalse<boolean, { selection: 'filter' }> // false
+type R = IsFalse<true, { selection: 'filter' }> // never
+type R = IsFalse<false, { selection: 'filter' }> // false
+
+type R = IsFalse<number, { selection: 'filter' }> // never
+type R = IsFalse<unknown, { selection: 'filter' }> // never
+type R = IsFalse<never, { selection: 'filter' }> // never
+type R = IsFalse<string | boolean, { selection: 'filter' }> // false
+```
+
+🔢 *customize*:
+
+Disable distribution of union types.
+
+```ts
+type R = IsFalse<false | 1> // boolean
+type R = IsFalse<boolean | 1> // boolean
+type R = IsFalse<boolean | 1, { distributive: false }> // false
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsFalse<false, $SelectionBranch> // $Then
+type R = IsFalse<boolean, $SelectionBranch> // $Then | $Else
+type R = IsFalse<string, $SelectionBranch> // $Else
+```
+
+## [IsNotBoolean](./is_not_boolean.ts)
+
+`IsNotBoolean<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is not `boolean`.
+
+```ts
+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
+type R = IsNotBoolean<string | boolean> // boolean
+ ```
+
+🔢 *customize*
+
+Filter to ensure `T` is not `boolean`, including `true` and `false`, otherwise returns `never`.
+
+```ts
+type R = IsNotBoolean<boolean, { selection: 'filter' }> // never
+type R = IsNotBoolean<true, { selection: 'filter' }> // never
+type R = IsNotBoolean<false, { selection: 'filter' }> // never
+
+type R = IsNotBoolean<number, { selection: 'filter' }> // number
+type R = IsNotBoolean<unknown, { selection: 'filter' }> // unknown
+type R = IsNotBoolean<never, { selection: 'filter' }> // never
+type R = IsNotBoolean<string | boolean, { selection: 'filter' }> // string
+```
+
+🔢 *customize*:
+
+Disable distribution of union types.
+
+```ts
+type R = IsNotBoolean<boolean | 1> // boolean
+type R = IsNotBoolean<boolean | 1, { distributive: false }> // true
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsNotBoolean<boolean, $SelectionBranch> // $Else
+type R = IsNotBoolean<string, $SelectionBranch> // $Then
+```
+
+## [IsNotTrue](./is_not_true.ts)
+
+`IsNotTrue<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is not `true`.
+
+```ts
+type R = IsNotTrue<boolean> // boolean
+type R = IsNotTrue<true> // false
+type R = IsNotTrue<false> // true
+
+type R = IsNotTrue<number> // true
+type R = IsNotTrue<unknown> // true
+type R = IsNotTrue<string | boolean> // boolean
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is not `true`, otherwise returns `never`.
+
+```ts
+type R = IsNotTrue<boolean, { selection: 'filter' }> // false
+type R = IsNotTrue<true, { selection: 'filter' }> // never
+type R = IsNotTrue<false, { selection: 'filter' }> // false
+
+type R = IsNotTrue<number, { selection: 'filter' }> // number
+type R = IsNotTrue<never, { selection: 'filter' }> // never
+type R = IsNotTrue<unknown, { selection: 'filter' }> // unknown
+type R = IsNotTrue<string | boolean, { selection: 'filter' }> // string | false
+type R = IsNotTrue<string | true, { selection: 'filter' }> // string
+```
+
+🔢 *customize*:
+
+Disable distribution of union types.
+
+```ts
+type R = IsNotTrue<boolean | 1> // boolean
+type R = IsNotTrue<true | 1> // boolean
+type R = IsNotTrue<false | 1> // true
+type R = IsNotTrue<boolean | 1, { distributive: false }> // true
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsNotTrue<true, $SelectionBranch> // $Else
+type R = IsNotTrue<boolean, $SelectionBranch> // $Then | $Else
+type R = IsNotTrue<string, $SelectionBranch> // $Then
+```
+
+## [IsNotFalse](./is_not_false.ts)
+
+`IsNotFalse<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is not `false`.
+
+```ts
+type R = IsNotFalse<boolean> // boolean
+type R = IsNotFalse<true> // true
+type R = IsNotFalse<false> // false
+
+type R = IsNotFalse<number> // true
+type R = IsNotFalse<unknown> // true
+type R = IsNotFalse<string | boolean> // boolean
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is not `false`, otherwise returns `never`.
+
+```ts
+type R = IsNotFalse<boolean, { selection: 'filter' }> // true
+type R = IsNotFalse<true, { selection: 'filter' }> // true
+type R = IsNotFalse<false, { selection: 'filter' }> // never
+
+type R = IsNotFalse<number, { selection: 'filter' }> // number
+type R = IsNotFalse<never, { selection: 'filter' }> // never
+type R = IsNotFalse<unknown, { selection: 'filter' }> // unknown
+type R = IsNotFalse<string | boolean, { selection: 'filter' }> // string | true
+type R = IsNotFalse<string | false, { selection: 'filter' }> // string
+```
+
+🔢 *customize*:
+
+Disable distribution of union types.
+
+```ts
+type R = IsNotFalse<false | 1> // boolean
+type R = IsNotFalse<boolean | 1> // boolean
+type R = IsNotFalse<boolean | 1, { distributive: false }> // true
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsNotFalse<false, $SelectionBranch> // $Else
+type R = IsNotFalse<boolean, $SelectionBranch> // $Then | $Else
+type R = IsNotFalse<string, $SelectionBranch> // $Then
+```
+
+## [IsStrictBoolean](./is_strict_boolean.ts)
+
+`IsStrictBoolean<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is exactly `boolean`.
+
+```ts
+type R = IsStrictBoolean<boolean> // true
+type R = IsStrictBoolean<true> // false
+type R = IsStrictBoolean<false> // false
+
+type R = IsStrictBoolean<number> // false
+type R = IsStrictBoolean<unknown> // false
+type R = IsStrictBoolean<string | boolean> // boolean
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is exactly `boolean`, otherwise returns `never`.
+
+```ts
+type R = IsStrictBoolean<boolean, { selection: 'filter' }> // boolean
+type R = IsStrictBoolean<true, { selection: 'filter' }> // never
+type R = IsStrictBoolean<false, { selection: 'filter' }> // never
+
+type R = IsStrictBoolean<number, { selection: 'filter' }> // never
+type R = IsStrictBoolean<unknown, { selection: 'filter' }> // never
+type R = IsStrictBoolean<never, { selection: 'filter' }> // never
+type R = IsStrictBoolean<string | boolean, { selection: 'filter' }> // boolean
+type R = IsStrictBoolean<string | true, { selection: 'filter' }> // never
+```
+
+🔢 *customize*:
+
+Disable distribution of union types.
+
+```ts
+type R = IsStrictBoolean<boolean | 1> // boolean
+type R = IsStrictBoolean<boolean | 1, { distributive: false }> // false
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsStrictBoolean<boolean, $SelectionBranch> // $Then
+type R = IsStrictBoolean<true, $SelectionBranch> // $Else
+type R = IsStrictBoolean<false, $SelectionBranch> // $Else
+type R = IsStrictBoolean<string, $SelectionBranch> // $Else
+```
+
+## [IsNotStrictBoolean](./is_not_strict_boolean.ts)
+
+`IsNotStrictBoolean<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is not exactly `boolean`.
+
+```ts
+type R = IsNotStrictBoolean<boolean> // false
+type R = IsNotStrictBoolean<true> // true
+type R = IsNotStrictBoolean<false> // true
+
+type R = IsNotStrictBoolean<number> // true
+type R = IsNotStrictBoolean<unknown> // true
+type R = IsNotStrictBoolean<string | boolean> // boolean
+ ```
+
+🔢 *customize*
+
+Filter to ensure `T` is not exactly `boolean`, otherwise returns `never`.
+
+```ts
+type R = IsNotStrictBoolean<boolean, { selection: 'filter' }> // never
+type R = IsNotStrictBoolean<true, { selection: 'filter' }> // true
+type R = IsNotStrictBoolean<false, { selection: 'filter' }> // false
+
+type R = IsNotStrictBoolean<number, { selection: 'filter' }> // number
+type R = IsNotStrictBoolean<unknown, { selection: 'filter' }> // unknown
+type R = IsNotStrictBoolean<never, { selection: 'filter' }> // never
+type R = IsNotStrictBoolean<string | boolean, { selection: 'filter' }> // string
+```
+
+🔢 *customize*:
+
+Disable distribution of union types.
+
+```ts
+type R = IsNotStrictBoolean<boolean | 1> // boolean
+type R = IsNotStrictBoolean<boolean | 1, { distributive: false }> // true
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsNotStrictBoolean<boolean, $SelectionBranch> // $Else
+type R = IsNotStrictBoolean<true, $SelectionBranch> // $Then
+type R = IsNotStrictBoolean<false, $SelectionBranch> // $Then
+type R = IsNotStrictBoolean<string, $SelectionBranch> // $Then
+```

package/src/class/AnyConstructor.ts

@@ -0,0 +1 @@
+export type AnyConstructor<Params extends any[] = any[]> = new (..._args: Params) => void

package/src/class/isConstructor.ts

@@ -0,0 +1,34 @@
+import type { AnyConstructor } from './AnyConstructor.js'
+
+/**
+ * Is the subject a constructor function.
+ *
+ * @deprecated this is not a failsafe test,
+ * it will return true for any function that can be called with `new`.
+ *
+ * If the subject is an arrow function,
+ * it can still return true after compilation.
+ *
+ * Thus this function is not safe to use.
+ */
+export function isConstructor(subject: unknown): subject is AnyConstructor {
+	try {
+		new (subject as AnyConstructor)()
+	} catch (err: any) {
+		const msg = err?.message as string | undefined
+		if (msg && msg.indexOf('is not a constructor') >= 0) {
+			return false
+		}
+	}
+	return true
+}
+
+/**
+ * instanceof type guard for unknown value.
+ */
+export function isInstanceof<T extends AnyConstructor>(
+	subject: unknown,
+	classConstructor: T
+): subject is InstanceType<T> {
+	return subject instanceof classConstructor
+}

package/src/equal/equal.ts

@@ -0,0 +1,135 @@
+import type { IsAny } from '../any/is_any.js'
+import type { IsNever } from '../never/is_never.js'
+import type { IsObject } from '../object/is_object.js'
+import type { Properties } from '../object/properties.js'
+import type { And, Or } from '../predicates/logical.js'
+import type { IsSymbol } from '../symbol/is_symbol.js'
+import type { IdentityEqual } from './identity_equal.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>>
+
+/**
+ * Checks `A` and `B` are equal.
+ *
+ * ```ts
+ * type R = IsEqual<1, 1> // true
+ * type R = IsEqual<any, any> // true
+ * type R = IsEqual<boolean, boolean> // true
+ * type R = IsEqual<true, true> // true
+ * type R = IsEqual<[1], [1]> // true
+ *
+ * type R = IsEqual<boolean, true> // false
+ * type R = IsEqual<any, 1> // false
+ * type R = IsEqual<[any], [1]> // false
+ * type R = IsEqual<{ a: 1 }, { a: 1; b: 2 }> // false
+ * ```
+ *
+ * Note that intersection type checks only works at first level.
+ * It cannot be check recursively,
+ * or else will run into infinite recursion if the type includes recursive types.
+ */
+export type IsEqual<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>,
+						[A, B] extends [(...args: infer P1) => any, (...args: infer P2) => any]
+						? IsEqual<P1, P2, Then, Else>
+						: Then,
+						Else
+					>,
+					// `A` and `B` are narrowed, need to check again.
+					// This is fixed in TS 5.0.2, but keeping it to support older versions.
+					[A, B] extends [B, A] ? Then : Else
+				>
+			>
+		>
+	>
+	: And<IsSymbol<A, { distributive: false }>, IsSymbol<B, { distributive: false }>, Then, Else>
+
+/**
+ * Checks `A` and `B` are not equal.
+ *
+ * ```ts
+ * type R = IsNotEqual<1, 1> // false
+ * type R = IsNotEqual<any, any> // false
+ * type R = IsNotEqual<boolean, boolean> // false
+ * type R = IsNotEqual<true, true> // false
+ * type R = IsNotEqual<[1], [1]> // false
+ *
+ * type R = IsNotEqual<boolean, true> // true
+ * type R = IsNotEqual<any, 1> // true
+ * type R = IsNotEqual<[any], [1]> // true
+ * type R = IsNotEqual<{ a: 1 }, { a: 1; b: 2 }> // true
+ * ```
+ *
+ * Note that intersection type checks only works at first level.
+ * It cannot be check recursively,
+ * or else will run into infinite recursion if the type includes recursive types.
+ */
+export type IsNotEqual<A, B, Then = true, Else = false> = IsEqual<A, B, Else, Then>
+
+/**
+ * Checks `A` and `B` are equal.
+ *
+ * @deprecated this will be changed to `filter` variant in the future.
+ * Please use `IsEqual` for the `predicate` behavior.
+ *
+ * ```ts
+ * 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> = IsEqual<A, B, Then, Else>
+
+/**
+ * Checks `A` and `B` are not equal.
+ *
+ * @deprecated this will be changed to `filter` variant in the future.
+ * Please use `IsNotEqual` for the `predicate` behavior.
+ *
+ * ```ts
+ * 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> = IsNotEqual<A, B, Then, Else>

package/src/function/is_function.ts

@@ -0,0 +1,62 @@
+import type { $Select } from '../type_plus/branch/$select.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is `Function` or function signature.
+ *
+ * @example
+ * ```ts
+ * type R = IsFunction<Function> // true
+ * type R = IsFunction<() => void> // true
+ *
+ * type R = IsFunction<never> // false
+ * type R = IsFunction<unknown> // false
+ * type R = IsFunction<number> // false
+ *
+ * type R = IsFunction<Function | number> // boolean
+ * type R = IsFunction<(() => string) | number> // boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is `Function` or function signature, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsFunction<Function, { selection: 'filter' }> // Function
+ * type R = IsFunction<() => void, { selection: 'filter' }> // () => void
+ *
+ * type R = IsFunction<never, { selection: 'filter' }> // never
+ * type R = IsFunction<unknown, { selection: 'filter' }> // never
+ * type R = IsFunction<Function | number, { selection: 'filter' }> // Function
+ *
+ * type R = IsFunction<(() => string) | number, { selection: 'filter' }> // () => string
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = IsFunction<Function | 1> // boolean
+ * type R = IsFunction<Function | 1, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsFunction<Function, $SelectionBranch> // $Then
+ * type R = IsFunction<string, $SelectionBranch> // $Else
+ * ```
+ */
+export type IsFunction<T, $O extends IsFunction.$Options = {}> = $Select<T, Function, $O>
+
+export namespace IsFunction {
+	export type $Options = $Select.$Options
+	export type $Default = $Select.$Default
+	export type $Branch = $Select.$Branch
+}