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

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'>

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

@@ -0,0 +1,40 @@
+import type { $BranchOptions } from '../branch/$branch.js'
+import type { $InputOptions } from '../branch/$input_options.js'
+import type { $ResolveBranch } from '../branch/$resolve_branch.js'
+import type { $Else, $Selection, $Then } from '../branch/$selection.js'
+import type { $Any } from './$any.js'
+import type { $Never } from './$never.js'
+import type { $Unknown } from './$unknown.js'
+import type { $Void } from './$void.js'
+
+/**
+ * A type to handle special types: `any`, `unknown`, `never`, and `void`.
+ *
+ * @example
+ * ```ts
+ * type YourType<T, $Options extends $Special.Options> = Special<T,
+ * {
+ *   $any: $ResolveBranch<$Options, [$Any, ...], T>
+ *   $unknown: $ResolveBranch<$Options, [$Unknown, ...], T>
+ *   $never: $ResolveBranch<$Options, [$Never, ...], T>
+ *   $void: $ResolveBranch<$Options, [$Void, ...], T>
+ *   $then: $ResolveBranch<$Options, [...], T>
+ *   $else: $ResolveBranch<$Options, [...], T>
+ * }>
+ *
+ * @since 🏷️ 8.0.0
+ */
+export type $Special<T, $O extends $Special.Options = {}> = 0 extends 1 & T
+	? $ResolveBranch<$O, [$Any, $Then], T>
+	: [T, unknown] extends [unknown, T]
+		? $ResolveBranch<$O, [$Unknown, $Then], T>
+		: [T, never] extends [never, T]
+			? $ResolveBranch<$O, [$Never, $Then], T>
+			: [T, void] extends [void, T]
+				? $ResolveBranch<$O, [$Void, $Then], T>
+				: $ResolveBranch<$O, [$Else]>
+
+export namespace $Special {
+	export type Options = $Selection.Options & $InputOptions<$Any | $Unknown | $Never | $Void>
+	export type Branch = $Selection.Branch & $BranchOptions<$Any | $Unknown | $Never | $Void>
+}

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

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

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

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

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

@@ -0,0 +1,51 @@
+# Special Types Handling
+
+"Special types" in TypeScript are `any`, `unknown`, `never`, and `void`.
+They serve as the top and bottom types of the type system,
+and not corresponding to a specific type in JavaScript.
+
+In type-level programming, in many cases we want to handle these types specially.
+
+## [`$Special`](./$special.ts)
+
+🏷️ **since 8.0.0**
+
+`$Special` is a type to handle special types in TypeScript.
+
+🎭 **predicate**
+By default, it acts as a predicate type:
+
+```ts
+type A = $Special<any> // true
+type A = $Special<unknown> // true
+type A = $Special<never> // true
+type A = $Special<void> // true
+type A = $Special<number> // false
+```
+
+🔢 **customize**
+
+`$Special` can be used as a `filter`:
+
+```ts
+type A = $Special<any, { selection: 'filter' }> // any
+type A = $Special<unknown, { selection: 'filter' }> // unknown
+type A = $Special<never, { selection: 'filter' }> // never
+type A = $Special<void, { selection: 'filter' }> // void
+type A = $Special<number, { selection: 'filter' }> // never
+```
+
+🔱 **branching**
+
+Most of the time, `$Special` is used with branching to handle special types.
+
+```ts
+type A<T> = $Special<T, {
+	$any: ...,
+	$unknown: ...,
+	$never: ...,
+	$void: ...,
+	$then: ...,
+	$else: ...,
+}>
+```

package/src/$type/utils/$merge_options.ts

@@ -0,0 +1,11 @@
+/**
+ * Merge type options.
+ *
+ * This is used in the type to merge the user provided options with the default options.
+ *
+ * @typeparam $O - The type of the options, typically provided by the user.
+ * @typeparam $P - The type of the default options.
+ */
+export type $MergeOptions<$O extends Record<string, any>, $P extends { [k in keyof $O]?: unknown }> = {
+	[k in Exclude<keyof $O, keyof $P>]: $O[k]
+} & $P

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

@@ -0,0 +1,10 @@
+# Type-level utilities
+
+This folder contains utility types for the types in type-level programming.
+
+## [`$MergeOptions`](./merge_options.ts)
+
+🏷️ **since 8.0.0**
+
+`$MergeOptions<$O, $P>` merges two options types `$O` and `$P`.
+This is used in the type to merge the user provided options with the default options.