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

package/src/nominal/flavor.ts

@@ -0,0 +1,51 @@
+// 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 '../type-guard/is_type.js'
+import type { Widen } from '../utils/index.js'
+import { typeSym, valueSym } from './constants.js'
+
+/**
+ * Create a "flavored" version of a type.
+ * TypeScript will disallow mixing flavors,
+ * but will allow unflavored values of that type to be passed in where a flavored version is expected.
+ * This is a less restrictive form of branding.
+ */
+export type Flavor<F extends string, T> = [T] extends [null] | [undefined] | [symbol] | [void]
+	? FlavoredUnit<F, T>
+	: Flavored<F> & T
+
+/**
+ * A flavored type of `F`
+ */
+export interface Flavored<F extends string> {
+	[typeSym]?: F
+}
+
+/**
+ * A special flavored type for special types.
+ */
+export interface FlavoredUnit<F extends string, T> {
+	[typeSym]?: F,
+	[valueSym]: T
+}
+
+/**
+ * Creates a brand creator with the specified type.
+ */
+export function flavor<F extends string>(type: F): <T>(subject: T) => Flavor<F, Widen<T>>
+/**
+ * Creates a branded value of specified type.
+ */
+export function flavor<F extends string, T>(type: F, subject: T): Flavor<F, Widen<T>>
+export function flavor(type: string, subject?: unknown) {
+	if (subject === undefined)
+		return <T>(subject: T) => flavor(type, subject)
+
+	if (isType<{ [typeSym]: string }>(subject, s => typeof s === 'object' && s !== null)) {
+		// if subject is not an object, the branding will exist only in type-level.
+		subject[typeSym] = type
+	}
+
+	return subject
+}

package/src/nominal/nominal_match.ts

@@ -0,0 +1,21 @@
+import type { Brand } from './brand.js'
+import { typeSym } from './constants.js'
+import type { Flavor } from './flavor.js'
+
+export function nominalMatch<A extends string, B extends A>(
+	a: Brand<A, unknown>,
+	b: Brand<B, unknown>
+): boolean
+export function nominalMatch<A extends string, B extends A>(
+	a: Flavor<A, unknown>,
+	b: Flavor<B, unknown>
+): boolean
+export function nominalMatch<A extends string, B extends A>(
+	a: Brand<A, unknown> | Flavor<A, unknown>,
+	b: Brand<B, unknown> | Flavor<B, unknown>
+) {
+	if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null)
+		return a[typeSym] === b[typeSym]
+
+	return true
+}

package/src/null/is_not_null.ts

@@ -0,0 +1,79 @@
+import type { NotAssignable } from '../predicates/not_assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Then } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is not `null`.
+ *
+ * ```ts
+ * type R = IsNotNull<null> // false
+ *
+ * type R = IsNotNull<never> // true
+ * type R = IsNotNull<unknown> // true
+ * type R = IsNotNull<string | boolean> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not `null`, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNull<null, { selection: 'filter' }> // never
+ *
+ * type R = IsNotNull<never, { selection: 'filter' }> // never
+ * type R = IsNotNull<unknown, { selection: 'filter' }> // unknown
+ * type R = IsNotNull<string | boolean, { selection: 'filter' }> // string | boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Disable distribution of union types.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNull<null | 1> // boolean
+ * type R = IsNotNull<null | 1, { distributive: false }> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNull<string, $SelectionBranch> // $Then
+ * type R = IsNotNull<null, $SelectionBranch> // $Else
+ * ```
+ */
+export type IsNotNull<T, $O extends IsNotNull.$Options = {}> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Then]>,
+			$else: IsNotNull.$<T, $O>
+		}
+	>
+>
+
+
+export namespace IsNotNull {
+	export type $Options = $Equality.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is not `null`.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> = NotAssignable.$<T, null, $O>
+
+	export type $UtilOptions = NotAssignable.$UtilOptions
+}

package/src/null/is_null.ts

