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

package/src/string/is_string_literal.ts

@@ -0,0 +1,132 @@
+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'
+import type { $SelectionOptions } from '../type_plus/branch/$selection_options.js'
+import type { _StringType } from './_string_type.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `T` is a string literal(s).
+ *
+ * @example
+ * ```ts
+ * type R = IsStringLiteral<string> // false
+ * type R = IsStringLiteral<'a'> // true
+ * type R = IsStringLiteral<`${number}`> // true
+ *
+ * type R = IsStringLiteral<never> // false
+ * type R = IsStringLiteral<unknown> // false
+ * type R = IsStringLiteral<'a' | boolean> // boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is a string literal(s), otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsStringLiteral<string, { selection: 'filter' }> // never
+ * type R = IsStringLiteral<'a', { selection: 'filter' }> // 'a'
+ *
+ * type R = IsStringLiteral<never, { selection: 'filter' }> // never
+ * type R = IsStringLiteral<unknown, { selection: 'filter' }> // never
+ * type R = IsStringLiteral<'a' | boolean, { selection: 'filter' }> // 'a'
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = IsStringLiteral<'abc' | 1> // boolean
+ * type R = IsStringLiteral<'abc' | 1, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Check if `T` is exactly a string literal, excluding template literals.
+ *
+ * ```ts
+ * type R = IsStringLiteral<'${number}'> // true
+ * type R = IsStringLiteral<'${number}', { exact: true }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsStringLiteral<'abc', $IsStringLiteral.$Branch> // $Then
+ * type R = IsStringLiteral<string, $IsStringLiteral.$Branch> // $Else
+ * ```
+ */
+export type IsStringLiteral<T, $O extends IsStringLiteral.$Options = {}> =
+	$SpecialType<T,
+		$MergeOptions<$O,
+			{
+				$then: $ResolveBranch<T, $O, [$Else]>,
+				$else: IsStringLiteral.$<T, $O>
+			}
+		>
+	>
+
+export namespace IsStringLiteral {
+	export type $Options = $Equality.$Options & $Exact.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `T` is string 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'], $Exact.$Default]> extends true
+		? $IsDistributive<$O, { $then: _ED<T, $O>, $else: _EN<T, $O> }>
+		: $IsDistributive<$O, { $then: _D<T, $O>, $else: _N<T, $O> }>
+
+	export type $UtilOptions = Assignable.$UtilOptions & $Exact.$Options
+
+	export type _ED<T, $O extends $SelectionOptions> =
+		T extends string ? (_E<T, $O>) : $ResolveBranch<T, $O, [$Else]>
+
+	export type _EN<T, $O extends $SelectionOptions> =
+		[T] extends [string] ? (_E<T, $O>) : $ResolveBranch<T, $O, [$Else]>
+
+	export type _E<T extends string, $O extends $SelectionOptions> =
+		T extends string
+		? _StringType<T> extends infer R
+		? R extends 'stringLiteral'
+		? $ResolveBranch<T, $O, [$Then]>
+		: $ResolveBranch<T, $O, [$Else]>
+		: never
+		: $ResolveBranch<T, $O, [$Else]>
+
+	export type _D<T, $O extends $SelectionOptions> =
+		T extends string & infer U ? _U<T, U, $O> : $ResolveBranch<T, $O, [$Else]>
+
+	export type _N<T, $O extends $SelectionOptions> =
+		[T] extends [string & infer U] ? _U<T, U, $O> : $ResolveBranch<T, $O, [$Else]>
+
+	export type _U<T, U, $O extends $SelectionOptions> =
+		U extends `${any}`
+		? $ResolveBranch<T, $O, [$Then]>
+		: (
+			U extends Uppercase<infer N>
+			? _D<N, $O>
+			: U extends Lowercase<infer N>
+			? _D<N, $O>
+			: $ResolveBranch<T, $O, [$Else]>
+		)
+
+}

package/src/string/is_template_literal.ts

@@ -0,0 +1,91 @@
+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'
+import type { _StringType } from './_string_type.js'
+
+/**
+ * 🎭 *validate*
+ *
+ * Validate if `T` is a template literal(s).
+ *
+ * @example
+ * ```ts
+ * type R = IsTemplateLiteral<string> // false
+ * type R = IsTemplateLiteral<'foo'> // false
+ * type R = IsTemplateLiteral<`a${number}`> // true
+ *
+ * type R = IsTemplateLiteral<`a${number}` | `${bigint}c`> // true
+ *
+ * type R = IsTemplateLiteral<never> // false
+ * type R = IsTemplateLiteral<unknown> // false
+ * type R = IsTemplateLiteral<`${number}` | boolean> // boolean
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is a template literal(s), otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsTemplateLiteral<`${number}`, { selection: 'filter' }> // `${number}`
+ * type R = IsTemplateLiteral<'a', { selection: 'filter' }> // never
+ * ```
+ *
+ * 🔢 *customize*:
+ *
+ * Disable distribution of union types.
+ *
+ * ```ts
+ * type R = IsTemplateLiteral<`${number}` | 1> // boolean
+ * type R = IsTemplateLiteral<`${number}` | 1, { distributive: false }> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsTemplateLiteral<`${number}`, $IsTemplateLiteral.$Branch> // $Then
+ * type R = IsTemplateLiteral<bigint, $IsString.$Branch> // $Else
+ * ```
+ */
+export type IsTemplateLiteral<T, $O extends IsTemplateLiteral.$Options = {}> =
+	$SpecialType<T,
+		$MergeOptions<$O,
+			{
+				$then: $ResolveBranch<T, $O, [$Else]>,
+				$else: IsTemplateLiteral.$<T, $O>
+			}
+		>
+	>
+
+export namespace IsTemplateLiteral {
+	export type $Options = $Equality.$Options
+	export type $Branch<$O extends $Options = {}> = $Equality.$Branch<$O>
+
+	export type $UtilOptions = Assignable.$UtilOptions
+
+	export type $<T, $O extends $UtilOptions> =
+		$IsDistributive<$O, { $then: _D<T, $O>, $else: _N<T, $O> }>
+
+	type _D<T, $O extends $UtilOptions> =
+		T extends string
+		? _StringType<T> extends infer R
+		? R extends 'templateLiteral'
+		? $ResolveBranch<T, $O, [$Then]>
+		: $ResolveBranch<T, $O, [$Else]>
+		: never
+		: $ResolveBranch<T, $O, [$Else]>
+
+	type _N<T, $O extends $UtilOptions> =
+		_D<T, { $then: $Then, $else: $Else }> extends infer R
+		? $Then | $Else extends R
+		? $ResolveBranch<T, $O, [$Else]>
+		: $ResolveBranch<T, $O, [R]>
+		: never
+}

package/src/string/string.ts

@@ -0,0 +1,36 @@
+/**
+ * Check if `Subject` includes `Search`.
+ * If either of them is not a string, returns `Else`.
+ *
+ * ```ts
+ * type R = StringIncludes<'abc', 'a'> // true
+ *
+ * type R = StringIncludes<'abc', 'd'> // false
+ * ```
+ */
+export type StringIncludes<
+	Subject extends string,
+	Search extends string,
+	Then = true,
+	Else = false
+> = Subject extends `${infer _X}${Search}${infer _Y}` ? Then : Else
+
+/**
+ * Split a string into substrings using the specified separator,
+ * and return them as an array.
+ *
+ * ```ts
+ * type R = StringSplit<'abc', ''> // ['a', 'b', 'c']
+ * type R = StringSplit<'abc', 'a'> // ['', 'bc']
+ * type R = StringSplit<'abc', 'b'> // ['a', 'c']
+ * type R = StringSplit<'abc', 'c'> // ['ab', '']
+ * ```
+ */
+export type StringSplit<
+	Subject extends string,
+	Seperator extends string
+> = Subject extends `${infer A}${Seperator}${infer B}`
+	? [A, ...StringSplit<B, Seperator>]
+	: Seperator extends ''
+	? []
+	: [Subject]

package/src/string/string_plus.ts

@@ -0,0 +1,34 @@
+import type { StringIncludes, StringSplit } from './string.js'
+
+export namespace StringPlus {
+	/**
+	 * Check if `Subject` includes `Search`.
+	 * If either of them is not a string, returns `Else`.
+	 *
+	 * ```ts
+	 * type R = StringPlus.Includes<'abc', 'a'> // true
+	 *
+	 * type R = StringPlus.Includes<'abc', 'd'> // false
+	 * ```
+	 */
+	export type Includes<
+		Subject extends string,
+		Search extends string,
+		Then = true,
+		Else = false
+	> = StringIncludes<Subject, Search, Then, Else>
+
+	/**
+	 * Split a string into substrings using the specified separator,
+	 * and return them as an array.
+	 *
+	 * ```ts
+	 * type R = StringPlus.Split<'abc', ''> // ['a', 'b', 'c']
+	 * type R = StringPlus.Split<'abc', 'a'> // ['', 'bc']
+	 * type R = StringPlus.Split<'abc', 'b'> // ['a', 'c']
+	 * type R = StringPlus.Split<'abc', 'c'> // ['ab', '']
+	 * ```
+	 */
+	export type Split<Subject extends string, Seperator extends string> = StringSplit<Subject, Seperator>
+
+}

package/src/symbol/is_not_symbol.ts

@@ -0,0 +1,78 @@
+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 `symbol`.
+ *
+ * ```ts
+ * type R = IsNotSymbol<symbol> // false
+ *
+ * type R = IsNotSymbol<never> // true
+ * type R = IsNotSymbol<unknown> // true
+ * type R = IsNotSymbol<string | boolean> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `T` is not `symbol`, otherwise returns `never`.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotSymbol<symbol, { selection: 'filter' }> // never
+ *
+ * type R = IsNotSymbol<never, { selection: 'filter' }> // never
+ * type R = IsNotSymbol<unknown, { selection: 'filter' }> // unknown
+ * type R = IsNotSymbol<symbol | string, { selection: 'filter' }> // string
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Disable distribution of union types.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotSymbol<symbol | 1> // boolean
+ * type R = IsNotSymbol<symbol | 1, { distributive: false }> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = IsNotSymbol<string, $SelectionBranch> // $Then
+ * type R = IsNotSymbol<symbol, $SelectionBranch> // $Else
+ * ```
+ */
+export type IsNotSymbol<T, $O extends IsNotSymbol.$Options = {}> = $SpecialType<T,
+	$MergeOptions<$O,
+		{
+			$then: $ResolveBranch<T, $O, [$Then]>,
+			$else: IsNotSymbol.$<T, $O>
+		}
+	>
+>
+
+export namespace IsNotSymbol {
+	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> = NotAssignable.$<T, symbol, $O>
+
+	export type $UtilOptions = NotAssignable.$UtilOptions
+}

package/src/symbol/is_symbol.ts

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

package/src/testing/stub.ts

@@ -0,0 +1,81 @@
+import { requiredDeep } from 'unpartial'
+
+import type { AnyFunction } from '../function/any_function.js'
+import type { RecursivePartial } from '../object/recursive_partial.js'
+import type { NoInfer } from '../type/no_infer.js'
+
+/**
+ * stub a value.
+ *
+ * If the value is a function, it will be passed through as-is.
+ *
+ * 🦴 `utilities`
+ */
+export function stub<T extends AnyFunction>(stub: T): T
+export function stub<T>(stub: RecursivePartial<NoInfer<T>>): T
+export function stub<T>(stub: unknown): T {
+	return stub as T
+}
+
+/**
+ * builds a stub function
+ */
+function build<T>(
+	init: RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)
+): (stub?: RecursivePartial<T>) => T
+function build<T>(init: RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)) {
+	return builder(init).create()
+}
+
+/**
+ * Create a builder for a stub function of type T.
+ *
+ * The builder contains two methods:
+ *
+ * `.with()`: adds additional handler or partial stub.
+ * `.create()`: creates the final stub function.
+ *
+ * @example
+ * ```ts
+ * const b = stub.builder<{ a: number; b: string }>({ a: 1 }).with({ b: 'b' }).create()
+ * b({ a: 2 }) // { a: 2, b: 'b' }
+ * ```
+ */
+function builder<T>(init: RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)) {
+	return builderInternal([init])
+}
+
+function builderInternal<T>(
+	initializers: Array<RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)>
+) {
+	const builder = {
+		/**
+		 * Adds an init object or handler to the builder.
+		 *
+		 * If `init` is an object, it will be merged with the stub object.
+		 * If `init` is a function, it will be called with the stub object.
+		 *
+		 * @return {Builder<T>} The builder instance.
+		 */
+		with(init: RecursivePartial<T> | ((stub?: RecursivePartial<T>) => RecursivePartial<T>)) {
+			return builderInternal([...initializers, init])
+		},
+		/**
+		 * Creates the resulting stub function.
+		 */
+
+		create() {
+			return (stub?: RecursivePartial<T>) => {
+				return initializers.reduce((acc, init) => {
+					if (typeof init === 'function') {
+						return init(acc)
+					}
+					return requiredDeep<RecursivePartial<T>>(init, acc)
+				}, stub) as T
+			}
+		}
+	}
+	return builder
+}
+stub.build = build
+stub.builder = builder