// 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
// ============================================================================

/**
 * @description Type for a no-operation function.
 *
 * @example
 *   ```
 *   // Expect: () => void
 *   type Example1 = FunctionNoop
 *   ```
 */
export type FunctionNoop = () => void

/**
 * @description 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

/**
 * @description Type for a constant function.
 *
 * @example
 *   ```
 *   // Expect: () => string
 *   type Example1 = FunctionConstant<string>
 *   // Expect: () => number
 *   type Example2 = FunctionConstant<number>
 *   ```
 */
export type FunctionConstant<T> = () => T

/**
 * @description Interface for type guard functions that use type predicates.
 *
 * Type predicates allow functions to narrow types at compile time.
 *
 * @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'
 *   ```
 *
 * @see {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates}
 * @see {@link https://github.com/ts-essentials/ts-essentials#predicatetype}
 */
export interface FunctionPredicate<Target = unknown> {
  (target: Target, ..._: unknown[]): target is Target
  (target: unknown, ..._: unknown[]): target is Target
}

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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>>

/**
 * @description 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>

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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
// ============================================================================

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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
// ============================================================================

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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
// ============================================================================

/**
 * @description 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

/**
 * @description 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>

/**
 * @description 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>>

/**
 * @description 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>>

/**
 * @description 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>

/**
 * @description 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>>

/**
 * @description Extract the predicated type from a type guard function.
 *
 * @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>
 *   ```
 *
 * @see {@link https://github.com/ts-essentials/ts-essentials#predicatetype}
 */
export type FunctionPredicateType<F extends FunctionPredicate> = F extends ((
  target: unknown,
  ...rest: any[]
) => target is infer P)
  ? P
  : never

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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)
// ============================================================================

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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>

/**
 * @description 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)
// ============================================================================

/**
 * @description 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>>

/**
 * @description 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>

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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>

/**
 * @description 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>

/**
 * @description 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)
// ============================================================================

/**
 * @description 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

/**
 * @description 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]
/**
 * @description 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>

/**
 * @description 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>

/**
 * @description 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
/**
 * @description 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>

/**
 * @description 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>

/**
 * @description 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
/**
 * @description 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>

/**
 * @description 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>

/**
 * @description 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
/**
 * @description 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>

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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>

/**
 * @description 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

/**
 * @description 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)
// ============================================================================

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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>>

/**
 * @description 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>]

/**
 * @description 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

/**
 * @description 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>>

/**
 * @description 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>

/**
 * @description 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)
// ============================================================================

/**
 * @description 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

/**
 * @description 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
/**
 * @description 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

/**
 * @description 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>
>

/**
 * @description 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

/**
 * @description 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

/**
 * @description 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
/**
 * @description 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
/**
 * @description 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
/**
 * @description 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>

/**
 * @description 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
// ============================================================================

/**
 * @description 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

/**
 * @description 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 }