type-plus 8.0.0-beta.6 → 8.0.0-beta.8

package/src/$type/branch/$resolve_branch.ts

@@ -0,0 +1,46 @@
+import type { $Type } from '../$type.js'
+import type { $InferError } from '../errors/$infer_error.js'
+import type { $Branch } from './$branch.js'
+import type { $Else, $Then } from './$selection.js'
+
+/**
+ * Resolve option value based on list of branches.
+ * It returns the first branch value that is specified in the option,
+ * otherwise will return the default value.
+ *
+ * Since this is an type utility,
+ * it does not perform extensive validations.
+ * Please check the description of each input below for information.
+ *
+ * @typeparam $O The input option. It should be a Record, not any, unknown, or never
+ * @typeparam $B Tuple of branches with at least one entry.
+ * @typeparam D Default value to return if no branch is found.
+ */
+export type $ResolveBranch<
+	$O extends Record<string, any>,
+	$Branches extends Array<$Branch<any> | unknown>,
+	D = unknown,
+> = $Branches extends [infer B]
+	? _Last<$O, B, D>
+	: $Branches extends [infer B, ...infer Rest extends Array<$Branch<any> | unknown>]
+		? _<$O, B, $ResolveBranch<$O, Rest, D>>
+		: $InferError<'$Branches must have at least one entry'>
+
+type _<$O extends Record<string, any>, $B, D> = $B extends $Branch<any>
+	? $B[$Type.$ValueKey] extends keyof $O
+		? $O[$B[$Type.$ValueKey]]
+		: D
+	: D
+type _Last<$O extends Record<string, any>, $B, D> = $B extends $Then
+	? '$then' extends keyof $O
+		? $O['$then']
+		: $O['selection'] extends 'filter'
+			? D
+			: true
+	: $B extends $Else
+		? '$else' extends keyof $O
+			? $O['$else']
+			: $O['selection'] extends 'filter'
+				? never
+				: false
+		: _<$O, $B, D>

package/src/$type/branch/$selection.ts

