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

package/src/object/split.ts

@@ -0,0 +1,191 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+import type { AnyRecord } from './any_record.js'
+import type { Omit } from './omit.js'
+import type { Partial } from './Partial.js'
+import { reduceByKey } from './reduceKey.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]> | Exclude<S[k], undefined>
+}
+
+/**
+ * Split an object into multiple objects.
+ * @returns [...entries, remaining]
+ */
+export function split<T extends AnyRecord, S1 extends Splitter<T>>(
+	target: T,
+	split1: S1
+): [Split<T, S1>, Omit<T, keyof S1>]
+export function split<T extends AnyRecord, S1 extends Splitter<T>, S2 extends Splitter<T>>(
+	target: T,
+	split1: S1,
+	split2: S2
+): [Split<T, S1>, Split<T, S2>, Omit<T, keyof S1 | keyof S2>]
+export function split<T extends AnyRecord, S1 extends Splitter<T>, S2 extends Splitter<T>, S3 extends Splitter<T>>(
+	target: T,
+	splitter1: S1,
+	splitter2: S2,
+	splitter3: S3
+): [Split<T, S1>, Split<T, S2>, Split<T, S3>, Omit<T, keyof S1 | keyof S2 | keyof S3>]
+export function split<
+	T extends AnyRecord,
+	S1 extends Splitter<T>,
+	S2 extends Splitter<T>,
+	S3 extends Splitter<T>,
+	S4 extends Splitter<T>
+>(
+	target: T,
+	splitter1: S1,
+	splitter2: S2,
+	splitter3: S3,
+	splitter4: S4
+): [Split<T, S1>, Split<T, S2>, Split<T, S3>, Split<T, S4>, Omit<T, keyof S1 | keyof S2 | keyof S3 | keyof S4>]
+export function split<
+	T extends AnyRecord,
+	S1 extends Splitter<T>,
+	S2 extends Splitter<T>,
+	S3 extends Splitter<T>,
+	S4 extends Splitter<T>,
+	S5 extends Splitter<T>
+>(
+	target: T,
+	splitter1: S1,
+	splitter2: S2,
+	splitter3: S3,
+	splitter4: S4,
+	splitter5: S5
+): [
+	Split<T, S1>,
+	Split<T, S2>,
+	Split<T, S3>,
+	Split<T, S4>,
+	Split<T, S5>,
+	Omit<T, keyof S1 | keyof S2 | keyof S3 | keyof S4 | keyof S5>
+]
+export function split<
+	T extends AnyRecord,
+	S1 extends Splitter<T>,
+	S2 extends Splitter<T>,
+	S3 extends Splitter<T>,
+	S4 extends Splitter<T>,
+	S5 extends Splitter<T>,
+	S6 extends Splitter<T>
+>(
+	target: T,
+	splitter1: S1,
+	splitter2: S2,
+	splitter3: S3,
+	splitter4: S4,
+	splitter5: S5,
+	splitter6: S6
+): [
+	Split<T, S1>,
+	Split<T, S2>,
+	Split<T, S3>,
+	Split<T, S4>,
+	Split<T, S5>,
+	Split<T, S6>,
+	Omit<T, keyof S1 | keyof S2 | keyof S3 | keyof S4 | keyof S5 | keyof S6>
+]
+export function split<
+	T extends AnyRecord,
+	S1 extends Splitter<T>,
+	S2 extends Splitter<T>,
+	S3 extends Splitter<T>,
+	S4 extends Splitter<T>,
+	S5 extends Splitter<T>,
+	S6 extends Splitter<T>,
+	S7 extends Splitter<T>
+>(
+	target: T,
+	splitter1: S1,
+	splitter2: S2,
+	splitter3: S3,
+	splitter4: S4,
+	splitter5: S5,
+	splitter6: S6,
+	splitter7: S7
+): [
+	Split<T, S1>,
+	Split<T, S2>,
+	Split<T, S3>,
+	Split<T, S4>,
+	Split<T, S5>,
+	Split<T, S6>,
+	Split<T, S7>,
+	Omit<T, keyof S1 | keyof S2 | keyof S3 | keyof S4 | keyof S5 | keyof S6 | keyof S7>
+]
+export function split<
+	T extends AnyRecord,
+	S1 extends Splitter<T>,
+	S2 extends Splitter<T>,
+	S3 extends Splitter<T>,
+	S4 extends Splitter<T>,
+	S5 extends Splitter<T>,
+	S6 extends Splitter<T>,
+	S7 extends Splitter<T>,
+	S8 extends Splitter<T>
+>(
+	target: T,
+	splitter1: S1,
+	splitter2: S2,
+	splitter3: S3,
+	splitter4: S4,
+	splitter5: S5,
+	splitter6: S6,
+	splitter7: S7,
+	splitter8: S8
+): [
+	Split<T, S1>,
+	Split<T, S2>,
+	Split<T, S3>,
+	Split<T, S4>,
+	Split<T, S5>,
+	Split<T, S6>,
+	Split<T, S7>,
+	Split<T, S8>,
+	Omit<T, keyof S1 | keyof S2 | keyof S3 | keyof S4 | keyof S5 | keyof S6 | keyof S7 | keyof S8>
+]
+export function split<
+	T extends AnyRecord,
+	S1 extends Splitter<T>,
+	S2 extends Splitter<T>,
+	S3 extends Splitter<T>,
+	S4 extends Splitter<T>,
+	S5 extends Splitter<T>,
+	S6 extends Splitter<T>,
+	S7 extends Splitter<T>,
+	S8 extends Splitter<T>,
+	S9 extends Splitter<T>
+>(
+	target: T,
+	splitter1: S1,
+	splitter2: S2,
+	splitter3: S3,
+	splitter4: S4,
+	splitter5: S5,
+	splitter6: S6,
+	splitter7: S7,
+	splitter8: S8,
+	splitter9: S9
+): [
+	Split<T, S1>,
+	Split<T, S2>,
+	Split<T, S3>,
+	Split<T, S4>,
+	Split<T, S5>,
+	Split<T, S6>,
+	Split<T, S7>,
+	Split<T, S8>,
+	Split<T, S9>,
+	Omit<T, keyof S1 | keyof S2 | keyof S3 | keyof S4 | keyof S5 | keyof S6 | keyof S7 | keyof S8 | keyof S9>
+]
+export function split(target: AnyRecord, ...splitters: AnyRecord[]): AnyRecord[] {
+	const keyMap: AnyRecord = {}
+	const s = splitters.map((s) =>
+		reduceByKey(s, (p, k) => ((keyMap[k] = true), (p[k] = target[k] ?? s[k]), p), {} as AnyRecord)
+	)
+	const r = reduceByKey(target, (p, k) => (keyMap[k] ? p : ((p[k] = target[k]), p)), {} as AnyRecord)
+	return [...s, r]
+}