@@ -0,0 +1,83 @@
+import type { Assignable } from '../predicates/assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is `null`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNull<null> // true
+ *
+ * type R = IsNull<never> // false
+ * type R = IsNull<unknown> // false
+ * type R = IsNull<string | boolean> // false
+ *
+ * type R = IsNull<string | null> // boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is `null`, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNull<null, { selection: 'filter' }> // null
+ *
+ * type R = IsNull<never, { selection: 'filter' }> // never
+ * type R = IsNull<unknown, { selection: 'filter' }> // never
+ * type R = IsNull<string | boolean, { selection: 'filter' }> // never
+ *
+ * type R = IsNull<string | null> // null
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = IsNull<null | 1> // boolean
+ * type R = IsNull<null | 1, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNull<null, $SelectionBranch> // $Then
+ * type R = IsNull<string, $SelectionBranch> // $Else
+ * ```
+ */
+export type IsNull<T, $O extends IsNull.$Options = {}> =
+	$SpecialType<T,
+		$MergeOptions<$O,
+			{
+				$then: $ResolveBranch<T, $O, [$Else]>,
+				$else: IsNull.$<T, $O>
+			}
+		>
+	>
+
+export namespace IsNull {
+	export type $Options = $Equality.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is `null`.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> = Assignable.$<T, null, $O>
+
+	export type $UtilOptions = Assignable.$UtilOptions
+}

package/src/null/readme.md

@@ -0,0 +1,107 @@
+# null
+
+`null` is one of the two primitive values in JavaScript to represent the absence of a value.
+
+Most of the time it is used when working with objects from JSON.
+
+## [IsNull](./is_null.ts)
+
+`IsNull<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is `null`.
+
+```ts
+type R = IsNull<null> // true
+
+type R = IsNull<never> // false
+type R = IsNull<unknown> // false
+type R = IsNull<string | boolean> // false
+
+type R = IsNull<string | null> // boolean
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is `null`, otherwise returns `never`.
+
+```ts
+type R = IsNull<null, { selection: 'filter' }> // null
+
+type R = IsNull<never, { selection: 'filter' }> // never
+type R = IsNull<unknown, { selection: 'filter' }> // never
+type R = IsNull<string | boolean, { selection: 'filter' }> // never
+
+type R = IsNull<string | null> // null
+```
+
+🔢 *customize*:
+
+Disable distribution of union types.
+
+```ts
+type R = IsNull<null | 1> // boolean
+type R = IsNull<null | 1, { distributive: false }> // false
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsNull<null, $SelectionBranch> // $Then
+type R = IsNull<string, $SelectionBranch> // $Else
+```
+
+## [IsNotnull](./is_not_null.ts)
+
+`IsNotnull<T, { distributive: true, selection: 'predicate' | 'filter', $then: true, $else: false }>`
+
+🎭 *predicate*
+
+Validate if `T` is not `null`.
+
+```ts
+type R = IsNotnull<null> // false
+
+type R = IsNotnull<never> // true
+type R = IsNotnull<unknown> // true
+type R = IsNotnull<string | boolean> // true
+```
+
+🔢 *customize*
+
+Filter to ensure `T` is not `null`, otherwise returns `never`.
+
+```ts
+type R = IsNotnull<null, { selection: 'filter' }> // never
+
+type R = IsNotnull<never, { selection: 'filter' }> // never
+type R = IsNotnull<unknown, { selection: 'filter' }> // unknown
+type R = IsNotnull<string | boolean, { selection: 'filter' }> // string | boolean
+```
+
+🔢 *customize*
+
+Disable distribution of union types.
+
+```ts
+type R = IsNotnull<null | 1> // boolean
+type R = IsNotnull<null | 1, { distributive: false }> // true
+```
+
+🔢 *customize*
+
+Use unique branch identifiers to allow precise processing of the result.
+
+```ts
+type R = IsNotnull<string, $SelectionBranch> // $Then
+type R = IsNotnull<null, $SelectionBranch> // $Else
+```
+
+## References
+
+- [Handbook]
+
+[handbook]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#null-and-null

package/src/number/is_not_number.ts

@@ -0,0 +1,99 @@
+import type { NotAssignable } from '../predicates/not_assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $ResolveOptions } from '../type_plus/$resolve_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $Exact } from '../type_plus/branch/$exact.js'
+import type { $IsDistributive } from '../type_plus/branch/$is_distributive.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $Then } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is not `number` nor `number` literals.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNumber<number> // false
+ * type R = IsNotNumber<1> // false
+ *
+ * type R = IsNotNumber<never> // true
+ * type R = IsNotNumber<unknown> // true
+ * type R = IsNotNumber<string | number> // boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not `number` nor `number` literals, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNumber<number, { selection: 'filter' }> // never
+ * type R = IsNotNumber<1, { selection: 'filter' }> // never
+ *
+ * type R = IsNotNumber<never, { selection: 'filter' }> // never
+ * type R = IsNotNumber<unknown, { selection: 'filter' }> // unknown
+ * type R = IsNotNumber<string | 1, { selection: 'filter' }> // string
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Disable distribution of union types.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNumber<number | 1> // boolean
+ * type R = IsNotNumber<number | 1, { distributive: false }> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNumber<string, $SelectionBranch> // $Then
+ * type R = IsNotNumber<number, $SelectionBranch> // $Else
+ * ```
+ */
+export type IsNotNumber<T, $O extends IsNotNumber.$Options = {}> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Then]>,
+			$else: IsNotNumber.$<T, $O>
+		}
+	>
+>
+
+export namespace IsNotNumber {
+	export type $Options = $Equality.$Options & $Exact.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is not `number` nor `number` literals.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> =
+		$ResolveOptions<[$O['exact'], false]> extends true
+		? $IsDistributive<$O, { $then: _D<T, $O>, $else: _N<T, $O> }>
+		: NotAssignable.$<T, number, $O>
+	export type $UtilOptions = NotAssignable.$UtilOptions & $Exact.$Options
+	export type _D<T, $O extends IsNotNumber.$Options> =
+	T extends number & infer U
+	? (
+		U extends number
+		? $ResolveBranch<T, $O, [$Then]>
+		: $ResolveBranch<T, $O, [$Else]>
+	)
+		: $ResolveBranch<T, $O, [$Then]>
+	export type _N<T, $O extends IsNotNumber.$Options> =
+		[T] extends [number & infer U] ?
+		U extends number ? $ResolveBranch<T, $O, [$Then]>
+		: $ResolveBranch<T, $O, [$Else]>
+		: $ResolveBranch<T, $O, [$Then]>
+}

