type-plus 6.8.1 → 7.0.1

package/ts/nominal/flavor.ts

@@ -1,7 +1,7 @@
 // By Drew Colthorp, <https://spin.atomicobject.com/2018/01/15/typescript-flexible-nominal-typing/#comment-604580>
 // <https://gist.github.com/dcolthorp/aa21cf87d847ae9942106435bf47565d>
 
-import { isType } from '../predicates/isType.js'
+import { isType } from '../type-guard/is_type.js'
 import type { Widen } from '../utils/index.js'
 import { typeSym, valueSym } from './constants.js'
 

package/ts/number/cast.ts

@@ -0,0 +1,17 @@
+/**
+ * Cast a string to a number literal type if possible.
+ *
+ * ```ts
+ * StringToNumber<'1'> // 1
+ * StringToNumber<'-1'> // -1
+ * ```
+ */
+export type StringToNumber<S extends string, Fail = never> = S extends `-0`
+	? 0
+	: S extends `${infer W}.0`
+	? StringToNumber<W>
+	: S extends `${infer W}.${infer F}0`
+	? StringToNumber<`${W}.${F}`>
+	: S extends `${infer N extends number}`
+	? N
+	: Fail

package/ts/number/number_array.ts

@@ -1,15 +1,15 @@
-import type { Add, IsStrictNumber } from '../index.js'
+// import type { Add, IsStrictNumber } from '../index.js'
 
-export type Sum<A extends number[], Fail = never> = IsStrictNumber<
-	A['length'],
-	Fail,
-	A['length'] extends 0
-		? 0
-		: A['length'] extends 1
-		? A[0]
-		: A['length'] extends 2
-		? Add<A[0], A[1]>
-		: A extends [infer F extends number, infer S extends number, ...infer Tail extends number[]]
-		? Sum<[Add<F, S>, ...Tail]>
-		: never
->
+// export type Sum<A extends number[], Fail = never> = IsStrictNumber<
+// 	A['length'],
+// 	Fail,
+// 	A['length'] extends 0
+// 		? 0
+// 		: A['length'] extends 1
+// 		? A[0]
+// 		: A['length'] extends 2
+// 		? Add<A[0], A[1]>
+// 		: A extends [infer F extends number, infer S extends number, ...infer Tail extends number[]]
+// 		? Sum<[Add<F, S>, ...Tail]>
+// 		: never
+// >

package/ts/number/number_plus.ts

