type-plus 7.4.0 → 7.6.0

package/ts/tuple/tuple_plus.pad_start.ts

@@ -17,39 +17,42 @@
  * PadStart<[1, 2, 3], 5> // [unknown, unknown, 1, 2, 3]
  * ```
  */
-export type PadStart<Tuple extends unknown[], MaxLength extends number, PadWith = unknown> = PadStartDevice<
+export type PadStart<Tuple extends unknown[], MaxLength extends number, PadWith = unknown> = PadStart.Device<
 	Tuple,
 	MaxLength,
 	PadWith,
 	[]
 >
 
-type PadStartDevice<
-	Source extends unknown[],
-	MaxLength extends number,
-	PadWith,
-	Result extends unknown[]
-> =
-	Result['length'] extends MaxLength
-	? (
-		Source extends []
-		? Result
-		: (
-			Source extends [...infer Head, infer Tail]
-			? (
-				[Tail, ...Result] extends infer R extends unknown[]
-				? PadStartDevice<Head, R['length'], PadWith, R>
+export namespace PadStart {
+	export type Device<
+		Source extends unknown[],
+		MaxLength extends number,
+		PadWith,
+		Result extends unknown[]
+	> =
+		Result['length'] extends MaxLength
+		? (
+			Source extends []
+			? Result
+			: (
+				Source extends [...infer Head, infer Tail]
+				? (
+					[Tail, ...Result] extends infer R extends unknown[]
+					? Device<Head, R['length'], PadWith, R>
+					: never
+				)
 				: never
 			)
-			: never
 		)
-	)
-	: (
-		Source extends []
-		? PadStartDevice<Source, MaxLength, PadWith, [PadWith, ...Result]>
 		: (
-			Source extends [...infer Head, infer Tail]
-			? PadStartDevice<Head, MaxLength, PadWith, [Tail, ...Result]>
-			: Source
+			Source extends []
+			? Device<Source, MaxLength, PadWith, [PadWith, ...Result]>
+			: (
+				Source extends [...infer Head, infer Tail]
+				? Device<Head, MaxLength, PadWith, [Tail, ...Result]>
+				: Source
+			)
 		)
-	)
+
+}

package/ts/tuple/tuple_plus.ts

@@ -1,2 +1,5 @@
+export type { CommonPropKeys } from './tuple_plus.common_prop_keys.js'
+export type { DropMatch } from './tuple_plus.drop_match.js'
 export type { Filter } from './tuple_plus.filter.js'
+export type { Find } from './tuple_plus.find.js'
 export type { PadStart } from './tuple_plus.pad_start.js'

package/ts/tuple/tuple_type.ts

@@ -1,8 +1,13 @@
-import type { IsNever } from '../never/never_type.js'
+import type { IsNever, NeverType } from '../never/never_type.js'
 
 /**
- * Check if `T` is a tuple and not an array.
+ * 🌪️ *filter*
  *
+ * Filter `T` to ensure it is a tuple, excluding array.
+ *
+ * @typeParam Cases['never'] Return type when `T` is `never`. Default to `Else`.
+ *
+ * @example
  * ```ts
  * type R = TupleType<[]>       // []
  * type R = TupleType<[1]>      // [1]
@@ -13,52 +18,89 @@ import type { IsNever } from '../never/never_type.js'
  * type R = TupleType<unknown>  // never
  * ```
  */
-export type TupleType<T, Then = T, Else = never> = IsNever<
+export type TupleType<
+	T,
+	Then = T,
+	Else = never,
+	Options extends TupleType.Options = TupleType.DefaultOptions<Else>
+> = IsNever<
 	T,
-	Else,
+	Options['caseNever'],
 	[T] extends [any[]] ? (number extends T['length'] ? Else : Then) : Else
 >
 
+export namespace TupleType {
+	export interface Options extends NeverType.Options {
+	}
+
+	export interface DefaultOptions<Else> {
+		caseNever: Else
+	}
+}
+
+
 /**
- * Check if `T` is not a tuple.
+ * 🎭 *validate*
+ *
+ * Validate that `T` is a tuple, excluding array.
  *
  * ```ts
