type-plus 7.3.1 → 7.4.0

package/ts/nodejs/isNodeError.ts

@@ -1,17 +1,17 @@
 export type SystemErrors = {
-	EACCES: Error & { code: 'EACCES' }
-	EADDRINUSE: Error & { code: 'EADDRINUSE' }
-	ECONNREFUSED: Error
-	ECONNRESET: Error
-	EEXIST: Error
-	EISDIR: Error
-	EMFILE: Error
-	ENOENT: Error & { code: 'ENOENT'; path: string }
-	ENOTDIR: Error
-	ENOTEMPTY: Error
-	ENOTFOUND: Error
-	EPERM: Error
-	EPIPE: Error
+	EACCES: Error & { code: 'EACCES' },
+	EADDRINUSE: Error & { code: 'EADDRINUSE' },
+	ECONNREFUSED: Error,
+	ECONNRESET: Error,
+	EEXIST: Error,
+	EISDIR: Error,
+	EMFILE: Error,
+	ENOENT: Error & { code: 'ENOENT', path: string },
+	ENOTDIR: Error,
+	ENOTEMPTY: Error,
+	ENOTFOUND: Error,
+	EPERM: Error,
+	EPIPE: Error,
 	ETIMEDOUT: Error
 }
 

package/ts/nominal/brand.ts

