@types/ramda/index.d.ts

// Type definitions for ramda 0.28
// Project: https://ramdajs.com
// Definitions by: Scott O'Malley <https://github.com/TheHandsomeCoder>
//                 Erwin Poeze <https://github.com/donnut>
//                 Matt DeKrey <https://github.com/mdekrey>
//                 Stephen King <https://github.com/sbking>
//                 Alejandro Fernandez Haro <https://github.com/afharo>
//                 Vítor Castro <https://github.com/teves-castro>
//                 Simon Højberg <https://github.com/hojberg>
//                 Samson Keung <https://github.com/samsonkeung>
//                 Angelo Ocana <https://github.com/angeloocana>
//                 Rayner Pupo <https://github.com/raynerd>
//                 Nikita Moshensky <https://github.com/moshensky>
//                 Ethan Resnick <https://github.com/ethanresnick>
//                 Tomas Szabo <https://github.com/deftomat>
//                 Maciek Blim <https://github.com/blimusiek>
//                 Marcin Biernat <https://github.com/biern>
//                 Rayhaneh Banyassady <https://github.com/rayhaneh>
//                 Ryan McCuaig <https://github.com/rgm>
//                 John Ottenlips <https://github.com/jottenlips>
//                 Nitesh Phadatare <https://github.com/minitesh>
//                 Krantisinh Deshmukh <https://github.com/krantisinh>
//                 Aram Kharazyan <https://github.com/nemo108>
//                 Jituan Lin <https://github.com/jituanlin>
//                 Philippe Mills <https://github.com/Philippe-mills>
//                 Saul Mirone <https://github.com/Saul-Mirone>
//                 Nicholai Nissen <https://github.com/Nicholaiii>
//                 Jorge Santana <https://github.com/LORDBABUINO>
//                 Mikael Couzic <https://github.com/couzic>
//                 Nikita Balikhin <https://github.com/NEWESTERS>
//                 Wang Zengdi <https://github.com/adispring>
//                 Marcus Blättermann <https://github.com/essenmitsosse>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 4.2

import * as _ from 'ts-toolbelt';
import {
    AnyConstructor,
    AnyFunction,
    AtLeastOneFunctionsFlow,
    AtLeastOneFunctionsFlowFromRightToLeft,
    AssocPartialOne,
    CondPair,
    CondPairTypeguard,
    Dictionary,
    Evolvable,
    Evolve,
    Evolver,
    Falsy,
    Find,
    Functor,
    InputTypesOfFns,
    KeyValuePair,
    Lens,
    Merge,
    MergeAll,
    ObjectHavingSome,
    ObjPred,
    Ord,
    Ordering,
    Path,
    Placeholder,
    Pred,
    PredTypeguard,
    Reduced,
    ReturnTypesOfFns,
    ValueOfUnion,
    Take,
    ToTupleOfArray,
    ToTupleOfFunction,
    Tuple,
    Fn,
    IfFunctionsArgumentsDoNotOverlap,
    LargestArgumentsList,
    mergeArrWithLeft,
    Prop,
} from './tools';

export * from './tools';

// NOTE: Example doesn't work with current level of support
/**
 * A special placeholder value used to specify "gaps" within curried functions,
 * allowing partial application of any combination of arguments, regardless of their positions.
 *
 * If `g` is a curried ternary function and `_` is `R.__`, the following are equivalent:
 *  - `g(1, 2, 3)`
 *  - `g(_, 2, 3)(1)`
 *  - `g(_, _, 3)(1)(2)`
 *  - `g(_, _, 3)(1, 2)`
 *  - `g(_, 2, _)(1, 3)`
 *  - `g(_, 2)(1)(3)`
 *  - `g(_, 2)(1, 3)`
 *  - `g(_, 2)(_, 3)(1)`
 *
 * @example
 * ```typescript
 * const greet = R.replace('{name}', R.__, 'Hello, {name}!');
 * greet('Alice'); //=> 'Hello, Alice!'
 * ```
 */
export const __: Placeholder;

/**
 * Adds two values. Equivalent to `a + b` but curried.
 *
 * @example
 * ```typescript
 * R.add(2, 3);       //=>  5
 * R.add(7)(10);      //=> 17
 * ```
 */
export function add(a: number, b: number): number;
export function add(a: number): (b: number) => number;

/**
 * Creates a new list iteration function from an existing one by adding two new parameters to its callback
 * function: the current index, and the entire list.
 *
 * This would turn, for instance, {@link map `R.map`} function into one that more closely resembles `Array.prototype.map`.
 *
 * @note This will only work for functions in which the iteration callback function is the first parameter,
 * and where the list is the last parameter.
 * (This latter might be unimportant if the list parameter is not used.)
 *
 * See also {@link subtract}.
 *
 * @example
 * ```typescript
 * const mapIndexed = R.addIndex(R.map);
 * mapIndexed((val, idx) => idx + '-' + val, ['f', 'o', 'o', 'b', 'a', 'r']);
 * //=> ['0-f', '1-o', '2-o', '3-b', '4-a', '5-r']
 * ```
 */
/* Special case for forEach */
export function addIndex<T>(
    fn: (f: (item: T) => void, list: readonly T[]) => T[],
): _.F.Curry<(a: (item: T, idx: number, list: T[]) => void, b: readonly T[]) => T[]>;
/* Special case for filter */
export function addIndex<T>(
    fn: (f: (item: T) => boolean, list: readonly T[]) => T[],
): _.F.Curry<(a: (item: T, idx: number, list: T[]) => boolean, b: readonly T[]) => T[]>;
/* Special case for map */
export function addIndex<T, U>(
    fn: (f: (item: T) => U, list: readonly T[]) => U[],
): _.F.Curry<(a: (item: T, idx: number, list: T[]) => U, b: readonly T[]) => U[]>;
/* Special case for reduce */
export function addIndex<T, U>(
    fn: (f: (acc: U, item: T) => U, aci: U, list: readonly T[]) => U,
): _.F.Curry<(a: (acc: U, item: T, idx: number, list: T[]) => U, b: U, c: readonly T[]) => U>;

/**
 * Applies a function to the value at the given index of an array, returning a new copy of the array with the
 * element at the given index replaced with the result of the function application.
 *
 * See also {@link update}.
 *
 * @example
 * ```typescript
 * R.adjust(1, R.toUpper, ['a', 'b', 'c', 'd']);      //=> ['a', 'B', 'c', 'd']
 * R.adjust(-1, R.toUpper, ['a', 'b', 'c', 'd']);     //=> ['a', 'b', 'c', 'D']
 * ```
 */
export function adjust<T>(index: number, fn: (a: T) => T, list: readonly T[]): T[];
export function adjust<T>(index: number, fn: (a: T) => T): (list: readonly T[]) => T[];

/**
 * Returns `true` if all elements of the list match the predicate, `false` if there are any that don't.
 *
 * Dispatches to the `all` method of the second argument, if present.
 *
 * Acts as a transducer if a transformer is given in list position.
 *
 * See also {@link any}, {@link none}, {@link transduce}.
 *
 * @example
 * ```typescript
 * const equals3 = R.equals(3);
 * R.all(equals3)([3, 3, 3, 3]); //=> true
 * R.all(equals3)([3, 3, 1, 3]); //=> false
 * ```
 */
export function all<T>(fn: (a: T) => boolean, list: readonly T[]): boolean;
export function all<T>(fn: (a: T) => boolean): (list: readonly T[]) => boolean;