- * type R = NotTupleType<[]>       // never
- * type R = NotTupleType<[1]>      // never
+ * type R = IsTuple<[]>       // true
  *
- * type R = NotTupleType<number[]> // number[]
- * type R = NotTupleType<string>   // string
- * type R = NotTupleType<never>    // never
- * type R = NotTupleType<unknown>  // unknown
+ * type R = IsTuple<number[]> // false
+ * type R = IsTuple<string>   // false
+ * type R = IsTuple<never>    // false
+ * type R = IsTuple<unknown>  // false
  * ```
  */
-export type NotTupleType<T, Then = T, Else = never> = TupleType<T, Else, Then>
+export type IsTuple<
+	T,
+	Then = true,
+	Else = false,
+	Options extends TupleType.Options = TupleType.DefaultOptions<Else>
+> = TupleType<T, Then, Else, Options>
+
 
 /**
- * Is `T` a tuple and not an array.
+ * 🌪️ *filter*
+ *
+ * Filter `T` to ensure it is not an tuple, excluding array.
  *
  * ```ts
- * type R = IsTuple<[]>       // true
+ * type R = NotTupleType<[]>       // never
+ * type R = NotTupleType<[1]>      // never
  *
- * type R = IsTuple<number[]> // false
- * type R = IsTuple<string>   // false
- * type R = IsTuple<never>    // false
- * type R = IsTuple<unknown>  // false
+ * type R = NotTupleType<number[]> // number[]
+ * type R = NotTupleType<string>   // string
+ * type R = NotTupleType<never>    // never
+ * type R = NotTupleType<unknown>  // unknown
  * ```
  */
-export type IsTuple<T, Then = true, Else = false> = TupleType<T, Then, Else>
+export type NotTupleType<
+	T,
+	Then = T,
+	Else = never,
+	Options extends TupleType.Options = TupleType.DefaultOptions<Then>
+> = TupleType<T, Else, Then, Options>
 
 /**
- * Is `T` not a tuple.
+ * 🎭 *validate*
+ *
+ * Validate that `T` is not a tuple, excluding array.
  *
  * ```ts
  * type R = IsNotTuple<[]>       // false
  * type R = IsNotTuple<[1]>      // false
  *
