type-plus 7.6.2 → 8.0.0-beta.2

package/src/any/any.ts

@@ -0,0 +1,46 @@
+import type { $Branch } from '../type_plus/branch/$branch.js'
+
+export type $Any = $Branch<'$any'>
+
+export namespace $Any {
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Options for specifically handling the type `any`.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<
+	 *   T,
+	 *   $Options extends YourType.$Options = YourType.$Default
+	 * > = ...
+	 *
+	 * namespace YourType {
+	 *   export type $Options = $AnyOptions
+	 * }
+	 * ```
+	 */
+	export type $Options = { $any?: unknown }
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Branch option for specifically handling the type `any`.
+	 *
+	 * Use this to finely customize the behavior of your type.
+	 *
+	 * ```ts
+	 * type YourType<
+	 *   T,
+	 *   $Options extends YourType.$Options = YourType.$Default
+	 * > = ...
+	 *
+	 * namespace YourType {
+	 *   export type $Options = $Any.$Options
+	 *   export type $Branch = $Any.$Branch
+	 * }
+	 *
+	 * type R = YourType<T, YourType.$Branch> extends $Any ? HandleAny : HandleOthers
+	 * ```
+	 */
+	export type $Branch = { $any: $Any }
+}

package/src/any/is_any.ts

@@ -0,0 +1,59 @@
+import type { $Never } from '../never/never.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $InputOptions } from '../type_plus/branch/$input_options.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $SelectionBranch, $Then } from '../type_plus/branch/$selection.js'
+import type { $SelectionOptions } from '../type_plus/branch/$selection_options.js'
+import type { $Unknown } from '../unknown/unknown.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is `any`.
+ *
+ * @example
+ * ```ts
+ * type R = IsAny<any> // true
+ *
+ * type R = IsAny<never> // false
+ * type R = IsAny<unknown> // false
+ * type R = IsAny<string | boolean> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is `any`.
+ *
+ * @example
+ * ```ts
+ * type R = IsAny<any, { selection: 'filter' }> // any
+ *
+ * type R = IsAny<never, { selection: 'filter' }> // never
+ * type R = IsAny<unknown, { selection: 'filter' }> // never
+ * type R = IsAny<string | boolean, { selection: 'filter' }> // never
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsAny<any, $SelectionBranch> // $Then
+ * type R = IsAny<string, $SelectionBranch> // $Else
+ * ```
+ */
+export type IsAny<
+	T,
+	$O extends IsAny.$Options = {}
+> = $SpecialType<T, {
+	$any: $ResolveBranch<T, $O, [$Then]>,
+	$unknown: $ResolveBranch<T, $O, [$Unknown, $Else]>,
+	$never: $ResolveBranch<T, $O, [$Never, $Else]>,
+	$else: $ResolveBranch<T, $O, [$Else]>
+}>
+
+export namespace IsAny {
+	export type $Options = $SelectionOptions & $InputOptions<$Unknown | $Never>
+	export type $Branch = $SelectionBranch
+}

package/src/any/is_not_any.ts

@@ -0,0 +1,59 @@
+import type { $Never } from '../never/never.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $InputOptions } from '../type_plus/branch/$input_options.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $SelectionBranch, $Then } from '../type_plus/branch/$selection.js'
+import type { $SelectionOptions } from '../type_plus/branch/$selection_options.js'
+import type { $Unknown } from '../unknown/unknown.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is not `any`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotAny<any> // false
+ *
+ * type R = IsNotAny<never> // true
+ * type R = IsNotAny<unknown> // true
+ * type R = IsNotAny<string | boolean> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not `any`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotAny<any, { selection: 'filter' }> // never
+ *
+ * type R = IsNotAny<never, { selection: 'filter' }> // never
+ * type R = IsNotAny<unknown, { selection: 'filter' }> // unknown
+ * type R = IsNotAny<string | boolean, { selection: 'filter' }> // string | boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotAny<any, $SelectionBranch> // $Else
+ * type R = IsNotAny<string, $SelectionBranch> // $Then
+ * ```
+ */
+export type IsNotAny<
+	T,
+	$O extends IsNotAny.$Options = {}
+> = $SpecialType<T, {
+	$any: $ResolveBranch<T, $O, [$Else]>,
+	$unknown: $ResolveBranch<T, $O, [$Unknown, $Then]>,
+	$never: $ResolveBranch<T, $O, [$Never, $Then]>,
+	$else: $ResolveBranch<T, $O, [$Then]>
+}>
+
+export namespace IsNotAny {
+	export type $Options = $SelectionOptions & $InputOptions<$Unknown | $Never>
+	export type $Branch = $SelectionBranch
+}

package/src/any/readme.md

@@ -0,0 +1,104 @@
+# Any
+
+`any` is one of the two top types in TypeScript.
+It is a supertype of all types.
+It is a way to opt-out of type checking and let the values pass through compile-time checks.
+
+## [IsAny](./is_any.ts)
+
+`IsAny<T, $O = { selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is exactly `any`.
+
+```ts
+type R = IsAny<any> // true
+
+type R = IsAny<never> // false
+type R = IsAny<unknown> // false
+type R = IsAny<string | boolean> // false
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is exactly `any`.
+
+```ts
+type R = IsAny<any, { selection: 'filter' }> // any
+
+type R = IsAny<never, { selection: 'filter' }> // never
+type R = IsAny<unknown, { selection: 'filter' }> // never
+type R = IsAny<string | boolean, { selection: 'filter' }> // never
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsAny<any, $SelectionBranch> // $Then
+type R = IsAny<string, $SelectionBranch> // $Else
+```
+
+### [IsNotAny](./is_not_any.ts)
+
+`IsNotAny<T, $O = { selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is not exactly `any`.
+
+```ts
+type R = IsNotAny<any> // false
+
+type R = IsNotAny<never> // true
+type R = IsNotAny<unknown> // true
+type R = IsNotAny<string | boolean> // true
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is not exactly `any`.
+
+```ts
+type R = IsNotAny<any, { selection: 'filter' }> // never
+
+type R = IsNotAny<never, { selection: 'filter' }> // never
+type R = IsNotAny<unknown, { selection: 'filter' }> // unknown
+type R = IsNotAny<string | boolean, { selection: 'filter' }> // string | boolean
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsNotAny<any, $SelectionBranch> // $Else
+type R = IsNotAny<string, $SelectionBranch> // $Then
+```
+
+## Trivia
+
+> Both `any` and `unknown` are top types?
+
+Well, yeah:
+
+```ts
+type A = any extends unknown ? 1 : 2 // 1
+type B = unknown extends any ? 1 : 2 // 1
+```
+
+> Aren't using `any` is bad?
+
+If you use it to simply tell TypeScript to shut up because you are lazy, then yes.
+
+But it is ok to use `any` in many cases, as the type system of TypeScript is not sounded.
+
+There are many cases it is not possible to induce the type correctly.
+
+## References
+
+- [handbook]
+
+[handbook]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any

package/src/array/array.at.ts

@@ -0,0 +1,40 @@
+import type { IsNumber } from '../number/is_number.js'
+import type { IsTuple } from '../tuple/is_tuple.js'
+import type { IndexAt } from './array_plus.index_at.js'
+
+/**
+ * 🦴 *utilities*
+ *
+ * Gets the type of the array or tuple at positive or negative index `N`.
+ *
+ * Like `Array.at()`, this type supports negative numbers.
+ *
+ * @alias ArrayPlus.At
+ * @see https://github.com/microsoft/TypeScript/issues/53345#issuecomment-1477138167
+ *
+ * ```ts
+ * type R = At<[1, 2, 3], 2> // 3
+ * type R = At<[1, 2, 3], -1> // 3
+ * ```
+ */
+export type At<A extends readonly unknown[], N extends number, Fail = never> =
+	IndexAt<
+		A,
+		N,
+		Fail,
+		Fail,
+		Fail
+	> extends infer I
+	? I extends number
+	? IsTuple.$<
+		A,
+		{
+			$then: IsNumber.$<I, {
+				exact: true,
+				$then: A[I] | undefined,
+				$else: A[I]
+			}>,
+			$else: A[I] | undefined
+		}>
+	: Fail
+	: never

package/src/array/array.entries.ts

@@ -0,0 +1,28 @@
+import type { IsTuple } from '../tuple/is_tuple.js'
+/**
+ * Returns an array of key-value pairs for every entry in the array or tuple.
+ *
+ * Note that this is not the same as `Array.entries(A)`,
+ * which returns an iterable interator.
+ *
+ * @example
+ * ```ts
+ * ArrayPlus.Entries<Array<string | number>> // Array<[number, string | number]>
+ * ArrayPlus.Entries<[1, 2, 3]> // [[0, 1], [1, 2], [2, 3]]
+ * ```
+ */
+export type Entries<A extends readonly unknown[]> = IsTuple<
+	A,
+	{
+		$then: Entries.Device<A, []>,
+		$else: A extends Array<infer T> ? Array<[number, T]> : never
+	}
+>
+
+export namespace Entries {
+	export type Device<A extends readonly unknown[], R extends unknown[]> = A['length'] extends 0
+		? R
+		: (A extends readonly [...infer F, infer N]
+			? Device<F, [[F['length'], N], ...R]>
+			: never)
+}

package/src/array/array.find_last.ts

@@ -0,0 +1,31 @@
+import type { IsTuple } from '../tuple/is_tuple.js'
+
+/**
+ * 🦴 *utilities*
+ *
+ * Gets the last type in the array or tuple that matches the `Criteria`.
+ *
+ * If the `Criteria` is not met, it will return `never'.
+ *
+ * For `Array<T>`, it will return `T | undefined` if `T` satisfies `Criteria`.
+ *
+ * @example
+ * ```ts
+ * ArrayPlus.Find<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
+ *
+ * ArrayPlus.Find<[true, 123, 'x', 321], number> // 321
+ * ```
+ */
+export type FindLast<A extends readonly unknown[], Criteria> = IsTuple<
+	A,
+	{
+		$then: A['length'] extends 0
+		? never
+		: (A extends readonly [...infer Heads, infer Last]
+			? (Last extends Criteria
+				? Last
+				: FindLast<Heads, Criteria>)
+			: never),
+		$else: A extends Readonly<Array<infer T>> ? (T extends Criteria ? T | undefined : never) : never
+	}
+>

package/src/array/array.reverse.ts

@@ -0,0 +1,25 @@
+import type { IsReadonly } from './array_plus.is_readonly.js'
+
+/*
+ * Reverses the order of elements in the array or tuple.
+ *
+ * @example
+ * ```ts
+ * Reverse<Array<string | number>> // Array<string | number>
+ *
+ * Reverse<[1, 2, 3]> // [3, 2, 1]
+ * ```
+ *
+ * @param T The array type to reverse.
+ * @returns The reversed array type.
+ */
+export type Reverse<A extends readonly unknown[]> = Reverse._<A> extends infer R
+	? IsReadonly<A> extends true ? Readonly<R> : R
+	: never
+
+export namespace Reverse {
+	export type _<A extends readonly unknown[]> = A extends readonly [infer First, ...infer Rest]
+		? [..._<Rest>, First]
+		: A
+
+}

package/src/array/array.some.ts

@@ -0,0 +1,67 @@
+import type { IsEqual } from '../equal/equal.js'
+import type { CanAssign } from '../index.js'
+import type { Tail } from '../tuple/tail.js'
+import type { UnionOfValues } from './union_of_values.js'
+
+/**
+ * Determines whether the array type `A` contains any elements that satisfies the specified `Criteria` type.
+ *
+ * It operates in `loose` mode by default,
+ * which means literal types satisfies their widened counterparts.
+ *
+ * You can also change it to `strict` mode.
+ *
+ * 🦴 *utilities*
+ *
+ * @example
+ * ```ts
+ * Some<string[], string> // true
+ * Some<['a', boolean], boolean> // true
+ * Some<['a', true], boolean> //true
+ *
+ * Some<['a', true], boolean, 'strict'> // false
+ * ```
+ */
+export type Some<
+	A extends readonly unknown[],
+	Criteria,
+	Mode extends 'strict' | 'loose' = 'loose',
+	Then = true,
+	Else = false
+> = Mode extends 'strict' ? Some.Strict<A, Criteria, Then, Else> : Some.Loose<A, Criteria, Then, Else>
+
+export namespace Some {
+	export type Strict<A extends readonly unknown[], Criteria, Then, Else> = number extends A['length']
+		? StrictArray<A, Criteria, Then, Else>
+		: StrictTuple<A, Criteria, Then, Else>
+
+	export type StrictArray<A extends readonly unknown[], Criteria, Then, Else> = IsEqual<
+		UnionOfValues<A>,
+		Criteria,
+		Then,
+		Else
+	>
+
+	export type StrictTuple<A extends readonly unknown[], Criteria, Then, Else> = A['length'] extends 0
+		? Else
+		: (IsEqual<A[0], Criteria> extends true
+			? Then
+			: StrictTuple<Tail<A>, Criteria, Then, Else>)
+
+	export type Loose<A extends readonly unknown[], Criteria, Then, Else> = number extends A['length']
+		? LooseArray<A, Criteria, Then, Else>
+		: LooseTuple<A, Criteria, Then, Else>
+
+	export type LooseArray<A extends readonly unknown[], Criteria, Then, Else> = CanAssign<
+		UnionOfValues<A>,
+		Criteria,
+		Then,
+		Else
+	>
+
+	export type LooseTuple<A extends readonly unknown[], Criteria, Then, Else> = A['length'] extends 0
+		? Else
+		: (A[0] extends Criteria
+			? Then
+			: LooseTuple<Tail<A>, Criteria, Then, Else>)
+}

package/src/array/array_plus.common_prop_keys.ts

@@ -0,0 +1,38 @@
+import type { IsNever } from '../never/is_never.js'
+import type { $Never } from '../never/never.js'
+import type { KeyTypes } from '../object/KeyTypes.js'
+
+/**
+ * ⚗️ *transform*
+ * 🔢 *customization*
+ *
+ * Gets the common keys of the record types in the array `A`.
+ *
+ * @example
+ * ```ts
+ * import { type ArrayPlus } from 'type-plus'
+ *
+ * type R = ArrayPlus.CommonPropKeys<Array<{ a: 1 }>> // 'a'
+ * type R = ArrayPlus.CommonPropKeys<Array<{ a: 1, b: 1 } | { a: 1, c: 1 }>> // 'a'
+ * ```
+ *
+ * @typeParam Options['$never'] Return type when `T` is `never`.
+ * Default to `never`.
+ */
+export type CommonPropKeys<
+	A extends readonly Record<KeyTypes, unknown>[],
+	Options extends CommonPropKeys.Options = CommonPropKeys.DefaultOptions
+> = IsNever<A,
+	{
+		$then: Options['$never'],
+		$else: A extends Readonly<Array<infer R extends Record<KeyTypes, unknown>>> ? keyof R : never
+	}
+>
+
+export namespace CommonPropKeys {
+	export interface Options extends $Never.$Options {
+	}
+
+	export interface DefaultOptions extends $Never.$Default {
+	}
+}

package/src/array/array_plus.concat.ts

@@ -0,0 +1,15 @@
+/**
+ * 🦴 *utilities
+ * 💀 *deprecated* Will be available only as `ArrayPlus.Concat` in the next version
+ *
+ * Concats two arrays or tuples.
+ *
+ * alias of: `[...A, ...B]`
+ *
+ * @alias ArrayPlus.Concat
+ *
+ * ```ts
+ * type R = Concat<[1], [2, 3]> // [1, 2, 3]
+ * ```
+ */
+export type Concat<A extends Readonly<unknown[]>, B extends Readonly<unknown[]>> = [...A, ...B]

package/src/array/array_plus.drop_match.ts

@@ -0,0 +1,16 @@
+/**
+ * ⚗️ *transform*
+ */
+export type DropMatch<A extends Readonly<Array<unknown>>, Criteria> = A[0] extends Criteria
+	? never[]
+	: (undefined extends Criteria
+		? (null extends Criteria
+			? Array<NonNullable<A[0]>>
+			: Array<Exclude<A[0], undefined>>)
+		: (null extends Criteria
+			? Array<Exclude<A[0], null>>
+			: (Criteria extends A[0]
+				? Array<Exclude<A[0], Criteria>>
+				: (A[0] extends Criteria
+					? A
+					: Array<Exclude<A[0], Criteria>>))))

package/src/array/array_plus.element_match.ts

@@ -0,0 +1,61 @@
+import type { IsNever } from '../never/is_never.js'
+import type { IsUnion } from '../union/union.js'
+import type { TypePlusOptions } from '../utils/options.js'
+
+/**
+ * 🦴 *utilities*
+ * 🔢 *customizable*
+ *
+ * Filter the element `T` in an array or tuple to match `Criteria`.
+ *
+ * @typeParam Options['widen'] Allow using narrow type to match widen type.
+ * e.g. `number, 1` -> `1 | undefined`.
+ * Default to `true`.
+ *
+ * @typeParam Options['$notMatch'] Return value when `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * @typeParam Options['$widen'] Return value when `widen` is true.
+ * Default to `Criteria | undefined`.
+ *
+ * @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.
+ * e.g. `ElementMatch<1 | 2, 1>` -> `1 | undefined`
+ */
+export type ElementMatch<
+	T,
+	Criteria,
+	Options extends ElementMatch.Options = ElementMatch.DefaultOptions<Criteria>
+> = [T] extends [Criteria]
+	? T
+	: (TypePlusOptions.Merge<Options, ElementMatch.DefaultOptions<Criteria>> extends infer C extends Record<keyof ElementMatch.Options, unknown>
+		? ((T extends Criteria
+			? T
+			: (C['widen'] extends true
+				? (Criteria extends T
+					? C['$widen']
+					: C['$notMatch'])
+				: C['$notMatch'])) extends infer R
+			? IsUnion<T, IsNever<R, { $then: R, $else: R | C['$unionNotMatch'] }>, R>
+			: C['$notMatch'])
+		: never)
+
+export namespace ElementMatch {
+	export interface Options {
+		widen?: boolean | undefined,
+		$notMatch?: unknown,
+		$widen?: unknown,
+		$unionNotMatch?: unknown
+	}
+	export interface DefaultOptions<Criteria> {
+		widen: true,
+		$notMatch: never,
+		$widen: Criteria | undefined,
+		$unionNotMatch: never
+	}
+}

package/src/array/array_plus.filter.ts

@@ -0,0 +1,52 @@
+// import type { IsEqual } from '../equal/equal.js'
+
+// /**
+//  * Filters an array or tuple based on criteria
+//  */
+// export type Filter<A extends readonly unknown[], Criteria = true> = Filter._<A, Criteria, []>
+
+import type { IsEqual } from '../equal/equal.js'
+import type { IsNever } from '../never/is_never.js'
+import type { $Never } from '../never/never.js'
+import type { TypePlusOptions } from '../utils/options.js'
+
+/**
+ * ⚗️ *transform*
+ * 🔢 *customizable*
+ *
+ * Filter the array `A`, keeping entries satisfying `Criteria`.
+ *
+ * @example
+ * ```ts
+ * type R = Filter<Array<string | undefined>, string> // string[]
+ * ```
+ */
+export type Filter<
+	A extends readonly unknown[],
+	Criteria = true,
+	Options extends Filter.Options = Filter.DefaultOptions
+> = TypePlusOptions.Merge<Options, Filter.DefaultOptions> extends infer O extends Filter.Options
+	? (IsNever<
+		A,
+		{
+			$then: O['$never'],
+			$else: (A[0] extends Criteria
+				? A
+				: Criteria extends A[0] ? Array<Criteria> : O['$notArray'])
+		}>)
+	: never
+
+export namespace Filter {
+	export interface Options extends TypePlusOptions.NotArray, $Never.$Options { }
+
+	export interface DefaultOptions {
+		$never: never,
+		$notArray: never[]
+	}
+
+	export type _<A extends readonly unknown[], Criteria, Result extends unknown[]> = A['length'] extends 0
+		? Result
+		: (A extends [infer H, ...infer Rest]
+			? IsEqual<H, Criteria, _<Rest, Criteria, [...Result, H]>, _<Rest, Criteria, Result>>
+			: never)
+}