type-plus 7.3.1 → 7.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "type-plus",
-  "version": "7.3.1",
+  "version": "7.5.0",
   "description": "Provides additional types for TypeScript.",
   "homepage": "https://github.com/unional/type-plus/tree/main/type-plus#readme",
   "bugs": {
@@ -19,14 +19,18 @@
   "sideEffects": false,
   "type": "module",
   "exports": {
-    "import": {
-      "types": "./esm/index.d.ts",
+    ".": {
+      "import": {
+        "types": "./esm/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "require": {
+        "types": "./cjs/index.d.ts",
+        "default": "./cjs/index.js"
+      },
       "default": "./esm/index.js"
     },
-    "require": {
-      "types": "./cjs/index.d.ts",
-      "default": "./cjs/index.js"
-    }
+    "./package.json": "./package.json"
   },
   "main": "./cjs/index.js",
   "module": "./esm/index.js",
@@ -64,8 +68,7 @@
     "satisfier": "^5.2.2",
     "size-limit": "^8.2.4",
     "ts-jest": "^29.1.0",
-    "tslib": "^2.4.0",
-    "typescript": "^5.0.4"
+    "tslib": "^2.4.0"
   },
   "scripts": {
     "build": "run-p build:cjs build:esm build:tslib",

package/ts/any/any_type.ts

@@ -1,8 +1,7 @@
-
 /**
- * Parse `T` to ensure it is exactly `any`.
+ * 🌪️ *filter*
  *
- * 🐾 *parse*
+ * Filter `T` to ensure it is exactly `any`.
  *
  * @example
  * ```ts
@@ -16,10 +15,10 @@
 export type AnyType<T, Then = T, Else = never> = 0 extends 1 & T ? Then : Else
 
 /**
- * Validate if `T` is exactly `any`.
- *
  * 🎭 *validate*
  *
+ * Validate if `T` is exactly `any`.
+ *
  * @example
  * ```ts
  * type R = IsAny<any> // true
@@ -32,9 +31,9 @@ export type AnyType<T, Then = T, Else = never> = 0 extends 1 & T ? Then : Else
 export type IsAny<T, Then = true, Else = false> = AnyType<T, Then, Else>
 
 /**
- * Parse `T` to ensure it is not exactly `any`.
+ * 🌪️ *filter*
  *
- * 🐾 *parse*
+ * Filter `T` to ensure it is not exactly `any`.
  *
  * @example
  * ```ts
@@ -48,10 +47,10 @@ export type IsAny<T, Then = true, Else = false> = AnyType<T, Then, Else>
 export type NotAnyType<T, Then = T, Else = never> = AnyType<T, Else, Then>
 
 /**
- * Validate if `T` is not exactly `any`.
- *
  * 🎭 *validate*
  *
+ * Validate if `T` is not exactly `any`.
+ *
  * @example
  * ```ts
  * import type { IsNotAny } from 'type-plus'

package/ts/any/readme.md

@@ -12,10 +12,77 @@ 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<T, Then = T, Else = never>`](any_type.ts#L15): check if `T` is exactly `any`.
-- [`IsAny<T, Then = true, Else = false`](any_type.ts#L30): is `T` exactly `any`.
-- [`NotAnyType<T, Then = T, Else = never>`](any_type.ts#L45): check if `T` is not exactly `any`.
-- [`IsNotAny<T, Then = true, Else = false>`](any_type.ts#L60): is `T` not exactly `any`.
+### [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
 

package/ts/array/array.at.ts

@@ -3,7 +3,9 @@ import type { TupleType } from '../tuple/tuple_type.js'
 import type { IndexAt } from './array_index.js'
 
 /**
- * Gets the type of the array or tuple at index `N`.
+ * 🦴 *utilities*
+ *
+ * Gets the type of the array or tuple at positive or negative index `N`.
  *
  * Like `Array.at()`, this type supports negative numbers.
  *

package/ts/array/array.entries.ts

@@ -13,12 +13,14 @@ import type { IsTuple } from '../tuple/tuple_type.js'
  */
 export type Entries<A extends unknown[]> = IsTuple<
 	A,
-	Device<A, []>,
+	Entries.Device<A, []>,
 	A extends Array<infer T> ? Array<[number, T]> : never
 >
 
-type Device<A extends unknown[], R extends unknown[]> = A['length'] extends 0
+export namespace Entries {
+	export type Device<A extends unknown[], R extends unknown[]> = A['length'] extends 0
 	? R
 	: A extends [...infer F, infer N]
 	? Device<F, [[F['length'], N], ...R]>
 	: never
+}

package/ts/array/array.find_last.ts

@@ -1,7 +1,9 @@
 import type { TupleType } from '../tuple/tuple_type.js'
 
 /**
- * Returns the last type in the array or tuple that matches the `Criteria`.
+ * 🦴 *utilities*
+ *
+ * Gets the last type in the array or tuple that matches the `Criteria`.
  *
  * If the `Criteria` is not met, it will return `never'.
  *

package/ts/array/array.some.ts

@@ -1,6 +1,6 @@
 import type { IsEqual } from '../equal/equal.js'
 import type { CanAssign } from '../index.js'
-import type { Tail } from './tail.js'
+import type { Tail } from '../tuple/tail.js'
 import type { UnionOfValues } from './union_of_values.js'
 
 /**

package/ts/array/array_plus.common_prop_keys.ts

@@ -0,0 +1,35 @@
+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['caseNever'] Return type when `T` is `never`.
+ * Default to `never`.
+ */
+export type CommonPropKeys<
+	A extends Record<KeyTypes, unknown>[],
+	Options extends CommonPropKeys.Options = CommonPropKeys.DefaultOptions
+> = NeverType<A,
+	Options['caseNever'],
+	A extends 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.concat.ts → array_plus.concat.ts}

@@ -1,4 +1,7 @@
 /**
+ * 🦴 *utilities
+ * 💀 *deprecated* Will be available only as `ArrayPlus.Concat` in the next version
+ *
  * Concats two arrays or tuples.
  *
  * alias of: `[...A, ...B]`

package/ts/array/array_plus.drop_match.ts

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

@@ -0,0 +1,61 @@
+import type { IsNever } from '../never/never_type.js'
+import type { IsUnion } from '../union/union.js'
+import type { MergeOptions } 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['caseNotMatch'] Return value when `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * @typeParam Options['caseWiden'] Return value when `widen` is true.
+ * Default to `Criteria | undefined`.
+ *
+ * @typeParam Options['caseUnionNotMatch'] 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
+	: (MergeOptions<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['caseWiden']
+					: C['caseNotMatch'])
+				: C['caseNotMatch'])) extends infer R
+			? IsUnion<T, IsNever<R, R, R | C['caseUnionNotMatch']>, R>
+			: C['caseNotMatch'])
+		: never)
+
+export namespace ElementMatch {
+	export interface Options {
+		widen?: boolean | undefined,
+		caseNotMatch?: unknown,
+		caseWiden?: unknown,
+		caseUnionNotMatch?: unknown
+	}
+	export interface DefaultOptions<Criteria> {
+		widen: true,
+		caseNotMatch: never,
+		caseWiden: Criteria | undefined,
+		caseUnionNotMatch: never
+	}
+}

package/ts/array/array_plus.filter.ts

@@ -0,0 +1,5 @@
+export type Filter<A extends unknown[], Criteria> = A[0] extends Criteria
+	? A
+	: Criteria extends A[0]
+	? Array<Criteria>
+	: never[]

package/ts/array/array_plus.find.ts

@@ -0,0 +1,71 @@
+import type { NeverType } from '../never/never_type.js'
+import type { TupleType } from '../tuple/tuple_type.js'
+import type { MergeOptions } 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['caseWiden']`
+ *
+ * @typeParam Options['caseNever'] return type when `A` is `never`. Default to `never`.
+ *
+ * @typeParam Options['caseNotMatch'] Return value when `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * @typeParam Options['caseTuple'] return type when `A` is a tuple. Default to `not supported` message.
+ *
+ * @typeParam Options['caseWiden'] 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['caseUnionNotMatch'] 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 unknown[],
+	Criteria,
+	Options extends Find.Options = Find.DefaultOptions<Criteria>
+> =
+	MergeOptions<Options, Find.DefaultOptions<Criteria>> extends infer O extends Find.Options
+	? TupleType<
+		A,
+		O['caseTuple'],
+		A extends Array<infer T> ? ElementMatch<T, Criteria, O> : never,
+		O
+	>
+	: never
+
+export namespace Find {
+	export interface Options extends ElementMatch.Options, NeverType.Options {
+		caseTuple?: unknown,
+	}
+
+	export interface DefaultOptions<Criteria> extends ElementMatch.DefaultOptions<Criteria>, NeverType.DefaultOptions {
+		caseTuple: 'does not support tuple. Please use `FindFirst` or `TuplePlus.Find` instead.',
+	}
+}

package/ts/array/array_plus.pad_start.ts

@@ -0,0 +1,13 @@
+import type { CanAssign } from '../index.js'
+import type { CreateTuple } from '../tuple/create_tuple.js'
+import type { UnionOfValues } from './union_of_values.js'
+
+export type PadStart<
+	A extends unknown[],
+	MaxLength extends number,
+	PadWith = unknown
+> = MaxLength extends 0
+	? A
+	: CanAssign<PadWith, UnionOfValues<A>> extends true
+	? A
+	: PadStart<[...CreateTuple<MaxLength, PadWith>, ...A], MaxLength, PadWith>

package/ts/array/array_plus.ts

@@ -1,10 +1,14 @@
 export type { At } from './array.at.js'
-export type { Concat } from './array.concat.js'
 export type { Entries } from './array.entries.js'
-export type { FindFirst as Find } from './array.find.js'
 export type { FindLast } from './array.find_last.js'
 export type { Reverse } from './array.reverse.js'
 export type { Some } from './array.some.js'
 export type { IndexAt, IsIndexOutOfBound } from './array_index.js'
+export type { CommonPropKeys } from './array_plus.common_prop_keys.js'
+export type { Concat } from './array_plus.concat.js'
+export type { DropMatch } from './array_plus.drop_match.js'
+export type { ElementMatch } from './array_plus.element_match.js'
+export type { Filter } from './array_plus.filter.js'
+export type { Find } from './array_plus.find.js'
+export type { PadStart } from './array_plus.pad_start.js'
 export type { SplitAt } from './array_plus.split_at.js'
-export type { PadStart } from './pad_start.js'

package/ts/array/array_type.ts

@@ -2,12 +2,17 @@ import type { IsNever } from '../never/never_type.js'
 import type { StrictNumberType } from '../number/strict_number_type.js'
 
 /**
- * Check if the type `T` is an array and not a tuple.
+ * 🌪️ *filter*
  *
+ * Filter `T` to ensure it is an array, excluding tuple.
+ *
+ * @example
  * ```ts
  * type R = ArrayType<number[]> // number[]
  *
  * type R = ArrayType<[1]> // never
+ * type R = ArrayType<number[] | 1> // never
+ * type R = ArrayType<number[] & { a: 1 }> // never
  * ```
  */
 export type ArrayType<T, Then = T, Else = never> = IsNever<
@@ -17,32 +22,45 @@ export type ArrayType<T, Then = T, Else = never> = IsNever<
 >
 
 /**
- * Check if the type `T` is not an array.
+ * 🎭 *validate*
+ *
+ * Validate that `T` is an array, excluding tuple.
  *
+ * @example
  * ```ts
- * type R = NotArrayType<number[]> // never
+ * type R = IsArray<number[]> // true
  *
- * type R = NotArrayType<number> // number
- * type R = NotArrayType<[1]> // [1]
+ * type R = IsArray<number> // false
+ * type R = IsArray<[1]> // false
  * ```
  */
-export type NotArrayType<T, Then = T, Else = never> = ArrayType<T, Else, Then>
+export type IsArray<T, Then = true, Else = false> = ArrayType<T, Then, Else>
 
 /**
- * Is `T` an array?
+ * 🌪️ *filter*
+ *
+ * Filter `T` to ensure it is not an array, excluding tuple.
  *
+ * i.e. *tuple* will pass through this filter.
+ *
+ * @example
  * ```ts
- * type R = IsArray<number[]> // true
+ * type R = NotArrayType<number[]> // never
  *
- * type R = IsArray<number> // false
- * type R = IsArray<[1]> // false
+ * type R = NotArrayType<number> // number
+ * type R = NotArrayType<[1]> // [1]
  * ```
  */
-export type IsArray<T, Then = true, Else = false> = ArrayType<T, Then, Else>
+export type NotArrayType<T, Then = T, Else = never> = ArrayType<T, Else, Then>
 
 /**
- * Is `T` not an array?
+ * 🎭 *validate*
+ *
+ * Validate that `T` is not an array, excluding tuple.
+ *
+ * i.e. *tuple* will pass through this filter.
  *
+ * @example
  * ```ts
  * type R = IsNotArray<number[]> // false
  *

package/ts/array/filter.ts

@@ -1,27 +1,32 @@
+import type { Filter as FilterTuple } from '../tuple/tuple_plus.filter.js'
+import type { Filter as FilterArray } from './array_plus.filter.js'
+
 /**
- * filter the array or tuple `A`, keeping entries satisfying `Criteria`.
+ * ⚗️ *transform*
+ *
+ * Filter the array or tuple `A`, keeping entries satisfying `Criteria`.
+ *
+ * @example
+ * ```ts
+ * type R = Filter<[1, 2, '3'], number> // [1, 2]
+ * type R = Filter<Array<string | undefined>, string> // string[]
+ * ```
  */
-export type Filter<A extends Array<any>, Criteria> = number extends A['length']
-	? // array
-	  A[0] extends Criteria
-		? A
-		: Criteria extends A[0]
-		? Array<Criteria>
-		: never[]
-	: // tuple
-	A['length'] extends 0
-	? never
-	: A extends [infer Head, ...infer Tail]
-	? Tail['length'] extends 0
-		? Head extends Criteria
-			? [Head]
-			: never[]
-		: Head extends Criteria
-		? [Head, ...Filter<Tail, Criteria>]
-		: Filter<Tail, Criteria>
-	: never
+export type Filter<A extends unknown[], Criteria> = number extends A['length']
+	? FilterArray<A, Criteria>
+	: FilterTuple<A, Criteria>
 
 /**
- * keeps entries satisfying `Criteria` in array or tuple `A`.
+ * ⚗️ *transform*
+ * 👽 *alias*
+ *
+ * Keeps entries satisfying `Criteria` in array or tuple `A`.
+ *
+ * @alias of [Filter](./filter.ts)
+ * @example
+ * ```ts
+ * type R = KeepMatch<[1, 2, 3], number> // [1, 2]
+ * type R = KeepMatch<Array<string|undefined>, string> // string[]
+ * ```
  */
-export type KeepMatch<A extends Array<any>, Criteria> = Filter<A, Criteria>
+export type KeepMatch<A extends unknown[], Criteria> = Filter<A, Criteria>

package/ts/array/find_first.ts

@@ -0,0 +1,71 @@
+import type { TupleType } from '../tuple/tuple_type.js'
+import type { Find as TupleFind } from '../tuple/tuple_plus.find.js'
+import type { Find as ArrayFind } from './array_plus.find.js'
+
+/**
+ * 🦴 *utilities*
+ * 🔢 *customizable*
+ *
+ * Find the first type in the array or tuple `A` that matches `Criteria`.
+ *
+ * If the `Criteria` is not met, it will return `never'.
+ *
+ * @example
+ * ```ts
+ * type R = FindFirst<[true, 1, 'x', 3], string> // 'x'
+ * type R = FindFirst<[true, 1, 'x', 3], number> // 1
+ * type R = FindFirst<[string, number, 1], 1> // widen: 1 | undefined
+ * type R = FindFirst<[true, number | string], string> // unionMiss: string | undefined
+ * type R = FindFirst<Array<string>, string> // string
+ * type R = FindFirst<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
+ * type R = FindFirst<Array<string | number>, number | string> // string | number
+ * type R = FindFirst<Array<number>, 1> // widen: 1 | undefined
+ * type R = FindFirst<Array<string | number>, number> // unionMiss: number | undefined
+ *
+ * type R = FindFirst<[true, 1, 'x'], 2> // never
+ * type R = FindFirst<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['caseWiden']`
+ *
+ * @typeParam Options['caseEmptyTuple'] return type when `A` is an empty tuple.
+ * Default to `never`.
+ *
+ * @typeParam Options['caseNever'] return type when `A` is `never`. Default to `never`.
+ *
+ * @typeParam Options['caseNoMatch'] Return value when `T` does not match `Criteria`.
+ * Default to `never`.
+ *
+ * @typeParam Options['caseWiden'] 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['caseUnionMiss'] Return value when a branch of the union `T` does not match `Criteria`.
+ * Default to `undefined`.
+ * Since it is a union, the result will be join to the matched branch as union.
+ */
+export type FindFirst<
+	A extends unknown[],
+	Criteria, Options extends FindFirst.Options = FindFirst.DefaultOptions<Criteria>
+> = TupleType<
+	A,
+	TupleFind<A, Criteria, Options>,
+	ArrayFind<A, Criteria, Options>
+>
+
+export namespace FindFirst {
+	export interface Options extends ArrayFind.Options, TupleFind.Options { }
+	export interface DefaultOptions<Criteria>
+		extends ArrayFind.DefaultOptions<Criteria>, TupleFind.DefaultOptions<Criteria> { }
+}
+
+
+/**
+ * @deprecated use FindFirst
+ */
+export type First<A extends any[], Criteria> = FindFirst<A, Criteria>