/**
 * Takes a list of predicates and returns a predicate that returns true for a given list of arguments
 * if every one of the provided predicates is satisfied by those arguments.
 *
 * The function returned is a curried function whose arity matches that of the highest-arity predicate.
 *
 * See also {@link anyPass}.
 *
 * @example
 * ```typescript
 * type Card = { rank: string; suit: string; };
 *
 * const isQueen = R.propEq('rank', 'Q');
 * const isSpade = R.propEq('suit', '♠︎');
 * const isQueenOfSpades = R.allPass<R.Pred<[Card]>>([isQueen, isSpade]);
 *
 * isQueenOfSpades({rank: 'Q', suit: '♣︎'}); //=> false
 * isQueenOfSpades({rank: 'Q', suit: '♠︎'}); //=> true
 * ```
 */
export function allPass<T, TF1 extends T, TF2 extends T>(
    preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>],
): (a: T) => a is TF1 & TF2;
export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T>(
    preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>],
): (a: T) => a is TF1 & TF2 & TF3;
export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T>(
    preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>],
): (a: T) => a is TF1 & TF2 & TF3;
export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T>(
    preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>, PredTypeguard<T, TF4>],
): (a: T) => a is TF1 & TF2 & TF3 & TF4;
export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T>(
    preds: [
        PredTypeguard<T, TF1>,
        PredTypeguard<T, TF2>,
        PredTypeguard<T, TF3>,
        PredTypeguard<T, TF4>,
        PredTypeguard<T, TF5>,
    ],
): PredTypeguard<T, TF1 & TF2 & TF3 & TF4 & TF5>;
export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T, TF6 extends T>(
    preds: [
        PredTypeguard<T, TF1>,
        PredTypeguard<T, TF2>,
        PredTypeguard<T, TF3>,
        PredTypeguard<T, TF4>,
        PredTypeguard<T, TF5>,
        PredTypeguard<T, TF6>,
    ],
): PredTypeguard<T, TF1 & TF2 & TF3 & TF4 & TF5 & TF6>;
export function allPass<F extends Pred>(preds: readonly F[]): F;

/**
 * Returns a function that always returns the given value.
 *
 * @note For non-primitives the value returned is a reference to the original value.
 *
 * This function is known as `const`, `constant`, or `K` (for K combinator) in other languages and libraries.
 *
 * @example
 * ```typescript
 * const t = R.always('Tee');
 * t(); //=> 'Tee'
 * ```
 */
export function always<T>(val: T): (...args: unknown[]) => T;

/**
 * A function that returns the first argument if it's falsy otherwise the second argument.
 *
 * See also {@link both}, {@link or}, {@link xor}.
 *
 * @note This is **not** short-circuited, meaning that if expressions are passed they are both evaluated.
 *
 * @example
 * ```typescript
 * R.and(true, true); //=> true
 * R.and(true, false); //=> false
 * R.and(false, true); //=> false
 * R.and(false, false); //=> false
 * ```
 */
export function and<T, U>(a: T, b: U): T | U;
export function and<T>(a: T): <U>(b: U) => T | U;

/**
 * Returns the result of applying the `onSuccess` function to the value inside a successfully resolved `Promise`.
 * This is useful for working with `Promise`s inside function compositions.
 *
 * See also {@link otherwise}.
 *
 * @example
 * ```typescript
 * type Query = { query: { email: string; }; };
 *
 * const makeQuery = (email: string) => ({ query: { email }});
 * const fetchMember = (request: Query) =>
 *   Promise.resolve({ firstName: 'Bob', lastName: 'Loblaw', id: 42 });
 *
 * //getMemberName :: String -> Promise ({ firstName, lastName })
 * const getMemberName = R.pipe(
 *   makeQuery,
 *   fetchMember,
 *   R.andThen(R.pick(['firstName', 'lastName']))
 * );
 *
 * getMemberName('bob@gmail.com').then(console.log);
 * ```
 */
export function andThen<A, B>(onSuccess: (a: A) => B | Promise<B>, promise: Promise<A>): Promise<B>;
export function andThen<A, B>(onSuccess: (a: A) => B | Promise<B>): (promise: Promise<A>) => Promise<B>;

/**
 * Returns `true` if at least one of elements of the list match the predicate, `false` otherwise.
 *
 * Dispatches to the `any` method of the second argument, if present.
 *
 * Acts as a transducer if a transformer is given in list position.
 *
 * See also {@link all}, {@link none}, {@link transduce}.
 *
 * @example
 * ```typescript
 * const lessThan0 = R.flip(R.lt)(0);
 * const lessThan2 = R.flip(R.lt)(2);
 * R.any(lessThan0)([1, 2]); //=> false
 * R.any(lessThan2)([1, 2]); //=> true
 * ```
 */
export function any<T>(fn: (a: T) => boolean, list: readonly T[]): boolean;
export function any<T>(fn: (a: T) => boolean): (list: readonly T[]) => boolean;

/**
 * Takes a list of predicates and returns a predicate that returns true for a
 * given list of arguments if at least one of the provided predicates is
 * satisfied by those arguments.
 *
 * The function returned is a curried function whose arity matches that of the
 * highest-arity predicate.
 *
 * See also {@link allPass}.
 *
 * @example
 * ```typescript
 * type Card = { rank: string; suit: string; };
 *
 * const isClub = R.propEq('suit', '♣');
 * const isSpade = R.propEq('suit', '♠');
 * const isBlackCard = R.anyPass<R.Pred<[Card]>>([isClub, isSpade]);
 *
 * isBlackCard({rank: '10', suit: '♣'}); //=> true
 * isBlackCard({rank: 'Q', suit: '♠'}); //=> true
 * isBlackCard({rank: 'Q', suit: '♦'}); //=> false
 * ```
 */
export function anyPass<T, TF1 extends T, TF2 extends T>(
    preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>],
): (a: T) => a is TF1 | TF2;
export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T>(
    preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>],
): (a: T) => a is TF1 | TF2 | TF3;
export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T>(
    preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>],
): (a: T) => a is TF1 | TF2 | TF3;
export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T>(
    preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>, PredTypeguard<T, TF4>],
): (a: T) => a is TF1 | TF2 | TF3 | TF4;
export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T>(
    preds: [
        PredTypeguard<T, TF1>,
        PredTypeguard<T, TF2>,
        PredTypeguard<T, TF3>,
        PredTypeguard<T, TF4>,
        PredTypeguard<T, TF5>,
    ],
): PredTypeguard<T, TF1 | TF2 | TF3 | TF4 | TF5>;
export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T, TF6 extends T>(
    preds: [
        PredTypeguard<T, TF1>,
        PredTypeguard<T, TF2>,
        PredTypeguard<T, TF3>,
        PredTypeguard<T, TF4>,
        PredTypeguard<T, TF5>,
        PredTypeguard<T, TF6>,
    ],
): PredTypeguard<T, TF1 | TF2 | TF3 | TF4 | TF5 | TF6>;
export function anyPass<F extends Pred>(preds: readonly F[]): F;

/**
 * `ap` applies a list of functions to a list of values.
 *
 * Dispatches to the `ap` method of the first argument, if present.
 * Also treats curried functions as applicatives.
 *
 * @example
 * ```typescript
 * R.ap([R.multiply(2), R.add(3)], [1,2,3]); //=> [2, 4, 6, 4, 5, 6]
 * R.ap([R.concat('tasty '), R.toUpper], ['pizza', 'salad']); //=> ["tasty pizza", "tasty salad", "PIZZA", "SALAD"]
 *
 * // R.ap can also be used as S combinator
 * // when only two functions are passed
 * R.ap((s, s2) => R.concat(s, s2), R.toUpper)('Ramda') //=> 'RamdaRAMDA'
 * ```
 */
