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

package/ts/any/readme.md

@@ -1,110 +0,0 @@
-# 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.
-
-## Type Checking
-
-The `AnyType<T>` and friends are used to check if a type is `any` or not.
-
-They are strict type checks, meaning they match only the type `any`.
-Union and intersections are not a factor here they are resolved to `any`,
-except `any & never` which is `never`.
-
-### [AnyType](./any.spec.ts#15)
-
-`AnyType<T, Then = T, Else = never>`
-
-🌪️ *filter*
-
-Filter `T` to ensure it is exactly `any`.
-
-```ts
-import type { AnyType } from 'type-plus'
-
-type R = AnyType<any> // any
-
-type R = AnyType<never> // never
-type R = AnyType<unknown> // never
-type R = AnyType<string | boolean> // never
-```
-
-### [IsAny](./any.spec.ts#31)
-
-`IsAny<T, Then = true, Else = false>`
-
-🎭 *validate*
-
-Validate if `T` is exactly `any`.
-
-```ts
-import type { IsAny } from 'type-plus'
-
-type R = IsAny<any> // true
-
-type R = IsAny<never> // false
-type R = IsAny<unknown> // false
-type R = IsAny<string | boolean> // false
-```
-
-### [NotAnyType](./any.spec.ts#47)
-
-`NotAnyType<T, Then = T, Else = never>`
-
-🌪️ *filter*
-
-Filter `T` to ensure it is not exactly `any`.
-
-```ts
-import type { NotAnyType } from 'type-plus'
-
-type R = NotAnyType<any> // never
-
-type R = NotAnyType<never> // never
-type R = NotAnyType<unknown> // never
-type R = NotAnyType<string | boolean> // string | boolean
-```
-
-### [IsNotAny](./any.spec.ts#65)
-
-`IsNotAny<T, Then = true, Else = false>`
-
-🎭 *validate*
-
-Validate if `T` is not exactly `any`.
-
-```ts
-import type { IsNotAny } from 'type-plus'
-
-type R = IsNotAny<any> // false
-
-type R = IsNotAny<never> // true
-type R = IsNotAny<unknown> // true
-type R = IsNotAny<string | boolean> // true
-```
-
-## 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/ts/array/array.at.ts

@@ -1,30 +0,0 @@
-import type { IsStrictNumber } from '../number/strict_number_type.js'
-import type { TupleType } from '../tuple/tuple_type.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
-		? TupleType<A, IsStrictNumber<I, A[I] | undefined, A[I]>, A[I] | undefined>
-		: Fail
-	: never

package/ts/array/array.entries.ts

@@ -1,26 +0,0 @@
-import type { IsTuple } from '../tuple/tuple_type.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,
-	Entries.Device<A, []>,
-	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/ts/array/array.find_last.ts

@@ -1,29 +0,0 @@
-import type { TupleType } from '../tuple/tuple_type.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> = TupleType<
-	A,
-	A['length'] extends 0
-	? never
-	: (A extends readonly [...infer Heads, infer Last]
-		? (Last extends Criteria
-			? Last
-			: FindLast<Heads, Criteria>)
-		: never),
-	A extends Readonly<Array<infer T>> ? (T extends Criteria ? T | undefined : never) : never
->

package/ts/array/array_plus.common_prop_keys.ts

@@ -1,35 +0,0 @@
-import type { NeverType } from '../never/never_type.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
-> = NeverType<A,
-	Options['$never'],
-	A extends Readonly<Array<infer R extends Record<KeyTypes, unknown>>> ? keyof R : never
->
-
-export namespace CommonPropKeys {
-	export interface Options extends NeverType.Options {
-	}
-
-	export interface DefaultOptions extends NeverType.DefaultOptions {
-	}
-}

package/ts/array/array_plus.drop_match.ts

