type-plus 7.6.2 → 8.0.0-beta.2

package/src/tuple/tuple_plus.find.ts

@@ -0,0 +1,89 @@
+import type { ElementMatch } from '../array/array_plus.element_match.js'
+import type { $Never } from '../never/never.js'
+import type { TypePlusOptions } from '../utils/options.js'
+import type { IsTuple } from './is_tuple.js'
+
+/**
+ * 🦴 *utilities*
+ * 🔢 *customizable*
+ *
+ * Find the first type in tuple `A` that matches `Criteria`.
+ *
+ * @example
+ * ```ts
+ * type R = TuplePlus.Find<[true, 1, 'x', 3], string> // 'x'
+ * type R = TuplePlus.Find<[true, 1, 'x', 3], number> // 1
+ * type R = TuplePlus.Find<[string, number, 1], 1> // widen: 1 | undefined
+ * type R = TuplePlus.Find<[true, number | string], string> // unionMiss: string | undefined
+ *
+ * type R = TuplePlus.Find<[true, 1, 'x'], 2> // never
+ * ```
+ *
+ * @typeParam Options['widen'] performs widen match.
+ * Default to `true`.
+ * With widen match, a narrowed type will match its widen type.
+ * e.g. matching `1` against `number` yields `1 | undefined`
+ *
+ * The widen behavior can be customized by `Options['$widen']`
+ *
+ * @typeParam Options['$array'] return type when `A` is an array. Default to `not supported` message.
+ *
+ * @typeParam Options['caseEmptyTuple'] return type when `A` is an empty tuple.
+ * Default to `never`.
+ *
+ * @typeParam Options['$never'] return type when `A` is `never`. Default to `never`.
+ *
+ * @typeParam Options['$notMatch'] Return value when `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * @typeParam Options['$widen'] return type when `T` in `A` is a widen type of `Criteria`.
+ * Default to `Criteria | undefined`.
+ * Set it to `never` for a more type-centric behavior
+ *
+ * @typeParam Options['$unionNotMatch'] Return value when a branch of the union `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * If you want the type to behave more like JavaScript,
+ * you can override it to return `undefined`.
+ *
+ * Since it is a union, the result will be joined to the matched branch as union.
+ */
+export type Find<
+	A extends readonly unknown[],
+	Criteria,
+	Options extends Find.Options = Find.DefaultOptions<Criteria>
+> = TypePlusOptions.Merge<Options, Find.DefaultOptions<Criteria>> extends infer O extends Find.Options
+	? IsTuple<
+		A,
+		{
+			$then: A['length'] extends 0
+			? O['$emptyTuple']
+			: Find.Device<A, Criteria, O>,
+			$else: O['$array']
+		}
+	>
+	: never
+export namespace Find {
+	export type Device<
+		A extends readonly unknown[],
+		Criteria,
+		Options extends Find.Options
+	> = A['length'] extends 0
+		? Options['$notMatch']
+		: (A extends readonly [infer Head, ...infer Tail]
+			? ElementMatch<
+				Head,
+				Criteria,
+				TypePlusOptions.Merge<{ $notMatch: Device<Tail, Criteria, Options> }, Options>
+			>
+			: never)
+	export interface Options extends ElementMatch.Options, $Never.$Options {
+		$array?: unknown,
+		$emptyTuple?: unknown,
+	}
+
+	export interface DefaultOptions<Criteria> extends ElementMatch.DefaultOptions<Criteria>, $Never.$Default {
+		$array: 'does not support array. Please use `FindFirst` or `ArrayPlus.Find` instead.',
+		$emptyTuple: never,
+	}
+}

package/src/tuple/tuple_plus.pad_start.ts

@@ -0,0 +1,61 @@
+/**
+ * Pad `T` with `PadWith` at the start of the tuple.
+ *
+ * If the `MaxLength` is less than the length of the tuple,
+ * the `Tuple` will be returned unchanged.
+ *
+ * ⚗️ *transform*
+ *
+ * @example
+ * ```ts
+ * PadStart<[1, 2, 3], 5, 0> // [0, 0, 1, 2, 3]
+ *
+ * // Ignore if MaxLength is less than the length of the tuple
+ * PadStart<[1, 2, 3], 2> // [1, 2, 3]
+ *
+ * // Default to unknown
+ * PadStart<[1, 2, 3], 5> // [unknown, unknown, 1, 2, 3]
+ * ```
+ */
+export type PadStart<
+	Tuple extends readonly unknown[],
+	MaxLength extends number,
+	PadWith = unknown> = PadStart.Device<
+		Tuple,
+		MaxLength,
+		PadWith,
+		[]
+	>
+
+export namespace PadStart {
+	export type Device<
+		Source extends readonly unknown[],
+		MaxLength extends number,
+		PadWith,
+		Result extends unknown[]
+	> =
+		Result['length'] extends MaxLength
+		? (
+			Source extends []
+			? Result
+			: (
+				Source extends readonly [...infer Head, infer Tail]
+				? (
+					[Tail, ...Result] extends infer R extends unknown[]
+					? Device<Head, R['length'], PadWith, R>
+					: never
+				)
+				: never
+			)
+		)
+		: (
+			Source extends []
+			? Device<Source, MaxLength, PadWith, [PadWith, ...Result]>
+			: (
+				Source extends readonly [...infer Head, infer Tail]
+				? Device<Head, MaxLength, PadWith, [Tail, ...Result]>
+				: Source
+			)
+		)
+
+}