export function ap<T, U>(fns: ReadonlyArray<(a: T) => U>, vs: readonly T[]): U[];
export function ap<T, U>(fns: ReadonlyArray<(a: T) => U>): (vs: readonly T[]) => U[];
export function ap<R, A, B>(fn: (r: R, a: A) => B, fn1: (r: R) => A): (r: R) => B;

/**
 * Returns a new list, composed of n-tuples of consecutive elements.
 * If `n` is greater than the length of the list, an empty list is returned.
 *
 * Acts as a transducer if a transformer is given in list position.
 *
 * See also {@link transduce}.
 *
 * @example
 * ```typescript
 * R.aperture(2, [1, 2, 3, 4, 5]); //=> [[1, 2], [2, 3], [3, 4], [4, 5]]
 * R.aperture(3, [1, 2, 3, 4, 5]); //=> [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
 * R.aperture(7, [1, 2, 3, 4, 5]); //=> []
 * ```
 */
export function aperture<N extends number, T>(n: N, list: readonly T[]): Array<Tuple<T, N>> | [];
export function aperture<N extends number>(n: N): <T>(list: readonly T[]) => Array<Tuple<T, N>> | [];

/**
 * Returns a new list containing the contents of the given list, followed by the given element.
 *
 * See also {@link prepend}.
 *
 * @example
 * ```typescript
 * R.append('tests', ['write', 'more']); //=> ['write', 'more', 'tests']
 * R.append('tests', []); //=> ['tests']
 * R.append<string | string[]>(['tests'], ['write', 'more']); //=> ['write', 'more', ['tests']]
 * ```
 */
export function append<T>(el: T, list: readonly T[]): T[];
export function append<T>(el: T): (list: readonly T[]) => T[];

/**
 * Applies function `fn` to the argument list `args`.
 * This is useful for creating a fixed-arity function from a variadic function.
 * `fn` should be a bound function if context is significant.
 *
 * See also {@link call}, {@link unapply}.
 */
export function apply<F extends AnyFunction>(fn: F, args: Parameters<F>): ReturnType<F>;
export function apply<F extends AnyFunction>(fn: F): (args: Parameters<F>) => ReturnType<F>;

/**
 * Given a spec object recursively mapping properties to functions,
 * creates a function producing an object of the same structure,
 * by mapping each property to the result of calling its associated function with the supplied arguments.
 *
 * See also {@link converge}, {@link juxt}.
 *
 * @example
 * ```typescript
 * const getMetrics = R.applySpec({
 *   sum: R.add,
 *   nested: { mul: R.multiply }
 * });
 * getMetrics(2, 4); // => { sum: 6, nested: { mul: 8 } }
 * ```
 */
export function applySpec<Obj extends Record<string, AnyFunction>>(
    obj: Obj,
): (...args: Parameters<Obj[keyof Obj]>) => { [Key in keyof Obj]: ReturnType<Obj[Key]> };
export function applySpec<T>(obj: any): (...args: unknown[]) => T;

/**
 * Takes a value and applies a function to it.
 *
 * This function is also known as the `thrush` combinator.
 *
 * @example
 * ```typescript
 * const t42 = R.applyTo(42);
 * t42(R.identity); //=> 42
 * t42(R.add(1)); //=> 43
 * ```
 */
export function applyTo<T, U>(el: T, fn: (t: T) => U): U;
export function applyTo<T>(el: T): <U>(fn: (t: T) => U) => U;

/**
 * Makes an ascending comparator function out of a function that returns a value that can be compared with `<` and `>`.
 *
 * See also {@link descend}.
 *
 * @example
 * ```typescript
 * const byAge = R.ascend(R.prop<number>('age'));
 * const people = [
 *   { name: 'Emma', age: 70 },
 *   { name: 'Peter', age: 78 },
 *   { name: 'Mikhail', age: 62 },
 * ];
 * const peopleByYoungestFirst = R.sort(byAge, people);
 *   //=> [{ name: 'Mikhail', age: 62 },{ name: 'Emma', age: 70 }, { name: 'Peter', age: 78 }]
 * ```
 */
export function ascend<T>(fn: (obj: T) => Ord, a: T, b: T): Ordering;
export function ascend<T>(fn: (obj: T) => Ord): (a: T, b: T) => Ordering;

/**
 * Makes a shallow clone of an object, setting or overriding the specified property with the given value.
 *
 * @note This copies and flattens prototype properties onto the new object as well.
 * All non-primitive properties are copied by reference.
 *
 * See also {@link dissoc}, {@link pick}.
 *
 * @example
 * ```typescript
 * R.assoc('c', 3, {a: 1, b: 2}); //=> {a: 1, b: 2, c: 3}
 * ```
 */
export function assoc<T, U>(__: Placeholder, val: T, obj: U): <K extends string>(prop: K) => K extends keyof U ? T extends U[K] ? U : Record<K, T> & Omit<U, K> : Record<K, T> & Omit<U, K>;
export function assoc<U, K extends keyof U>(prop: K, __: Placeholder, obj: U): <T>(val: T) => T extends U[K] ? U : Record<K, T> & Omit<U, K>;
export function assoc<U, K extends string>(prop: K, __: Placeholder, obj: U): <T>(val: T) => Record<K, T> & Omit<U, K>;
export function assoc<K extends keyof U, U>(prop: K, val: U[K], obj: U): U;
export function assoc<T, U, K extends string>(prop: K, val: T, obj: U): Record<K, T> & Omit<U, K>;
export function assoc<T, K extends string>(prop: K, val: T): <U>(obj: U) => Record<K, T> & Omit<U, K>;
export function assoc<K extends string>(prop: K): AssocPartialOne<K>;

/**
 * Makes a shallow clone of an object,
 * setting or overriding the nodes required to create the given path,
 * and placing the specific value at the tail end of that path.
 *
 * @note This copies and flattens prototype properties onto the new object as well.
 * All non-primitive properties are copied by reference.
 *
 * See also {@link dissocPath}.
 *
 * @example
 * ```typescript
 * R.assocPath(['a', 'b', 'c'], 42, {a: {b: {c: 0}}}); //=> {a: {b: {c: 42}}}
 *
 * // Any missing or non-object keys in path will be overridden
 * R.assocPath(['a', 'b', 'c'], 42, {a: 5}); //=> {a: {b: {c: 42}}}
 * ```
 */
export function assocPath<T, U>(__: Placeholder, val: T, obj: U): (path: Path) => U;
export function assocPath<T, U>(path: Path, __: Placeholder, obj: U): (val: T) => U;
export function assocPath<T, U>(path: Path, val: T, obj: U): U;
export function assocPath<T, U>(path: Path, val: T): (obj: U) => U;
export function assocPath<T, U>(path: Path): _.F.Curry<(a: T, b: U) => U>;

/**
 * Wraps a function of any arity (including nullary) in a function that accepts exactly 2
 * parameters. Any extraneous parameters will not be passed to the supplied function.
 *
 * See also {@link nAry}, {@link unary}.
 *
 * @example
 * ```typescript
 * const takesThreeArgs = function(a: number, b: number, c: number) {
 *   return [a, b, c];
 * };
 * takesThreeArgs.length; //=> 3
 * takesThreeArgs(1, 2, 3); //=> [1, 2, 3]
 *
 * const takesTwoArgs = R.binary(takesThreeArgs);
 * takesTwoArgs.length; //=> 2
 * // Only 2 arguments are passed to the wrapped function
 * // @ts-expect-error TypeScript is designed to not let you do this
 * takesTwoArgs(1, 2, 3); //=> [1, 2, undefined]
 * ```
 */