@@ -1,19 +0,0 @@
-import type { NonNull } from '../utils/NonNull.js'
-import type { NonUndefined } from '../utils/NonUndefined.js'
-
-/**
- * ⚗️ *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<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>>))))

package/ts/array/array_plus.element_match.ts

@@ -1,61 +0,0 @@
-import type { IsNever } from '../never/never_type.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, R, 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/ts/array/array_plus.filter.ts

@@ -1,49 +0,0 @@
-// 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 { NeverType } from '../never/never_type.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
-	? (NeverType<
-		A,
-		O['$never'],
-		(A[0] extends Criteria
-			? A
-			: Criteria extends A[0] ? Array<Criteria> : O['$notArray'])>)
-	: never
-
-export namespace Filter {
-	export interface Options extends TypePlusOptions.NotArray, NeverType.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)
-}

package/ts/array/array_plus.find.ts

@@ -1,71 +0,0 @@
-import type { NeverType } from '../never/never_type.js'
-import type { TupleType } from '../tuple/tuple_type.js'
-import type { TypePlusOptions } from '../utils/options.js'
-import type { ElementMatch } from './array_plus.element_match.js'
-
-/**
- * 🦴 *utilities*
- * 🔢 *customizable*
- *
- * Finds the type in array `A` that matches `Criteria`.
- *
- * @example
- * ```ts
- * type R = ArrayPlus.Find<Array<string>, string> // string
- * type R = ArrayPlus.Find<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
- * type R = ArrayPlus.Find<Array<string | number>, number | string> // string | number
- * type R = ArrayPlus.Find<Array<number>, 1> // widen: 1 | undefined
- * type R = ArrayPlus.Find<Array<string | number>, number> // unionMiss: number | undefined
- *
- * type R = ArrayPlus.Find<string[], number> // 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['$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['$tuple'] return type when `A` is a tuple. Default to `not supported` message.
- *
- * @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
-	? TupleType<
-		A,
-		O['$tuple'],
-		A extends Readonly<Array<infer T>> ? ElementMatch<T, Criteria, O> : never,
-		O
-	>
-	: never
-
-export namespace Find {
-	export interface Options extends ElementMatch.Options, NeverType.Options {
-		$tuple?: unknown,
-	}
-
-	export interface DefaultOptions<Criteria> extends ElementMatch.DefaultOptions<Criteria>, NeverType.DefaultOptions {
-		$tuple: 'does not support tuple. Please use `FindFirst` or `TuplePlus.Find` instead.',
-	}
-}

package/ts/array/array_plus.index_at.ts

@@ -1,69 +0,0 @@
-import type { IsAny } from '../any/any_type.js'
-import type { IsEqual } from '../equal/equal.js'
-import type { Abs } from '../math/abs.js'
-import type { GreaterThan } from '../math/greater_than.js'
-import type { Subtract } from '../math/subtract.js'
-import type { IsNever } from '../never/never_type.js'
-import type { StrictNumberType } from '../number/strict_number_type.js'
-import type { Integer } from '../numeric/integer.js'
-import type { Negative } from '../numeric/negative.js'
-
-/**
- * 🦴 *utilities*
- *
- * Gets the normalized index to access the element of an array or tuple.
- *
- * @example
- * ```ts
- * type R = IndexAt<['a', 'b', 'c'], 2> // 2
- * type R = IndexAt<['a', 'b', 'c'], -2> // 1
- *
- * type R = IndexAt<['a', 'b', 'c'], 3> // never
- * type R = IndexAt<['a', 'b', 'c'], -4> // never
- * ```
- */
-export type IndexAt<
-	A extends readonly unknown[],
-	N extends number,
-	Fail = never,
-	Upper = A['length'],
-	Lower = 0
-> = IsNever<A, Fail, IndexAt._<A, N, Fail, Upper, Lower>>
-
-export namespace IndexAt {
-	export type _<
-		A extends readonly unknown[],
-		N extends number,
-		Fail = never,
-		Upper = A['length'],
-		Lower = 0
-	> = IsEqual<
-		A['length'],
-		0,
-		Fail,
-		Integer<
-			N,
-			StrictNumberType<
-				A['length'],
-				// A: array
-				N,
-				// A: tuple
-				Negative<
-					N,
-					GreaterThan<Abs<N>, A['length']> extends true ? Lower : Subtract<A['length'], Abs<N>>,
-					GreaterThan<A['length'], N> extends true ? N : Upper
-				>
-			>,
-			// N: number or float
-			IsAny<
-				N,
-				number,
-				StrictNumberType<
-					N,
-					// TODO: handle tuple to union of indexes
-					N
-				>
-			>
-		>
-	>
-}

package/ts/array/array_plus.is_index_out_of_bound.ts

@@ -1,22 +0,0 @@
-import type { IsNever } from '../never/never_type.js'
-import type { IndexAt } from './array_plus.index_at.js'
-
-/**
- * 🎭 *validate*
- *
- * Is `N` an out of bound index of `A`.
- *
- * @example
- * ```ts
- * type R = IsIndexOutOfBound<[1], 0> // false
- * type R = IsIndexOutOfBound<[1], -1> // false
- *
- * type R = IsIndexOutOfBound<[1], 1> // true
- * type R = IsIndexOutOfBound<[1], -2> // true
- * ```
- */
-export type IsIndexOutOfBound<A extends readonly unknown[], N extends number, Then = true, Else = false> = IsNever<
-	IndexAt<A, N, never, never, never>,
-	Then,
-	Else
->