package/src/object/typeOverrideIncompatible.ts

@@ -0,0 +1,8 @@
+import type { ANotB, AnyRecord } from './index.js'
+
+export function typeOverrideIncompatible<A extends AnyRecord>() {
+	return <B extends AnyRecord>(source: B, override: ANotB<A, B>): A => ({
+		...source,
+		...override
+	})
+}

package/src/predicates/CanAssign.ts

@@ -0,0 +1,65 @@
+import type { Assignable } from './assignable.js'
+import type { NotExtendable } from './Extends.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.
+ *
+ * @deprecated use `Assignable<A, B>` instead
+ *
+ * @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> = boolean extends A
+	? boolean extends B
+		? Then
+		: Else
+	: A extends B
+		? Then
+		: Else
+
+/**
+ * Can `A` strictly assign to `B`.
+ *
+ * All branches in an union `A` are assignable to `B`.
+ *
+ * @deprecated use `Assignable<A, B, { distributive: false }>` instead
+ *
+ * @example
+ * ```ts
+ * StrictCanAssign<number | string, number> // false
+ * StrictCanAssign<number | string, number | string> // true
+ * ```
+ */
+export type StrictCanAssign<A, B, Then = true, Else = false> = Assignable<
+	A,
+	B,
+	{ distributive: false; $then: Then; $else: Else }
+>
+
+/**
+ * @deprecated use `Assignable<A, B>` 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
+export function canAssign<T>(): <S extends T>(subject: S) => CanAssign<S, T>
+export function canAssign<T>(): <S extends T>(subject: S) => any {
+	return () => true
+}

package/src/predicates/Extends.ts

@@ -0,0 +1,7 @@
+/**
+ * @deprecated use `$Assignable`
+ */
+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/src/predicates/assignable.ts