@@ -17,7 +17,7 @@ export type Brand<B extends string, T = never> = [T] extends [null] | [undefined
  * A branded type of `B` with value of `T`.
  */
 export interface Branded<B extends string, T> {
-	[typeSym]: B
+	[typeSym]: B,
 	[valueSym]: T
 }
 

package/ts/nominal/flavor.ts

@@ -26,7 +26,7 @@ export interface Flavored<F extends string> {
  * A special flavored type for special types.
  */
 export interface FlavoredUnit<F extends string, T> {
-	[typeSym]?: F
+	[typeSym]?: F,
 	[valueSym]: T
 }
 

package/ts/testing/readme.md

@@ -16,4 +16,34 @@ 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`
+
+const t = testType.equal<SomeComplexType, SomeCompositeType>(true)
+type T = typeof t // type resolution
+```
+
+## [testType.inspect](./test_type.ts)
+
+`testType.inspect<T>(fn)`
+
+A quick way to inspect a type.
+
+```ts
+import { testType } from 'type-plus'
+
+testType.inspect<SomeType>(t => {
+  type T = typeof t.type // type resolution
+})
+```
+
+It also provides additional methods and predefined inspections so that you can quickly check how the type behaves in specific cases.
+
+```ts
+import { testType } from 'type-plus'
+
+testType.inspect<SomeType>(t => {
+  t.extends<AnotherType>() // true or false
+  t.union<number>() // SomeType | number`
+  t.intersect<string>() // `SomeType & string`
+  t.extends_boolean // true or false
+})
 ```

package/ts/testing/test_type.ts

@@ -29,13 +29,13 @@ interface TestType {
 	 *
 	 * @return `expected` as `A` for type inspection.
 	 */
-	equal<A, B, C>(expected: IsEqual<A, B> & IsEqual<A, C>): A
+	equal<A, B, C>(expected: IsEqual<A, B> & IsEqual<A, C>): A,
 	/**
 	 * Check if type `A` is equal to type `B`.
 	 *
 	 * @return `expected` as `A` for type inspection.
 	 */
-	equal<A, B>(expected: IsEqual<A, B>): A
+	equal<A, B>(expected: IsEqual<A, B>): A,
 	/**
 	 * Check if `A` can assign to `B`.
 	 *
@@ -57,7 +57,7 @@ interface TestType {
 	 *
 	 * @return `expected` as `A` for type inspection.
 	 */
-	canAssign<A, B>(expected: CanAssign<A, B>): A
+	canAssign<A, B>(expected: CanAssign<A, B>): A,
 	/**
 	 * Check if `A` can fully assign to `B`.
 	 *
@@ -72,91 +72,91 @@ interface TestType {
 	 *
 	 * @return `expected` as `A` for type inspection.
 	 */
-	strictCanAssign<A, B>(expected: StrictCanAssign<A, B>): A
+	strictCanAssign<A, B>(expected: StrictCanAssign<A, B>): A,
 	/**
 	 * Check if type `T` is exactly `any`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	any<T>(expected: IsAny<T>): T
+	any<T>(expected: IsAny<T>): T,
 	/**
 	 * Check if type `T` is exactly `array`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	array<T>(expected: IsArray<T>): T
+	array<T>(expected: IsArray<T>): T,
 	/**
 	 * Check if type `T` is exactly `bigint`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	strictBigint<T>(expected: IsStrictBigint<T>): T
+	strictBigint<T>(expected: IsStrictBigint<T>): T,
 	/**
 	 * Check if type `T` is `bigint` or bigint literals.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	bigint<T>(expected: IsBigint<T>): T
+	bigint<T>(expected: IsBigint<T>): T,
 	/**
 	 * Check if type `T` is exactly `boolean`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	strictBoolean<T>(expected: IsStrictBoolean<T>): T
+	strictBoolean<T>(expected: IsStrictBoolean<T>): T,
 	/**
 	 * Check if type `T` is `boolean` and boolean literals.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	boolean<T>(expected: IsBoolean<T>): T
+	boolean<T>(expected: IsBoolean<T>): T,
 	/**
 	 * Check if type `T` is exactly `true`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	true<T>(expected: IsTrue<T>): T
+	true<T>(expected: IsTrue<T>): T,
 	/**
 	 * Check if type `T` is exactly `false`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	false<T>(expected: IsFalse<T>): T
+	false<T>(expected: IsFalse<T>): T,
 	/**
 	 * Check if type `T` is exactly `boolean`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	strictFunction<T>(expected: IsStrictFunction<T>): T
+	strictFunction<T>(expected: IsStrictFunction<T>): T,
 	/**
 	 * Check if type `T` is `boolean` and boolean literals.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	function<T>(expected: IsFunction<T>): T
+	function<T>(expected: IsFunction<T>): T,
 	/**
 	 * Check if type `T` is exactly `never`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	never<T>(expected: IsNever<T>): T
+	never<T>(expected: IsNever<T>): T,
 	/**
 	 * Check if type `T` is exactly `null`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	null<T>(expected: IsNull<T>): T
+	null<T>(expected: IsNull<T>): T,
 	/**
 	 * Check if type `T` is exactly `number`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	strictNumber<T>(expected: IsStrictNumber<T>): T
+	strictNumber<T>(expected: IsStrictNumber<T>): T,
 	/**
 	 * Check if type `T` is `number` or number literals.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	number<T>(expected: IsNumber<T>): T
+	number<T>(expected: IsNumber<T>): T,
 	/**
 	 * Check if type `T` is `object`.
 	 *
@@ -164,50 +164,50 @@ interface TestType {
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	object<T>(expected: IsObject<T>): T
+	object<T>(expected: IsObject<T>): T,
 	/**
 	 * Check if type `T` is exactly `string`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	strictString<T>(expected: IsStrictString<T>): T
+	strictString<T>(expected: IsStrictString<T>): T,
 	/**
 	 * Check if type `T` is `string` or string literals.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	string<T>(expected: IsString<T>): T
+	string<T>(expected: IsString<T>): T,
 	/**
 	 * Check if type `T` is a `symbol`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	symbol<T>(expected: IsSymbol<T>): T
+	symbol<T>(expected: IsSymbol<T>): T,
 	/**
 	 * Check if type `T` is a *tuple*.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	tuple<T>(expected: IsTuple<T>): T
+	tuple<T>(expected: IsTuple<T>): T,
 	/**
 	 * Check if type `T` is exactly `undefined`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	undefined<T>(expected: IsUndefined<T>): T
+	undefined<T>(expected: IsUndefined<T>): T,
 	// hasUndefined<T>(expected: CanAssign<T, undefined>): T
 	/**
 	 * Check if type `T` is exactly `unknown`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	unknown<T>(expected: IsUnknown<T>): T
+	unknown<T>(expected: IsUnknown<T>): T,
 	/**
 	 * Check if type `T` is exactly `void`.
 	 *
 	 * @return `expected` as `T` for type inspection.
 	 */
-	void<T>(expected: IsVoid<T>): T
+	void<T>(expected: IsVoid<T>): T,
 	/**
 	 * A quick way to inspect a type.
 	 *
@@ -248,25 +248,68 @@ export const testType = new Proxy({} as TestType, {
 })
 
 export type InspectedType<T> = {
-	value: T
-	extends_any: T extends any ? true : false
-	extends_unknown: T extends unknown ? true : false
-	extends_void: T extends void ? true : false
-	extends_never: T extends never ? true : false
-	extends_undefined: T extends undefined ? true : false
-	extends_null: T extends null ? true : false
-	extends_boolean: T extends boolean ? true : false
-	extends_true: T extends true ? true : false
-	extends_false: T extends false ? true : false
-	extends_number: T extends number ? true : false
-	extends_1: T extends 1 ? true : false
-	extends_bigint: T extends bigint ? true : false
-	extends_1n: T extends 1n ? true : false
-	extends_string: T extends string ? true : false
-	extends_a: T extends 'a' ? true : false
-	extends_symbol: T extends symbol ? true : false
-	extends_object: T extends object ? true : false
-	extends_function: T extends Function ? true : false
-	extends_array_unknown: T extends unknown[] ? true : false
-	extends_tuple_empty: T extends [] ? true : false
+	type: T,
+	extends<R>(): T extends R ? true : false,
+	extends_any: T extends any ? true : false,
+	extends_unknown: T extends unknown ? true : false,
+	extends_void: T extends void ? true : false,
+	extends_never: T extends never ? true : false,
+	extends_undefined: T extends undefined ? true : false,
+	extends_null: T extends null ? true : false,
+	extends_boolean: T extends boolean ? true : false,
+	extends_true: T extends true ? true : false,
+	extends_false: T extends false ? true : false,
+	extends_number: T extends number ? true : false,
+	extends_1: T extends 1 ? true : false,
+	extends_bigint: T extends bigint ? true : false,
+	extends_1n: T extends 1n ? true : false,
+	extends_string: T extends string ? true : false,
+	extends_a: T extends 'a' ? true : false,
+	extends_symbol: T extends symbol ? true : false,
+	extends_object: T extends object ? true : false,
+	extends_function: T extends Function ? true : false,
+	extends_array_unknown: T extends unknown[] ? true : false,
+	extends_tuple_empty: T extends [] ? true : false,
+	union<R>(): T | R,
+	union_any: T | any,
+	union_unknown: T | unknown,
+	union_void: T | void,
+	union_never: T | never,
+	union_undefined: T | undefined,
+	union_null: T | null,
+	union_boolean: T | boolean,
+	union_true: T | true,
+	union_false: T | false,
+	union_number: T | number,
+	union_1: T | 1,
+	union_bigint: T | bigint,
+	union_1n: T | 1n,
+	union_string: T | string,
+	union_a: T | 'a',
+	union_symbol: T | symbol,
+	union_object: T | object,
+	union_function: T | Function,
+	union_array_unknown: T | unknown[],
+	union_tuple_empty: T | [],
+	intersect<R>(): T & R,
+	intersect_any: T & any,
+	intersect_unknown: T & unknown,
+	intersect_void: T & void,
+	intersect_never: T & never,
+	intersect_undefined: T & undefined,
+	intersect_null: T & null,
+	intersect_boolean: T & boolean,
+	intersect_true: T & true,
+	intersect_false: T & false,
+	intersect_number: T & number,
+	intersect_1: T & 1,
+	intersect_bigint: T & bigint,
+	intersect_1n: T & 1n,
+	intersect_string: T & string,
+	intersect_a: T & 'a',
+	intersect_symbol: T & symbol,
+	intersect_object: T & object,
+	intersect_function: T & Function,
+	intersect_array_unknown: T & unknown[],
+	intersect_tuple_empty: T & []
 }

package/ts/tuple/common_prop_keys.ts

@@ -0,0 +1,55 @@
+import type { NotNeverType } from '../never/never_type.js'
+import type { KeyTypes } from '../object/KeyTypes.js'
+import type { Tail } from './tail.js'
+
+/**
+ * ⚗️ *transform*
+ *
+ * Gets the common property keys of the elements in tuple `T`.
+ *
+ * ```ts
+ * import { CommonPropKeys } from 'type-plus'
+ *
+ * type R = CommonPropKeys<[{ a: number }, { b: number }]> // never
+ * type R = CommonPropKeys<[{ a: number, c: 1 }, { b: number, c: 2 }]> // 'c'
+ * ```
+ */
+export type CommonPropKeys<
+	T extends Record<KeyTypes, unknown>[],
+	Cases extends {
+		array?: unknown,
+		no_common_keys?: unknown
+	} = {
+		array: T extends Array<infer R extends Record<KeyTypes, unknown>> ? keyof R : never,
+		no_common_keys: never
+	}
+> = number extends T['length']
+	? Cases['array']
+	: (
+		T['length'] extends 0
+		? Cases['no_common_keys']
+		: (
+			T['length'] extends 1
+			? keyof T[0]
+			: (
+				T['length'] extends 2
+				? (
+					keyof T[0] & keyof T[1] extends infer R
+					? NotNeverType<R, R, Cases['no_common_keys']>
+					: never
+				)
+				: (
+					keyof T[0] & keyof T[1] & CommonPropKeys<Tail<Tail<T>>> extends infer R
+					? NotNeverType<R, R, Cases['no_common_keys']>
+					: never
+				)
+			)
+		)
+	)
+
+/**
+ * Gets the common property keys of the elements in `A`.
+ *
+ * @deprecated Please use `CommonPropKeys` instead.
+ */
+export type CommonKeys<A extends Record<KeyTypes, any>[]> = CommonPropKeys<A>

package/ts/tuple/create_tuple.ts

@@ -28,15 +28,15 @@ export type ToTuple<R extends any[], S extends number[], X = any> = S['length']
 type DigitToTuple<T = 1> = {
 	[k in number]: any[]
 } & {
-	0: []
-	1: [T]
-	2: [T, T]
-	3: [T, T, T]
-	4: [T, T, T, T]
-	5: [T, T, T, T, T]
-	6: [T, T, T, T, T, T]
-	7: [T, T, T, T, T, T, T]
-	8: [T, T, T, T, T, T, T, T]
+	0: [],
+	1: [T],
+	2: [T, T],
+	3: [T, T, T],
+	4: [T, T, T, T],
+	5: [T, T, T, T, T],
+	6: [T, T, T, T, T, T],
+	7: [T, T, T, T, T, T, T],
+	8: [T, T, T, T, T, T, T, T],
 	9: [T, T, T, T, T, T, T, T, T]
 }
 type Multi10<C extends any[]> = [...C, ...C, ...C, ...C, ...C, ...C, ...C, ...C, ...C, ...C]

package/ts/tuple/drop.ts

@@ -0,0 +1,124 @@
+import type { IsEqual } from '../equal/equal.js'
+import type { NonNull, NonUndefined } from '../utils/index.js'
+
+/**
+ * Drops the first entry in the tuple `T`.
+ *
+ * If the type is an array, the same array will be returned.
+ *
+ * ⚗️ *transform*
+ *
+ * @example
+ * ```ts
+ * type R = DropFirst<[1, 2, 3]> // [2, 3]
+ * type R = DropFirst<[string]> // []
+ * type R = DropFirst<[]> // []
+ * type R = DropFirst<string[]> // string[]
+ * ```
+ */
+export type DropFirst<T extends unknown[], Cases extends {
+	'array'?: unknown,
+	'empty_tuple'?: unknown,
+} = {
+	'array': T,
+	'empty_tuple': [],
+}> = number extends T['length']
+	? Cases['array']
+	: T['length'] extends 0
+	? Cases['empty_tuple']
+	: T['length'] extends 1
+	? []
+	: T extends [any, ...infer Tail]
+	? Tail
+	: never
+
+/**
+ * Drops the last entry in the tuple `T`.
+ *
+ * If the type is an array, the same array will be returned.
+ *
+ * ⚗️ *transform*
+ *
+ * @example
+ * ```ts
+ * type R = DropLast<[1, 2, 3]> // [2, 3]
+ * type R = DropLast<[string]> // []
+ * type R = DropLast<[]> // []
+ * type R = DropLast<string[]> // string[]
+ * ```
+ */
+export type DropLast<T extends unknown[], Cases extends {
+	'array'?: unknown,
+	'empty_tuple'?: unknown,
+} = {
+	'array': T,
+	'empty_tuple': [],
+}> = number extends T['length']
+	? Cases['array']
+	: T['length'] extends 0
+	? Cases['empty_tuple']
+	: T['length'] extends 1
+	? []
+	: T extends [...infer Heads, any]
+	? Heads
+	: never
+
+type ExcludeUnionOfEmptyTuple<A> = IsEqual<A, []> extends true ? A : Exclude<A, []>
+
+/**
+ * drops entries matching `Criteria` in array or tuple `A`.
+ *
+ * ⚗️ *transform*
+ *
+ * @example
+ * ```ts
+ * type R = DropMatch<Array<string | undefined>, undefined> // string[]
+ * type R = DropMatch<Array<string>, string> // never[]
+ * type R = DropMatch<Array<1 | 2>, number> // never[]
+ * ```
+ */
+export type DropMatch<A extends Readonly<Array<unknown>>, Criteria> = number extends A['length']
+	? // array
+	A[0] extends Criteria
+	? // criteria matches: DropAll<string[], string>
+	never[]
+	: undefined extends Criteria
+	? null extends Criteria
+	? Array<NonNullable<A[0]>>
+	: Array<NonUndefined<A[0]>>
+	: null extends Criteria
+	? Array<NonNull<A[0]>>
+	: Criteria extends A[0]
+	? Array<Exclude<A[0], Criteria>>
+	: A[0] extends Criteria
+	? A
+	: Array<Exclude<A[0], Criteria>>
+	: DropMatchTuple<A, Criteria>
+
+type DropMatchTuple<A extends Readonly<Array<any>>, Criteria> = A['length'] extends 0
+	? // empty tuple
+	A
+	: A extends readonly [infer Head, ...infer Tail]
+	? Tail['length'] extends 0
+	? // single element tuple
+	undefined extends Criteria
+	? ExcludeUnionOfEmptyTuple<Head extends Criteria ? [] : [Head]>
+	: ExcludeUnionOfEmptyTuple<Head extends Criteria ? [] : [Head]>
+	: // multiple elements
+	Exclude<Head, Criteria> extends never
+	? DropMatch<Tail, Criteria>
+	: [Exclude<Head, Criteria>, ...DropMatch<Tail, Criteria>]
+	: never[]
+
+export type DropNull<A extends Array<any>> = DropMatch<A, null>
+export type DropNullable<A extends Array<any>> = DropMatch<A, null | undefined>
+export type DropUndefined<A extends Array<any>> = DropMatch<A, undefined>
+
+/**
+ * drop a particular value from an array.
+ *
+ * 💀 *deprecated* the type does not sufficiently cover the use cases.
+ */
+export function drop<A extends Readonly<unknown[]>, const C> (array: A, value: C): DropMatch < A, C > {
+	return array.filter(v => v !== value) as DropMatch<A, C>
+}