package/ts/array/array_plus.is_readonly.ts

@@ -1,46 +0,0 @@
-import type { NeverType } from '../never/never_type.js'
-import type { TypePlusOptions } from '../utils/options.js'
-import type { LooseArrayType } from './loose_array_type.js'
-
-/**
- * 🎭 *validate*
- * 🔢 *customizable*
- *
- * Checks if `A` is a readonly array or tuple
- *
- * @example
- * ```ts
- * type R = IsReadonly<readonly string[]> // true
- * type R = IsReadonly<readonly [1, 2, 3, 4, 5]> // true
- *
- * type R = IsReadonly<[1, 2, 3, 4, 5]> // false
- * type R = IsReadonly<readonly string[] | number> // boolean
- * ```
- */
-export type IsReadonly<
-	A,
-	Options extends IsReadonly.Options = IsReadonly.DefaultOptions
-> =
-	TypePlusOptions.Merge<Options, IsReadonly.DefaultOptions> extends infer O extends IsReadonly.Options ?
-	NeverType<
-		A,
-		O['$never'],
-		A extends any ?
-		LooseArrayType<A,
-			Readonly<A> extends A ? O['$then'] : O['$else'],
-			O['$notArray']
-		> : never
-	>
-	: never
-
-export namespace IsReadonly {
-	export interface Options
-		extends NeverType.Options, TypePlusOptions.Selection, TypePlusOptions.NotArray { }
-
-	export interface DefaultOptions {
-		$then: true,
-		$else: false,
-		$never: false,
-		$notArray: false
-	}
-}

package/ts/array/array_plus.split_at.ts

@@ -1,74 +0,0 @@
-import type { NeverType } from '../never/never_type.js'
-import type { IsTuple } from '../tuple/tuple_type.js'
-import type { IndexAt } from './array_plus.index_at.js'
-import type { ArrayType } from './array_type.js'
-
-/**
- * ⚗️ *transform*
- *
- * Splits array or tuple `A` into two at the specified `Index`.
- *
- * If the `Index` is out of bounds,
- * it will set to the boundary value.
- *
- * It is the type level `splice()`.
- *
- * @example
- * ```ts
- * SplitAt<[1, 2, 3, 4, 5], 2> // [[1, 2], [3, 4, 5]]
- * SplitAt<[1, 2, 3, 4, 5], -3> // [[1, 2], [3, 4, 5]]
- *
- * SplitAt<[1, 2, 3, 4, 5], 2, 2> // [[1, 2, 5], [3, 4]]
- *
- * SplitAt<[1, 2, 3, 4, 5], 2, 2, ['a', 'b']> // [[1, 2, 'a', 'b', 5], [3, 4]]
- *
- * // out of bound resets to boundary
- * SplitAt<[1, 2, 3, 4, 5], 6> // [[1, 2, 3, 4, 5], []]
- * SplitAt<[1, 2, 3, 4, 5], -6> // [[], [1, 2, 3, 4, 5]]
- * ```
- */
-export type SplitAt<
-	A extends readonly unknown[],
-	Index extends number,
-	DeleteCount extends number | never = never,
-	Insert extends readonly unknown[] | never = never
-> = ArrayType<
-	A,
-	[A, A],
-	SplitAt._<A, [], [], IndexAt._<A, Index>, DeleteCount, Insert>
->
-
-export namespace SplitAt {
-	export type _<
-		A extends readonly unknown[],
-		B extends readonly unknown[],
-		C extends readonly unknown[],
-		Index extends number,
-		DeleteCount,
-		Insert extends readonly unknown[],
-	> = 0 extends A['length']
-		? IsTuple<Insert, [[...Insert, ...B], C], [B, C]>
-		: (Index extends B['length']
-			? NeverType<
-				DeleteCount,
-				[B, A],
-				_D<A, B, C, DeleteCount, Insert>>
-			: (A extends readonly [infer Head, ...infer Tail]
-				? _<Tail, [...B, Head], [], Index, DeleteCount, Insert>
-				: 'unexpected: A does not extends [Head, ...Tail]'))
-
-	export type _D<
-		A extends readonly unknown[],
-		B extends readonly unknown[],
-		C extends readonly unknown[],
-		DeleteCount,
-		Insert extends readonly unknown[],
-	> = DeleteCount extends C['length']
-		? IsTuple<Insert, [[...B, ...Insert, ...A], C], [[...B, ...A], C]>
-		: (A extends readonly [infer Head, ...infer Tail]
-			? _D<Tail, B, [...C, Head], DeleteCount, Insert>
-			: IsTuple<Insert, [[...Insert, ...B], C], [B, C]>
-		)
-
-}
-