type-plus 7.6.2 → 8.0.0-beta.2

package/src/string/string_plus.ts

@@ -0,0 +1,34 @@
+import type { StringIncludes, StringSplit } from './string.js'
+
+export namespace StringPlus {
+	/**
+	 * Check if `Subject` includes `Search`.
+	 * If either of them is not a string, returns `Else`.
+	 *
+	 * ```ts
+	 * type R = StringPlus.Includes<'abc', 'a'> // true
+	 *
+	 * type R = StringPlus.Includes<'abc', 'd'> // false
+	 * ```
+	 */
+	export type Includes<
+		Subject extends string,
+		Search extends string,
+		Then = true,
+		Else = false
+	> = StringIncludes<Subject, Search, Then, Else>
+
+	/**
+	 * Split a string into substrings using the specified separator,
+	 * and return them as an array.
+	 *
+	 * ```ts
+	 * type R = StringPlus.Split<'abc', ''> // ['a', 'b', 'c']
+	 * type R = StringPlus.Split<'abc', 'a'> // ['', 'bc']
+	 * type R = StringPlus.Split<'abc', 'b'> // ['a', 'c']
+	 * type R = StringPlus.Split<'abc', 'c'> // ['ab', '']
+	 * ```
+	 */
+	export type Split<Subject extends string, Seperator extends string> = StringSplit<Subject, Seperator>
+
+}

package/src/symbol/is_not_symbol.ts

@@ -0,0 +1,78 @@
+import type { NotAssignable } from '../predicates/not_assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Then } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is not `symbol`.
+ *
+ * ```ts
+ * type R = IsNotSymbol<symbol> // false
+ *
+ * type R = IsNotSymbol<never> // true
+ * type R = IsNotSymbol<unknown> // true
+ * type R = IsNotSymbol<string | boolean> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not `symbol`, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotSymbol<symbol, { selection: 'filter' }> // never
+ *
+ * type R = IsNotSymbol<never, { selection: 'filter' }> // never
+ * type R = IsNotSymbol<unknown, { selection: 'filter' }> // unknown
+ * type R = IsNotSymbol<symbol | string, { selection: 'filter' }> // string
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Disable distribution of union types.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotSymbol<symbol | 1> // boolean
+ * type R = IsNotSymbol<symbol | 1, { distributive: false }> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotSymbol<string, $SelectionBranch> // $Then
+ * type R = IsNotSymbol<symbol, $SelectionBranch> // $Else
+ * ```
+ */
+export type IsNotSymbol<T, $O extends IsNotSymbol.$Options = {}> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Then]>,
+			$else: IsNotSymbol.$<T, $O>
+		}
+	>
+>
+
+export namespace IsNotSymbol {
+	export type $Options = $Equality.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is `null`.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> = NotAssignable.$<T, symbol, $O>
+
+	export type $UtilOptions = NotAssignable.$UtilOptions
+}

package/src/symbol/is_symbol.ts

@@ -0,0 +1,80 @@
+import type { Assignable } from '../predicates/assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is `symbol`.
+ *
+ * @example
+ * ```ts
+ * type R = IsSymbol<symbol> // true
+ *
+ * type R = IsSymbol<never> // false
+ * type R = IsSymbol<unknown> // false
+ * type R = IsSymbol<symbol | number> // boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is `symbol`, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsSymbol<symbol, { selection: 'filter' }> // symbol
+ *
+ * type R = IsSymbol<never, { selection: 'filter' }> // never
+ * type R = IsSymbol<unknown, { selection: 'filter' }> // never
+ * type R = IsSymbol<string | boolean, { selection: 'filter' }> // never
+ *
+ * type R = IsSymbol<symbol | null> // symbol
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = IsSymbol<symbol | 1> // boolean
+ * type R = IsSymbol<symbol | 1, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsSymbol<symbol, $SelectionBranch> // $Then
+ * type R = IsSymbol<string, $SelectionBranch> // $Else
+ * ```
+ */
+export type IsSymbol<T, $O extends IsSymbol.$Options = {}> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Else]>,
+			$else: IsSymbol.$<T, $O>
+		}
+	>
+>
+
+export namespace IsSymbol {
+	export type $Options = $Equality.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is `symbol`.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> = Assignable.$<T, symbol, $O>
+
+	export type $UtilOptions = Assignable.$UtilOptions
+}

package/src/testing/stub.ts