export function binary<T extends AnyFunction>(fn: T): (...arg: _.T.Take<Parameters<T>, '2'>) => ReturnType<T>;

/**
 * Creates a function that is bound to a context.
 *
 * @note `R.bind` does not provide the additional argument-binding capabilities of `Function.prototype.bind`.
 *
 * @example
 * ```typescript
 * const log = R.bind(console.log, console);
 * R.pipe(R.assoc('a', 2), R.tap(log), R.assoc('a', 3))({a: 1}); //=> {a: 3}
 * // logs {a: 2}
 * ```
 */
export function bind<F extends AnyFunction, T>(fn: F, thisObj: T): (...args: Parameters<F>) => ReturnType<F>;
export function bind<F extends AnyFunction, T>(fn: F): (thisObj: T) => (...args: Parameters<F>) => ReturnType<F>;

/**
 * A function which calls the two provided functions and returns the `&&` of the
 * results. It returns the result of the first function if it is falsy and
 * the result of the second function otherwise.
 *
 * @note This is short-circuited,
 * meaning that the second function will not be invoked if the first returns a falsy value.
 *
 * In addition to functions, `R.both` also accepts any fantasy-land compatible applicative functor.
 *
 * See also {@link either}, {@link and}.
 *
 * @example
 * ```typescript
 * const gt10 = R.gt(R.__, 10)
 * const lt20 = R.lt(R.__, 20)
 * const f = R.both(gt10, lt20);
 * f(15); //=> true
 * f(30); //=> false
 * ```
 */
export function both<T, TF1 extends T, TF2 extends T>(
    pred1: PredTypeguard<T, TF1>,
    pred2: PredTypeguard<T, TF2>,
): (a: T) => a is TF1 & TF2;
export function both<T extends Pred>(pred1: T, pred2: T): T;
export function both<T extends Pred>(pred1: T): (pred2: T) => T;

// NOTE: It is currently difficult to use it as a converging function for `R.converge`
/**
 * Returns the result of calling its first argument with the remaining arguments.
 * This is occasionally useful as a converging function for {@link converge `R.converge`}:
 * the first branch can produce a function
 * while the remaining branches produce values to be passed to that function as its arguments.
 *
 * See also {@link apply}.
 *
 * @example
 * ```typescript
 * R.call<(a: number, b: number) => number>(R.add, 1, 2); //=> 3
 *
 * const indentN = R.pipe(
 *   R.repeat(' '),
 *   R.join(''),
 *   R.replace(/^(?!$)/gm)
 * );
 * ```
 */
export function call<T extends AnyFunction>(fn: T, ...args: Parameters<T>): ReturnType<T>;

/**
 * `chain` maps a function over a list and concatenates the results. `chain` is also known as `flatMap` in some libraries.
 *
 * Dispatches to the `chain` method of the second argument, if present, according to the FantasyLand Chain spec.
 *
 * If second argument is a function, `chain(f, g)(x)` is equivalent to `f(g(x), x)`.
 *
 * Acts as a transducer if a transformer is given in list position.
 *
 * See also {@link transduce}.
 *
 * @example
 * ```typescript
 * const duplicate = <T>(n: T) => [n, n];
 * R.chain(duplicate, [1, 2, 3]); //=> [1, 1, 2, 2, 3, 3]
 *
 * R.chain(R.append, R.head)([1, 2, 3]); //=> [1, 2, 3, 1]
 * ```
 */
export function chain<A, B, T = never>(fn: (n: A) => readonly B[], list: readonly A[]): B[];
export function chain<A, B, T = never>(fn: (n: A) => readonly B[]): (list: readonly A[]) => B[];

export function chain<A, Ma extends { chain: (fn: (a: A) => Mb) => Mb }, Mb>(fn: (a: A) => Mb, monad: Ma): Mb;
export function chain<A, Ma extends { chain: (fn: (a: A) => Mb) => Mb }, Mb>(fn: (a: A) => Mb): (monad: Ma) => Mb;

export function chain<A, B, R>(aToMb: (a: A, r: R) => B, Ma: (r: R) => A): (r: R) => B;
export function chain<A, B, R>(aToMb: (a: A, r: R) => B): (Ma: (r: R) => A) => (r: R) => B;

/**
 * Restricts a number to be within a range.
 * Also works for other ordered types such as strings and `Date`s.
 *
 * @example
 * ```typescript
 * R.clamp(1, 10, -5) // => 1
 * R.clamp(1, 10, 15) // => 10
 * R.clamp(1, 10, 4)  // => 4
 * ```
 */
export function clamp<T>(min: T, max: T, value: T): T;
export function clamp<T>(min: T, max: T): (value: T) => T;
export function clamp<T>(min: T): (max: T, value: T) => T;
export function clamp<T>(min: T): (max: T) => (value: T) => T;

/**
 * Creates a deep copy of the source that can be used in place of the source object without retaining any references to it.
 * The source object may contain (nested) `Array`s and `Object`s, numbers, strings, booleans and `Date`s.
 * `Functions` are assigned by reference rather than copied.
 *
 * Dispatches to a `clone` method if present.
 *
 * Note that if the source object has multiple nodes that share a reference,
 * the returned object will have the same structure,
 * but the references will be pointed to the location within the cloned value.
 *
 * @example
 * ```typescript
 * const objects = [{}, {}, {}];
 * const objectsClone = R.clone(objects);
 * objects === objectsClone; //=> false
 * objects[0] === objectsClone[0]; //=> false
 * ```
 */
export function clone<T>(value: T): T;
export function clone<T>(value: readonly T[]): T[];

/**
 * Splits a list into sub-lists,
 * based on the result of calling a key-returning function on each element,
 * and grouping the results according to values returned.
 *
 * See also {@link groupBy}, {@link partition}.
 *
 * @example
 * ```typescript
 * R.collectBy(R.prop('type'), [
 *   {type: 'breakfast', item: '☕️'},
 *   {type: 'lunch', item: '🌯'},
 *   {type: 'dinner', item: '🍝'},
 *   {type: 'breakfast', item: '🥐'},
 *   {type: 'lunch', item: '🍕'}
 * ]);
 *
 * // [ [ {type: 'breakfast', item: '☕️'},
 * //     {type: 'breakfast', item: '🥐'} ],
 * //   [ {type: 'lunch', item: '🌯'},
 * //     {type: 'lunch', item: '🍕'} ],
 * //   [ {type: 'dinner', item: '🍝'} ] ]
 * ```
 */
export function collectBy<T, K extends PropertyKey>(keyFn: (value: T) => K, list: readonly T[]): T[][];
export function collectBy<T, K extends PropertyKey>(keyFn: (value: T) => K): (list: readonly T[]) => T[][];

/**
 * Makes a comparator function out of a function that reports whether the first element is less than the second.
 *
 * @example
 * ```typescript
 * type Person = { name: string; age: number; };
 *
 * const byAge = R.comparator<Person>((a, b) => a.age < b.age);
 * const people = [
 *   { name: 'Emma', age: 70 },
 *   { name: 'Peter', age: 78 },
 *   { name: 'Mikhail', age: 62 },
 * ];
 * const peopleByIncreasingAge = R.sort(byAge, people);
 *   //=> [{ name: 'Mikhail', age: 62 },{ name: 'Emma', age: 70 }, { name: 'Peter', age: 78 }]
 * ```
 */
