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

package/src/tuple/tuple_plus.find.ts

@@ -0,0 +1,79 @@
+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,46 @@
+/**
+ * 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,12 @@
+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,23 @@
+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,8 @@
+/**
+ * 🧰 *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,17 @@
+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,26 @@
+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,26 @@
+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,38 @@
+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,8 @@
+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,15 @@
+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,71 @@
+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,89 @@
+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]>
+}