type-plus 6.3.0 → 6.4.0

package/ts/object/object_type.ts

@@ -0,0 +1,65 @@
+import { IsAnyOrNever } from '../any/any_or_never.js'
+
+/**
+ * Check if `T` is an `object`.
+ *
+ * ```ts
+ * import { type ObjectType } from 'type-plus'
+ *
+ * type R = ObjectType<{}> // {}
+ * type R = ObjectType<{ a: 1 }> // { a: 1 }
+ * type R = ObjectType<Function> // Function
+ *
+ * type R = ObjectType<number> // never
+ * ```
+ */
+export type ObjectType<T, Then = T, Else = never> = IsAnyOrNever<T, Else, [T] extends [object] ? Then : Else>
+
+/**
+ * Is `T` an `object`.
+ *
+ * Note that `Function` is also an `object`.
+ *
+ * ```ts
+ * import { type IsObject } from 'type-plus'
+ *
+ * type R = IsObject<{}> // true
+ * type R = IsObject<{ a: 1 }> // true
+ * type R = IsObject<Function> // true
+ *
+ * type R = IsObject<number> // false
+ * ```
+ */
+export type IsObject<T, Then = true, Else = false> = ObjectType<T, Then, Else>
+
+/**
+ * Check if `T` is not an `object`.
+ *
+ * ```ts
+ * import { type NotObjectType } from 'type-plus'
+ *
+ * type R = NotObjectType<{}> // never
+ * type R = NotObjectType<{ a: 1 }> // never
+ * type R = NotObjectType<Function> // never
+ *
+ * type R = NotObjectType<number> // number
+ * ```
+ */
+export type NotObjectType<T, Then = T, Else = never> = ObjectType<T, Else, Then>
+
+/**
+ * Is `T` not an `object`.
+ *
+ * Note that `Function` is also an `object`.
+ *
+ * ```ts
+ * import { type IsNotObject } from 'type-plus'
+ *
+ * type R = IsNotObject<{}> // false
+ * type R = IsNotObject<{ a: 1 }> // false
+ * type R = IsNotObject<Function> // false
+ *
+ * type R = IsNotObject<number> // true
+ * ```
+ */
+export type IsNotObject<T, Then = true, Else = false> = ObjectType<T, Else, Then>

package/ts/object/omit.ts

@@ -1,4 +1,4 @@
-import type { UnionKeys } from '../UnionKeys.js'
+import type { UnionKeys } from '../union_keys.js'
 import type { AnyRecord } from './AnyRecord.js'
 import type { Pick } from './pick.js'
 import { record } from './record.js'

package/ts/object/pick.ts

@@ -1,4 +1,4 @@
-import type { UnionKeys } from '../UnionKeys.js'
+import type { UnionKeys } from '../union_keys.js'
 import type { AnyRecord } from './AnyRecord.js'
 import { record } from './record.js'
 import { reduceByKey } from './reduceKey.js'

package/ts/object/properties.ts

@@ -0,0 +1,4 @@
+/**
+ * Gets the properties of an object type.
+ */
+export type Properties<T> = { [k in keyof T]: T[k] } // & {}

package/ts/object/readme.md