package/src/type/no_infer.ts

@@ -0,0 +1,28 @@
+import type { IsNull } from '../null/is_null.js'
+import type { Or } from '../predicates/logical.js'
+import type { $SelectionPredicate } from '../type_plus/branch/$selection.js'
+import type { IsUndefined } from '../undefined/is_undefined.js'
+
+/**
+ * Prevents inference of a type parameter `T`.
+ *
+ * 🦴 *utilities*
+ *
+ * @ajafff original version author
+ * @see https://github.com/microsoft/TypeScript/issues/14829#issuecomment-298425341
+ *
+ * @example
+ * ```ts
+ * function assertEqual<T>(a: T, b: NoInfer<T>) {
+ *   return a === b
+ * }
+ *
+ * assertEqual(123, 324) // OK
+ * assertEqual(123, 'abc') // Error
+ * assertEqual({ x: 1 }, { x: 1, y: 2 }) // Error
+ * ```
+ *
+ * A build-in `NoInfer` is coming soon.
+ * @see https://github.com/microsoft/TypeScript/pull/52968
+ */
+export type NoInfer<T> = Or<IsNull<T>, IsUndefined<T, $SelectionPredicate>, T, T & {}>

package/src/type-guard/is_type.ts

@@ -0,0 +1,48 @@
+import type { IsEqual } from '../equal/equal.js'
+
+/**
+ * Is the subject of type T
+ */
+export function isType<T>(subject: T): subject is T
+/**
+ * Is the subject of type T, satisfying the supplied validator
+ */
+export function isType<T>(subject: unknown, validator: (s: T) => unknown): subject is T
+export function isType(subject: unknown, validator?: (s: unknown) => unknown) {
+	return validator ? !!validator(subject) : true
+}
+
+/**
+ * @deprecated use `isType<T>()` or `testType.true<T>()` instead
+ */
+isType.t = <T extends true>(subject?: T) => subject === undefined || subject === true
+
+/**
+ * @deprecated use `isType<T>()` or `testType.false<T>()` instead
+ */
+isType.f = <T extends false>(subject?: T) => subject === undefined || subject === false
+
+/**
+ * Check is the type `never`
+ * @deprecated use `isType<T>()` or `testType.never<T>()` instead
+ */
+function isNever<_S extends never>(): unknown
+/**
+ * Check is the value is type `never`
+ * @deprecated use `isType<T>()` or `testType.never<T>()` instead
+ */
+function isNever(subject: never): subject is never
+function isNever(_subject?: unknown): _subject is never {
+	return true
+}
+
+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 `testType.equal()` instead
+ */
+isType.equal = <_C extends IsEqual<A, B>, A, B>() => {}

package/src/type_plus/$equality.ts

@@ -0,0 +1,14 @@
+import type { $Any } from '../any/any.js'
+import type { $Never } from '../never/never.js'
+import type { $Unknown } from '../unknown/unknown.js'
+import type { $DistributiveOptions } from './branch/$distributive.js'
+import type { $InputOptions } from './branch/$input_options.js'
+import type { $SelectionBranch } from './branch/$selection.js'
+import type { $SelectionOptions } from './branch/$selection_options.js'
+
+export namespace $Equality {
+	export type $Options = $SelectionOptions &
+		$DistributiveOptions &
+		$InputOptions<$Any | $Unknown | $Never>
+	export type $Branch<$O extends $SelectionOptions = {}> = $SelectionBranch<$O>
+}

package/src/type_plus/$error.ts

@@ -0,0 +1,8 @@
+import type { $Type } from './$type.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * A basic type-level error.
+ */
+export type $Error<M extends string, T = unknown> = M extends any ? $Type<'error', M, T> : never

package/src/type_plus/$infer_error.ts