@@ -1,7 +1,5 @@
-export type { Integer, IsInteger, IsNotInteger, IsWhole, NotInteger } from './integer.js'
-export type { IsNegative, IsNotNegative, Negative, NotNegative } from './negative.js'
-export type { Sum } from './number_array.js'
-export type { IsNotNumber, IsNumber, NotNumberType, NumberType } from './number_type.js'
+export type { Integer, IsInteger, IsNotInteger, IsWhole, NotInteger } from '../numeric/integer.js'
+export type { IsNegative, IsNotNegative, Negative, NotNegative } from '../numeric/negative.js'
 export type {
 	IsNotNumeric,
 	IsNumeric,
@@ -9,8 +7,10 @@ export type {
 	Numeric,
 	NumericType,
 	Zero
-} from './numeric_type.js'
-export type { IsNotPositive, IsPositive, NonPositive, Positive } from './positive.js'
+} from '../numeric/numeric_type.js'
+export type { IsNotPositive, IsPositive, NonPositive, Positive } from '../numeric/positive.js'
+// export type { Sum } from './number_array.js'
+export type { IsNotNumber, IsNumber, NotNumberType, NumberType } from './number_type.js'
 export type {
 	IsNotStrictNumber,
 	IsStrictNumber,

package/ts/number/readme.md

@@ -40,114 +40,6 @@ type R = StrictNumberType<unknown> // never
 - [`NotStrictNumberType<T, Then = T, Else = never>`](strict_number_type.ts#L50): check if `T` is not `number`.
 - [`IsNotStrictNumber<T, Then = true, Else = false>`](strict_number_type.ts#L65): is `T` not `number`.
 
----
-
-`Numeric` type is either `number` or `bigint`.
-
-The `NumericType<T>` and friends are used to check if `T` is `number` or `bigint`.
-
-```ts
-import type { NumericType } from 'type-plus'
-
-type R = NumericType<number> // number
-type R = NumericType<bigint> // bigint
-type R = NumericType<1> // 1
-type R = NumericType<1n> // 1n
-
-type R = NumericType<never> // never
-```
-
-- [`NumericType<T, Then = T, Else = never>`](numeric_type.ts#L27): check if `T` is `number` or `bigint`.
-- [`IsNumeric<T, Then = true, Else = false>`](numeric_type.ts#L42): is `T` `number` or `bigint`.
-- [`NotNumericType<T, Then = T, Else = never>`](numeric_type.ts#L57): check if `T` is not `number` nor `bigint`.
-- [`IsNotNumeric<T, Then = true, Else = false>`](numeric_type.ts#L72): is `T` not `number` nor `bigint`.
-
----
-
-`Integer<T>` and friends are used to check if `T` is an integer.
-
-```ts
-import type { Integer } from 'type-plus'
-
-type R = Integer<1> // 1
-type R = Integer<1.0> // 1.0
-
-type R = Integer<1.1> // never
-```
-
-- [`Integer<T, Then = T, Else = never>`](integer.ts#L17): check if `T` is an integer.
-- [`IsInteger<T, Then = true, Else = false>`](integer.ts#L36): is `T` an integer.
-- [`NotIntegerType<T, Then = T, Else = never>`](integer.ts#L51): check if `T` is not an integer.
-- [`IsNotInteger<T, Then = true, Else = false>`](integer.ts#L66): is `T` not an integer.
-- [`IsWhole<T, Then = true, Else = false>`](integer.ts#L81): same as `Integer<T>`, will be deprecated in the future.
-
----
-
-`Positive<T>` and friends are used to check if `T` is a positive numeric value.
-
-The `number` and `bigint` can be considered as a union of all positive and negative numeric literals.
-
-That is why `IsPositive<T>` will yield `boolean` as the union is distributive.
-`Positive<T>` returns `T` for `number` and `bigint` for the same reason.
-It is a bit confusing but it is correct as it really returns `T | never`,
-which resolves to `T`.
-
-This behavior is different than `TrueType<T>` which `TrueType<boolean>` returns `never`.
-
-This is because `TrueType<T>` is checking for the exect `true` type,
-while `Positive<T>` is checking for a criteria of types (i.e. a set).
-
-```ts
-import type { Positive } from 'type-plus'
-
-type R = Positive<1> // 1
-type R = Positive<1.0> // 1.0
-type R = Positive<1n> // 1n
-
-type R = Positive<-1> // never
-type R = Positive<'1'> // never
-```
-
-- [`Positive<T, Then = T, Else = never>`](positive.ts#L17): check if `T` is a positive numeric value.
-- [`IsPositive<T, Then = true, Else = false>`](positive.ts#L40): is `T` a positive numeric value.
-- [`NotPositiveType<T, Then = T, Else = never>`](positive.ts#L54): check if `T` is not a positive numeric value.
-- [`IsNotPositive<T, Then = true, Else = false>`](positive.ts#L68): is `T` not a positive numeric value.
-
----
-
-`Negative<T>` and friends are used to check if `T` is a negative numeric value.
-
-The `number` and `bigint` can be considered as a union of all negative and negative numeric literals.
-
-That is why `IsNegative<T>` will yield `boolean` as the union is distributive.
-`Negative<T>` returns `T` for `number` and `bigint` for the same reason.
-It is a bit confusing but it is correct as it really returns `T | never`,
-which resolves to `T`.
-
-This behavior is different than `TrueType<T>` which `TrueType<boolean>` returns `never`.
-
-This is because `TrueType<T>` is checking for the exect `true` type,
-while `Negative<T>` is checking for a criteria of types (i.e. a set).
-
-```ts
-import type { Negative } from 'type-plus'
-
-type R = Negative<1> // never
-type R = Negative<1.0> // never
-type R = Negative<1n> // never
-
-type R = Negative<number> // number
-type R = Negative<any> // any
-
-type R = Negative<-1> // -1
-type R = Negative<'1'> // '1'
-```
-
-- [`Negative<T, Then = T, Else = never>`](negative.ts#L21): check if `T` is a negative numeric value.
-- [`IsNegative<T, Then = true, Else = false>`](negative.ts#L57): is `T` a negative numeric value.
-- [`NotNegativeType<T, Then = T, Else = never>`](negative.ts#L75): check if `T` is not a negative numeric value.
-- [`IsNotNegative<T, Then = true, Else = false>`](negative.ts#L109): is `T` not a negative numeric value.
-
 ## References
 
 - [Handbook]

package/ts/number/strict_number_type.ts

@@ -3,6 +3,11 @@ import type { IsAny } from '../any/any_type.js'
 /**
  * Check if the type `T` is exactly the type `number` and not numeric literals.
  *
+ * Note that if `T` is guaranteed to be a `number`, e.g. `SomeArray['length']`,
+ *
+ * A simple `number extends SomeArray['length'] ? Then, Else` is sufficient.
+ *
+ * @example
  * ```ts
  * type R = StrictNumberType<number> // true
  * type R = StrictNumberType<1> // false
@@ -20,6 +25,11 @@ export type StrictNumberType<T, Then = T, Else = never> = IsAny<
 /**
  * Is the type `T` exactly the type `number` and not numeric literals.
  *
+ * Note that if `T` is guaranteed to be a `number`, e.g. `SomeArray['length']`,
+ *
+ * A simple `number extends SomeArray['length'] ? Then, Else` is sufficient.
+ *
+ * @example
  * ```ts
  * type R = IsStrictNumber<number> // true
  * type R = IsStrictNumber<1> // false
@@ -33,6 +43,7 @@ export type IsStrictNumber<T, Then = true, Else = false> = StrictNumberType<T, T
 /**
  * Check if the type `T` is not the type `number` or numeric literals.
  *
+ * @example
  * ```ts
  * type R = NotStrictNumberType<number> // false
  * type R = NotStrictNumberType<1> // true
@@ -46,6 +57,7 @@ export type NotStrictNumberType<T, Then = T, Else = never> = StrictNumberType<T,
 /**
  * Is the type `T` not the type `number` or numeric literals.
  *
+ * @example
  * ```ts
  * type R = IsNotStrictNumber<number> // false
  * type R = IsNotStrictNumber<1> // true

package/ts/numeric/cast.ts

@@ -0,0 +1,28 @@
+import type { StringToBigint } from '../bigint/cast.js'
+import type { StringToNumber } from '../number/cast.js'
+
+/**
+ * Cast a string to a numeric literal type (number or bigint) if possible.
+ *
+ * ```ts
+ * StringToNumeric<'1'> // 1
+ * StringToNumeric<'1n'> // 1n
+ * StringToNumeric<'-1'> // -1
+ * StringToNumeric<'-1n'> // -1n
+ * ```
+ */
+export type StringToNumeric<S extends string, Fail = never> = StringToBigint<S, StringToNumber<S, Fail>>
+
+/**
+ * Cast a numeric literal type (number or bigint) to string.
+ *
+ * ```ts
+ * NumericToString<1> // '1'
+ * NumericToString<1.23> // '1.23'
+ * NumericToString<0.00123> // '0.00123'
+ * NumericToString<1n> // '1n'
+ * NumericToString<-1> // '-1'
+ * NumericToString<-1n> // '-1n'
+ * ```
+ */
+export type NumericToString<N extends number | bigint> = N extends number ? `${N}` : `${N}n`

package/ts/{number → numeric}/integer.ts

@@ -62,6 +62,8 @@ export type IsNotInteger<T, Then = true, Else = false> = NotInteger<T, Else, The
 /**
  * Check if T is an integer, including bigint.
  *
+ * @deprecated use `IsInteger` instead
+ *
  * ```ts
  * type R = IsWhole<0> // 0
  * type R = IsWhole<1n> // 1n

package/ts/numeric/numeric_plus.ts

@@ -0,0 +1,12 @@
+export type { Integer, IsInteger, IsNotInteger, IsWhole, NotInteger } from './integer.js'
+export type { IsNegative, IsNotNegative, Negative, NotNegative } from './negative.js'
+export type {
+	IsNotNumeric,
+	IsNumeric,
+	NotNumericType,
+	Numeric,
+	NumericType,
+	Zero
+} from './numeric_type.js'
+export type { IsNotPositive, IsPositive, NonPositive, Positive } from './positive.js'
+

package/ts/{number → numeric}/positive.ts

@@ -1,5 +1,5 @@
-import { IsAny } from '../any/any_type.js'
-import { IsNever } from '../index.js'
+import type { IsAny } from '../any/any_type.js'
+import type { IsNever } from '../index.js'
 
 /**
  * Check if `T` is a positive numeric type.

package/ts/numeric/readme.md

@@ -0,0 +1,115 @@
+# number
+
+## Type Checking
+
+`Numeric` type is either `number` or `bigint`.
+
+The `NumericType<T>` and friends are used to check if `T` is `number` or `bigint`.
+
+```ts
+import type { NumericType } from 'type-plus'
+
+type R = NumericType<number> // number
+type R = NumericType<bigint> // bigint
+type R = NumericType<1> // 1
+type R = NumericType<1n> // 1n
+
+type R = NumericType<never> // never
+```
+
+- [`NumericType<T, Then = T, Else = never>`](numeric_type.ts#L27): check if `T` is `number` or `bigint`.
+- [`IsNumeric<T, Then = true, Else = false>`](numeric_type.ts#L42): is `T` `number` or `bigint`.
+- [`NotNumericType<T, Then = T, Else = never>`](numeric_type.ts#L57): check if `T` is not `number` nor `bigint`.
+- [`IsNotNumeric<T, Then = true, Else = false>`](numeric_type.ts#L72): is `T` not `number` nor `bigint`.
+
+---
+
+`Integer<T>` and friends are used to check if `T` is an integer.
+
+```ts
+import type { Integer } from 'type-plus'
+
+type R = Integer<1> // 1
+type R = Integer<1.0> // 1.0
+
+type R = Integer<1.1> // never
+```
+
+- [`Integer<T, Then = T, Else = never>`](integer.ts#L17): check if `T` is an integer.
+- [`IsInteger<T, Then = true, Else = false>`](integer.ts#L36): is `T` an integer.
+- [`NotIntegerType<T, Then = T, Else = never>`](integer.ts#L51): check if `T` is not an integer.
+- [`IsNotInteger<T, Then = true, Else = false>`](integer.ts#L66): is `T` not an integer.
+- [`IsWhole<T, Then = true, Else = false>`](integer.ts#L81): same as `Integer<T>`, will be deprecated in the future.
+
+---
+
+`Positive<T>` and friends are used to check if `T` is a positive numeric value.
+
+The `number` and `bigint` can be considered as a union of all positive and negative numeric literals.
+
+That is why `IsPositive<T>` will yield `boolean` as the union is distributive.
+`Positive<T>` returns `T` for `number` and `bigint` for the same reason.
+It is a bit confusing but it is correct as it really returns `T | never`,
+which resolves to `T`.
+
+This behavior is different than `TrueType<T>` which `TrueType<boolean>` returns `never`.
+
+This is because `TrueType<T>` is checking for the exact `true` type,
+while `Positive<T>` is checking for a criteria of types (i.e. a set).
+
+```ts
+import type { Positive } from 'type-plus'
+
+type R = Positive<1> // 1
+type R = Positive<1.0> // 1.0
+type R = Positive<1n> // 1n
+
+type R = Positive<-1> // never
+type R = Positive<'1'> // never
+```
+
+- [`Positive<T, Then = T, Else = never>`](positive.ts#L17): check if `T` is a positive numeric value.
+- [`IsPositive<T, Then = true, Else = false>`](positive.ts#L40): is `T` a positive numeric value.
+- [`NotPositiveType<T, Then = T, Else = never>`](positive.ts#L54): check if `T` is not a positive numeric value.
+- [`IsNotPositive<T, Then = true, Else = false>`](positive.ts#L68): is `T` not a positive numeric value.
+
+---
+
+`Negative<T>` and friends are used to check if `T` is a negative numeric value.
+
+The `number` and `bigint` can be considered as a union of all negative and negative numeric literals.
+
+That is why `IsNegative<T>` will yield `boolean` as the union is distributive.
+`Negative<T>` returns `T` for `number` and `bigint` for the same reason.
+It is a bit confusing but it is correct as it really returns `T | never`,
+which resolves to `T`.
+
+This behavior is different than `TrueType<T>` which `TrueType<boolean>` returns `never`.
+
+This is because `TrueType<T>` is checking for the exact `true` type,
+while `Negative<T>` is checking for a criteria of types (i.e. a set).
+
+```ts
+import type { Negative } from 'type-plus'
+
+type R = Negative<1> // never
+type R = Negative<1.0> // never
+type R = Negative<1n> // never
+
+type R = Negative<number> // number
+type R = Negative<any> // any
+
+type R = Negative<-1> // -1
+type R = Negative<'1'> // '1'
+```
+
+- [`Negative<T, Then = T, Else = never>`](negative.ts#L21): check if `T` is a negative numeric value.
+- [`IsNegative<T, Then = true, Else = false>`](negative.ts#L57): is `T` a negative numeric value.
+- [`NotNegativeType<T, Then = T, Else = never>`](negative.ts#L75): check if `T` is not a negative numeric value.
+- [`IsNotNegative<T, Then = true, Else = false>`](negative.ts#L109): is `T` not a negative numeric value.
+
+## References
+
+- [Handbook]
+
+[handbook]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#the-primitives-string-number-and-boolean

package/ts/object/ANotB.ts

@@ -1,9 +1,9 @@
-import { Equal } from '../equal/equal.js'
+import type { IsEqual } from '../equal/equal.js'
 import type { AnyRecord } from './AnyRecord.js'
 import type { IsDisjoint } from './IsDisjoint.js'
 import type { KeysWithDiffType } from './KeysWithDiffType.js'
 
-export type ANotB<A extends AnyRecord, B extends AnyRecord> = Equal<A, B> extends true
+export type ANotB<A extends AnyRecord, B extends AnyRecord> = IsEqual<A, B> extends true
 	? never
 	: IsDisjoint<A, B> extends true
 	? A
@@ -11,7 +11,7 @@ export type ANotB<A extends AnyRecord, B extends AnyRecord> = Equal<A, B> extend
 
 export type BNotA<A extends AnyRecord, B extends AnyRecord> = ANotB<B, A>
 
-export type LeftJoin<A extends AnyRecord, B extends AnyRecord> = Equal<A, B> extends true
+export type LeftJoin<A extends AnyRecord, B extends AnyRecord> = IsEqual<A, B> extends true
 	? A
 	: IsDisjoint<A, B> extends true
 	? A & B

package/ts/object/Partial.ts

@@ -2,6 +2,11 @@ import type { UnionKeys } from '../union_keys.js'
 import type { Omit } from './omit.js'
 import type { Pick } from './pick.js'
 
+/**
+ * An alternative `Partial<T>` type that works with `exactOptionalPropertyTypes`
+ */
+export type Partial<T> = { [P in keyof T]?: T[P] | undefined }
+
 /**
  * Apply `Partial<>` on the selected properties.
  */

package/ts/object/Required.ts

@@ -1,5 +1,9 @@
 // Thanks [jack-williams](https://github.com/jack-williams) for the [solution](https://github.com/Microsoft/TypeScript/issues/29269#issuecomment-451602962)
 
+import { NonUndefined } from '../utils/NonUndefined.js'
+
+export type Required<T> = { [P in keyof T]-?: NonUndefined<T[P]> }
+
 export type RequiredPick<T, U extends keyof T> = Required<Pick<T, U>> & Pick<T, Exclude<keyof T, U>>
 
 export type RequiredExcept<T, U extends keyof T> = Required<Pick<T, Exclude<keyof T, U>>> & Pick<T, U>

package/ts/object/index.ts

@@ -8,7 +8,7 @@ export type { KeysOfOptional } from './KeyofOptional.js'
 export type { KeysWithDiffType } from './KeysWithDiffType.js'
 export type { KnownKeys } from './KnownKeys.js'
 export type { OptionalKeys } from './OptionalKeys.js'
-export type { PartialExcept, PartialOmit, PartialPick } from './Partial.js'
+export type { Partial, PartialExcept, PartialOmit, PartialPick } from './Partial.js'
 export type { RecursiveIntersect } from './RecursiveIntersect.js'
 export type { RecursivePartial } from './RecursivePartial.js'
 export type { RecursiveRequired } from './RecursiveRequired.js'

package/ts/object/object_type.ts

@@ -16,7 +16,7 @@ export type ObjectType<T, Then = T, Else = never> = IsAnyOrNever<T, Else, [T] ex
 /**
  * Is `T` an `object`.
  *
- * Note that `Function` is also an `object`.
+ * Note that `Function`, `Array`, and *tuple* are also `object`.
  *
  * ```ts
  * type R = IsObject<{}> // true

package/ts/object/split.ts

@@ -2,10 +2,12 @@
 import type { AnyRecord } from './AnyRecord.js'
 import type { Omit } from './omit.js'
 import { reduceByKey } from './reduceKey.js'
+import type { Partial } from './Partial.js'
+import { NonUndefined } from '../utils/NonUndefined.js'
 
 type Splitter<T extends AnyRecord> = Partial<{ [k in keyof T]: T[k] | undefined }>
 export type Split<T extends AnyRecord, S extends AnyRecord> = {
-	[k in keyof S]-?: S[k] extends undefined ? T[k] : NonNullable<T[k]> | S[k]
+	[k in keyof S]-?: S[k] extends undefined ? T[k] : NonNullable<T[k]> | NonUndefined<S[k]>
 }
 
 /**

package/ts/predicates/CanAssign.ts

@@ -3,6 +3,26 @@ import type { IsEmptyObject } from './IsEmptyObject.js'
 
 /**
  * Can `A` assign to `B`
+ *
+ * Note that when union is involved, the assignability is measured distributively.
+ * Meaning the result can be `Then | Else` (i.e. `boolean` by default),
+ * instead of distinctive `Then` (`true`) or `Else` (`false`).
+ *
+ * This is the correct behavior.
+ *
+ * @example
+ * ```ts
+ * CanAssign<number | string, number> // boolean
+ * ```
+ *
+ * We are checking can `A` assign to `B`.
+ * Since `A` is `number | string`,
+ * `A` can assign to `B` when `A` is number` (true), and
+ * `A` cannot assign to `B` when `A` is string` (false).
+ * So the result is `true | false = boolean`.
+ *
+ * If you want to make sure all branches are assignable,
+ * use `StrictCanAssign<A, B>`.
  */
 export type CanAssign<A, B, Then = true, Else = false> = IsEmptyObject<A> extends true
 	? Record<string, unknown> extends B
@@ -16,6 +36,32 @@ export type CanAssign<A, B, Then = true, Else = false> = IsEmptyObject<A> extend
 	? Then
 	: Else
 
+/**
+ * Can `A` strictly assign to `B`.
+ *
+ * All branches in an union `A` are assignable to `B`.
+ *
+ * @example
+ * ```ts
+ * StrictCanAssign<number | string, number> // false
+ * StrictCanAssign<number | string, number | string> // true
+ * ```
+ */
+export type StrictCanAssign<A, B, Then = true, Else = false> = IsEmptyObject<A> extends true
+	? Record<string, unknown> extends B
+		? Then
+		: Else
+	: boolean extends A
+	? boolean extends B
+		? Then
+		: Else
+	: [A] extends [B]
+	? Then
+	: Else
+
+/**
+ * @deprecated use `CanAssign` instead
+ */
 export type IsAssign<A, B, Then = true, Else = false> = CanAssign<A, B, Then, Else>
 
 export function canAssign<T>(canAssign: false): <S>(subject: NotExtendable<S, T>) => true

package/ts/predicates/Extends.ts

@@ -1,4 +1,4 @@
-export type Extendable<A, B> = A extends B ? A : never
-export type NotExtendable<A, B> = A extends B ? never : A
+export type Extendable<A, B, Then = A, Else = never> = A extends B ? Then : Else
+export type NotExtendable<A, B, Then = A, Else = never> = A extends B ? Else : Then
 export type IsExtend<A, B, Then = true, Else = false> = A extends B ? Then : Else
 export type IsNotExtend<A, B, Then = true, Else = false> = A extends B ? Else : Then

package/ts/predicates/index.ts

@@ -2,7 +2,6 @@ export * from './CanAssign.js'
 export type { Extendable, IsExtend, IsNotExtend, NotExtendable } from './Extends.js'
 export type { If } from './If.js'
 export type { IsEmptyObject } from './IsEmptyObject.js'
-export * from './isType.js'
 export type { And, Not, Or, Xor } from './logical.js'
 
 export type IsLiteral<T extends number | string, Then = true, Else = false> = number extends T