export function comparator<T>(pred: (a: T, b: T) => boolean): (x: T, y: T) => Ordering;

/**
 * Takes a function `f` and returns a function `g` such that
 * if called with the same arguments
 * when `f` returns a truthy value, `g` returns `false`
 * and when `f` returns a falsy value `g` returns `true`.
 *
 * `R.complement` may be applied to any functor.
 *
 * See also {@link not}.
 *
 * @example
 * ```typescript
 * const isNotNil = R.complement(R.isNil);
 * R.isNil(null); //=> true
 * isNotNil(null); //=> false
 * R.isNil(7); //=> false
 * isNotNil(7); //=> true
 * ```
 */
export function complement<T, TFiltered extends T>(
    pred: (value: T) => value is TFiltered,
): (value: T) => value is Exclude<T, TFiltered>;
export function complement<TArgs extends any[]>(pred: (...args: TArgs) => unknown): (...args: TArgs) => boolean;

/**
 * Performs right-to-left function composition.
 * The rightmost function may have any arity;
 * the remaining functions must be unary.
 *
 * @note The result of `R.compose` is not automatically curried.
 *
 * See also {@link pipe}.
 *
 * @example
 * ```typescript
 * const classyGreeting = (firstName: string, lastName: string) => "The name's " + lastName + ", " + firstName + " " + lastName
 * const yellGreeting = R.compose(R.toUpper, classyGreeting);
 * yellGreeting('James', 'Bond'); //=> "THE NAME'S BOND, JAMES BOND"
 *
 * R.compose(Math.abs, R.add(1), R.multiply(2))(-4) //=> 7
 * ```
 */
export function compose<TArgs extends any[], R1, R2, R3, R4, R5, R6, R7, TResult>(
    ...func: [
        fnLast: (a: any) => TResult,
        ...func: Array<(a: any) => any>,
        f7: (a: R6) => R7,
        f6: (a: R5) => R6,
        f5: (a: R4) => R5,
        f4: (a: R3) => R4,
        f3: (a: R2) => R3,
        f2: (a: R1) => R2,
        f1: (...args: TArgs) => R1,
    ]
): (...args: TArgs) => TResult; // fallback overload if number of composed functions greater than 7
export function compose<TArgs extends any[], R1, R2, R3, R4, R5, R6, R7>(
    f7: (a: R6) => R7,
    f6: (a: R5) => R6,
    f5: (a: R4) => R5,
    f4: (a: R3) => R4,
    f3: (a: R2) => R3,
    f2: (a: R1) => R2,
    f1: (...args: TArgs) => R1,
): (...args: TArgs) => R7;
export function compose<TArgs extends any[], R1, R2, R3, R4, R5, R6, R7>(
    f7: (a: R6) => R7,
    f6: (a: R5) => R6,
    f5: (a: R4) => R5,
    f4: (a: R3) => R4,
    f3: (a: R2) => R3,
    f2: (a: R1) => R2,
    f1: (...args: TArgs) => R1,
): (...args: TArgs) => R7;
export function compose<TArgs extends any[], R1, R2, R3, R4, R5, R6>(
    f6: (a: R5) => R6,
    f5: (a: R4) => R5,
    f4: (a: R3) => R4,
    f3: (a: R2) => R3,
    f2: (a: R1) => R2,
    f1: (...args: TArgs) => R1,
): (...args: TArgs) => R6;
export function compose<TArgs extends any[], R1, R2, R3, R4, R5>(
    f5: (a: R4) => R5,
    f4: (a: R3) => R4,
    f3: (a: R2) => R3,
    f2: (a: R1) => R2,
    f1: (...args: TArgs) => R1,
): (...args: TArgs) => R5;
export function compose<TArgs extends any[], R1, R2, R3, R4>(
    f4: (a: R3) => R4,
    f3: (a: R2) => R3,
    f2: (a: R1) => R2,
    f1: (...args: TArgs) => R1,
): (...args: TArgs) => R4;
export function compose<TArgs extends any[], R1, R2, R3>(
    f3: (a: R2) => R3,
    f2: (a: R1) => R2,
    f1: (...args: TArgs) => R1,
): (...args: TArgs) => R3;
export function compose<TArgs extends any[], R1, R2>(
    f2: (a: R1) => R2,
    f1: (...args: TArgs) => R1,
): (...args: TArgs) => R2;
export function compose<TArgs extends any[], R1>(f1: (...args: TArgs) => R1): (...args: TArgs) => R1;

/**
 * Performs right-to-left function composition using transforming function.
 * The last function may have any arity; the remaining functions must be unary.
 *
 * @note The result of `R.composeWith` is not automatically curried.
 * The transforming function is not used on the last argument.
 *
 * See also {@link compose}, {@link pipeWith}.
 *
 * @example
 * ```typescript
 * const composeWhileNotNil = R.composeWith((f, res) => R.isNil(res) ? res : f(res));
 *
 * composeWhileNotNil([R.inc, R.prop('age')])({age: 1}) //=> 2
 * ```
 */
export function composeWith<TArgs extends any[], TResult>(
    transformer: (fn: AnyFunction, intermediatResult: any) => any,
    fns: AtLeastOneFunctionsFlowFromRightToLeft<TArgs, TResult>,
): (...args: TArgs) => TResult;
export function composeWith(
    transformer: (fn: AnyFunction, intermediatResult: any) => any,
): <TArgs extends any[], TResult>(
    fns: AtLeastOneFunctionsFlowFromRightToLeft<TArgs, TResult>,
) => (...args: TArgs) => TResult;

/**
 * Returns the result of concatenating the given lists or strings.
 *
 * @note `R.concat` expects both arguments to be of the same type,
 * unlike the native `Array.prototype.concat` method.
 * It will throw an error if you concat an `Array` with a non-`Array` value.
 *
 * Dispatches to the `concat` method of the first argument, if present.
 * Can also concatenate two members of a fantasy-land compatible semigroup.
 *
 * @example
 * ```typescript
 * R.concat('ABC', 'DEF'); // 'ABCDEF'
 * R.concat([4, 5, 6], [1, 2, 3]); //=> [4, 5, 6, 1, 2, 3]
 * R.concat([], []); //=> []
 * ```
 */
export function concat(
    placeholder: Placeholder,
): (<L1 extends any[], L2 extends any[]>(list1: L1, list2: L2) => [...L1, ...L2]) &
    (<S1 extends string, S2 extends string>(s1: S1, s2: S2) => `${S1}${S2}`);
export function concat<L2 extends any[]>(
    placeholder: Placeholder,
    list2: L2,
): <L1 extends any[]>(list1: L1) => [...L1, ...L2];
export function concat<S2 extends string>(
    placeholder: Placeholder,
    s2: S2,
): <S1 extends string>(s1: S1) => `${S1}${S2}`;
export function concat<L1 extends any[]>(list1: L1): <L2 extends any[]>(list2: L2) => [...L1, ...L2];
export function concat<S1 extends string>(s1: S1): <S2 extends string>(s2: S2) => `${S1}${S2}`;
export function concat<L1 extends any[], L2 extends any[]>(list1: L1, list2: L2): [...L1, ...L2];
export function concat<S1 extends string, S2 extends string>(s1: S1, s2: S2): `${S1}${S2}`;
export function concat(s1: string, s2: string): string;
export function concat(s1: string): (s2: string) => string;