@@ -0,0 +1,81 @@
+import { requiredDeep } from 'unpartial'
+
+import type { AnyFunction } from '../function/any_function.js'
+import type { RecursivePartial } from '../object/recursive_partial.js'
+import type { NoInfer } from '../type/no_infer.js'
+
+/**
+ * stub a value.
+ *
+ * If the value is a function, it will be passed through as-is.
+ *
+ * 🦴 `utilities`
+ */
+export function stub<T extends AnyFunction>(stub: T): T
+export function stub<T>(stub: RecursivePartial<NoInfer<T>>): T
+export function stub<T>(stub: unknown): T {
+	return stub as T
+}
+
+/**
+ * builds a stub function
+ */
+function build<T>(
+	init: RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)
+): (stub?: RecursivePartial<T>) => T
+function build<T>(init: RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)) {
+	return builder(init).create()
+}
+
+/**
+ * Create a builder for a stub function of type T.
+ *
+ * The builder contains two methods:
+ *
+ * `.with()`: adds additional handler or partial stub.
+ * `.create()`: creates the final stub function.
+ *
+ * @example
+ * ```ts
+ * const b = stub.builder<{ a: number; b: string }>({ a: 1 }).with({ b: 'b' }).create()
+ * b({ a: 2 }) // { a: 2, b: 'b' }
+ * ```
+ */
+function builder<T>(init: RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)) {
+	return builderInternal([init])
+}
+
+function builderInternal<T>(
+	initializers: Array<RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)>
+) {
+	const builder = {
+		/**
+		 * Adds an init object or handler to the builder.
+		 *
+		 * If `init` is an object, it will be merged with the stub object.
+		 * If `init` is a function, it will be called with the stub object.
+		 *
+		 * @return {Builder<T>} The builder instance.
+		 */
+		with(init: RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)) {
+			return builderInternal([...initializers, init])
+		},
+		/**
+		 * Creates the resulting stub function.
+		 */
+
+		create() {
+			return (stub?: RecursivePartial<T>) => {
+				return initializers.reduce((acc, init) => {
+					if (typeof init === 'function') {
+						return init(acc)
+					}
+					return requiredDeep<RecursivePartial<T>>(init, acc)
+				}, stub) as T
+			}
+		}
+	}
+	return builder
+}
+stub.build = build
+stub.builder = builder

package/src/testing/test_type.ts