@@ -0,0 +1,170 @@
+import type { $Branch } from './$branch.js'
+
+export type $Then = $Branch<'$then'>
+export type $Else = $Branch<'$else'>
+
+declare const $then: '$then'
+declare const $else: '$else'
+
+export namespace $Then {
+	export type $Key = '$then'
+	export type $Branch = {
+		[$then]: $Then
+	}
+}
+
+export namespace $Else {
+	export type $Key = '$else'
+	export type $Branch = {
+		[$else]: $Else
+	}
+}
+
+export namespace $Selection {
+	/**
+	 * Options for selection (if-then-else) logic.
+	 *
+	 * The word "selection" refers to the basic elements in structural programming:
+	 * sequence, selection, and iteration.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<
+	 *   T,
+	 *   $Options extends YourType.$Options = YourType.$Branch
+	 * > = ...
+	 *
+	 * namespace YourType {
+	 *   export type $Options = $SelectionOptions
+	 *   export type $Branch = $SelectionBranch
+	 * }
+	 * ```
+	 */
+	export type Options = {
+		/**
+		 * Specifies which default selection logic to use.
+		 *
+		 * `filter` returns `T` when the condition is met,
+		 * and returns `never` otherwise.
+		 *
+		 * `predicate` returns boolean depends on the condition.
+		 *
+		 * Note that setting `$then` and `$else` overrides the default selection logic.
+		 */
+		selection?: 'predicate' | 'filter' | undefined
+		$then?: unknown
+		$else?: unknown
+	}
+
+	export type $BaseOptions = {
+		$then?: unknown
+		$else?: unknown
+	}
+
+	/**
+	 * Invert the selection branch.
+	 *
+	 * i.e.
+	 * - `$Then` -> `$Else`
+	 * - `$Else` -> `$Then`
+	 */
+	export type Invert<Branch extends $Then | $Else> = Branch extends $Then ? $Else : $Then
+
+	/**
+	 * Branch option for selection logic.
+	 * It allows finely customizing the behavior of your type.
+	 *
+	 * Using this as the default value of your `$Options` is the recommended best practice.
+	 *
+	 * This encourage consumer of your type to use conditional type to avoid performance issues.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<
+	 *   T,
+	 *   $Options extends YourType.$Options = YourType.$Branch
+	 * > = ...
+	 *
+	 * namespace YourType {
+	 *   export type $Options = $SelectionOptions
+	 *   export type $Branch = $SelectionBranch
+	 * }
+	 *
+	 * type R = YourType<T> extends infer R
+	 *   ? R extends $Then ? HandleThen
+	 *   : R extends $Else ? HandleElse
+	 *   : never
+	 * ```
+	 */
+	export type Branch<$O extends $Selection.Options = {}> = {
+		[$then]: $Then
+		[$else]: $Else
+	} & $O
+
+	/**
+	 * Default Options for filter selection logic.
+	 *
+	 * `filter` means the logic returns `T` when the condition is met,
+	 * and returns `never` otherwise.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<
+	 *   T,
+	 *   Options extends YourType.$Options = YourType.$Default> = ...
+	 *
+	 * namespace YourType {
+	 *   export type $Options = $SelectionOptions
+	 *   export type $Default = $SelectionFilter
+	 * }
+	 *
+	 * type R = YourType<ThenType> // ThenType
+	 * type X = YourType<ElseType> // never
+	 * ```
+	 */
+	export type Filter<T> = {
+		selection: 'filter'
+		[$then]: T
+		[$else]: never
+	}
+
+	/**
+	 * Default Options for predicate selection logic.
+	 *
+	 * `predicate` means the logic returns `true` or `false` depending on the condition.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<
+	 *   T,
+	 *   Options extends YourType.$Options = YourType.$Default> = ...
+	 *
+	 * namespace YourType {
+	 *   export type $Options = $SelectionOptions
+	 *   export type $Default = $SelectionPredicate
+	 * }
+	 *
+	 * type R = YourType<ThenType> // true
+	 * type X = YourType<ElseType> // false
+	 * ```
+	 */
+	export type Predicate = {
+		[$then]: true
+		[$else]: false
+	}
+
+	/**
+	 * Flip the selection options.
+	 *
+	 * @example
+	 * ```ts
+	 * type IsBoolean<T, $Options = $SelectionOptions> = ...
+	 *
+	 * type IsNotBoolean<T, $Options = $SelectionOptions> = IsBoolean<T, $FlipSelection<$Options>>
+	 * ```
+	 */
+	export type Flip<$Options extends $Selection.Options> = {
+		[$then]: $Options['$else']
+		[$else]: $Options['$then']
+	} & Omit<$Options, '$then' | '$else'>
+}

package/src/$type/branch/readme.md

@@ -0,0 +1,78 @@
+# Type-level branching
+
+This folder contains utility types related to type-level branching.
+
+Type-level branching is a core mechanism in [`type-plus`](../../../readme.md) for type-level programming.
+
+In essence, type-level branching is a way to separate the type-level logic based on some conditions.
+
+There are a few elements to make branching work:
+
+## Branch Options
+
+To participate in branching, a type should accept a `$O` option.
+
+The option would accept a branch property, typically with `unknown` as the type.
+The branch property it accustomed to be named `$<key>`.
+Its key can also be referred to as branch identifier,
+but typically we would just call it by name.
+
+Here we use [`IsAny`](../../any/is_any.ts) as an example:
+
+```ts
+type IsAny<T, $O extends {
+	$unknown?: unknown
+	$never?: unknown
+	$then?: unknown
+	$else?: unknown
+ }> = ...
+```
+
+Note that the actual definition of `IsAny` looks different, but the idea is the same.
+
+The property keys `$unknown`, `$never`, `$then`, and `$else` are branch identifiers.
+They come from individual options: `$Unknown.$Options`, `$Never.$Options`, `$SelectionOptions`.
+
+When you implement your type with branching support,
+you can use these branch options and compose them.
+
+## Branch Selectors
+
+Branch selectors are used to select a branch during resolution.
+There are a few branch selectors provided in [`type-plus`](../../../readme.md): `$Any`, `$Unknown`, `$Never`, `$Void`, `$Then`, and `$Else`.
+
+They are primarily used with `$ResolveBranch` inside the type.
+
+```ts
+export type SomeType<T, $O extends $SelectionOptions> = ...
+	? $ResolveBranch<$O, [$Then], T>
+	: $ResolveBranch<$O, [$Else]>
+```
+
+## Branching Types
+
+There are a few branching provided in [`type-plus`](../../../readme.md).
+
+### Selection Branching
+
+The most common branching is `$Selection`, referring to "selection" in the 3 fundamental building blocks of structured programming: sequence, selection, and iteration.
+
+Using `IsAny` as an example, we can see how branching works:
+
+```ts
+type R = IsAny<any, { $then: 1, $else: 2 }> // 1
+type R = IsAny<number, { $then: 1, $else: 2 }> // 2
+```
+
+### Special Types Branching
+
+Special types in TypeScript are: `any`, `unknown`, `never`, and `void`.
+
+Besides selection branching, many types in [`type-plus`](../../../readme.md) provide specific branching for special types in TypeScript.
+
+Using `IsAny` as an example again:
+
+```ts
+type R = IsAny<unknown, { $unknown: 'u', $then: 1, $else: 2 }> // u
+type R = IsAny<never, { $never: 'n', $then: 1, $else: 2 }> // n
+```