@@ -0,0 +1,101 @@
+import type { $Any } from '../any/any.js'
+import type { $Never } from '../never/never.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $DistributiveDefault, $DistributiveOptions } from '../type_plus/branch/$distributive.js'
+import type { $InputOptions } from '../type_plus/branch/$input_options.js'
+import type { $IsDistributive } from '../type_plus/branch/$is_distributive.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $SelectionBranch, $SelectionPredicate, $Then } from '../type_plus/branch/$selection.js'
+import type { $SelectionOptions } from '../type_plus/branch/$selection_options.js'
+import type { $Unknown } from '../unknown/unknown.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `A` is assignable to `B`.
+ *
+ * @example
+ * ```ts
+ * type R = Assignable<any, any> // true
+ * type R = Assignable<any, 1> // true
+ * type R = Assignable<unknown, unknown> // true
+ * type R = Assignable<never, never> // true
+ * type R = Assignable<1, 1> // true
+ * type R = Assignable<'a', 'a'> // true
+ * type R = Assignable<'a', 'b'> // false
+ * type R = Assignable<'a', string> // true
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `A` is assignable to `B`.
+ *
+ * @example
+ * ```ts
+ * type R = Assignable<any, any, { selection: 'filter' }> // any
+ * type R = Assignable<1, number, { selection: 'filter' }> // 1
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = Assignable<any, any, Assignable.$Branch> // $Then
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Override special types branch.
+ *
+ * @example
+ * ```ts
+ * type R = Assignable<any, any, { $any: 1 }> // 1
+ * type R = Assignable<unknown, any, { $unknown: 1 }> // 1
+ * type R = Assignable<never, any, { $never: 1 }> // 1
+ * ```
+ */
+export type Assignable<A, B, $O extends Assignable.$Options = {}> = $SpecialType<
+	B,
+	{
+		$any: $ResolveBranch<A, $O, [0 extends 1 & A ? $Any : unknown, $Then]>
+		$unknown: $ResolveBranch<A, $O, [[A, unknown] extends [unknown, A] ? $Unknown : unknown, $Then]>
+		$never: $ResolveBranch<A, $O, [A, never] extends [never, A] ? [$Never, $Then] : [$Else]>
+		$else: $SpecialType<
+			A,
+			{
+				$any: $ResolveBranch<A, $O, [$Any, $Then]>
+				$unknown: $ResolveBranch<A, $O, [$Unknown, $Then]>
+				$never: $ResolveBranch<A, $O, [$Never, $Then]>
+				$else: Assignable.$<A, B, $O>
+			}
+		>
+	}
+>
+
+export namespace Assignable {
+	export type $Options = $SelectionOptions & $DistributiveOptions & $InputOptions<$Any | $Unknown | $Never>
+	export type $Default = $SelectionPredicate & $DistributiveDefault
+	export type $Branch<$O extends $DistributiveOptions = {}> = $SelectionBranch & $O
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `A` is assignable to `B`.
+	 *
+	 * This is the internal logic of `Assignable`.
+	 * It does not check against special types.
+	 *
+	 * It is suitable for building custom types.
+	 */
+	export type $<A, B, $O extends $UtilOptions> = $IsDistributive<
+		$O,
+		{
+			$then: A extends B ? $ResolveBranch<A, $O, [$Then]> : $ResolveBranch<A, $O, [$Else]>
+			$else: [A] extends [B] ? $ResolveBranch<A, $O, [$Then]> : $ResolveBranch<A, $O, [$Else]>
+		}
+	>
+
+	export type $UtilOptions = $SelectionOptions & $DistributiveOptions
+}

package/src/predicates/index.ts

@@ -0,0 +1,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 type { IsLiteral } from './literal.js'
+export type { And, Not, Or, Xor } from './logical.js'

package/src/predicates/literal.ts

@@ -0,0 +1,35 @@
+/**
+ * Validate if specified type is a scalar literal.
+ *
+ * 🎭 *predicate*
+ *
+ * @example
+ * ```ts
+ * type R = IsLiteral<string> // false
+ * type R = IsLiteral<number> // false
+ * type R = IsLiteral<boolean> // false
+ * type R = IsLiteral<bigint> // false
+ * type R = IsLiteral<symbol> // false
+ *
+ * type R = IsLiteral<'a'> // true
+ * type R = IsLiteral<1> // true
+ * type R = IsLiteral<true> // true
+ * type R = IsLiteral<1n> // true
+ * type R = IsLiteral<typeof someSymbol> // true
+ * ```
+ */
+export type IsLiteral<
+	T extends number | boolean | bigint | string | symbol,
+	Then = true,
+	Else = false
+> = number extends T
+	? Else
+	: string extends T
+		? Else
+		: boolean extends T
+			? Else
+			: symbol extends T
+				? Else
+				: bigint extends T
+					? Else
+					: Then

