@planet-matrix/mobius-model 0.3.0 → 0.5.0

package/src/type/function.ts

@@ -0,0 +1,1519 @@
+// oxlint-disable explicit-module-boundary-types
+// oxlint-disable no-explicit-any
+
+import type { AnyFunction, AnyGeneratorFunction } from "./is.ts"
+import type {
+  TupleAt, TupleHead, TupleLast, TuplePrev, TupleReverse, TupleTail
+} from "./tuple.ts"
+
+// ============================================================================
+// Primitives
+// ============================================================================
+
+/**
+ * Type for a no-operation function.
+ *
+ * @example
+ * ```
+ * // Expect: () => void
+ * type Example1 = FunctionNoop
+ * ```
+ */
+export type FunctionNoop = () => void
+
+/**
+ * Type for an identity function.
+ *
+ * @example
+ * ```
+ * // Expect: (x: string) => string
+ * type Example1 = FunctionIdentity<string>
+ * // Expect: (x: number) => number
+ * type Example2 = FunctionIdentity<number>
+ * ```
+ */
+export type FunctionIdentity<T> = (x: T) => T
+
+/**
+ * Type for a constant function.
+ *
+ * @example
+ * ```
+ * // Expect: () => string
+ * type Example1 = FunctionConstant<string>
+ * // Expect: () => number
+ * type Example2 = FunctionConstant<number>
+ * ```
+ */
+export type FunctionConstant<T> = () => T
+
+/**
+ * Interface for type guard functions that use type predicates.
+ *
+ * Type predicates allow functions to narrow types at compile time.
+ *
+ * @see {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates}
+ * @see {@link https://github.com/ts-essentials/ts-essentials#predicatetype}
+ *
+ * @example
+ * ```
+ * // Expect: valid predicate function
+ * const isString: FunctionPredicate<string> = (value: unknown): value is string => typeof value === 'string'
+ * // Expect: valid predicate function
+ * const isNumber: FunctionPredicate<number> = (value: unknown): value is number => typeof value === 'number'
+ * ```
+ */
+export interface FunctionPredicate<Target = unknown> {
+  (target: Target, ..._: unknown[]): target is Target
+  (target: unknown, ..._: unknown[]): target is Target
+}
+
+/**
+ * Type for a mapper function.
+ *
+ * @example
+ * ```
+ * // Expect: (x: string) => number
+ * type Example1 = FunctionMapper<string, number>
+ * // Expect: (x: boolean) => string
+ * type Example2 = FunctionMapper<boolean, string>
+ * ```
+ */
+export type FunctionMapper<T, U> = (x: T) => U
+
+/**
+ * Type for a reducer function.
+ *
+ * @example
+ * ```
+ * // Expect: (acc: number, x: string) => number
+ * type Example1 = FunctionReducer<string, number>
+ * ```
+ */
+export type FunctionReducer<T, Acc> = (acc: Acc, x: T) => Acc
+
+/**
+ * Type for a comparator function.
+ *
+ * @example
+ * ```
+ * // Expect: (a: number, b: number) => number
+ * type Example1 = FunctionComparator<number>
+ * // Expect: (a: string, b: string) => number
+ * type Example2 = FunctionComparator<string>
+ * ```
+ */
+export type FunctionComparator<T> = (a: T, b: T) => number
+
+/**
+ * Type for a callback function.
+ *
+ * @example
+ * ```
+ * // Expect: (value: string) => void
+ * type Example1 = FunctionCallback<string>
+ * // Expect: (value: number) => void
+ * type Example2 = FunctionCallback<number>
+ * ```
+ */
+export type FunctionCallback<T> = (value: T) => void
+
+/**
+ * Type for an event handler function.
+ *
+ * @example
+ * ```
+ * type ClickEvent = { x: number; y: number }
+ * // Expect: (event: ClickEvent) => void
+ * type Example1 = FunctionEventHandler<ClickEvent>
+ * ```
+ */
+export type FunctionEventHandler<E> = (event: E) => void
+
+/**
+ * Type for an assertion function.
+ *
+ * @example
+ * ```
+ * // Expect: (value: unknown) => asserts value is string
+ * type Example1 = FunctionAssert<string>
+ * ```
+ */
+export type FunctionAssert<T> = (value: unknown) => asserts value is T
+
+/**
+ * Type for a decorator function that wraps another function.
+ *
+ * @example
+ * ```
+ * type Func = (a: number) => string
+ * // Expect: (fn: Func) => Func
+ * type Example1 = FunctionDecorator<Func>
+ * ```
+ */
+export type FunctionDecorator<F extends AnyFunction> = (fn: F) => F
+
+/**
+ * Type for a middleware function.
+ *
+ * @example
+ * ```
+ * type Context = { req: Request; res: Response }
+ * type Next = () => void
+ * // Expect: (ctx: Context, next: Next) => void
+ * type Example1 = FunctionMiddleware<Context, Next>
+ * ```
+ */
+export type FunctionMiddleware<Context, Next extends AnyFunction> =
+  (ctx: Context, next: Next) => ReturnType<Next> | Promise<ReturnType<Next>>
+
+/**
+ * Type for an interceptor function.
+ *
+ * @example
+ * ```
+ * type Value = string
+ * // Expect: (value: string) => string | Promise<string>
+ * type Example1 = FunctionInterceptor<Value>
+ * ```
+ */
+export type FunctionInterceptor<T> = (value: T) => T | Promise<T>
+
+/**
+ * Type for a memoized function (same signature but with cache).
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string) => boolean
+ * // Expect: (a: number, b: string) => boolean
+ * type Example1 = FunctionMemoized<Func>
+ * ```
+ */
+export type FunctionMemoized<F extends AnyFunction> = F
+
+/**
+ * Type for a throttled function.
+ *
+ * @example
+ * ```
+ * type Func = (a: number) => void
+ * // Expect: (a: number) => void
+ * type Example1 = FunctionThrottled<Func>
+ * ```
+ */
+export type FunctionThrottled<F extends AnyFunction> = F
+
+/**
+ * Type for a debounced function.
+ *
+ * @example
+ * ```
+ * type Func = (a: number) => void
+ * // Expect: (a: number) => void
+ * type Example1 = FunctionDebounced<Func>
+ * ```
+ */
+export type FunctionDebounced<F extends AnyFunction> = F
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Check if a function is synchronous (does not return Promise).
+ *
+ * @example
+ * ```
+ * type Func1 = () => string
+ * type Func2 = () => Promise<string>
+ * // Expect: true
+ * type Example1 = FunctionIsSync<Func1>
+ * // Expect: false
+ * type Example2 = FunctionIsSync<Func2>
+ * ```
+ */
+export type FunctionIsSync<F> = F extends (...args: any[]) => Promise<any> ? false : (F extends AnyFunction ? true : false)
+
+/**
+ * Check if a function is asynchronous (returns Promise).
+ *
+ * @example
+ * ```
+ * type Func1 = () => Promise<string>
+ * type Func2 = () => string
+ * // Expect: true
+ * type Example1 = FunctionIsAsync<Func1>
+ * // Expect: false
+ * type Example2 = FunctionIsAsync<Func2>
+ * ```
+ */
+export type FunctionIsAsync<F> = F extends (...args: any[]) => Promise<any> ? true : false
+
+/**
+ * Check if a function returns void.
+ *
+ * @example
+ * ```
+ * type Func1 = () => void
+ * type Func2 = () => string
+ * // Expect: true
+ * type Example1 = FunctionIsVoid<Func1>
+ * // Expect: false
+ * type Example2 = FunctionIsVoid<Func2>
+ * ```
+ */
+export type FunctionIsVoid<F> = F extends (...args: any[]) => void ? true : false
+
+/**
+ * Check if a function has variadic parameters (rest parameters).
+ *
+ * @example
+ * ```
+ * type Func1 = (...args: string[]) => void
+ * type Func2 = (a: string, b: number) => void
+ * // Expect: true
+ * type Example1 = FunctionIsVariadic<Func1>
+ * // Expect: false
+ * type Example2 = FunctionIsVariadic<Func2>
+ * ```
+ */
+export type FunctionIsVariadic<F> = F extends (...args: infer P) => any
+  ? (P extends [...any[], ...infer Rest]
+    ? (Rest extends readonly any[] ? (number extends Rest['length'] ? true : false) : false)
+    : false)
+  : false
+
+/**
+ * Check if a function has zero parameters.
+ *
+ * @example
+ * ```
+ * type Func1 = () => string
+ * type Func2 = (a: string) => string
+ * // Expect: true
+ * type Example1 = FunctionIsNullary<Func1>
+ * // Expect: false
+ * type Example2 = FunctionIsNullary<Func2>
+ * ```
+ */
+export type FunctionIsNullary<F> = F extends () => any ? true : false
+
+/**
+ * Check if a function has exactly one parameter.
+ *
+ * @example
+ * ```
+ * type Func1 = (a: string) => string
+ * type Func2 = (a: string, b: number) => string
+ * // Expect: true
+ * type Example1 = FunctionIsUnary<Func1>
+ * // Expect: false
+ * type Example2 = FunctionIsUnary<Func2>
+ * ```
+ */
+export type FunctionIsUnary<F> = F extends (arg: any) => any ? true : false
+
+/**
+ * Check if a function has exactly two parameters.
+ *
+ * @example
+ * ```
+ * type Func1 = (a: string, b: number) => string
+ * type Func2 = (a: string) => string
+ * // Expect: true
+ * type Example1 = FunctionIsBinary<Func1>
+ * // Expect: false
+ * type Example2 = FunctionIsBinary<Func2>
+ * ```
+ */
+export type FunctionIsBinary<F> = F extends (arg1: any, arg2: any) => any ? true : false
+
+/**
+ * Check if a function has exactly three parameters.
+ *
+ * @example
+ * ```
+ * type Func1 = (a: string, b: number, c: boolean) => string
+ * type Func2 = (a: string, b: number) => string
+ * // Expect: true
+ * type Example1 = FunctionIsTernary<Func1>
+ * // Expect: false
+ * type Example2 = FunctionIsTernary<Func2>
+ * ```
+ */
+export type FunctionIsTernary<F> = F extends (arg1: any, arg2: any, arg3: any) => any ? true : false
+
+/**
+ * Check if a function is a constructor function.
+ *
+ * @example
+ * ```
+ * class MyClass {}
+ * type Func = () => void
+ * // Expect: true
+ * type Example1 = FunctionIsConstructor<typeof MyClass>
+ * // Expect: false
+ * type Example2 = FunctionIsConstructor<Func>
+ * ```
+ */
+export type FunctionIsConstructor<F> = F extends new (...args: any[]) => any ? true : false
+
+/**
+ * Check if a function is a generator function.
+ *
+ * @example
+ * ```
+ * function* genFunc() { yield 1; yield 2; }
+ * type Func = () => void
+ * // Expect: true
+ * type Example1 = FunctionIsGenerator<typeof genFunc>
+ * // Expect: false
+ * type Example2 = FunctionIsGenerator<Func>
+ * ```
+ */
+export type FunctionIsGenerator<F> = F extends (...args: any[]) => Generator<any, any, any> ? true : false
+
+/**
+ * Check if a function is an async generator function.
+ *
+ * @example
+ * ```
+ * async function* asyncGenFunc() { yield 1; yield 2; }
+ * type Func = () => void
+ * // Expect: true
+ * type Example1 = FunctionIsAsyncGenerator<typeof asyncGenFunc>
+ * // Expect: false
+ * type Example2 = FunctionIsAsyncGenerator<Func>
+ * ```
+ */
+export type FunctionIsAsyncGenerator<F> = F extends (...args: any[]) => AsyncGenerator<any, any, any> ? true : false
+
+// ============================================================================
+// Comparison
+// ============================================================================
+
+/**
+ * Check if two functions have equal parameter types.
+ *
+ * @example
+ * ```
+ * type F1 = (a: number, b: string) => void
+ * type F2 = (a: number, b: string) => boolean
+ * type F3 = (a: number) => void
+ * // Expect: true
+ * type Example1 = FunctionParametersEqual<F1, F2>
+ * // Expect: false
+ * type Example2 = FunctionParametersEqual<F1, F3>
+ * ```
+ */
+export type FunctionParametersEqual<F1 extends AnyFunction, F2 extends AnyFunction> =
+  Parameters<F1> extends Parameters<F2>
+  ? (Parameters<F2> extends Parameters<F1> ? true : false)
+  : false
+
+/**
+ * Check if two functions have equal return types.
+ *
+ * @example
+ * ```
+ * type F1 = (a: number) => string
+ * type F2 = (b: boolean) => string
+ * type F3 = (a: number) => number
+ * // Expect: true
+ * type Example1 = FunctionReturnEqual<F1, F2>
+ * // Expect: false
+ * type Example2 = FunctionReturnEqual<F1, F3>
+ * ```
+ */
+export type FunctionReturnEqual<F1 extends AnyFunction, F2 extends AnyFunction> =
+  ReturnType<F1> extends ReturnType<F2>
+  ? (ReturnType<F2> extends ReturnType<F1> ? true : false)
+  : false
+
+/**
+ * Check if two functions have equal signatures.
+ *
+ * @example
+ * ```
+ * type F1 = (a: number, b: string) => boolean
+ * type F2 = (a: number, b: string) => boolean
+ * type F3 = (a: number) => boolean
+ * // Expect: true
+ * type Example1 = FunctionSignatureEqual<F1, F2>
+ * // Expect: false
+ * type Example2 = FunctionSignatureEqual<F1, F3>
+ * ```
+ */
+export type FunctionSignatureEqual<F1 extends AnyFunction, F2 extends AnyFunction> =
+  FunctionParametersEqual<F1, F2> extends true
+  ? FunctionReturnEqual<F1, F2>
+  : false
+
+/**
+ * Check if function F1 is compatible with (assignable to) F2.
+ *
+ * @example
+ * ```
+ * type F1 = (a: number) => string
+ * type F2 = (a: number) => string | number
+ * // Expect: true
+ * type Example1 = FunctionCompatible<F1, F2>
+ * ```
+ */
+export type FunctionCompatible<F1 extends AnyFunction, F2 extends AnyFunction> = F1 extends F2 ? true : false
+
+// ============================================================================
+// Query
+// ============================================================================
+
+/**
+ * Get the parameter length of a function type.
+ *
+ * @example
+ * ```
+ * type Func1 = (a: number, b: string) => string
+ * type Func2 = (...args: string[]) => string
+ * // Expect: 2
+ * type Example1 = FunctionLength<Func1>
+ * // Expect: number
+ * type Example2 = FunctionLength<Func2>
+ * // Expect: never
+ * type Example3 = FunctionLength<string>
+ * ```
+ */
+export type FunctionLength<F extends AnyFunction> = F extends (...args: infer Parameters) => any ? Parameters["length"] : never
+
+/**
+ * Get the arity (parameter count) of a function.
+ *
+ * @example
+ * ```
+ * type Func1 = (a: number, b: string) => string
+ * type Func2 = () => void
+ * // Expect: 2
+ * type Example1 = FunctionArity<Func1>
+ * // Expect: 0
+ * type Example2 = FunctionArity<Func2>
+ * ```
+ */
+export type FunctionArity<F extends AnyFunction> = FunctionLength<F>
+
+/**
+ * Extract the first parameter type of a function.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string) => void
+ * // Expect: number
+ * type Example1 = FunctionFirstParameter<Func>
+ * type NoParam = () => void
+ * // Expect: never
+ * type Example2 = FunctionFirstParameter<NoParam>
+ * ```
+ */
+export type FunctionFirstParameter<F extends AnyFunction> = TupleHead<Parameters<F>>
+
+/**
+ * Extract the last parameter type of a function.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string) => void
+ * // Expect: string
+ * type Example1 = FunctionLastParameter<Func>
+ * type Single = (a: number) => void
+ * // Expect: number
+ * type Example2 = FunctionLastParameter<Single>
+ * ```
+ */
+export type FunctionLastParameter<F extends AnyFunction> = TupleLast<Parameters<F>>
+
+/**
+ * Extract the parameter type at index N.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string, c: boolean) => void
+ * // Expect: number
+ * type Example1 = FunctionParameterAt<Func, 0>
+ * // Expect: string
+ * type Example2 = FunctionParameterAt<Func, 1>
+ * // Expect: boolean
+ * type Example3 = FunctionParameterAt<Func, 2>
+ * ```
+ */
+export type FunctionParameterAt<F extends AnyFunction, N extends number> = TupleAt<Parameters<F>, N>
+
+/**
+ * Extract rest parameters from a function (all parameters except the first).
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string, c: boolean) => void
+ * // Expect: [string, boolean]
+ * type Example1 = FunctionRestParameters<Func>
+ * type Single = (a: number) => void
+ * // Expect: []
+ * type Example2 = FunctionRestParameters<Single>
+ * ```
+ */
+export type FunctionRestParameters<F extends AnyFunction> = TupleTail<Parameters<F>>
+
+/**
+ * Extract the predicated type from a type guard function.
+ *
+ * @see {@link https://github.com/ts-essentials/ts-essentials#predicatetype}
+ *
+ * @example
+ * ```
+ * const isString = (value: unknown): value is string => typeof value === 'string'
+ * const isNumber = (value: unknown): value is number => typeof value === 'number'
+ * // Expect: string
+ * type Example1 = PredicateTypeOf<typeof isString>
+ * // Expect: number
+ * type Example2 = PredicateTypeOf<typeof isNumber>
+ * ```
+ */
+export type FunctionPredicateType<F extends FunctionPredicate> =
+  F extends (target: unknown, ...rest: any[]) => target is infer P ? P : never
+
+/**
+ * Extract the yield type from a generator function.
+ *
+ * @example
+ * ```
+ * type GenFunc = () => Generator<string, number, boolean>
+ * // Expect: string
+ * type Example1 = FunctionGeneratorYield<GenFunc>
+ * ```
+ */
+export type FunctionGeneratorYield<F extends AnyGeneratorFunction> =
+  ReturnType<F> extends Generator<infer Y, any, any> ? Y : never
+
+/**
+ * Extract the return type from a generator function.
+ *
+ * @example
+ * ```
+ * type GenFunc = () => Generator<string, number, boolean>
+ * // Expect: number
+ * type Example1 = FunctionGeneratorReturn<GenFunc>
+ * ```
+ */
+export type FunctionGeneratorReturn<F extends AnyGeneratorFunction> =
+  ReturnType<F> extends Generator<any, infer R, any> ? R : never
+
+/**
+ * Extract the next parameter type from a generator function.
+ *
+ * @example
+ * ```
+ * type GenFunc = () => Generator<string, number, boolean>
+ * // Expect: boolean
+ * type Example1 = FunctionGeneratorNext<GenFunc>
+ * ```
+ */
+export type FunctionGeneratorNext<F extends AnyGeneratorFunction> =
+  ReturnType<F> extends Generator<any, any, infer N> ? N : never
+
+// ============================================================================
+// Manipulation (this)
+// ============================================================================
+
+/**
+ * Extract the this type from a function.
+ *
+ * @example
+ * ```
+ * type Func = (this: { x: number }, a: string) => void
+ * // Expect: { x: number }
+ * type Example1 = FunctionThisType<Func>
+ * type NoThis = (a: string) => void
+ * // Expect: unknown
+ * type Example2 = FunctionThisType<NoThis>
+ * ```
+ */
+export type FunctionThisType<F> = F extends (this: infer This, ...args: any[]) => any ? This : unknown
+
+/**
+ * Bind this type to a function.
+ *
+ * @example
+ * ```
+ * type Func = (a: string) => void
+ * // Expect: (this: { x: number }, a: string) => void
+ * type Example1 = FunctionBindThis<Func, { x: number }>
+ * ```
+ */
+export type FunctionBindThis<F extends AnyFunction, This> =
+  F extends (...args: infer P) => infer R
+  ? (this: This, ...args: P) => R
+  : never
+
+/**
+ * Remove this parameter from a function.
+ *
+ * @example
+ * ```
+ * type Func = (this: { x: number }, a: string, b: number) => void
+ * // Expect: (a: string, b: number) => void
+ * type Example1 = FunctionOmitThis<Func>
+ * type NoThis = (a: string) => void
+ * // Expect: (a: string) => void
+ * type Example2 = FunctionOmitThis<NoThis>
+ * ```
+ */
+export type FunctionOmitThis<F> =
+  F extends (this: any, ...args: infer P) => infer R
+  ? (...args: P) => R
+  : F
+
+/**
+ * Convert function to arrow function type (removes this).
+ *
+ * @example
+ * ```
+ * type Func = (this: { x: number }, a: string) => void
+ * // Expect: (a: string) => void
+ * type Example1 = FunctionToArrow<Func>
+ * ```
+ */
+export type FunctionToArrow<F> = FunctionOmitThis<F>
+
+/**
+ * Add this parameter to a function that doesn't have one.
+ *
+ * @example
+ * ```
+ * type Func = (a: string) => void
+ * // Expect: (this: { x: number }, a: string) => void
+ * type Example1 = FunctionWithThis<Func, { x: number }>
+ * ```
+ */
+export type FunctionWithThis<F extends AnyFunction, This> = FunctionBindThis<F, This>
+
+// ============================================================================
+// Manipulation (whole)
+// ============================================================================
+
+/**
+ * Convert a function type to return a Promise of its original return type.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string) => string
+ * // Expect: (a: number, b: string) => Promise<string>
+ * type Example1 = FunctionPromisify<Func>
+ * type VoidFunc = () => void
+ * // Expect: () => Promise<void>
+ * type Example2 = FunctionPromisify<VoidFunc>
+ * ```
+ */
+export type FunctionPromisify<Target extends AnyFunction> = (...args: Parameters<Target>) => Promise<ReturnType<Target>>
+
+/**
+ * Alias for FunctionPromisify.
+ *
+ * @example
+ * ```
+ * type Func = (a: number) => string
+ * // Expect: (a: number) => Promise<string>
+ * type Example1 = FunctionAsyncify<Func>
+ * ```
+ */
+export type FunctionAsyncify<F extends AnyFunction> = FunctionPromisify<F>
+
+/**
+ * Convert function parameters to Promises and return Promise of result.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string) => boolean
+ * // Expect: (a: Promise<number>, b: Promise<string>) => Promise<boolean>
+ * type Example1 = FunctionPromisifyAll<Func>
+ * ```
+ */
+export type FunctionPromisifyAll<F extends AnyFunction> =
+  Parameters<F> extends [infer First, ...infer Rest]
+  ? (
+    Rest extends []
+    ? (a: Promise<First>) => Promise<ReturnType<F>>
+    : (a: Promise<First>, ...args: { [K in keyof Rest]: Promise<Rest[K]> }) => Promise<ReturnType<F>>
+  )
+  : F
+
+/**
+ * Unwrap Promise return type to make function synchronous.
+ *
+ * @example
+ * ```
+ * type AsyncFunc = () => Promise<string>
+ * // Expect: () => string
+ * type Example1 = FunctionSyncify<AsyncFunc>
+ * type SyncFunc = () => string
+ * // Expect: () => string
+ * type Example2 = FunctionSyncify<SyncFunc>
+ * ```
+ */
+export type FunctionSyncify<F extends AnyFunction> =
+  ReturnType<F> extends Promise<infer T> ? (...args: Parameters<F>) => T : F
+
+/**
+ * Convert function return type to void.
+ *
+ * @example
+ * ```
+ * type Func = (a: number) => string
+ * // Expect: (a: number) => void
+ * type Example1 = FunctionVoidify<Func>
+ * ```
+ */
+export type FunctionVoidify<F extends AnyFunction> = (...args: Parameters<F>) => void
+
+/**
+ * Convert function return type to null.
+ *
+ * @example
+ * ```
+ * type Func = (a: number) => string
+ * // Expect: (a: number) => null
+ * type Example1 = FunctionNullify<Func>
+ * ```
+ */
+export type FunctionNullify<F extends AnyFunction> = (...args: Parameters<F>) => null
+
+/**
+ * Make all function parameters optional.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string) => void
+ * // Expect: (a?: number, b?: string) => void
+ * type Example1 = FunctionOptionalify<Func>
+ * ```
+ */
+export type FunctionOptionalify<F extends AnyFunction> = (...args: Partial<Parameters<F>>) => ReturnType<F>
+
+/**
+ * Make all function parameters required.
+ *
+ * @example
+ * ```
+ * type Func = (a?: number, b?: string) => void
+ * // Expect: (a: number, b: string) => void
+ * type Example1 = FunctionRequiredify<Func>
+ * ```
+ */
+export type FunctionRequiredify<F extends AnyFunction> = (...args: Required<Parameters<F>>) => ReturnType<F>
+
+/**
+ * Make all function parameters readonly.
+ *
+ * @example
+ * ```
+ * type Func = (a: number[], b: { x: number }) => void
+ * // Expect: (a: readonly number[], b: Readonly<{ x: number }>) => void
+ * type Example1 = FunctionReadonly<Func>
+ * ```
+ */
+export type FunctionReadonly<F extends AnyFunction> = (...args: Readonly<Parameters<F>>) => ReturnType<F>
+
+// ============================================================================
+// Manipulation (parameters)
+// ============================================================================
+
+/**
+ * Check if a function has optional parameters.
+ *
+ * @example
+ * ```
+ * type Func1 = (a: number, b?: string) => void
+ * type Func2 = (a: number, b: string) => void
+ * // Expect: true
+ * type Example1 = FunctionHasOptionalParameters<Func1>
+ * // Expect: false
+ * type Example2 = FunctionHasOptionalParameters<Func2>
+ * ```
+ */
+export type FunctionHasOptionalParameters<F extends AnyFunction> =
+  Parameters<F> extends Partial<Parameters<F>>
+  ? (Partial<Parameters<F>> extends Parameters<F> ? false : true)
+  : false
+
+/**
+ * Reverse the order of function parameters.
+ *
+ * @example
+ * ```
+ * type Func = (a: string, b: number, c: boolean) => void
+ * // Expect: (c: boolean, b: number, a: string) => void
+ * type Example1 = FunctionReverseParameters<Func>
+ * ```
+ */
+export type FunctionReverseParameters<F extends AnyFunction> = (...args: TupleReverse<Parameters<F>>) => ReturnType<F>
+
+type InternalInsertParameter<
+  Params extends readonly any[],
+  N extends number,
+  T,
+  Count extends readonly any[] = [],
+  Acc extends readonly any[] = []
+> = Count['length'] extends N
+  ? [...Acc, T, ...Params]
+  : (Params extends [infer First, ...infer Rest]
+    ? InternalInsertParameter<Rest, N, T, [...Count, any], [...Acc, First]>
+    : [...Acc, T])
+/**
+ * Insert a parameter at index N in the function parameter list.
+ *
+ * @example
+ * ```
+ * type Func = (a: string, c: boolean) => void
+ * // Expect: (a: string, b: number, c: boolean) => void
+ * type Example1 = FunctionInsertParameter<Func, 1, number>
+ * ```
+ */
+export type FunctionInsertParameter<F extends AnyFunction, N extends number, T> =
+  (...args: InternalInsertParameter<Parameters<F>, N, T>) => ReturnType<F>
+
+/**
+ * Prepend a parameter to the function parameter list.
+ *
+ * @example
+ * ```
+ * type Func = (b: string) => void
+ * // Expect: (a: number, b: string) => void
+ * type Example1 = FunctionPrependParameter<Func, number>
+ * ```
+ */
+export type FunctionPrependParameter<F extends AnyFunction, T> = (arg: T, ...args: Parameters<F>) => ReturnType<F>
+
+/**
+ * Append a parameter to the function parameter list.
+ *
+ * @example
+ * ```
+ * type Func = (a: string) => void
+ * // Expect: (a: string, b: number) => void
+ * type Example1 = FunctionAppendParameter<Func, number>
+ * ```
+ */
+export type FunctionAppendParameter<F extends AnyFunction, T> = (...args: [...Parameters<F>, T]) => ReturnType<F>
+
+type InternalRemoveParameter<
+  Params extends readonly any[],
+  N extends number,
+  Count extends readonly any[] = [],
+  Acc extends readonly any[] = []
+> = Params extends [infer First, ...infer Rest]
+  ? (Count['length'] extends N
+    ? [...Acc, ...Rest]
+    : InternalRemoveParameter<Rest, N, [...Count, any], [...Acc, First]>)
+  : Acc
+/**
+ * Remove the parameter at index N from the function parameter list.
+ *
+ * @example
+ * ```
+ * type Func = (a: string, b: number, c: boolean) => void
+ * // Expect: (a: string, c: boolean) => void
+ * type Example1 = FunctionRemoveParameter<Func, 1>
+ * ```
+ */
+export type FunctionRemoveParameter<F extends AnyFunction, N extends number> =
+  (...args: InternalRemoveParameter<Parameters<F>, N>) => ReturnType<F>
+
+/**
+ * Remove the first parameter from the function parameter list.
+ *
+ * @example
+ * ```
+ * type Func = (a: string, b: number) => void
+ * // Expect: (b: number) => void
+ * type Example1 = FunctionRemoveFirstParameter<Func>
+ * ```
+ */
+export type FunctionRemoveFirstParameter<F extends AnyFunction> = (...args: TupleTail<Parameters<F>>) => ReturnType<F>
+
+/**
+ * Remove the last parameter from the function parameter list.
+ *
+ * @example
+ * ```
+ * type Func = (a: string, b: number) => void
+ * // Expect: (a: string) => void
+ * type Example1 = FunctionRemoveLastParameter<Func>
+ * ```
+ */
+export type FunctionRemoveLastParameter<F extends AnyFunction> =
+  Parameters<F> extends [...infer Init, any]
+  ? (...args: Init) => ReturnType<F>
+  : () => ReturnType<F>
+
+type InternalReplaceParameter<
+  Params extends readonly any[],
+  N extends number,
+  T,
+  Count extends readonly any[] = [],
+  Acc extends readonly any[] = []
+> = Params extends [infer First, ...infer Rest]
+  ? (Count['length'] extends N
+    ? [...Acc, T, ...Rest]
+    : InternalReplaceParameter<Rest, N, T, [...Count, any], [...Acc, First]>)
+  : Acc
+/**
+ * Replace the parameter at index N with a new type.
+ *
+ * @example
+ * ```
+ * type Func = (a: string, b: number, c: boolean) => void
+ * // Expect: (a: string, b: Date, c: boolean) => void
+ * type Example1 = FunctionReplaceParameter<Func, 1, Date>
+ * ```
+ */
+export type FunctionReplaceParameter<F extends AnyFunction, N extends number, T> =
+  (...args: InternalReplaceParameter<Parameters<F>, N, T>) => ReturnType<F>
+
+/**
+ * Narrow parameter type to a more specific type.
+ *
+ * @example
+ * ```
+ * type Func = (a: any) => void
+ * // Expect: (a: number) => void
+ * type Example1 = FunctionNarrowParameter<Func, 0, number>
+ * ```
+ */
+export type FunctionNarrowParameter<F extends AnyFunction, Index extends number, Narrow> =
+  FunctionReplaceParameter<F, Index, Narrow>
+
+/**
+ * Widen parameter type to a more general type.
+ *
+ * @example
+ * ```
+ * type Func = (a: number) => void
+ * // Expect: (a: any) => void
+ * type Example1 = FunctionWidenParameter<Func, 0, any>
+ * ```
+ */
+export type FunctionWidenParameter<F extends AnyFunction, Index extends number, Widen> =
+  FunctionReplaceParameter<F, Index, Widen>
+
+type InternalSliceParameters<
+  Params extends readonly any[],
+  Start extends number,
+  End extends number | undefined,
+  Count extends readonly any[] = [],
+  Acc extends readonly any[] = []
+> = Params extends [infer First, ...infer Rest]
+  ? (Count['length'] extends End
+    ? Acc
+    : (Start extends Count['length']
+      ? InternalSliceParameters<Rest, Start, End, [...Count, any], [...Acc, First]>
+      : (Count['length'] extends Start
+        ? InternalSliceParameters<Rest, Start, End, [...Count, any], [First]>
+        : InternalSliceParameters<Rest, Start, End, [...Count, any], Acc>)))
+  : Acc
+/**
+ * Slice parameters from Start to End (like Array.slice).
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string, c: boolean, d: symbol) => void
+ * // Expect: (b: string, c: boolean) => void
+ * type Example1 = FunctionSliceParameters<Func, 1, 3>
+ * // Expect: (b: string, c: boolean, d: symbol) => void
+ * type Example2 = FunctionSliceParameters<Func, 1, undefined>
+ * // Expect: (a: number, b: string) => void
+ * type Example3 = FunctionSliceParameters<Func, 0, 2>
+ * ```
+ */
+export type FunctionSliceParameters<
+  F extends AnyFunction,
+  Start extends number,
+  End extends number | undefined = undefined
+> = (...args: InternalSliceParameters<Parameters<F>, Start, End>) => ReturnType<F>
+
+/**
+ * Pick specific parameters by index.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string, c: boolean) => void
+ * // Expect: (a: number, c: boolean) => void
+ * type Example1 = FunctionPickParameters<Func, 0 | 2>
+ * ```
+ */
+export type FunctionPickParameters<F extends AnyFunction, Indices extends number> =
+  Parameters<F> extends [...infer P]
+  ? (...args: Array<{ [K in Indices]: K extends keyof P ? P[K] : never }[Indices]>) => ReturnType<F>
+  : never
+
+/**
+ * Omit specific parameters by index.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string, c: boolean) => void
+ * // Expect: (b: string) => void
+ * type Example1 = FunctionOmitParameters<Func, 0 | 2>
+ * ```
+ */
+export type FunctionOmitParameters<F extends AnyFunction, Indices extends number> =
+  Parameters<F> extends [...infer P]
+  ? (...args: Array<{ [K in keyof P]: K extends `${Indices}` ? never : P[K] }[number]>) => ReturnType<F>
+  : never
+
+/**
+ * Flatten nested tuple parameters into a single parameter list.
+ *
+ * @example
+ * ```
+ * type Func = (a: [number, string], b: [boolean]) => void
+ * // Expect: (a: number, b: string, c: boolean) => void
+ * type Example1 = FunctionFlattenParameters<Func>
+ * ```
+ */
+export type FunctionFlattenParameters<F extends AnyFunction> =
+  Parameters<F> extends [infer A, ...infer Rest]
+  ? (A extends readonly any[]
+    ? (...args: [...A, ...Rest]) => ReturnType<F>
+    : F)
+  : F
+
+/**
+ * Group parameters into a tuple.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string, c: boolean) => void
+ * // Expect: (args: [number, string, boolean]) => void
+ * type Example1 = FunctionGroupParameters<Func>
+ * ```
+ */
+export type FunctionGroupParameters<F extends AnyFunction> =
+  (args: Parameters<F>) => ReturnType<F>
+
+/**
+ * Spread grouped parameters back to individual parameters.
+ *
+ * @example
+ * ```
+ * type Func = (args: [number, string, boolean]) => void
+ * // Expect: (a: number, b: string, c: boolean) => void
+ * type Example1 = FunctionSpreadParameters<Func>
+ * ```
+ */
+export type FunctionSpreadParameters<F extends AnyFunction> =
+  Parameters<F> extends [infer A]
+  ? (A extends readonly any[]
+    ? (...args: A) => ReturnType<F>
+    : F)
+  : F
+
+/**
+ * Distribute function over union parameters.
+ *
+ * @example
+ * ```
+ * type Func = (a: number | string) => void
+ * // Expect: ((a: number) => void) | ((a: string) => void)
+ * type Example1 = FunctionDistributeParameters<Func>
+ * ```
+ */
+export type FunctionDistributeParameters<F extends AnyFunction> =
+  Parameters<F> extends [infer First, ...infer Rest]
+  ? (
+    First extends any
+    ? (arg: First, ...rest: Rest) => ReturnType<F>
+    : never
+  )
+  : F
+
+// ============================================================================
+// Manipulation (return)
+// ============================================================================
+
+/**
+ * Map the return type of a function through a type transformation.
+ *
+ * @example
+ * ```
+ * type Func = () => string
+ * // Expect: () => string[]
+ * type Example1 = FunctionMapReturn<Func, Array<string>>
+ * ```
+ */
+export type FunctionMapReturn<F extends AnyFunction, R> = (...args: Parameters<F>) => R
+
+/**
+ * Flatten nested Promise return types.
+ *
+ * @example
+ * ```
+ * type Func = () => Promise<Promise<string>>
+ * // Expect: () => Promise<string>
+ * type Example1 = FunctionFlatReturn<Func>
+ * ```
+ */
+export type FunctionFlatReturn<F extends AnyFunction> =
+  ReturnType<F> extends Promise<infer Inner>
+  ? (Inner extends Promise<any>
+    ? (...args: Parameters<F>) => Inner
+    : F)
+  : F
+
+/**
+ * Unwrap the return type (Promise or Array).
+ *
+ * @example
+ * ```
+ * type AsyncFunc = () => Promise<string>
+ * type ArrayFunc = () => string[]
+ * // Expect: () => string
+ * type Example1 = FunctionUnwrapReturn<AsyncFunc>
+ * // Expect: () => string
+ * type Example2 = FunctionUnwrapReturn<ArrayFunc>
+ * ```
+ */
+export type FunctionUnwrapReturn<F extends AnyFunction> =
+  ReturnType<F> extends Promise<infer T>
+  ? (...args: Parameters<F>) => T
+  : (
+    ReturnType<F> extends Array<infer U>
+    ? (...args: Parameters<F>) => U
+    : F
+  )
+
+/**
+ * Wrap the return type with a wrapper type.
+ *
+ * @example
+ * ```
+ * type Func = () => string
+ * // Expect: () => Promise<string>
+ * type Example1 = FunctionWrapReturn<Func, Promise<string>>
+ * // Expect: () => Array<string>
+ * type Example2 = FunctionWrapReturn<Func, Array<string>>
+ * ```
+ */
+export type FunctionWrapReturn<F extends AnyFunction, Wrapper> = (...args: Parameters<F>) => Wrapper
+
+/**
+ * Convert return type to an array.
+ *
+ * @example
+ * ```
+ * type Func = () => string
+ * // Expect: () => string[]
+ * type Example1 = FunctionReturnArray<Func>
+ * type VoidFunc = () => void
+ * // Expect: () => void[]
+ * type Example2 = FunctionReturnArray<VoidFunc>
+ * ```
+ */
+export type FunctionReturnArray<F extends AnyFunction> = (...args: Parameters<F>) => Array<ReturnType<F>>
+
+/**
+ * Convert return type to a tuple with one element.
+ *
+ * @example
+ * ```
+ * type Func = () => string
+ * // Expect: () => [string]
+ * type Example1 = FunctionReturnTuple<Func>
+ * ```
+ */
+export type FunctionReturnTuple<F extends AnyFunction> = (...args: Parameters<F>) => [ReturnType<F>]
+
+/**
+ * Make return type nullable (add null | undefined).
+ *
+ * @example
+ * ```
+ * type Func = () => string
+ * // Expect: () => string | null | undefined
+ * type Example1 = FunctionReturnNullable<Func>
+ * ```
+ */
+export type FunctionReturnNullable<F extends AnyFunction> =
+  (...args: Parameters<F>) => ReturnType<F> | null | undefined
+
+/**
+ * Remove null and undefined from return type.
+ *
+ * @example
+ * ```
+ * type Func = () => string | null | undefined
+ * // Expect: () => string
+ * type Example1 = FunctionReturnNonNullable<Func>
+ * type NoNull = () => string
+ * // Expect: () => string
+ * type Example2 = FunctionReturnNonNullable<NoNull>
+ * ```
+ */
+export type FunctionReturnNonNullable<F extends AnyFunction> =
+  (...args: Parameters<F>) => NonNullable<ReturnType<F>>
+
+/**
+ * Extract specific type from union return type.
+ *
+ * @example
+ * ```
+ * type Func = () => string | number | boolean
+ * // Expect: () => string
+ * type Example1 = FunctionReturnExtract<Func, string>
+ * // Expect: () => string | number
+ * type Example2 = FunctionReturnExtract<Func, string | number>
+ * ```
+ */
+export type FunctionReturnExtract<F extends AnyFunction, U> =
+  (...args: Parameters<F>) => Extract<ReturnType<F>, U>
+
+/**
+ * Exclude specific type from union return type.
+ *
+ * @example
+ * ```
+ * type Func = () => string | number | boolean
+ * // Expect: () => number | boolean
+ * type Example1 = FunctionReturnExclude<Func, string>
+ * // Expect: () => boolean
+ * type Example2 = FunctionReturnExclude<Func, string | number>
+ * ```
+ */
+export type FunctionReturnExclude<F extends AnyFunction, U> =
+  (...args: Parameters<F>) => Exclude<ReturnType<F>, U>
+
+// ============================================================================
+// Manipulation (functional)
+// ============================================================================
+
+/**
+ * Compose two functions (f1(f2(x))).
+ *
+ * @example
+ * ```
+ * type F1 = (x: number) => string
+ * type F2 = (x: boolean) => number
+ * // Expect: (x: boolean) => string
+ * type Example1 = FunctionCompose<F1, F2>
+ * ```
+ */
+export type FunctionCompose<F1 extends AnyFunction, F2 extends AnyFunction> =
+  ReturnType<F2> extends Parameters<F1>[0]
+  ? (...args: Parameters<F2>) => ReturnType<F1>
+  : never
+
+/**
+ * Pipe two functions (f2(f1(x))).
+ *
+ * @example
+ * ```
+ * type F1 = (x: boolean) => number
+ * type F2 = (x: number) => string
+ * // Expect: (x: boolean) => string
+ * type Example1 = FunctionPipe<F1, F2>
+ * ```
+ */
+export type FunctionPipe<F1 extends AnyFunction, F2 extends AnyFunction> = FunctionCompose<F2, F1>
+
+interface FunctionComposeError<Fn, Expected, Got> {
+  __compose_error__: true
+  function: Fn
+  expected: Expected
+  got: Got
+}
+type FunctionComposeChain<
+  Fns extends AnyFunction[],
+  CurrentReturn,
+  InitialArgs extends any[]
+> =
+  Fns extends []
+  ? (...args: InitialArgs) => CurrentReturn
+  : (
+    TupleLast<Fns> extends (arg: infer A) => infer R
+    ? (
+      [CurrentReturn] extends [A]
+      ? FunctionComposeChain<TuplePrev<Fns>, R, InitialArgs>
+      : FunctionComposeError<TupleLast<Fns>, A, CurrentReturn>
+    )
+    : never
+  )
+/**
+ * Compose multiple functions from right to left.
+ *
+ * @example
+ * ```
+ * type F1 = (x: string) => number
+ * type F2 = (x: boolean) => string
+ * type F3 = (x: symbol) => boolean
+ * // Expect: (x: symbol) => number
+ * type Example1 = FunctionComposeAll<[F1, F2, F3]>
+ * ```
+ */
+export type FunctionComposeAll<Fns extends AnyFunction[]> =
+  Fns extends [AnyFunction]
+  ? Fns[0]
+  : (
+    TupleLast<Fns> extends (...args: infer Args) => infer R
+    ? FunctionComposeChain<TuplePrev<Fns>, R, Args>
+    : never
+  )
+
+/**
+ * Pipe multiple functions from left to right.
+ *
+ * @example
+ * ```
+ * type F1 = (x: symbol) => boolean
+ * type F2 = (x: boolean) => string
+ * type F3 = (x: string) => number
+ * // Expect: (x: symbol) => number
+ * type Example1 = FunctionPipeAll<[F1, F2, F3]>
+ * ```
+ */
+export type FunctionPipeAll<Fns extends readonly AnyFunction[]> =
+  FunctionComposeAll<TupleReverse<Fns>>
+
+/**
+ * Create a union of function types.
+ *
+ * @example
+ * ```
+ * type F1 = (a: number) => string
+ * type F2 = (b: boolean) => number
+ * // Expect: F1 | F2
+ * type Example1 = FunctionUnion<F1, F2>
+ * ```
+ */
+export type FunctionUnion<F1 extends AnyFunction, F2 extends AnyFunction> = F1 | F2
+
+/**
+ * Create an intersection of function types (overload).
+ *
+ * @example
+ * ```
+ * type F1 = (a: number) => string
+ * type F2 = (b: boolean) => number
+ * // Expect: F1 & F2 (creates overload)
+ * type Example1 = FunctionIntersection<F1, F2>
+ * ```
+ */
+export type FunctionIntersection<F1 extends AnyFunction, F2 extends AnyFunction> = F1 & F2
+
+/**
+ * Merge two function signatures (parameter union, return intersection).
+ *
+ * @example
+ * ```
+ * type F1 = (a: number) => string
+ * type F2 = (a: number) => number
+ * // Expect: (a: number) => string & number (never)
+ * type Example1 = FunctionMerge<F1, F2>
+ * ```
+ */
+export type FunctionMerge<F1 extends AnyFunction, F2 extends AnyFunction> =
+  (...args: Parameters<F1> | Parameters<F2>) => ReturnType<F1> & ReturnType<F2>
+
+type InternalCurry<P extends readonly any[], R> =
+  P extends [infer First, ...infer Rest]
+  ? (arg: First) => (Rest extends [] ? R : InternalCurry<Rest, R>)
+  : R
+/**
+ * Curry a function type.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string, c: boolean) => void
+ * // Expect: (a: number) => (b: string) => (c: boolean) => void
+ * type Example1 = FunctionCurry<Func>
+ * ```
+ */
+export type FunctionCurry<F extends AnyFunction> = InternalCurry<Parameters<F>, ReturnType<F>>
+
+type InternalUncurry<F, Acc extends readonly any[] = []> =
+  F extends (arg: infer A) => infer R
+  ? InternalUncurry<R, [...Acc, A]>
+  : (...args: Acc) => F
+/**
+ * Uncurry a curried function type.
+ *
+ * @example
+ * ```
+ * type Curried = (a: number) => (b: string) => (c: boolean) => void
+ * // Expect: (a: number, b: string, c: boolean) => void
+ * type Example1 = FunctionUncurry<Curried>
+ * type Single = (a: number) => string
+ * // Expect: (a: number) => string
+ * type Example2 = FunctionUncurry<Single>
+ * ```
+ */
+export type FunctionUncurry<F> = InternalUncurry<F>
+
+type InternalPartialApply<P extends readonly any[], Applied extends readonly any[]> =
+  Applied extends []
+  ? P
+  : (P extends [any, ...infer Rest]
+    ? (Applied extends [any, ...infer RestApplied]
+      ? InternalPartialApply<Rest, RestApplied>
+      : P)
+    : P)
+/**
+ * Partially apply arguments to a function.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string, c: boolean) => void
+ * // Expect: (c: boolean) => void
+ * type Example1 = FunctionPartialApply<Func, [number, string]>
+ * ```
+ */
+export type FunctionPartialApply<F extends AnyFunction, Args extends readonly any[]> =
+  (...args: InternalPartialApply<Parameters<F>, Args>) => ReturnType<F>
+
+/**
+ * Bind first N arguments of a function.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string, c: boolean) => void
+ * // Expect: (c: boolean) => void
+ * type Example1 = FunctionBind<Func, [number, string]>
+ * // Expect: (b: string, c: boolean) => void
+ * type Example2 = FunctionBind<Func, [number]>
+ * ```
+ */
+export type FunctionBind<F extends AnyFunction, BoundArgs extends readonly any[]> =
+  FunctionPartialApply<F, BoundArgs>
+
+// ============================================================================
+// Conversion
+// ============================================================================
+
+/**
+ * Convert a regular function to a constructor function.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string) => MyClass
+ * // Expect: new (a: number, b: string) => MyClass
+ * type Example1 = FunctionToClassConstructor<Func, MyClass>
+ * ```
+ */
+export type FunctionToClassConstructor<F extends AnyFunction, Instance> =
+  new (...args: Parameters<F>) => Instance
+
+/**
+ * Convert a function to an object method signature.
+ *
+ * @example
+ * ```
+ * type Func = (a: number, b: string) => boolean
+ * // Expect: { method(a: number, b: string): boolean }
+ * type Example1 = FunctionToObject<Func, 'method'>
+ * ```
+ */
+export type FunctionToObject<F extends AnyFunction, Key extends string> =
+  { [K in Key]: F }