@@ -0,0 +1,21 @@
+import type { $Type } from './$type.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * An error for unexpected failure of infer type.
+ *
+ * In your type,
+ * you can use `T extends infer U extends V` to specify the type of the inferred type `U`.
+ *
+ * But doing so means you have to do an extra conditional type.
+ *
+ * This type can be use in the else case to indicate unexpected failure to infer the type.
+ *
+ * ```ts
+ * type F<T> = T extends infer U extends V
+ *   ? ...your type logic...
+ *   : InferError<'some message', T>
+ * ```
+ */
+export type $InferError<M extends string, T = unknown> = M extends any ? $Type<'error', `Unable to infer: ${M}`, T> : never

package/src/type_plus/$merge_options.ts

@@ -0,0 +1,9 @@
+/**
+ * 🧰 *type util*
+ *
+ * Merge type options.
+ */
+export type $MergeOptions<
+	$O extends Record<string, any>,
+	$V extends { [k in keyof $O]?: unknown }
+> = { [k in Exclude<keyof $O, keyof $V>]: $O[k] } & $V

package/src/type_plus/$resolve_options.ts

@@ -0,0 +1,16 @@
+import type { $InferError } from './$infer_error.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * Resolve options to the first non `unknown` value.
+ *
+ * The `Values` are assumed to be a tuple with at least one value.
+ * These checks are not performed for performance considerations.
+ */
+export type $ResolveOptions<V extends unknown[]> =
+	V extends [infer T]
+	? T
+	: (V extends [infer T, ...infer U]
+		? ([T, unknown] extends [unknown, T] ? $ResolveOptions<U> : T)
+		: $InferError<'cannot [infer T, ...infer U] from', V>)

package/src/type_plus/$special_type.ts

@@ -0,0 +1,24 @@
+import type { $Any } from '../any/any.js'
+import type { $Never } from '../never/never.js'
+import type { $Unknown } from '../unknown/unknown.js'
+import type { $BranchOptions } from './branch/$branch.js'
+import type { $InputOptions } from './branch/$input_options.js'
+import type { $ResolveBranch } from './branch/$resolve_branch.js'
+import type { $Else, $SelectionBranch, $Then } from './branch/$selection.js'
+import type { $SelectionOptions } from './branch/$selection_options.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * A type utility to handle special types: `any`, `unknown`, and `never`.
+ */
+export type $SpecialType<T, $O extends $SpecialType.$Options> =
+	0 extends 1 & T ? $ResolveBranch<T, $O, [$Any, $Then]> :
+	[T, unknown] extends [unknown, T] ? $ResolveBranch<T, $O, [$Unknown, $Then]> :
+	[T, never] extends [never, T] ? $ResolveBranch<T, $O, [$Never, $Then]> :
+	$ResolveBranch<T, $O, [$Else]>
+
+export namespace $SpecialType {
+	export type $Options = $SelectionOptions & $InputOptions<$Any | $Unknown | $Never>
+	export type $Branch = $SelectionBranch & $BranchOptions<$Any | $Unknown | $Never>
+}

package/src/type_plus/$type.ts

@@ -0,0 +1,10 @@
+/**
+ * 🧰 *type util*
+ *
+ * Special `type-plus` interface to represent unique types with messages.
+ */
+export interface $Type<T extends string, M extends string = '', V = unknown> {
+	type: T,
+	message: M,
+	value: V,
+}

package/src/type_plus/branch/$branch.ts