/**
 * Returns a function, `fn`, which encapsulates `if/else, if/else, ...` logic.
 * `R.cond` takes a list of [predicate, transformer] pairs. All of the arguments
 * to `fn` are applied to each of the predicates in turn until one returns a
 * "truthy" value, at which point `fn` returns the result of applying its
 * arguments to the corresponding transformer. If none of the predicates
 * matches, `fn` returns undefined.
 *
 * @note This is not a direct substitute for a `switch` statement.
 * Remember that both elements of every pair passed to `cond` are *functions*,
 * and `cond` returns a function.
 *
 * @note When using this function with a typeguard as predicate,
 * **all** predicates in all pairs must be typeguards.
 *
 * See also {@link ifElse}, {@link unless}, {@link when}.
 *
 * @example
 * ```typescript
 * const fn = R.cond([
 *   [R.equals(0),   R.always('water freezes at 0°C')],
 *   [R.equals(100), R.always('water boils at 100°C')],
 *   [R.T,           temp => 'nothing special happens at ' + temp + '°C']
 * ]);
 * fn(0); //=> 'water freezes at 0°C'
 * fn(50); //=> 'nothing special happens at 50°C'
 * fn(100); //=> 'water boils at 100°C'
 * ```
 */
export function cond<T, TF1 extends T, R>(pairs: [CondPairTypeguard<T, TF1, R>]): (value: T) => R;
export function cond<T, TF1 extends T, TF2 extends T, R>(
    pairs: [CondPairTypeguard<T, TF1, R>, CondPairTypeguard<T, TF2, R>],
): (value: T) => R;
export function cond<T, TF1 extends T, TF2 extends T, TF3 extends T, R>(
    pairs: [CondPairTypeguard<T, TF1, R>, CondPairTypeguard<T, TF2, R>, CondPairTypeguard<T, TF3, R>],
): (value: T) => R;
export function cond<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, R>(
    pairs: [
        CondPairTypeguard<T, TF1, R>,
        CondPairTypeguard<T, TF2, R>,
        CondPairTypeguard<T, TF3, R>,
        CondPairTypeguard<T, TF4, R>,
    ],
): (value: T) => R;
export function cond<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T, R>(
    pairs: [
        CondPairTypeguard<T, TF1, R>,
        CondPairTypeguard<T, TF2, R>,
        CondPairTypeguard<T, TF3, R>,
        CondPairTypeguard<T, TF4, R>,
        CondPairTypeguard<T, TF5, R>,
    ],
): (value: T) => R;
export function cond<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T, TF6 extends T, R>(
    pairs: [
        CondPairTypeguard<T, TF1, R>,
        CondPairTypeguard<T, TF2, R>,
        CondPairTypeguard<T, TF3, R>,
        CondPairTypeguard<T, TF4, R>,
        CondPairTypeguard<T, TF5, R>,
        CondPairTypeguard<T, TF6, R>,
    ],
): (value: T) => R;
export function cond<
    T,
    TF1 extends T,
    TF2 extends T,
    TF3 extends T,
    TF4 extends T,
    TF5 extends T,
    TF6 extends T,
    TF7 extends T,
    R,
>(
    pairs: [
        CondPairTypeguard<T, TF1, R>,
        CondPairTypeguard<T, TF2, R>,
        CondPairTypeguard<T, TF3, R>,
        CondPairTypeguard<T, TF4, R>,
        CondPairTypeguard<T, TF5, R>,
        CondPairTypeguard<T, TF6, R>,
        CondPairTypeguard<T, TF7, R>,
    ],
): (value: T) => R;
export function cond<
    T,
    TF1 extends T,
    TF2 extends T,
    TF3 extends T,
    TF4 extends T,
    TF5 extends T,
    TF6 extends T,
    TF7 extends T,
    TF8 extends T,
    R,
>(
    pairs: [
        CondPairTypeguard<T, TF1, R>,
        CondPairTypeguard<T, TF2, R>,
        CondPairTypeguard<T, TF3, R>,
        CondPairTypeguard<T, TF4, R>,
        CondPairTypeguard<T, TF5, R>,
        CondPairTypeguard<T, TF6, R>,
        CondPairTypeguard<T, TF7, R>,
        CondPairTypeguard<T, TF8, R>,
    ],
): (value: T) => R;
export function cond<
    T,
    TF1 extends T,
    TF2 extends T,
    TF3 extends T,
    TF4 extends T,
    TF5 extends T,
    TF6 extends T,
    TF7 extends T,
    TF8 extends T,
    TF9 extends T,
    R,
>(
    pairs: [
        CondPairTypeguard<T, TF1, R>,
        CondPairTypeguard<T, TF2, R>,
        CondPairTypeguard<T, TF3, R>,
        CondPairTypeguard<T, TF4, R>,
        CondPairTypeguard<T, TF5, R>,
        CondPairTypeguard<T, TF6, R>,
        CondPairTypeguard<T, TF7, R>,
        CondPairTypeguard<T, TF8, R>,
        CondPairTypeguard<T, TF9, R>,
    ],
): (value: T) => R;
export function cond<
    T,
    TF1 extends T,
    TF2 extends T,
    TF3 extends T,
    TF4 extends T,
    TF5 extends T,
    TF6 extends T,
    TF7 extends T,
    TF8 extends T,
    TF9 extends T,
    TF10 extends T,
    R,
>(
    pairs: [
        CondPairTypeguard<T, TF1, R>,
        CondPairTypeguard<T, TF2, R>,
        CondPairTypeguard<T, TF3, R>,
        CondPairTypeguard<T, TF4, R>,
        CondPairTypeguard<T, TF5, R>,
        CondPairTypeguard<T, TF6, R>,
        CondPairTypeguard<T, TF7, R>,
        CondPairTypeguard<T, TF8, R>,
        CondPairTypeguard<T, TF9, R>,
        CondPairTypeguard<T, TF10, R>,
    ],
): (value: T) => R;
export function cond<T extends any[], R>(pairs: ReadonlyArray<CondPair<T, R>>): (...args: T) => R;

/**
 * Wraps a constructor function inside a curried function that can be called with the same arguments and returns the same type.
 *
 * See also {@link invoker}.
 *
 * @example
 * ```typescript
 * // Constructor function
 * class Animal {
 *   constructor(public kind: string) {}
 *
 *   sighting() {
 *     return "It's a " + this.kind + "!";
 *   }
 * }
 *
 * const AnimalConstructor = R.construct(Animal)
 *
 * // Notice we no longer need the 'new' keyword:
 * AnimalConstructor('Pig'); //=> {"kind": "Pig", "sighting": function (){...}};
 *
 * const animalTypes = ["Lion", "Tiger", "Bear"];
 * const animalSighting = R.invoker(0, 'sighting');
 * const sightNewAnimal = R.compose(animalSighting, AnimalConstructor);
 * R.map(sightNewAnimal, animalTypes); //=> ["It's a Lion!", "It's a Tiger!", "It's a Bear!"]
 * ```
 */
export function construct<A extends any[], T>(
    constructor: { new (...args: A): T } | ((...args: A) => T),
): _.F.Curry<(...args: A) => T>;

// NOTE: Example doesn't work with this typing
/**
 * Wraps a constructor function inside a curried function that can be called with the same arguments and returns the same type.
 * The arity of the function returned is specified to allow using variadic constructor functions.
 */
export function constructN<A extends any[], T, N extends number>(
    n: N,
    constructor: { new (...args: A): T } | ((...args: A) => T),
): _.F.Curry<(...args: mergeArrWithLeft<Tuple<any, N>, A>) => T>;