- * type R = IsNotTuple<number[]> // false
- * type R = IsNotTuple<string>   // false
- * type R = IsNotTuple<never>    // false
- * type R = IsNotTuple<unknown>  // false
+ * type R = IsNotTuple<number[]> // true
+ * type R = IsNotTuple<string>   // true
+ * type R = IsNotTuple<never>    // true
+ * type R = IsNotTuple<unknown>  // true
  * ```
  */
-export type IsNotTuple<T, Then = true, Else = false> = TupleType<T, Else, Then>
+export type IsNotTuple<
+	T,
+	Then = true,
+	Else = false,
+	Options extends TupleType.Options = TupleType.DefaultOptions<Then>
+> = TupleType<T, Else, Then, Options>

package/ts/union/readme.md

@@ -0,0 +1,81 @@
+# union
+
+Union type is a type that combines multiple types as union.
+
+A value belongs to a union type if it belongs to one (or more) of its member types.
+
+For example:
+
+```ts
+type U1 = string | number
+
+const u1: U1 = 'a'
+const u2: U1 = 1
+```
+
+As a mental shortcut, you can think of it as an *or* operator.
+But it is better to think of it as union of category instead.
+
+## Union Members
+
+Each member of a union type is referred to as the union's member.
+
+It is useful to understand the relationship between members of a union type.
+
+In this context, we are going to consider types as sets,
+instead of categories, to make it easier to understand.
+
+Given two union members of a union,
+their relationship can be describe as "A x B" where "x" is:
+
+- disjoint: there is no overlap between A and B (e.g. `number | string`).
+- overlap: there are some overlap between A and B (e.g. `1 | 2` and `2 | 3` has overlap `2`)
+- subset/superset: A is a subset of B (or B is a superset of A) when every element in A is also in B (e.g. `1 | 2` is a subset of `number`)
+
+The union type will consider these relations when it is declared.
+
+There are other relations between members of a union type,
+which will affect how the union type behaves.
+
+For example:
+
+- property overlap: e.g. `{ a: 1 } | { a: 2 }`
+- property overlap with extension: e.g. `{ a: 1, b?: 2 } | { a: 1, c?: 3 }`
+
+The names of these relations are not properly defined and may change in the future.
+
+## [UnionType](./union.ts#l13)
+
+`UnionType<T, Then = T, Else = never>`
+
+🌪️ *filter*
+
+Filter the type `T` to ensure it is a union.
+
+```ts
+import type { UnionType } from 'type-plus'
+
+type R = UnionType<1 | 2> // 1 | 2
+type R = UnionType<boolean> // boolean
+type R = UnionType<number> // never
+```
+
+## [IsUnion](./union.ts#l30)
+
+🎭 *validate*
+
+Validate that `T` is a union.
+
+```ts
+import type { IsUnion } from 'type-plus'
+
+type R = IsUnion<1 | 2> // true
+type R = IsUnion<boolean> // true
+type R = IsUnion<number> // false
+```
+
+## Reference
+
+- [handbook]
+
+[handbook]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types

package/ts/union/union.ts

@@ -0,0 +1,37 @@
+/**
+ * 🌪️ *filter*
+ *
+ * Filter the type `T` to ensure it is a union.
+ *
+ * @example
+ * ```ts
+ * type R = IsUnion<'a' | 'b'> // 'a' | 'b'
+ * type R = IsUnion<boolean> // boolean
+ * type R = IsUnion<number> // never
+ * ```
+ */
+export type UnionType<T, Then = T, Else = never> = UnionType.Device<T, Then, Else>
+
+/**
+ * 🎭 *validate*
+ *
+ * Validate the type `T` is a union.
+ *
+ * @author Nurbol Alpysbayev
+ * @see https://stackoverflow.com/questions/53953814/typescript-check-if-a-type-is-a-union
+ *
+ * @example
+ * ```ts
+ * type R = IsUnion<'a' | 'b'> // true
+ * type R = IsUnion<boolean> // true
+ * type R = IsUnion<number> // false
+ * ```
+ */
+export type IsUnion<T, Then = true, Else = false> = UnionType.Device<T, Then, Else>
+
+export namespace UnionType {
+	export type Device<T, Then, Else, U = T> =
+		(T extends unknown ? (U extends T ? 1 : 2) : never) extends 1
+		? Else
+		: Then
+}

package/ts/unknown/unknown_type.ts

@@ -53,3 +53,16 @@ export type NotUnknownType<T, Then = T, Else = never> = UnknownType<T, Else, The
  * ```
  */
 export type IsNotUnknown<T, Then = true, Else = false> = UnknownType<T, Else, Then>
+
+/**
+ * 🌪️ *filter*
+ *
+ * Returns `T` if `T` is not `unknown`, otherwise `Else`.
+ *
+ * @example
+ * ```ts
+ * type R = NotUnknownOr<number, string> // number
+ * type R = NotUnknownOr<unknown, number> // number
+ * ```
+ */
+export type NotUnknownOr<T, Else> = UnknownType<T, Else, T>

package/ts/utils/options.ts

@@ -0,0 +1,10 @@
+
+/**
+ * 🦴 *utilities*
+ * ㊙️ *internal*
+ *
+ * Merge the input Options `I` with the default Options `D`.
+ */
+export type MergeOptions<I, D> = {
+	[k in keyof D]: k extends keyof I ? I[k] : D[k]
+}