package/src/predicates/logical.ts

@@ -0,0 +1,19 @@
+export type And<A extends boolean, B extends boolean, Then = true, Else = false> = A extends true
+	? B extends true
+		? Then
+		: Else
+	: Else
+
+export type Or<A extends boolean, B extends boolean, Then = true, Else = false> = A extends true
+	? Then
+	: B extends true
+		? Then
+		: Else
+
+export type Not<X extends boolean, Then = true, Else = false> = X extends true ? Else : Then
+
+export type Xor<A extends boolean, B extends boolean, Then = true, Else = false> = A extends Then
+	? Not<B>
+	: B extends true
+		? Then
+		: Else

package/src/predicates/not_assignable.ts

@@ -0,0 +1,101 @@
+import type { $Any } from '../any/any.js'
+import type { $Never } from '../never/never.js'
+import type { $SpecialType } from '../type_plus/$special_type.js'
+import type { $DistributiveDefault, $DistributiveOptions } from '../type_plus/branch/$distributive.js'
+import type { $InputOptions } from '../type_plus/branch/$input_options.js'
+import type { $IsDistributive } from '../type_plus/branch/$is_distributive.js'
+import type { $ResolveBranch } from '../type_plus/branch/$resolve_branch.js'
+import type { $Else, $SelectionBranch, $SelectionPredicate, $Then } from '../type_plus/branch/$selection.js'
+import type { $SelectionOptions } from '../type_plus/branch/$selection_options.js'
+import type { $Unknown } from '../unknown/unknown.js'
+
+/**
+ * 🎭 *predicate*
+ *
+ * Validate if `A` is not assignable to `B`.
+ *
+ * @example
+ * ```ts
+ * type R = NotAssignable<any, any> // false
+ * type R = NotAssignable<any, 1> // false
+ * type R = NotAssignable<unknown, unknown> // false
+ * type R = NotAssignable<never, never> // false
+ * type R = NotAssignable<1, 1> // false
+ * type R = NotAssignable<'a', 'a'> // false
+ * type R = NotAssignable<'a', 'b'> // true
+ * type R = NotAssignable<'a', string> // false
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Filter to ensure `A` is not assignable to `B`.
+ *
+ * @example
+ * ```ts
+ * type R = NotAssignable<any, any, { selection: 'filter' }> // never
+ * type R = NotAssignable<string, number, { selection: 'filter' }> // string
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Use unique branch identifiers to allow precise processing of the result.
+ *
+ * @example
+ * ```ts
+ * type R = NotAssignable<any, any, NotAssignable.$Branch> // $Else
+ * ```
+ *
+ * 🔢 *customize*
+ *
+ * Override special types branch.
+ *
+ * @example
+ * ```ts
+ * type R = NotAssignable<any, any, { $any: 1 }> // 1
+ * type R = NotAssignable<unknown, any, { $unknown: 1 }> // 1
+ * type R = NotAssignable<never, any, { $never: 1 }> // 1
+ * ```
+ */
+export type NotAssignable<A, B, $O extends NotAssignable.$Options = {}> = $SpecialType<
+	B,
+	{
+		$any: $ResolveBranch<A, $O, [0 extends 1 & A ? $Any : unknown, $Else]>
+		$unknown: $ResolveBranch<A, $O, [[A, unknown] extends [unknown, A] ? $Unknown : unknown, $Else]>
+		$never: $ResolveBranch<A, $O, [A, never] extends [never, A] ? [$Never, $Else] : [$Then]>
+		$else: $SpecialType<
+			A,
+			{
+				$any: $ResolveBranch<A, $O, [$Any, $Else]>
+				$unknown: $ResolveBranch<A, $O, [$Unknown, $Else]>
+				$never: $ResolveBranch<A, $O, [$Never, $Else]>
+				$else: NotAssignable.$<A, B, $O>
+			}
+		>
+	}
+>
+
+export namespace NotAssignable {
+	export type $Options = $SelectionOptions & $DistributiveOptions & $InputOptions<$Any | $Unknown | $Never>
+	export type $Default = $SelectionPredicate & $DistributiveDefault
+	export type $Branch<$O extends $DistributiveOptions = {}> = $SelectionBranch & $O
+
+	/**
+	 * 🧰 *type util*
+	 *
+	 * Validate if `A` is assignable to `B`.
+	 *
+	 * This is the internal logic of `NotAssignable`.
+	 * It does not check against special types.
+	 *
+	 * It is suitable for building custom types.
+	 */
+	export type $<A, B, $O extends $UtilOptions> = $IsDistributive<
+		$O,
+		{
+			$then: A extends B ? $ResolveBranch<A, $O, [$Else]> : $ResolveBranch<A, $O, [$Then]>
+			$else: [A] extends [B] ? $ResolveBranch<A, $O, [$Else]> : $ResolveBranch<A, $O, [$Then]>
+		}
+	>
+
+	export type $UtilOptions = $SelectionOptions & $DistributiveOptions
+}