package/src/$type/distributive/$distributive.ts

@@ -0,0 +1,34 @@
+import type { $ResolveOptions } from '../$resolve_options.js'
+import type { $InputOptions } from '../branch/$input_options.js'
+import type { $Else, $Then } from '../branch/$selection.js'
+
+export namespace $Distributive {
+	/**
+	 * Options for controlling if the type is distributive.
+	 */
+	export type Options = {
+		distributive?: boolean | undefined
+	}
+
+	/**
+	 * Default options for `distributive` behavior.
+	 *
+	 * By default it is `true`.
+	 */
+	export type Default = {
+		distributive: true
+	}
+
+	/**
+	 * Parse the options for `distributive`.
+	 */
+	export type Parse<$Options extends Options, $O extends $InputOptions<$Then | $Else> = {}> = $ResolveOptions<
+		[$Options['distributive'], Default['distributive']]
+	> extends true
+		? '$then' extends keyof $O
+			? $O['$then']
+			: true
+		: '$else' extends keyof $O
+			? $O['$else']
+			: false
+}

package/src/$type/distributive/readme.md

@@ -0,0 +1,26 @@
+# Distributive
+
+Distributive in TypeScript means each type in a union type is treated as a separate type during type calculation.
+
+Each type in a union type is passed through the type calculation independently.
+
+## [`$Distributive.Options`](./$distributive.ts)
+
+🏷️ **since 8.0.0**
+
+Many types in this library are distributive.
+
+`$Distributive.Options` is a type option indicating the type support distributive and non-distributive mode.
+
+## [`$Distributive.Default`](./$distributive.ts)
+
+🏷️ **since 8.0.0**
+
+`$Distributive.Default` is the default value for [`$Distributive.Options`](#distributiveoptions).
+`distributive` is `true` by default.
+
+## [`$Distributive.Parse`](./$distributive.ts)
+
+🏷️ **since 8.0.0**
+
+`$Distributive.Parse<$Option, $O>` checks if a type `$Option` enables distributive or not.

package/src/$type/errors/$error.ts

@@ -0,0 +1,20 @@
+import type { $Type } from '../$type.js'
+
+/**
+ * 🧰 *type util*
+ *
+ * A type-level error.
+ *
+ * This is analogous to the `Error` class in JavaScript.
+ *
+ * It can be used in type-level programming to represent an error with a message.
+ *
+ * @example
+ * ```ts
+ * type T = $Error<'error message'>
+ * type T = $Error<'error message', number>
+ * ```
+ *
+ * @since 8.0.0
+ */
+export type $Error<M extends string, T = unknown> = M extends any ? $Type<'error', { message: M; type: T }> : never

package/src/{type_plus → $type/errors}/$infer_error.ts

@@ -1,23 +1,22 @@
-import type { $Type } from './$type.js'
+import type { $Error } from './$error.js'
 
 /**
- * 🧰 *type util*
- *
- * An error for unexpected failure of infer type.
+ * An error to indicate unexpected failure when inferring type.
  *
  * In your type,
  * you can use `T extends infer U extends V` to specify the type of the inferred type `U`.
  *
  * But doing so means you have to do an extra conditional type.
  *
- * This type can be use in the else case to indicate unexpected failure to infer the type.
+ * This type can be use in the else case to indicate unexpected failure when inferring type.
  *
+ * @example
  * ```ts
  * type F<T> = T extends infer U extends V
  *   ? ...your type logic...
  *   : InferError<'some message', T>
  * ```
+ *
+ * @since 8.0.0
  */
-export type $InferError<M extends string, T = unknown> = M extends any
-	? $Type<'error', `Unable to infer: ${M}`, T>
-	: never
+export type $InferError<M extends string, T = unknown> = M extends any ? $Error<`Unable to infer: ${M}`, T> : never

package/src/{type → $type/errors}/failed.ts

@@ -1,6 +1,8 @@
 declare const uniSym: unique symbol
 
 /**
+ * @deprecated **💀 deprecated since 8.0.0**: use `$Error` instead.
+ *
  * A failed type with message.
  *
  * This is analogous to the `Error` class in JavaScript.
@@ -19,6 +21,8 @@ export interface Failed<Msg extends string> {
 }
 
 /**
+ * @deprecated **💀 deprecated since 8.0.0**: use `$Error` instead.
+ *
  * A failed type with message and one additional type.
  *
  * Use this to add a generic type to the failed type.

package/src/$type/errors/readme.md

@@ -0,0 +1,60 @@
+# Type-level Errors
+
+This folder contains error types for type-level programming.
+
+## [`$Error`](./error.ts)
+
+🏷️ **since 8.0.0**
+
+`$Error<M, V = unknown>` is a basic type-level error.
+You can use this for some ad-hoc errors.
+
+This is analogous to the `Error` class ~~in~~ JavaScript.
+
+```ts
+type YourComplexType<A, B, C> = A extends B ?
+	... // and many more hard work later...
+	: $Error<'you are doing something wrong!'>
+
+type YourComplexType<A, B, C> = A extends B ?
+	... // and many more hard work later...
+	: $Error<'you are doing something wrong!', C>
+```
+
+## [`$InferError`](./infer_error.ts)
+
+🏷️ **since 8.0.0**
+
+`$InferError<T>` is an error for unexpected failure when inferring type.
+
+In your type,
+you can use `T extends infer U extends V` to specify the type of the inferred type `U`.
+
+But doing so means you have to do an extra conditional type.
+
+This type can be use in the else case to indicate unexpected failure to infer the type.
+
+```ts
+type F<T> = T extends infer U extends V
+	? ...your type logic...
+	: InferError<'some message', T>
+```
+
+## [`Failed`](./failed.ts)
+
+💀 **deprecated 8.0.0**: use `$Error` instead.
+
+`Failed<Msg>` is a type to describe a failure.
+
+Use the same concept to create your own failure types.
+
+```ts
+type YourComplexType<A,B,C> = A extends B ?
+	... // and many more hard work later...
+	: Failed<'you are doing something wrong!'>
+```
+
+[![Just Code: I failed][failed-type]][failed-type-url]
+
+[failed-type]: https://img.youtube.com/vi/3pEXVe6KJO4/0.jpg
+[failed-type-url]: https://www.youtube.com/live/3pEXVe6KJO4

package/src/$type/exact/$exact.ts

@@ -0,0 +1,34 @@
+import type { $ResolveOptions } from '../$resolve_options.js'
+import type { $InputOptions } from '../branch/$input_options.js'
+import type { $Else, $Then } from '../branch/$selection.js'
+
+export namespace $Exact {
+	/**
+	 * Options for controlling if the type perform exact comparison.
+	 */
+	export type Options = {
+		exact?: boolean | undefined
+	}
+
+	/**
+	 * Default options for `exact` behavior.
+	 *
+	 * By default it is `false`.
+	 */
+	export type Default = {
+		exact: false
+	}
+
+	/**
+	 * Parse the options for `exact`.
+	 */
+	export type Parse<$Options extends Options, $O extends $InputOptions<$Then | $Else> = {}> = $ResolveOptions<
+		[$Options['exact'], Default['exact']]
+	> extends true
+		? '$then' extends keyof $O
+			? $O['$then']
+			: true
+		: '$else' extends keyof $O
+			? $O['$else']
+			: false
+}