// NOTE: Example doesn't work with this typing
/**
 * Accepts a converging function and a list of branching functions and returns a new function.
 * When invoked, this new function is applied to some arguments,
 * each branching function is applied to those same arguments.
 * The results of each branching function are passed as arguments to the converging function
 * to produce the return value.
 *
 * See also {@link useWith}.
 */
export function converge<
    TResult,
    FunctionsList extends ReadonlyArray<Fn> &
        IfFunctionsArgumentsDoNotOverlap<_Fns, 'Functions arguments types must overlap'>,
    _Fns extends ReadonlyArray<Fn> = FunctionsList,
>(
    converging: (...args: ReturnTypesOfFns<FunctionsList>) => TResult,
    branches: FunctionsList,
): _.F.Curry<(...args: LargestArgumentsList<FunctionsList>) => TResult>;
export function converge<
    CArgs extends ReadonlyArray<any>,
    TResult,
    FunctionsList extends readonly [
        ...{
            [Index in keyof CArgs]: (...args: ReadonlyArray<any>) => CArgs[Index];
        },
    ] &
        IfFunctionsArgumentsDoNotOverlap<_Fns, 'Functions arguments types must overlap'>,
    _Fns extends ReadonlyArray<Fn> = FunctionsList,
>(
    converging: (...args: CArgs) => TResult,
    branches: FunctionsList,
): _.F.Curry<(...args: LargestArgumentsList<FunctionsList>) => TResult>;

/**
 * Returns the number of items in a given `list` matching the predicate `f`.
 *
 * @example
 * ```typescript
 * const even = (x: number) => x % 2 == 0;
 *
 * R.count(even, [1, 2, 3, 4, 5]); // => 2
 * R.map(R.count(even), [[1, 1, 1], [2, 3, 4, 5], [6]]); // => [0, 2, 1]
 * ```
 */
export function count<T>(fn: (a: T) => boolean, list: readonly T[]): number;
export function count<T>(fn: (a: T) => boolean): (list: readonly T[]) => number;

/**
 * Counts the elements of a list according to how many match each value of a key generated by the supplied function.
 * Returns an object mapping the keys produced by `fn` to the number of occurrences in the list.
 * Note that all keys are coerced to strings because of how JavaScript objects work.
 *
 * Acts as a transducer if a transformer is given in list position.
 *
 * See also {@link transduce}.
 *
 * @example
 * ```typescript
 * const numbers = [1.0, 1.1, 1.2, 2.0, 3.0, 2.2];
 * R.countBy(Math.floor)(numbers);    //=> {'1': 3, '2': 2, '3': 1}
 *
 * const letters = ['a', 'b', 'A', 'a', 'B', 'c'];
 * R.countBy(R.toLower)(letters);   //=> {'a': 3, 'b': 2, 'c': 1}
 * ```
 */
export function countBy<T>(fn: (a: T) => string | number, list: readonly T[]): { [index: string]: number };
export function countBy<T>(fn: (a: T) => string | number): (list: readonly T[]) => { [index: string]: number };

/**
 * Returns a curried equivalent of the provided function.
 *
 * See also {@link curryN}, {@link partial}.
 *
 * The curried function has two unusual capabilities.
 *
 * First, its arguments needn't be provided one at a time.
 * If `f` is a ternary function and `g` is `R.curry(f)`, the following are equivalent:
 *  - `g(1)(2)(3)`
 *  - `g(1)(2, 3)`
 *  - `g(1, 2)(3)`
 *  - `g(1, 2, 3)`
 *
 * Secondly, the special placeholder value `R.__` may be used to specify "gaps",
 * allowing partial application of any combination of arguments,
 * regardless of their positions.
 * If `g` is as above and `_` is `R.__`, the following are equivalent:
 *  - `g(1, 2, 3)`
 *  - `g(_, 2, 3)(1)`
 *  - `g(_, _, 3)(1)(2)`
 *  - `g(_, _, 3)(1, 2)`
 *  - `g(_, 2)(1)(3)`
 *  - `g(_, 2)(1, 3)`
 *  - `g(_, 2)(_, 3)(1)`
 *
 * @example
 * ```typescript
 * const addFourNumbers = (a: number, b: number, c: number, d: number) => a + b + c + d;
 *
 * const curriedAddFourNumbers = R.curry(addFourNumbers);
 * const f = curriedAddFourNumbers(1, 2);
 * const g = f(3);
 * g(4); //=> 10
 * ```
 */
export function curry<F extends AnyFunction>(f: F): _.F.Curry<F>;

/**
 * Returns a curried equivalent of the provided function, with the specified arity.
 *
 * See also {@link curry}.
 *
 * The curried function has two unusual capabilities.
 *
 * First, its arguments needn't be provided one at a time.
 * If `f` is a ternary function and `g` is `R.curry(f)`, the following are equivalent:
 *  - `g(1)(2)(3)`
 *  - `g(1)(2, 3)`
 *  - `g(1, 2)(3)`
 *  - `g(1, 2, 3)`
 *
 * Secondly, the special placeholder value `R.__` may be used to specify "gaps",
 * allowing partial application of any combination of arguments,
 * regardless of their positions.
 * If `g` is as above and `_` is `R.__`, the following are equivalent:
 *  - `g(1, 2, 3)`
 *  - `g(_, 2, 3)(1)`
 *  - `g(_, _, 3)(1)(2)`
 *  - `g(_, _, 3)(1, 2)`
 *  - `g(_, 2)(1)(3)`
 *  - `g(_, 2)(1, 3)`
 *  - `g(_, 2)(_, 3)(1)`
 *
 * @example
 * ```typescript
 * const sumArgs = (...args: number[]) => R.sum(args);
 *
 * const curriedAddFourNumbers = R.curryN(4, sumArgs);
 * const f = curriedAddFourNumbers(1, 2);
 * const g = f(3);
 * g(4); //=> 10
 * ```
 */
export function curryN<N extends number, F extends AnyFunction>(
    length: N,
    fn: F,
): _.F.Curry<(...args: _.T.Take<Parameters<F>, _.N.NumberOf<N>>) => ReturnType<F>>;
export function curryN<N extends number>(
    length: N,
): <F extends AnyFunction>(fn: F) => _.F.Curry<(...args: _.T.Take<Parameters<F>, _.N.NumberOf<N>>) => ReturnType<F>>;

/**
 * Decrements its argument.
 *
 * See also {@link inc}.
 *
 * @example
 * ```typescript
 * R.dec(42); //=> 41
 * ```
 */
export function dec(n: number): number;

/**
 * Returns the second argument if it is not `null`, `undefined` or `NaN`; otherwise the first argument is returned.
 *
 * @example
 * ```typescript
 * const defaultTo42 = R.defaultTo(42);
 *
 * defaultTo42(null);      //=> 42
 * defaultTo42(undefined); //=> 42
 * defaultTo42(false);     //=> false
 * defaultTo42('Ramda');   //=> 'Ramda'
 * // parseInt('string') results in NaN
 * defaultTo42(parseInt('string')); //=> 42
 * ```
 */
export function defaultTo<T, U>(a: T, b: U | null | undefined): T | U;
export function defaultTo<T>(a: T): <U>(b: U | null | undefined) => T | U;

/**
 * Makes a descending comparator function out of a function that returns a value that can be compared with `<` and `>`.
 *
 * See also {@link ascend}.
 *
 * @example
 * ```typescript
 * type Person = { name: string; age: number; };
 *
 * const byAge = R.descend<Person>(R.prop('age'));
 * const people = [
 *   { name: 'Emma', age: 70 },
 *   { name: 'Peter', age: 78 },
 *   { name: 'Mikhail', age: 62 },
 * ];
 * const peopleByOldestFirst = R.sort(byAge, people);
 *   //=> [{ name: 'Peter', age: 78 }, { name: 'Emma', age: 70 }, { name: 'Mikhail', age: 62 }]
 * ```
 */