@@ -0,0 +1,28 @@
+# object
+
+## Type Checking
+
+The `ObjectType<T>` and friends are used to check if a type is `object` or object types.
+
+Note that `Function` are also considered `object` in TypeScript.
+
+```ts
+import type { ObjectType } from 'type-plus'
+
+type R = ObjectType<object> // object
+type R = ObjectType<{}> // {}
+type R = ObjectType<{ a: number }> // { a: number }
+
+type R = ObjectType<1> // never
+```
+
+- [`ObjectType<T, Then = T, Else = never>`](object_type.ts#L16): check if `T` is `object`.
+- [`IsObject<T, Then = true, Else = false`](object_type.ts#L33): is `T` `object`.
+- [`NotObjectType<T, Then = T, Else = never>`](object_type.ts#L48): check if `T` is not `object`.
+- [`IsNotObject<T, Then = true, Else = false>`](object_type.ts#L65): is `T` not `object`.
+
+## References
+
+- [Handbook]
+
+[handbook]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#object-types

package/ts/predicates/index.ts

@@ -1,5 +1,4 @@
 export * from './CanAssign.js'
-export type { Equal, IsEqual, IsNotEqual, NotEqual } from './Equal.js'
 export type { Extendable, IsExtend, IsNotExtend, NotExtendable } from './Extends.js'
 export type { If } from './If.js'
 export type { IsEmptyObject } from './IsEmptyObject.js'
@@ -11,5 +10,3 @@ export type IsLiteral<T extends number | string, Then = true, Else = false> = nu
 	: string extends T
 	? Else
 	: Then
-
-export type IsBoolean<T, Then = true, Else = false> = boolean extends T ? Then : Else

package/ts/predicates/isType.ts

@@ -1,4 +1,4 @@
-import type { Equal } from './Equal.js'
+import type { Equal } from '../equal/equal.js'
 
 /**
  * Is the subject of type T
@@ -15,6 +15,7 @@ export function isType(subject: unknown, validator?: (s: unknown) => unknown) {
 isType.t = function <T extends true>(subject?: T) {
 	return subject === undefined || subject === true
 }
+
 isType.f = function <T extends false>(subject?: T) {
 	return subject === undefined || subject === false
 }
@@ -37,6 +38,7 @@ 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 `type.equal()` instead
  */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
 isType.equal = function <C extends Equal<A, B>, A, B>() {}

package/ts/primitive.ts

@@ -0,0 +1,10 @@
+export type PrimitiveTypes =
+	| boolean
+	| number
+	| string
+	| object
+	| symbol
+	| bigint
+	| Function
+	| undefined
+	| null

package/ts/string/readme.md

@@ -0,0 +1,43 @@
+# string
+
+## Type Checking
+
+The `StringType<T>` and friends are used to check if a type is `string` or string literals.
+
+```ts
+import type { StringType } from 'type-plus'
+
+type R = StringType<string> // string
+type R = StringType<'a'> // 'a'
+
+type R = StringType<1> // never
+```
+
+- [`StringType<T, Then = T, Else = never>`](string_type.ts#L18): check if `T` is `string`.
+- [`IsString<T, Then = true, Else = false`](string_type.ts#L35): is `T` `string`.
+- [`NotStringType<T, Then = T, Else = never>`](string_type.ts#L52): check if `T` is not `string`.
+- [`IsNotString<T, Then = true, Else = false>`](string_type.ts#L69): is `T` not `string`.
+
+---
+
+The `StrictStringType<T>` and friends are used to check if a type is exactly `string` type.
+
+```ts
+import type { StrictStringType } from 'type-plus'
+
+type R = StrictStringType<string> // string
+
+type R = StrictStringType<'a'> // never
+type R = StrictStringType<1> // never
+```
+
+- [`StrictStringType<T, Then = T, Else = never>`](strict_string_type.ts#L18): check if `T` is exactly `string`.
+- [`IsStrictString<T, Then = true, Else = false`](strict_string_type.ts#L35): is `T` exactly `string`.
+- [`NotStrictStringType<T, Then = T, Else = never>`](strict_string_type.ts#L52): check if `T` is not exactly `string`.
+- [`IsNotStrictString<T, Then = true, Else = false>`](strict_string_type.ts#L69): is `T` not exactly `string`.
+
+## References
+
+- [Handbook]
+
+[handbook]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#the-primitives-string-number-and-boolean

package/ts/string/strict_string_type.ts

@@ -0,0 +1,69 @@
+import type { IsAny } from '../any/any_type.js'
+
+/**
+ * Check if the type `T` is exactly `string`.
+ *
+ * ```
+ * import type { StrictStringType } from 'type-plus'
+ *
+ * type R = StrictStringType<string> // string
+*
+* type R = StrictStringType<''> // never
+* type R = StrictStringType<'1'> // never
+* type R = StrictStringType<string | boolean> // never
+* type R = StrictStringType<never> // never
+* type R = StrictStringType<unknown> // never
+ * ```
+ */
+export type StrictStringType<T, Then = T, Else = never> = IsAny<T, Else, [T, string] extends [string, T] ? Then : Else>
+
+/**
+ * Is the type `T` exactly `string`.
+ *
+ * ```
+ * import type { IsStrictString } from 'type-plus'
+ *
+ * type R = IsStrictString<string> // true
+ *
+ * type R = IsStrictString<''> // false
+ * type R = IsStrictString<'a'> // false
+ * type R = IsStrictString<string | boolean> // false
+ * type R = IsStrictString<never> // false
+ * type R = IsStrictString<unknown> // false
+ * ```
+ */
+export type IsStrictString<T, Then = true, Else = false> = StrictStringType<T, Then, Else>
+
+/**
+ * Check if the type `T` is not exactly `string`.
+ *
+ * ```
+ * import type { NotStrictStringType } from 'type-plus'
+ *
+ * type R = NotStrictStringType<string> // never
+ *
+ * type R = NotStrictStringType<''> // ''
+ * type R = NotStrictStringType<'a'> // 'a'
+ * type R = NotStrictStringType<string | boolean> // string | boolean
+ * type R = NotStrictStringType<never> // never
+ * type R = NotStrictStringType<unknown> // unknown
+ * ```
+ */
+export type NotStrictStringType<T, Then = T, Else = never> = StrictStringType<T, Else, Then>
+
+/**
+ * Is the type `T` not exactly `string`.
+ *
+ * ```
+ * import type { IsNotStrictString } from 'type-plus'
+ *
+ * type R = IsNotStrictString<string> // false
+ *
+ * type R = IsNotStrictString<''> // true
+ * type R = IsNotStrictString<'a'> // true
+ * type R = IsNotStrictString<string | boolean> // true
+ * type R = IsNotStrictString<never> // true
+ * type R = IsNotStrictString<unknown> // true
+ * ```
+ */
+export type IsNotStrictString<T, Then = true, Else = false> = StrictStringType<T, Else, Then>

package/ts/string/string_type.ts

@@ -0,0 +1,69 @@
+import type { IsAnyOrNever } from '../any/any_or_never.js'
+
+/**
+ * Check if the type `T` is `string` or string literals.
+ *
+ * ```
+ * import type { StringType } from 'type-plus'
+ *
+ * type R = StringType<string> // string
+ * type R = StringType<''> // ''
+ * type R = StringType<'1'> // '1'
+ *
+ * type R = StringType<string | boolean> // never
+ * type R = StringType<never> // never
+ * type R = StringType<unknown> // never
+ * ```
+ */
+export type StringType<T, Then = T, Else = never> = IsAnyOrNever<T, Else, [T] extends [string] ? Then : Else>
+
+/**
+ * Is the type `T` `string` or string literals.
+ *
+ * ```
+ * import type { IsString } from 'type-plus'
+ *
+ * type R = IsString<string> // true
+ * type R = IsString<''> // true
+ * type R = IsString<'a'> // true
+ *
+ * type R = IsString<string | boolean> // false
+ * type R = IsString<never> // false
+ * type R = IsString<unknown> // false
+ * ```
+ */
+export type IsString<T, Then = true, Else = false> = StringType<T, Then, Else>
+
+/**
+ * Check if the type `T` is not `string` nor string literals.
+ *
+ * ```
+ * import type { NotStringType } from 'type-plus'
+ *
+ * type R = NotStringType<string> // never
+ * type R = NotStringType<''> // ''
+ * type R = NotStringType<'a'> // 'a'
+ *
+ * type R = NotStringType<string | boolean> // string | boolean
+ * type R = NotStringType<never> // never
+ * type R = NotStringType<unknown> // unknown
+ * ```
+ */
+export type NotStringType<T, Then = T, Else = never> = StringType<T, Else, Then>
+
+/**
+ * Is the type `T` not `string` nor string literals.
+ *
+ * ```
+ * import type { IsNotString } from 'type-plus'
+ *
+ * type R = IsNotString<string> // false
+ * type R = IsNotString<''> // false
+ * type R = IsNotString<'a'> // false
+ *
+ * type R = IsNotString<string | boolean> // true
+ * type R = IsNotString<never> // true
+ * type R = IsNotString<unknown> // true
+ * ```
+ */
+export type IsNotString<T, Then = true, Else = false> = StringType<T, Else, Then>

package/ts/symbol/readme.md

@@ -0,0 +1,34 @@
+# symbol
+
+`symbol` is a primitive type of `Symbol` in TypeScript.
+
+## Type Checking
+
+The `SymbolType<T>` and friends are used to check if a type is a `symbol` or not.
+
+Note that when creating a `Symbol`, the type of the `Symbol` is `unique symbol` and not `symbol`.
+
+There is no way to declare a `unique symbol` type in TypeScript, so `SymbolType` can only check if a type is `symbol` and treat `unique symbol` the same way.
+
+```ts
+import type { SymbolType } from 'type-plus'
+
+type R = SymbolType<symbol> // symbol
+
+const s = Symbol() // unique symbol
+type R = SymbolType<typeof s> // unique symbol
+type.equal<R, symbol>(true) // true
+
+type R = SymbolType<1> // never
+```
+
+- [`SymbolType<T, Then = T, Else = never>`](symbol_type.ts#L16): check if `T` is `symbol`.
+- [`IsSymbol<T, Then = true, Else = false`](symbol_type.ts#L35): is `T` `symbol`.
+- [`NotSymbolType<T, Then = T, Else = never>`](symbol_type.ts#L50): check if `T` is not `symbol`.
+- [`IsNotSymbol<T, Then = true, Else = false>`](symbol_type.ts#L65): is `T` not `symbol`.
+
+## References
+
+- [Handbook]
+
+[handbook]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#symbol

package/ts/symbol/symbol_type.ts

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

package/ts/testing/readme.md

@@ -0,0 +1,19 @@
+# testing
+
+This folder contains utilities for testing.
+
+## `testType`
+
+`testType` is a test utilities for types.
+
+This is designed specifically for testing.
+The return value is the input `expected` parameter asserted as the first type parameter,
+so that the type can be further inspected.
+
+```ts
+import { testType } from 'type-plus'
+
+testType.any<T>(true) // T is `any`
+testType.equal<A, B>(true) // A is equal to B
+testType.never<T>(false) // T is not `never`
+```

package/ts/testing/stub.ts

@@ -1,6 +1,6 @@
 import { requiredDeep } from 'unpartial'
-import type { AnyFunction } from '../function/index.js'
-import type { RecursivePartial } from '../object/index.js'
+import type { AnyFunction } from '../function/any_function.js'
+import type { RecursivePartial } from '../object/RecursivePartial.js'
 
 export namespace stub {
 	export type Param<T> = T extends AnyFunction ? T : RecursivePartial<T>

package/ts/testing/test_type.ts

@@ -0,0 +1,127 @@
+import type { IsAny } from '../any/any_type.js'
+import type { IsBoolean } from '../boolean/boolean_type.js'
+import type { IsFalse } from '../boolean/false_type.js'
+import type { IsStrictBoolean } from '../boolean/strict_boolean_type.js'
+import type { IsTrue } from '../boolean/true_type.js'
+import type { Equal } from '../equal/equal.js'
+import type { IsNever } from '../never/never_type.js'
+import { IsNumber } from '../number/number_type.js'
+import type { IsStrictNumber } from '../number/strict_number_type.js'
+import type { CanAssign } from '../predicates/CanAssign.js'
+import type { IsUnknown } from '../unknown/unknown_type.js'
+import type { IsVoid } from '../void/void_type.js'
+
+/**
+ * Check if type `A` is equal to type `B` and `C`.
+ *
+ * @return `expected` as `A` for type inspection.
+ */
+function equal<A, B, C>(expected: Equal<A, B> & Equal<A, C>): A
+/**
+ * Check if type `A` is equal to type `B`.
+ *
+ * @return `expected` as `A` for type inspection.
+ */
+function equal<A, B>(expected: Equal<A, B>): A
+function equal(expected: unknown) {
+	return expected
+}
+
+/**
+ * Test utilities for types.
+ *
+ * This is designed specifically for testing.
+ * The return value is the input `expected` parameter asserted as the first type parameter,
+ * so that the type can be further inspected.
+ */
+export const testType = {
+	/**
+	 * Check if type `T` is exactly `any`.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	any<T>(expected: IsAny<T>) {
+		return expected as T
+	},
+	/**
+	 * Check if type `T` is exactly `unknown`.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	unknown<T>(expected: IsUnknown<T>) {
+		return expected as T
+	},
+	/**
+	 * Check if type `T` is exactly `never`.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	never<T>(expected: IsNever<T>) {
+		return expected as T
+	},
+	/**
+	 * Check if type `T` is exactly `void`.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	void<T>(expected: IsVoid<T>) {
+		return expected as T
+	},
+	equal,
+	/**
+	 * Check if `A` can assign to `B`.
+	 *
+	 * @return `expected` as `A` for type inspection.
+	 */
+	canAssign<A, B>(expected: CanAssign<A, B>) {
+		return expected as A
+	},
+	/**
+	 * Check if type `T` is exactly `boolean`.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	strictBoolean<T>(expected: IsStrictBoolean<T>) {
+		return expected as T
+	},
+	/**
+	 * Check if type `T` is `boolean` and boolean literals.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	boolean<T>(expected: IsBoolean<T>) {
+		return expected as T
+	},
+	/**
+	 * Check if type `T` is exactly `true`.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	true<T>(expected: IsTrue<T>) {
+		return expected as T
+	},
+	/**
+	 * Check if type `T` is exactly `false`.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	false<T>(expected: IsFalse<T>) {
+		return expected as T
+	},
+	/**
+	 * Check if type `T` is exactly `number`.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	strictNumber<T>(expected: IsStrictNumber<T>) {
+		return expected as T
+	},
+	/**
+	 * Check if type `T` is `number` or number literals.
+	 *
+	 * @return `expected` as `T` for type inspection.
+	 */
+	number<T>(expected: IsNumber<T>) {
+		return expected as T
+	}
+}

package/ts/tuple/readme.md

@@ -1,7 +1,27 @@
-# Tuple
+# unknown
 
-## TupleType
+`unknown` is one of the top type in TypeScript.
+It is a "safer" variant of `any` that you cannot use the value until there are some type guards or type assertions to the value.
 
-> `TupleType<T, Then = T, Else = never>
+## Type Checking
 
-Check if `T` is a tuple, excluding array.
+The `TupleType<T>` and friends are used to check if `T` is a tuple, excluding array.
+
+```ts
+import type { TupleType } from 'type-plus'
+
+type R = TupleType<unknown> // unknown
+
+type R = TupleType<1> // never
+```
+
+- [`TupleType<T, Then = T, Else = never>`](unknown_type.ts#L16): check if `T` is `unknown`.
+- [`IsUnknown<T, Then = true, Else = false`](unknown_type.ts#L35): is `T` `unknown`.
+- [`NotUnknownType<T, Then = T, Else = never>`](unknown_type.ts#L50): check if `T` is not `unknown`.
+- [`IsNotUnknown<T, Then = true, Else = false>`](unknown_type.ts#L65): is `T` not `unknown`.
+
+## References
+
+- [Handbook]
+
+[handbook]: https://www.typescriptlang.org/docs/handbook/2/functions.html#unknown