package/src/number/is_not_number_literal.ts

@@ -0,0 +1,101 @@
+import type { Assignable } from '../predicates/assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $IsDistributive } from '../type_plus/branch/$is_distributive.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $Then } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is not number literals.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNumberLiteral<number> // true
+ * type R = IsNotNumberLiteral<1> // false
+ *
+ * type R = IsNotNumberLiteral<never> // true
+ * type R = IsNotNumberLiteral<unknown> // true
+ * type R = IsNotNumberLiteral<string | boolean> // true
+ *
+ * type R = IsNotNumberLiteral<string | 1> // boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not number literals, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNumberLiteral<number, { selection: 'filter' }> // number
+ * type R = IsNotNumberLiteral<1, { selection: 'filter' }> // never
+ *
+ * type R = IsNotNumberLiteral<never, { selection: 'filter' }> // never
+ * type R = IsNotNumberLiteral<unknown, { selection: 'filter' }> // unknown
+ * type R = IsNotNumberLiteral<1 | string, { selection: 'filter' }> // string
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = IsNotNumberLiteral<1 | string> // boolean
+ * type R = IsNotNumberLiteral<1 | string, { distributive: false }> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotNumberLiteral<1, $SelectionBranch> // $Else
+ * type R = IsNotNumberLiteral<string, $SelectionBranch> // $Then
+ * ```
+ */
+export type IsNotNumberLiteral<T, $O extends IsNotNumberLiteral.$Options = {}> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Then]>,
+			$else: IsNotNumberLiteral.$<T, $O>
+		}
+	>
+>
+
+export namespace IsNotNumberLiteral {
+	export type $Options = $Equality.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is not number literals.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> =
+		$IsDistributive<$O, {
+			$then: _D<T, $O>,
+			$else: _N<T, $O>
+		}>
+
+	export type $UtilOptions = Assignable.$UtilOptions
+
+	export type _D<T, $O extends $UtilOptions> =
+		T extends number & infer U
+		? (
+			U extends number
+			? $ResolveBranch<T, $O, [$Else]>
+			: $ResolveBranch<T, $O, [$Then]>
+		)
+		: $ResolveBranch<T, $O, [$Then]>
+	export type _N<T, $O extends $UtilOptions> =
+		[T] extends [number & infer U] ?
+		U extends number ? $ResolveBranch<T, $O, [$Else]>
+		: $ResolveBranch<T, $O, [$Then]>
+		: $ResolveBranch<T, $O, [$Then]>
+}

package/src/number/is_number.ts

@@ -0,0 +1,103 @@
+import type { Assignable } from '../predicates/assignable.js'
+import type { $Equality } from '../type_plus/$equality.js'
+import type { $MergeOptions } from '../type_plus/$merge_options.js'
+import type { $ResolveOptions } from '../type_plus/$resolve_options.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $Exact } from '../type_plus/branch/$exact.js'
+import type { $IsDistributive } from '../type_plus/branch/$is_distributive.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $Then } from '../type_plus/branch/$selection.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is `number` or `number` literals.
+ *
+ * @example
+ * ```ts
+ * type R = IsNumber<number> // true
+ * type R = IsNumber<1> // true
+ *
+ * type R = IsNumber<never> // false
+ * type R = IsNumber<unknown> // false
+ * type R = IsNumber<string | boolean> // false
+ *
+ * type R = IsNumber<string | number> // boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is `number` or `number` literals, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNumber<number, { selection: 'filter' }> // number
+ * type R = IsNumber<1, { selection: 'filter' }> // 1
+ *
+ * type R = IsNumber<never, { selection: 'filter' }> // never
+ * type R = IsNumber<unknown, { selection: 'filter' }> // never
+ * type R = IsNumber<string | boolean, { selection: 'filter' }> // never
+ *
+ * type R = IsNumber<string | number> // number
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = IsNumber<number | 1> // boolean
+ * type R = IsNumber<number | 1, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNumber<number, $SelectionBranch> // $Then
+ * type R = IsNumber<string, $SelectionBranch> // $Else
+ * ```
+ */
+export type IsNumber<T, $O extends IsNumber.$Options = {}> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Else]>,
+			$else: IsNumber.$<T, $O>
+		}
+	>
+>
+
+export namespace IsNumber {
+	export type $Options = $Equality.$Options & $Exact.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is `number` or `number` literals.
+	 *
+	 * This is a type util for building custom types.
+	 * It does not check against special types.
+	 */
+	export type $<T, $O extends $UtilOptions> =
+		$ResolveOptions<[$O['exact'], false]> extends true
+		? $IsDistributive<$O, { $then: _D<T, $O>, $else: _N<T, $O> }>
+		: Assignable.$<T, number, $O>
+	export type $UtilOptions = Assignable.$UtilOptions & $Exact.$Options
+
+	export type _D<T, $O extends $UtilOptions> =
+	T extends number & infer U
+	? (
+		U extends number
+		? $ResolveBranch<T, $O, [$Else]>
+		: $ResolveBranch<T, $O, [$Then]>
+	)
+		: $ResolveBranch<T, $O, [$Else]>
+	export type _N<T, $O extends $UtilOptions> =
+		[T] extends [number & infer U] ?
+		U extends number ? $ResolveBranch<T, $O, [$Else]>
+		: $ResolveBranch<T, $O, [$Then]>
+		: $ResolveBranch<T, $O, [$Else]>
+}