export function descend<T>(fn: (obj: T) => Ord, a: T, b: T): Ordering;
export function descend<T>(fn: (obj: T) => Ord): (a: T, b: T) => Ordering;

/**
 * Finds the set (i.e. no duplicates) of all elements in the first list not contained in the second list.
 * `Object`s and `Array`s are compared in terms of value equality, not reference equality.
 *
 * See also {@link differenceWith}, {@link symmetricDifference}, {@link symmetricDifferenceWith}, {@link without}.
 *
 * @example
 * ```typescript
 * R.difference([1,2,3,4], [7,6,5,4,3]); //=> [1,2]
 * R.difference([7,6,5,4,3], [1,2,3,4]); //=> [7,6,5]
 * R.difference<{ a: number; } | { b: number; } | { c: number; }>([{a: 1}, {b: 2}], [{a: 1}, {c: 3}]) //=> [{b: 2}]
 * ```
 */
export function difference<T>(list1: readonly T[], list2: readonly T[]): T[];
export function difference<T>(list1: readonly T[]): (list2: readonly T[]) => T[];

/**
 * Finds the set (i.e. no duplicates) of all elements in the first list not contained in the second list.
 * Duplication is determined according to the value returned
 * by applying the supplied predicate to two list elements.
 *
 * See also See also {@link difference}, {@link symmetricDifference}, {@link symmetricDifferenceWith}.
 *
 * @example
 * ```typescript
 * const cmp = (x: { a: number; }, y: { a: number; }) => x.a === y.a;
 * const l1 = [{a: 1}, {a: 2}, {a: 3}];
 * const l2 = [{a: 3}, {a: 4}];
 * R.differenceWith(cmp, l1, l2); //=> [{a: 1}, {a: 2}]
 * ```
 */
export function differenceWith<T1, T2>(
    pred: (a: T1, b: T2) => boolean,
    list1: readonly T1[],
    list2: readonly T2[],
): T1[];
export function differenceWith<T1, T2>(
    pred: (a: T1, b: T2) => boolean,
): (list1: readonly T1[], list2: readonly T2[]) => T1[];
export function differenceWith<T1, T2>(
    pred: (a: T1, b: T2) => boolean,
    list1: readonly T1[],
): (list2: readonly T2[]) => T1[];

/**
 * Returns a new object that does not contain the given property.
 *
 * See also {@link assoc}, {@link omit}.
 *
 * @example
 * ```typescript
 * R.dissoc('b', {a: 1, b: 2, c: 3}); //=> {a: 1, c: 3}
 * ```
 */
export function dissoc<T extends object, K extends keyof T>(prop: K, obj: T): Omit<T, K>;
export function dissoc<K extends string | number>(prop: K): <T extends object>(obj: T) => Omit<T, K>;

/**
 * Makes a shallow clone of an object, omitting the property at the given path.
 *
 * @note This copies and flattens prototype properties onto the new object as well.
 * All non-primitive properties are copied by reference.
 *
 * @example
 * ```typescript
 * R.dissocPath(['a', 'b', 'c'], {a: {b: {c: 42}}}); //=> {a: {b: {}}}
 * ```
 */
export function dissocPath<T>(path: Path, obj: any): T;
export function dissocPath<T>(path: Path): (obj: any) => T;

/**
 * Divides two numbers. Equivalent to `a / b` but curried.
 *
 * See also {@link multiply}.
 *
 * @example
 * ```typescript
 * R.divide(71, 100); //=> 0.71
 *
 * const half = R.divide(R.__, 2);
 * half(42); //=> 21
 *
 * const reciprocal = R.divide(1);
 * reciprocal(4);   //=> 0.25
 * ```
 */
export function divide(__: Placeholder, b: number): (a: number) => number;
export function divide(__: Placeholder): (b: number, a: number) => number;
export function divide(a: number, b: number): number;
export function divide(a: number): (b: number) => number;

/**
 * Returns all but the first `n` elements of the given list, string, or transducer/transformer.
 *
 * Dispatches to the `drop` method of the second argument, if present.
 *
 * See also {@link take}, {@link transduce}, {@link dropLast}, {@link dropWhile}.
 *
 * @example
 * ```typescript
 * R.drop(1, ['foo', 'bar', 'baz']); //=> ['bar', 'baz']
 * R.drop(2, ['foo', 'bar', 'baz']); //=> ['baz']
 * R.drop(3, ['foo', 'bar', 'baz']); //=> []
 * R.drop(4, ['foo', 'bar', 'baz']); //=> []
 * R.drop(3, 'ramda');               //=> 'da'
 * ```
 */
export function drop<T>(n: number, xs: readonly T[]): T[];
export function drop(n: number, xs: string): string;
export function drop<T>(n: number): {
    (xs: string): string;
    (xs: readonly T[]): T[];
};

/**
 * Returns a list containing all but the last `n` elements of the given list.
 *
 * Acts as a transducer if a transformer is given in list position.
 *
 * See also {@link takeLast}, {@link drop}, {@link dropWhile}, {@link dropLastWhile}, {@link transduce}.
 *
 * @example
 * ```typescript
 * R.dropLast(1, ['foo', 'bar', 'baz']); //=> ['foo', 'bar']
 * R.dropLast(2, ['foo', 'bar', 'baz']); //=> ['foo']
 * R.dropLast(3, ['foo', 'bar', 'baz']); //=> []
 * R.dropLast(4, ['foo', 'bar', 'baz']); //=> []
 * R.dropLast(3, 'ramda');               //=> 'ra'
 * ```
 */
export function dropLast<T>(n: number, xs: readonly T[]): T[];
export function dropLast(n: number, xs: string): string;
export function dropLast<T>(n: number): {
    (xs: readonly T[]): T[];
    (xs: string): string;
};

/**
 * Returns a new list excluding all the tailing elements of a given list which satisfy the supplied predicate function.
 * It passes each value from the right to the supplied predicate function,
 * skipping elements until the predicate function returns a falsy value.
 *
 * Acts as a transducer if a transformer is given in list position.
 *
 * See also {@link takeLastWhile}, {@link addIndex}, {@link drop}, {@link dropWhile}, {@link transduce}.
 *
 * @example
 * ```typescript
 * const lteThree = (x: number) => x <= 3;
 *
 * R.dropLastWhile(lteThree, [1, 2, 3, 4, 3, 2, 1]); //=> [1, 2, 3, 4]
 *
 * R.dropLastWhile(x => x !== 'd', 'Ramda'); //=> 'Ramd'
 * ```
 */
export function dropLastWhile<T>(fn: (a: T) => boolean, list: readonly T[]): T[];
export function dropLastWhile<T>(fn: (a: T) => boolean): (list: readonly T[]) => T[];

/**
 * Returns a new list without any consecutively repeating elements.
 * {@link equals `R.equals`} is used to determine equality.
 *
 * Acts as a transducer if a transformer is given in list position.
 *
 * See also {@link transduce}.
 *
 * @example
 * ```typescript
 * R.dropRepeats([1, 1, 1, 2, 3, 4, 4, 2, 2]); //=> [1, 2, 3, 4, 2]
 * ```
 */
export function dropRepeats<T>(list: readonly T[]): T[];

/**
 * Returns a new list without any consecutively repeating elements.
 * Equality is determi