package/src/$type/exact/readme.md

@@ -0,0 +1,27 @@
+# Exact comparison
+
+Types in TypeScript is a Set, they can contain subtypes.
+
+For example, The `string` type can have string literals,
+`boolean` can be `true` or `false`, etc.
+
+When comparing two types, we can compare them loosely or strictly.
+
+## [`$Exact.Options`](./$exact.ts)
+
+🏷️ **since 8.0.0**
+
+`$Exact.Options` is a type option indicating the type support exact comparison.
+
+## [`$Exact.Default`](./$exact.ts)
+
+🏷️ **since 8.0.0**
+
+`$Exact.Default` is the default value for [`$Exact.Options`](#exactoptions).
+`exact` is `false` by default.
+
+## [`$Exact.Parse`](./$exact.ts)
+
+🏷️ **since 8.0.0**
+
+`$Exact.Parse<$Option, $O>` checks if a type `$Option` enables exact comparison or not.

package/src/$type/readme.md

@@ -0,0 +1,23 @@
+# Type-level programming
+
+This folder contains utility types for type-level programming.
+
+These utility types are not meant to be used directly.
+They are primarily used to build custom types.
+
+Most of these types are named with a `$` prefix to distinguish them from regular types.
+
+## [`$Type`](./$type.ts)
+
+🏷️ **since 8.0.0**
+
+`$Type` is a branded type to define unique types for type-level programming.
+
+It supports all primitive types and object types.
+
+When using object types, the type intersect with the specified type to give easy access to its properties.
+
+Internally, it uses the properties `_$type` and `_$value` to store the type and value.
+The type you provide should avoid specifying these properties.
+
+If needed, use `$O: { bare: true }` to avoid the intersection.

package/src/$type/special/$any.ts

@@ -0,0 +1,34 @@
+import type { $Branch } from '../branch/$branch.js'
+
+/**
+ * Branch selector for type `any`.
+ */
+export type $Any = $Branch<'$any'>
+
+declare const $any: '$any'
+
+export namespace $Any {
+	export type $Key = '$any'
+	/**
+	 * Options to specifically handles the `any` type.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<T, $Options extends $Any.$Options> = ...
+	 * ```
+	 */
+	export type $Options = { [$any]?: unknown }
+
+	/**
+	 * Branch option to specifically handles the `any` type.
+	 *
+	 * Use this to finely customize the behavior of your type.
+	 *
+	 * ```ts
+	 * type YourType<T, $Options extends $Any.Options> = ...
+	 *
+	 * type R = YourType<T, $Any.$Branch> extends $Any ? HandleAny : HandleOthers
+	 * ```
+	 */
+	export type $Branch = { [$any]: $Any }
+}

package/src/$type/special/$never.ts

@@ -0,0 +1,51 @@
+import type { $Branch } from '../branch/$branch.js'
+
+/**
+ * Branch selector for type `never`.
+ */
+export type $Never = $Branch<'$never'>
+
+declare const $never: '$never'
+
+export namespace $Never {
+	export type $Key = '$never'
+
+	/**
+	 * Options to specifically handles the `never` type.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<T, $Options extends $Never.$Options> = ...
+	 * ```
+	 */
+	export type $Options = { [$never]?: unknown }
+
+	/**
+	 * Branch option to specifically handles the `never` type.
+	 *
+	 * Use this to finely customize the behavior of your type.
+	 *
+	 * @example
+	 * ```ts
+	 * type YourType<T, $Options $Never.$Options> = ...
+	 *
+	 * type R = YourType<T, $Never.$Branch> extends $Never ? HandleNever : HandleOthers
+
+	 * ```
+	 */
+	export type $Branch = { [$never]: $Never }
+
+	/**
+	 * Default option for the `$never` branch.
+	 *
+	 * Unsurprisingly, defaulting `$never` to `never`.
+	 */
+	export type $Default = { [$never]: never }
+}
+
+/**
+ * Branch selector for type is not `never`.
+ *
+ * It is used in [`IsNever`](../../never/is_never.ts).
+ */
+export type $NotNever = $Branch<'$not_never'>