package/src/primitive.ts

@@ -0,0 +1,4 @@
+/**
+ * 📘 Definition of all primitive types.
+ */
+export type PrimitiveTypes = boolean | number | string | object | symbol | bigint | Function | undefined | null

package/src/promise/index.ts

@@ -0,0 +1,5 @@
+export * from './isPromise.js'
+export * from './mapSeries.js'
+export * from './MaybePromise.js'
+export type { AwaitedProp, PromiseValue } from './PromiseValue.js'
+export type { PromiseValueMerge } from './PromiseValueMerge.js'

package/src/promise/mapSeries.ts

@@ -0,0 +1,3 @@
+export function mapSeries<R, T = any>(values: T[], fn: (value: T) => Promise<R>): Promise<R[]> {
+	return values.reduce((p, v) => p.then((r) => fn(v).then((v) => (r.push(v), r))), Promise.resolve<R[]>([]))
+}

package/src/string/$extract_manipulated_string.ts

@@ -0,0 +1,50 @@
+/**
+ * 🧰 *type util*
+ *
+ * Extract the manipulated string from any of the intrinsic string manipulation types:
+ *
+ * - `Uppercase`
+ * - `Lowercase`
+ * - `Capitalize`
+ * - `Uncapitalize`
+ */
+export type $ExtractManipulatedString<T extends string> = [T, unknown] extends [unknown, T]
+	? T
+	: $ExtractManipulatedString._UpperOrElse<
+			T,
+			$ExtractManipulatedString._LowerOrElse<
+				T,
+				$ExtractManipulatedString._CapOrElse<T, $ExtractManipulatedString._UncapOrElse<T, T>>
+			>
+		>
+
+export namespace $ExtractManipulatedString {
+	export type _UpperOrElse<N, Else> = N extends Uppercase<infer Y>
+		? string extends Y
+			? Uppercase<any> extends N
+				? Y
+				: N
+			: $ExtractManipulatedString<Y>
+		: Else
+	export type _LowerOrElse<N, Else> = N extends Lowercase<infer Y>
+		? string extends Y
+			? Lowercase<any> extends N
+				? Y
+				: N
+			: $ExtractManipulatedString<Y>
+		: Else
+	export type _CapOrElse<N, Else> = N extends Capitalize<infer Y>
+		? string extends Y
+			? Capitalize<any> extends N
+				? Y
+				: N
+			: $ExtractManipulatedString<Y>
+		: Else
+	export type _UncapOrElse<N, Else> = N extends Uncapitalize<infer Y>
+		? string extends Y
+			? Uncapitalize<any> extends N
+				? Y
+				: N
+			: $ExtractManipulatedString<Y>
+		: Else
+}

package/src/string/_string_type.ts

@@ -0,0 +1,11 @@
+import type { $ExtractManipulatedString } from './$extract_manipulated_string.js'
+
+export type _StringType<T extends string> = $ExtractManipulatedString<T> extends infer K
+	? K extends string & infer U
+		? [K, U] extends [U, K]
+			? {} extends { [P in `${K}`]: unknown }
+				? 'templateLiteral'
+				: 'stringLiteral'
+			: 'string'
+		: never
+	: never