@@ -0,0 +1,313 @@
+import type { IsAny } from '../any/is_any.js'
+import type { IsArray } from '../array/is_array.js'
+import type { IsBigint } from '../bigint/is_bigint.js'
+import type { IsBoolean } from '../boolean/is_boolean.js'
+import type { IsFalse } from '../boolean/is_false.js'
+import type { IsTrue } from '../boolean/is_true.js'
+import type { IsEqual } from '../equal/equal.js'
+import type { IsFunction } from '../function/is_function.js'
+import type { IsStrictFunction } from '../function/is_strict_function.js'
+import type { IsNever } from '../never/is_never.js'
+import type { IsNull } from '../null/is_null.js'
+import type { IsNumber } from '../number/is_number.js'
+import type { IsObject } from '../object/is_object.js'
+import type { Assignable } from '../predicates/assignable.js'
+import type { IsString } from '../string/is_string.js'
+import type { IsSymbol } from '../symbol/is_symbol.js'
+import type { IsTuple } from '../tuple/is_tuple.js'
+import type { IsUndefined } from '../undefined/is_undefined.js'
+import type { IsUnknown } from '../unknown/is_unknown.js'
+import type { IsVoid } from '../void/is_void.js'
+
+export namespace testType {
+	export interface TestType {
+		/**
+		 * Check if type `A` is equal to type `B` and `C`.
+		 *
+		 * @return `expected` as `A` for type inspection.
+		 */
+		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,
+		/**
+		 * Check if `A` can assign to `B`.
+		 *
+		 * If `A` is a union,
+		 * the check is distributive.
+		 *
+		 * Meaning the result can be `boolean`,
+		 * meaning both `true` and `false` will pass.
+		 *
+		 * If you want to avoid the distributivity,
+		 * use `testType.strictCanAssign()` instead.
+		 *
+		 * @example
+		 * ```ts
+		 * testType.canAssign<123, number> // true
+		 *
+		 * testType.canAssign<number | string, number> // boolean
+		 * ```
+		 *
+		 * @return `expected` as `A` for type inspection.
+		 */
+		canAssign<A, B>(expected: Assignable<A, B>): A,
+		/**
+		 * Check if `A` can fully assign to `B`.
+		 *
+		 * This checks all branches in an union `A` are assignable to `B`.
+		 *
+		 * @example
+		 * ```ts
+		 * testType.strictCanAssign<number | string, number | string> // true
+		 *
+		 * testType.strictCanAssign<number | string, number> // false
+		 * ```
+		 *
+		 * @return `expected` as `A` for type inspection.
+		 */
+		strictCanAssign<A, B>(expected: Assignable<A, B, { distributive: false }>): A,
+		/**
+		 * Check if type `T` is exactly `any`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		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, { exact: true }>): T,
+		/**
+		 * Check if type `T` is exactly `bigint`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		strictBigint<T>(expected: IsBigint<T, { distributive: false, exact: true }>): T,
+		/**
+		 * Check if type `T` is `bigint` or bigint literals.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		bigint<T>(expected: IsBigint<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is exactly `boolean`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		strictBoolean<T>(expected: IsBoolean<T, { distributive: false, exact: true }>): T,
+		/**
+		 * Check if type `T` is `boolean` and boolean literals.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		boolean<T>(expected: IsBoolean<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is exactly `true`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		true<T>(expected: IsTrue<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is exactly `false`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		false<T>(expected: IsFalse<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is exactly `boolean`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		strictFunction<T>(expected: IsStrictFunction<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is `boolean` and boolean literals.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		function<T>(expected: IsFunction<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is exactly `never`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		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, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is exactly `number`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		strictNumber<T>(expected: IsNumber<T, { distributive: false, exact: true }>): T,
+		/**
+		 * Check if type `T` is `number` or number literals.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		number<T>(expected: IsNumber<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is `object`.
+		 *
+		 * Note that `Function`, `Array`, and *tuple* are also `object`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		object<T>(expected: IsObject<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is exactly `string`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		strictString<T>(expected: IsString<T, { distributive: false, exact: true }>): T,
+		/**
+		 * Check if type `T` is `string` or string literals.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		string<T>(expected: IsString<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is a `symbol`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		symbol<T>(expected: IsSymbol<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is a *tuple*.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		tuple<T>(expected: IsTuple<T, { distributive: false }>): T,
+		/**
+		 * Check if type `T` is exactly `undefined`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		undefined<T>(expected: IsUndefined<T, { distributive: false }>): 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,
+		/**
+		 * Check if type `T` is exactly `void`.
+		 *
+		 * @return `expected` as `T` for type inspection.
+		 */
+		void<T>(expected: IsVoid<T, { distributive: false }>): T,
+		/**
+		 * A quick way to inspect a type.
+		 *
+		 * The handler receives a `InspectedType` object.
+		 * It contains `value` which is typed to `T`,
+		 * and many other properties to inspect the behavior of `T`.
+		 *
+		 * The handler is not being call,
+		 * it is use to hold the type in value for inspection.
+		 *
+		 * 🧪 *testing*
+		 * 🦴 *utilities*
+		 *
+		 * @example
+		 * ```ts
+		 * testType.inspect<SomeType>(t => {
+		 *   type T = typeof t.value // resolve and inspect the type `T`
+		 *   t.extend_boolean // result of `T extends boolean`
+		 * })
+		 * ```
+		 *
+		 * After trying out the type, remove the line.
+		 */
+		inspect<T>(handler: (t: InspectedType<T>) => unknown): T
+	}
+
+	export type InspectedType<T> = {
+		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 & []
+	}
+}
+
+/**
+ * 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 = new Proxy({} as testType.TestType, {
+	get(_target, _prop, _receiver) {
+		return (expected: unknown) => expected
+	}
+})

package/src/tuple/common_prop_keys.ts

@@ -0,0 +1,41 @@
+import type { CommonPropKeys as ArrayCommonPropKeys } from '../array/array_plus.common_prop_keys.js'
+import type { KeyTypes } from '../object/KeyTypes.js'
+import type { CommonPropKeys as TupleCommonPropKeys } from './tuple_plus.common_prop_keys.js'
+
+/**
+ * ⚗️ *transform*
+ * 🔢 *customization*
+ *
+ * Gets the common property keys of the elements in tuple or array `T`.
+ *
+ * @example
+ * ```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'
+ * ```
+ *
+ * @typeParam Options['$never'] Return type when `T` is `never`.
+ * Default to `never`.
+ */
+export type CommonPropKeys<
+	T extends Record<KeyTypes, unknown>[],
+	Options extends CommonPropKeys.Options = CommonPropKeys.DefaultOptions
+> = number extends T['length'] ? ArrayCommonPropKeys<T> : TupleCommonPropKeys<T, Options>
+
+
+export namespace CommonPropKeys {
+	export interface Options extends TupleCommonPropKeys.Options {
+	}
+
+	export interface DefaultOptions extends TupleCommonPropKeys.DefaultOptions {
+	}
+}
+
+/**
+ * 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/src/tuple/create_tuple.ts

@@ -0,0 +1,42 @@
+import type { DigitArray } from '../math/numeric_struct.js'
+import type { IsInteger } from '../numeric/is_integer.js'
+import type { IsPositive } from '../numeric/is_positive.js'
+
+/**
+ * Creates `Tuple<T>` with `L` number of elements.
+ * @note Other cool implementations by @lazytype, @jcalz:
+ * @see https://github.com/microsoft/TypeScript/issues/26223#issuecomment-674514787
+ * @see https://github.com/microsoft/TypeScript/issues/47874#issuecomment-1039157322
+ */
+export type CreateTuple<L extends number, T = unknown, Fail = never> = number extends L
+	? T[]
+	: IsPositive<L> extends true
+	? IsInteger<L> extends true
+		? ToTuple<[], DigitArray.FromString<`${L}`>, T>
+		: Fail
+	: Fail
+export type ToTuple<R extends any[], S extends number[], X = any> = S['length'] extends 0
+	? R
+	: S['length'] extends 1
+	? [...R, ...DigitToTuple<X>[S[0]]]
+	: S extends [any, ...infer T]
+	? T extends any[]
+		? ToTuple<Multi10<[...R, ...DigitToTuple<X>[S[0]]]>, T>
+		: never
+	: never
+
+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],
+	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]