@@ -0,0 +1,27 @@
+import type { $Type } from '../$type.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * Create a branch type.
+ *
+ * @typeparam P the property name for the branch.
+ *
+ * @example
+ * ```ts
+ * type $Then = $Branch<'$then'>
+ * type $Any = $Branch<'$any'>
+ */
+export type $Branch<P extends `$${string}`> = $Type<'branch', P, P>
+
+/**
+ * 🧰 *type util*
+ *
+ * Define the branch options of the specified branches.
+ *
+ * ```ts
+ * type $YourOptions = $BranchOptions<$Then | $Else> // { $then: $Then, $else: $Else }
+ * ```
+ */
+export type $BranchOptions<$B extends $Branch<any>> =
+	{ [k in $B['value']]: $B extends { value: k } ? $B : never }

package/src/type_plus/branch/$distributive.ts

@@ -0,0 +1,19 @@
+/**
+ * 🧰 *type util*
+ *
+ * Options for to control if the type is distributive.
+ */
+export type $DistributiveOptions = {
+	distributive?: boolean | undefined
+}
+
+/**
+ * 🧰 *type util*
+ *
+ * Default options for `distributive` behavior.
+ *
+ * By default it is `true`.
+ */
+export type $DistributiveDefault = {
+	distributive: true
+}

package/src/type_plus/branch/$exact.ts

@@ -0,0 +1,34 @@
+import type { $ResolveOptions } from '../$resolve_options.js'
+import type { $Branch } from './$branch.js'
+import type { $InputOptions } from './$input_options.js'
+import type { $Else, $Then } from './$selection.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * Branch to handle exact comparison.
+ */
+export type $Exact = $Branch<'$exact'>
+
+export namespace $Exact {
+	/**
+	 * 🧰 *type util*
+	 *
+	 * `$Exact.$Options` enables customizing the behavior of the `$exact` branch.
+	 *
+	 * The `$exact` branch is used to handle when it is an exact comparison.
+	 */
+	export type $Options = {
+		exact?: boolean | undefined
+	}
+
+	export type $Default = {
+		exact: false
+	}
+
+	export type $IsExact<$Opt extends $Options,
+		$O extends $InputOptions<$Then | $Else> = {}
+	> = $ResolveOptions<[$Opt['exact'], $Exact.$Default]> extends true
+		? '$then' extends keyof $O ? $O['$then'] : true
+		: '$else' extends keyof $O ? $O['$else'] : false
+}

package/src/type_plus/branch/$input_options.ts

@@ -0,0 +1,9 @@
+import type { $Branch } from './$branch.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * Define branch input options.
+ */
+export type $InputOptions<$B extends $Branch<any>> =
+	{ [k in $B['value']]?: unknown }

package/src/type_plus/branch/$is_distributive.ts

@@ -0,0 +1,12 @@
+import type { $ResolveOptions } from '../$resolve_options.js'
+import type { $DistributiveDefault, $DistributiveOptions } from './$distributive.js'
+import type { $InputOptions } from './$input_options.js'
+import type { $Else, $Then } from './$selection.js'
+
+export type $IsDistributive<
+	$Options extends $DistributiveOptions,
+	$O extends $InputOptions<$Then | $Else> = {}
+> =
+	$ResolveOptions<[$Options['distributive'], $DistributiveDefault['distributive']]> extends true
+	? '$then' extends keyof $O ? $O['$then'] : true
+	: '$else' extends keyof $O ? $O['$else'] : false

package/src/type_plus/branch/$override.ts

@@ -0,0 +1,22 @@
+import type { $Type } from '../$type.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * A utility type to override the behavior of a branch.
+ *
+ * ```ts
+ * type R = IsString<any, { $any: DoThisInstead }> // DoThisInstead
+ * type R = IsString<any, { $any: $Override<DoThisInstead> }> // use DoThisInstead as the sole branch logic
+ * ```
+ */
+export type $Override<T> = $Type<'override', 'override', T>
+
+export namespace $Override {
+	/**
+	 * 🧰 *type util*
+	 *
+	 * A utility type to unwrap an override.
+	 */
+	export type $Unwrap<T> = T extends $Override<infer U> ? U : T
+}

package/src/type_plus/branch/$resolve_branch.ts

@@ -0,0 +1,81 @@
+import type { $Branch } from './$branch.js'
+import type { $Override } from './$override.js'
+import type { $Else, $Then } from './$selection.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * Resolve option value based on list of branches.
+ * It returns the first branch value that is specified in the option,
+ * otherwise will return the default value.
+ *
+ * Since this is an type utility,
+ * it does not perform extensive validations.
+ * Please check the description of each input below for information.
+ *
+ * @typeparam $O Should be a Record, not any, unknown, or never
+ * @typeparam $B Tuple of branches with at least one entry.
+ * @typeparam $D When specified, resolve the branch in override mode.
+ * If no branch in `$B` is resolved to `$Override<X>`, `$D` will be returned.
+*/
+export type $ResolveBranch<
+	T,
+	$O extends Record<string, any>,
+	$B extends Array<$Branch<any> | unknown>,
+	$D = unknown
+> =
+	[unknown, $D] extends [$D, unknown]
+	? (
+		$B extends [infer B]
+		? $ResolveBranch._Last<T, $O, B>
+		: (
+			$B extends [infer B, ...infer Bs extends Array<$Branch<any> | unknown>]
+			? $ResolveBranch._<$ResolveBranch<T, $O, Bs>, $O, B>
+			: never
+		)
+	)
+	: $ResolveBranch._Override<$D, $O, $B>
+
+export namespace $ResolveBranch {
+	export type _Override<
+		$D,
+		$O extends Record<string, any>,
+		$B extends Array<$Branch<any> | unknown>,
+	> = $B extends [infer B]
+		? _OLast<$D, $O, B>
+		: (
+			$B extends [infer B, ...infer Bs extends Array<$Branch<any> | unknown>]
+			? _OLast<_Override<$D, $O, Bs>, $O, B>
+			: never
+		)
+
+	export type _OLast<
+		$D,
+		$O extends Record<string, any>,
+		$B extends $Branch<any> | unknown,
+	> = $B extends $Branch<any>
+		? (
+			$B['value'] extends keyof $O
+			? ($O[$B['value']] extends infer R extends $Override<any>
+				? ([R, never] extends [never, R] ? $D : R['value'])
+				: $D
+			)
+			: $D
+		)
+		: $D
+
+	export type _<T, $O extends Record<string, any>, $B> =
+		$B extends $Branch<any> ?
+		($B['value'] extends keyof $O ? $Override.$Unwrap<$O[$B['value']]> : T)
+		: T
+	export type _Last<T, $O extends Record<string, any>, $B> =
+		$B extends $Then
+		? ('$then' extends keyof $O
+			? $Override.$Unwrap<$O['$then']>
+			: $O['selection'] extends 'filter' ? T : true)
+		: $B extends $Else
+		? ('$else' extends keyof $O
+			? $Override.$Unwrap<$O['$else']>
+			: $O['selection'] extends 'filter' ? never : false)
+		: _<T, $O, $B>
+}

package/src/type_plus/branch/$select.ts

@@ -0,0 +1,90 @@
+import type { $Any } from '../../any/any.js'
+import type { $Never } from '../../never/never.js'
+import type { $Unknown } from '../../unknown/unknown.js'
+import type { $SpecialType } from '../$special_type.js'
+import type { $DistributiveDefault, $DistributiveOptions } from './$distributive.js'
+import type { $Exact } from './$exact.js'
+import type { $InputOptions } from './$input_options.js'
+import type { $IsDistributive } from './$is_distributive.js'
+import type { $ResolveBranch } from './$resolve_branch.js'
+import type { $Else, $SelectionBranch, $SelectionPredicate, $Then } from './$selection.js'
+import type { $SelectionOptions } from './$selection_options.js'
+
+/**
+ * 🎭 *predicate*
+ * ㊙️ *internal*
+ *
+ * Validate if `T` is `U`.
+ *
+ * @example
+ * ```ts
+ * type R = $Select<undefined, undefined> // true
+ *
+ * type R = $Select<never, undefined> // false
+ * type R = $Select<unknown, undefined> // false
+ * type R = $Select<string | boolean, undefined> // false
+ *
+ * type R = $Select<string | undefined, undefined> // boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is `U`, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = $Select<undefined, undefined, { selection: 'filter' }> // undefined
+ *
+ * type R = $Select<never, undefined, { selection: 'filter' }> // never
+ * type R = $Select<unknown, undefined, { selection: 'filter' }> // never
+ * type R = $Select<string | boolean, undefined, { selection: 'filter' }> // never
+ *
+ * type R = $Select<string | undefined, undefined> // undefined
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = $Select<undefined | 1, undefined> // boolean
+ * type R = $Select<undefined | 1, undefined, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = $Select<undefined, undefined, $SelectionBranch> // $Then
+ * type R = $Select<string, undefined, $SelectionBranch> // $Else
+ * ```
+ */
+export type $Select<
+	T,
+	U,
+	$O extends $Select.$Options = {}
+> = $SpecialType<
+	T,
+	{
+		$any: $ResolveBranch<T, $O, [$Any, $Else]>,
+		$unknown: $ResolveBranch<T, $O, [$Unknown, $Else]>,
+		$never: $ResolveBranch<T, $O, [$Never, $Else]>,
+		$else: $ResolveBranch<T, $O, [$Else], $Select._<T, U, $O>>
+	}
+>
+
+export namespace $Select {
+	export type $Options = $SelectionOptions & $DistributiveOptions & $InputOptions<$Any | $Unknown | $Never> & $Exact.$Options
+	export type $Default = $SelectionPredicate & $DistributiveDefault
+	export type $Branch<$O extends $DistributiveOptions = $DistributiveDefault> = $SelectionBranch & $O
+	export type _<T, U, $O extends $Select.$Options> = $IsDistributive<$O> extends true
+		? _D<T, U, $O>
+		: _N<T, U, $O>
+
+	export type _D<T, U, $O extends $Select.$Options> =
+		T extends U ? $ResolveBranch<T, $O, [$Then]> : $ResolveBranch<T, $O, [$Else]>
+	export type _N<T, U, $O extends $Select.$Options> =
+		[T] extends [U] ? $ResolveBranch<T, $O, [$Then]> : $ResolveBranch<T, $O, [$Else]>
+}