package/cjs/array/array.find.d.ts

@@ -1,23 +0,0 @@
-import type { TupleType } from '../tuple/tuple_type.js';
-/**
- * 🦴 *utilities*
- *
- * Gets the first 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, 1, 'x', 3], string> // 'x'
- * ```
- */
-export type FindFirst<A extends unknown[], Criteria> = TupleType<A, A['length'] extends 0 ? never : A extends [infer Head, ...infer Tail] ? Head extends Criteria ? Head : FindFirst<Tail, Criteria> : never, A extends Array<infer T> ? (T extends Criteria ? T | undefined : never) : never>;
-/**
- * @deprecated use FindFirst
- */
-export type First<A extends any[], Criteria> = FindFirst<A, Criteria>;
-//# sourceMappingURL=array.find.d.ts.map

package/cjs/array/array.find.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"array.find.d.ts","sourceRoot":"","sources":["../../ts/array/array.find.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,QAAQ,IAAI,SAAS,CAC/D,CAAC,EACD,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,GAClB,KAAK,GACL,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,GACrC,IAAI,SAAS,QAAQ,GACpB,IAAI,GACJ,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,GAC1B,KAAK,EACR,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,QAAQ,GAAG,CAAC,GAAG,SAAS,GAAG,KAAK,CAAC,GAAG,KAAK,CAC/E,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,QAAQ,IAAI,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA"}

package/cjs/array/array.find.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"array.find.js","sourceRoot":"","sources":["../../ts/array/array.find.ts"],"names":[],"mappings":""}

package/esm/array/array.find.d.ts

@@ -1,23 +0,0 @@
-import type { TupleType } from '../tuple/tuple_type.js';
-/**
- * 🦴 *utilities*
- *
- * Gets the first 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, 1, 'x', 3], string> // 'x'
- * ```
- */
-export type FindFirst<A extends unknown[], Criteria> = TupleType<A, A['length'] extends 0 ? never : A extends [infer Head, ...infer Tail] ? Head extends Criteria ? Head : FindFirst<Tail, Criteria> : never, A extends Array<infer T> ? (T extends Criteria ? T | undefined : never) : never>;
-/**
- * @deprecated use FindFirst
- */
-export type First<A extends any[], Criteria> = FindFirst<A, Criteria>;
-//# sourceMappingURL=array.find.d.ts.map

package/esm/array/array.find.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"array.find.d.ts","sourceRoot":"","sources":["../../ts/array/array.find.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,QAAQ,IAAI,SAAS,CAC/D,CAAC,EACD,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,GAClB,KAAK,GACL,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,GACrC,IAAI,SAAS,QAAQ,GACpB,IAAI,GACJ,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,GAC1B,KAAK,EACR,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,QAAQ,GAAG,CAAC,GAAG,SAAS,GAAG,KAAK,CAAC,GAAG,KAAK,CAC/E,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,QAAQ,IAAI,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA"}

package/esm/array/array.find.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=array.find.js.map

package/esm/array/array.find.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"array.find.js","sourceRoot":"","sources":["../../ts/array/array.find.ts"],"names":[],"mappings":""}

package/ts/array/array.find.ts

@@ -1,34 +0,0 @@
-import type { TupleType } from '../tuple/tuple_type.js'
-
-/**
- * 🦴 *utilities*
- *
- * Gets the first 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, 1, 'x', 3], string> // 'x'
- * ```
- */
-export type FindFirst<A extends unknown[], Criteria> = TupleType<
-	A,
-	A['length'] extends 0
-		? never
-		: A extends [infer Head, ...infer Tail]
-		? Head extends Criteria
-			? Head
-			: FindFirst<Tail, Criteria>
-		: never,
-	A extends Array<infer T> ? (T extends Criteria ? T | undefined : never) : never
->
-
-/**
- * @deprecated use FindFirst
- */
-export type First<A extends any[], Criteria> = FindFirst<A, Criteria>