UNPKG

206 kBTypeScriptView Raw
1// Type definitions for ramda 0.28
2// Project: https://ramdajs.com
3// Definitions by: Scott O'Malley <https://github.com/TheHandsomeCoder>
4// Erwin Poeze <https://github.com/donnut>
5// Matt DeKrey <https://github.com/mdekrey>
6// Stephen King <https://github.com/sbking>
7// Alejandro Fernandez Haro <https://github.com/afharo>
8// Vítor Castro <https://github.com/teves-castro>
9// Simon Højberg <https://github.com/hojberg>
10// Samson Keung <https://github.com/samsonkeung>
11// Angelo Ocana <https://github.com/angeloocana>
12// Rayner Pupo <https://github.com/raynerd>
13// Nikita Moshensky <https://github.com/moshensky>
14// Ethan Resnick <https://github.com/ethanresnick>
15// Tomas Szabo <https://github.com/deftomat>
16// Maciek Blim <https://github.com/blimusiek>
17// Marcin Biernat <https://github.com/biern>
18// Rayhaneh Banyassady <https://github.com/rayhaneh>
19// Ryan McCuaig <https://github.com/rgm>
20// John Ottenlips <https://github.com/jottenlips>
21// Nitesh Phadatare <https://github.com/minitesh>
22// Krantisinh Deshmukh <https://github.com/krantisinh>
23// Aram Kharazyan <https://github.com/nemo108>
24// Jituan Lin <https://github.com/jituanlin>
25// Philippe Mills <https://github.com/Philippe-mills>
26// Saul Mirone <https://github.com/Saul-Mirone>
27// Nicholai Nissen <https://github.com/Nicholaiii>
28// Jorge Santana <https://github.com/LORDBABUINO>
29// Mikael Couzic <https://github.com/couzic>
30// Nikita Balikhin <https://github.com/NEWESTERS>
31// Wang Zengdi <https://github.com/adispring>
32// Marcus Blättermann <https://github.com/essenmitsosse>
33// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
34// TypeScript Version: 4.2
35
36import * as _ from 'ts-toolbelt';
37import {
38 AnyConstructor,
39 AnyFunction,
40 AtLeastOneFunctionsFlow,
41 AtLeastOneFunctionsFlowFromRightToLeft,
42 AssocPartialOne,
43 CondPair,
44 CondPairTypeguard,
45 Dictionary,
46 Evolvable,
47 Evolve,
48 Evolver,
49 Falsy,
50 Find,
51 Functor,
52 InputTypesOfFns,
53 KeyValuePair,
54 Lens,
55 Merge,
56 MergeAll,
57 ObjectHavingSome,
58 ObjPred,
59 Ord,
60 Ordering,
61 Path,
62 Placeholder,
63 Pred,
64 PredTypeguard,
65 Reduced,
66 ReturnTypesOfFns,
67 ValueOfUnion,
68 Take,
69 ToTupleOfArray,
70 ToTupleOfFunction,
71 Tuple,
72 Fn,
73 IfFunctionsArgumentsDoNotOverlap,
74 LargestArgumentsList,
75 mergeArrWithLeft,
76 Prop,
77} from './tools';
78
79export * from './tools';
80
81// NOTE: Example doesn't work with current level of support
82/**
83 * A special placeholder value used to specify "gaps" within curried functions,
84 * allowing partial application of any combination of arguments, regardless of their positions.
85 *
86 * If `g` is a curried ternary function and `_` is `R.__`, the following are equivalent:
87 * - `g(1, 2, 3)`
88 * - `g(_, 2, 3)(1)`
89 * - `g(_, _, 3)(1)(2)`
90 * - `g(_, _, 3)(1, 2)`
91 * - `g(_, 2, _)(1, 3)`
92 * - `g(_, 2)(1)(3)`
93 * - `g(_, 2)(1, 3)`
94 * - `g(_, 2)(_, 3)(1)`
95 *
96 * @example
97 * ```typescript
98 * const greet = R.replace('{name}', R.__, 'Hello, {name}!');
99 * greet('Alice'); //=> 'Hello, Alice!'
100 * ```
101 */
102export const __: Placeholder;
103
104/**
105 * Adds two values. Equivalent to `a + b` but curried.
106 *
107 * @example
108 * ```typescript
109 * R.add(2, 3); //=> 5
110 * R.add(7)(10); //=> 17
111 * ```
112 */
113export function add(a: number, b: number): number;
114export function add(a: number): (b: number) => number;
115
116/**
117 * Creates a new list iteration function from an existing one by adding two new parameters to its callback
118 * function: the current index, and the entire list.
119 *
120 * This would turn, for instance, {@link map `R.map`} function into one that more closely resembles `Array.prototype.map`.
121 *
122 * @note This will only work for functions in which the iteration callback function is the first parameter,
123 * and where the list is the last parameter.
124 * (This latter might be unimportant if the list parameter is not used.)
125 *
126 * See also {@link subtract}.
127 *
128 * @example
129 * ```typescript
130 * const mapIndexed = R.addIndex(R.map);
131 * mapIndexed((val, idx) => idx + '-' + val, ['f', 'o', 'o', 'b', 'a', 'r']);
132 * //=> ['0-f', '1-o', '2-o', '3-b', '4-a', '5-r']
133 * ```
134 */
135/* Special case for forEach */
136export function addIndex<T>(
137 fn: (f: (item: T) => void, list: readonly T[]) => T[],
138): _.F.Curry<(a: (item: T, idx: number, list: T[]) => void, b: readonly T[]) => T[]>;
139/* Special case for filter */
140export function addIndex<T>(
141 fn: (f: (item: T) => boolean, list: readonly T[]) => T[],
142): _.F.Curry<(a: (item: T, idx: number, list: T[]) => boolean, b: readonly T[]) => T[]>;
143/* Special case for map */
144export function addIndex<T, U>(
145 fn: (f: (item: T) => U, list: readonly T[]) => U[],
146): _.F.Curry<(a: (item: T, idx: number, list: T[]) => U, b: readonly T[]) => U[]>;
147/* Special case for reduce */
148export function addIndex<T, U>(
149 fn: (f: (acc: U, item: T) => U, aci: U, list: readonly T[]) => U,
150): _.F.Curry<(a: (acc: U, item: T, idx: number, list: T[]) => U, b: U, c: readonly T[]) => U>;
151
152/**
153 * Applies a function to the value at the given index of an array, returning a new copy of the array with the
154 * element at the given index replaced with the result of the function application.
155 *
156 * See also {@link update}.
157 *
158 * @example
159 * ```typescript
160 * R.adjust(1, R.toUpper, ['a', 'b', 'c', 'd']); //=> ['a', 'B', 'c', 'd']
161 * R.adjust(-1, R.toUpper, ['a', 'b', 'c', 'd']); //=> ['a', 'b', 'c', 'D']
162 * ```
163 */
164export function adjust<T>(index: number, fn: (a: T) => T, list: readonly T[]): T[];
165export function adjust<T>(index: number, fn: (a: T) => T): (list: readonly T[]) => T[];
166
167/**
168 * Returns `true` if all elements of the list match the predicate, `false` if there are any that don't.
169 *
170 * Dispatches to the `all` method of the second argument, if present.
171 *
172 * Acts as a transducer if a transformer is given in list position.
173 *
174 * See also {@link any}, {@link none}, {@link transduce}.
175 *
176 * @example
177 * ```typescript
178 * const equals3 = R.equals(3);
179 * R.all(equals3)([3, 3, 3, 3]); //=> true
180 * R.all(equals3)([3, 3, 1, 3]); //=> false
181 * ```
182 */
183export function all<T>(fn: (a: T) => boolean, list: readonly T[]): boolean;
184export function all<T>(fn: (a: T) => boolean): (list: readonly T[]) => boolean;
185
186/**
187 * Takes a list of predicates and returns a predicate that returns true for a given list of arguments
188 * if every one of the provided predicates is satisfied by those arguments.
189 *
190 * The function returned is a curried function whose arity matches that of the highest-arity predicate.
191 *
192 * See also {@link anyPass}.
193 *
194 * @example
195 * ```typescript
196 * type Card = { rank: string; suit: string; };
197 *
198 * const isQueen = R.propEq('rank', 'Q');
199 * const isSpade = R.propEq('suit', '♠︎');
200 * const isQueenOfSpades = R.allPass<R.Pred<[Card]>>([isQueen, isSpade]);
201 *
202 * isQueenOfSpades({rank: 'Q', suit: '♣︎'}); //=> false
203 * isQueenOfSpades({rank: 'Q', suit: '♠︎'}); //=> true
204 * ```
205 */
206export function allPass<T, TF1 extends T, TF2 extends T>(
207 preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>],
208): (a: T) => a is TF1 & TF2;
209export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T>(
210 preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>],
211): (a: T) => a is TF1 & TF2 & TF3;
212export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T>(
213 preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>],
214): (a: T) => a is TF1 & TF2 & TF3;
215export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T>(
216 preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>, PredTypeguard<T, TF4>],
217): (a: T) => a is TF1 & TF2 & TF3 & TF4;
218export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T>(
219 preds: [
220 PredTypeguard<T, TF1>,
221 PredTypeguard<T, TF2>,
222 PredTypeguard<T, TF3>,
223 PredTypeguard<T, TF4>,
224 PredTypeguard<T, TF5>,
225 ],
226): PredTypeguard<T, TF1 & TF2 & TF3 & TF4 & TF5>;
227export function allPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T, TF6 extends T>(
228 preds: [
229 PredTypeguard<T, TF1>,
230 PredTypeguard<T, TF2>,
231 PredTypeguard<T, TF3>,
232 PredTypeguard<T, TF4>,
233 PredTypeguard<T, TF5>,
234 PredTypeguard<T, TF6>,
235 ],
236): PredTypeguard<T, TF1 & TF2 & TF3 & TF4 & TF5 & TF6>;
237export function allPass<F extends Pred>(preds: readonly F[]): F;
238
239/**
240 * Returns a function that always returns the given value.
241 *
242 * @note For non-primitives the value returned is a reference to the original value.
243 *
244 * This function is known as `const`, `constant`, or `K` (for K combinator) in other languages and libraries.
245 *
246 * @example
247 * ```typescript
248 * const t = R.always('Tee');
249 * t(); //=> 'Tee'
250 * ```
251 */
252export function always<T>(val: T): (...args: unknown[]) => T;
253
254/**
255 * A function that returns the first argument if it's falsy otherwise the second argument.
256 *
257 * See also {@link both}, {@link or}, {@link xor}.
258 *
259 * @note This is **not** short-circuited, meaning that if expressions are passed they are both evaluated.
260 *
261 * @example
262 * ```typescript
263 * R.and(true, true); //=> true
264 * R.and(true, false); //=> false
265 * R.and(false, true); //=> false
266 * R.and(false, false); //=> false
267 * ```
268 */
269export function and<T, U>(a: T, b: U): T | U;
270export function and<T>(a: T): <U>(b: U) => T | U;
271
272/**
273 * Returns the result of applying the `onSuccess` function to the value inside a successfully resolved `Promise`.
274 * This is useful for working with `Promise`s inside function compositions.
275 *
276 * See also {@link otherwise}.
277 *
278 * @example
279 * ```typescript
280 * type Query = { query: { email: string; }; };
281 *
282 * const makeQuery = (email: string) => ({ query: { email }});
283 * const fetchMember = (request: Query) =>
284 * Promise.resolve({ firstName: 'Bob', lastName: 'Loblaw', id: 42 });
285 *
286 * //getMemberName :: String -> Promise ({ firstName, lastName })
287 * const getMemberName = R.pipe(
288 * makeQuery,
289 * fetchMember,
290 * R.andThen(R.pick(['firstName', 'lastName']))
291 * );
292 *
293 * getMemberName('bob@gmail.com').then(console.log);
294 * ```
295 */
296export function andThen<A, B>(onSuccess: (a: A) => B | Promise<B>, promise: Promise<A>): Promise<B>;
297export function andThen<A, B>(onSuccess: (a: A) => B | Promise<B>): (promise: Promise<A>) => Promise<B>;
298
299/**
300 * Returns `true` if at least one of elements of the list match the predicate, `false` otherwise.
301 *
302 * Dispatches to the `any` method of the second argument, if present.
303 *
304 * Acts as a transducer if a transformer is given in list position.
305 *
306 * See also {@link all}, {@link none}, {@link transduce}.
307 *
308 * @example
309 * ```typescript
310 * const lessThan0 = R.flip(R.lt)(0);
311 * const lessThan2 = R.flip(R.lt)(2);
312 * R.any(lessThan0)([1, 2]); //=> false
313 * R.any(lessThan2)([1, 2]); //=> true
314 * ```
315 */
316export function any<T>(fn: (a: T) => boolean, list: readonly T[]): boolean;
317export function any<T>(fn: (a: T) => boolean): (list: readonly T[]) => boolean;
318
319/**
320 * Takes a list of predicates and returns a predicate that returns true for a
321 * given list of arguments if at least one of the provided predicates is
322 * satisfied by those arguments.
323 *
324 * The function returned is a curried function whose arity matches that of the
325 * highest-arity predicate.
326 *
327 * See also {@link allPass}.
328 *
329 * @example
330 * ```typescript
331 * type Card = { rank: string; suit: string; };
332 *
333 * const isClub = R.propEq('suit', '♣');
334 * const isSpade = R.propEq('suit', '♠');
335 * const isBlackCard = R.anyPass<R.Pred<[Card]>>([isClub, isSpade]);
336 *
337 * isBlackCard({rank: '10', suit: '♣'}); //=> true
338 * isBlackCard({rank: 'Q', suit: '♠'}); //=> true
339 * isBlackCard({rank: 'Q', suit: '♦'}); //=> false
340 * ```
341 */
342export function anyPass<T, TF1 extends T, TF2 extends T>(
343 preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>],
344): (a: T) => a is TF1 | TF2;
345export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T>(
346 preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>],
347): (a: T) => a is TF1 | TF2 | TF3;
348export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T>(
349 preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>],
350): (a: T) => a is TF1 | TF2 | TF3;
351export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T>(
352 preds: [PredTypeguard<T, TF1>, PredTypeguard<T, TF2>, PredTypeguard<T, TF3>, PredTypeguard<T, TF4>],
353): (a: T) => a is TF1 | TF2 | TF3 | TF4;
354export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T>(
355 preds: [
356 PredTypeguard<T, TF1>,
357 PredTypeguard<T, TF2>,
358 PredTypeguard<T, TF3>,
359 PredTypeguard<T, TF4>,
360 PredTypeguard<T, TF5>,
361 ],
362): PredTypeguard<T, TF1 | TF2 | TF3 | TF4 | TF5>;
363export function anyPass<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T, TF6 extends T>(
364 preds: [
365 PredTypeguard<T, TF1>,
366 PredTypeguard<T, TF2>,
367 PredTypeguard<T, TF3>,
368 PredTypeguard<T, TF4>,
369 PredTypeguard<T, TF5>,
370 PredTypeguard<T, TF6>,
371 ],
372): PredTypeguard<T, TF1 | TF2 | TF3 | TF4 | TF5 | TF6>;
373export function anyPass<F extends Pred>(preds: readonly F[]): F;
374
375/**
376 * `ap` applies a list of functions to a list of values.
377 *
378 * Dispatches to the `ap` method of the first argument, if present.
379 * Also treats curried functions as applicatives.
380 *
381 * @example
382 * ```typescript
383 * R.ap([R.multiply(2), R.add(3)], [1,2,3]); //=> [2, 4, 6, 4, 5, 6]
384 * R.ap([R.concat('tasty '), R.toUpper], ['pizza', 'salad']); //=> ["tasty pizza", "tasty salad", "PIZZA", "SALAD"]
385 *
386 * // R.ap can also be used as S combinator
387 * // when only two functions are passed
388 * R.ap((s, s2) => R.concat(s, s2), R.toUpper)('Ramda') //=> 'RamdaRAMDA'
389 * ```
390 */
391export function ap<T, U>(fns: ReadonlyArray<(a: T) => U>, vs: readonly T[]): U[];
392export function ap<T, U>(fns: ReadonlyArray<(a: T) => U>): (vs: readonly T[]) => U[];
393export function ap<R, A, B>(fn: (r: R, a: A) => B, fn1: (r: R) => A): (r: R) => B;
394
395/**
396 * Returns a new list, composed of n-tuples of consecutive elements.
397 * If `n` is greater than the length of the list, an empty list is returned.
398 *
399 * Acts as a transducer if a transformer is given in list position.
400 *
401 * See also {@link transduce}.
402 *
403 * @example
404 * ```typescript
405 * R.aperture(2, [1, 2, 3, 4, 5]); //=> [[1, 2], [2, 3], [3, 4], [4, 5]]
406 * R.aperture(3, [1, 2, 3, 4, 5]); //=> [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
407 * R.aperture(7, [1, 2, 3, 4, 5]); //=> []
408 * ```
409 */
410export function aperture<N extends number, T>(n: N, list: readonly T[]): Array<Tuple<T, N>> | [];
411export function aperture<N extends number>(n: N): <T>(list: readonly T[]) => Array<Tuple<T, N>> | [];
412
413/**
414 * Returns a new list containing the contents of the given list, followed by the given element.
415 *
416 * See also {@link prepend}.
417 *
418 * @example
419 * ```typescript
420 * R.append('tests', ['write', 'more']); //=> ['write', 'more', 'tests']
421 * R.append('tests', []); //=> ['tests']
422 * R.append<string | string[]>(['tests'], ['write', 'more']); //=> ['write', 'more', ['tests']]
423 * ```
424 */
425export function append<T>(el: T, list: readonly T[]): T[];
426export function append<T>(el: T): (list: readonly T[]) => T[];
427
428/**
429 * Applies function `fn` to the argument list `args`.
430 * This is useful for creating a fixed-arity function from a variadic function.
431 * `fn` should be a bound function if context is significant.
432 *
433 * See also {@link call}, {@link unapply}.
434 */
435export function apply<F extends AnyFunction>(fn: F, args: Parameters<F>): ReturnType<F>;
436export function apply<F extends AnyFunction>(fn: F): (args: Parameters<F>) => ReturnType<F>;
437
438/**
439 * Given a spec object recursively mapping properties to functions,
440 * creates a function producing an object of the same structure,
441 * by mapping each property to the result of calling its associated function with the supplied arguments.
442 *
443 * See also {@link converge}, {@link juxt}.
444 *
445 * @example
446 * ```typescript
447 * const getMetrics = R.applySpec({
448 * sum: R.add,
449 * nested: { mul: R.multiply }
450 * });
451 * getMetrics(2, 4); // => { sum: 6, nested: { mul: 8 } }
452 * ```
453 */
454export function applySpec<Obj extends Record<string, AnyFunction>>(
455 obj: Obj,
456): (...args: Parameters<Obj[keyof Obj]>) => { [Key in keyof Obj]: ReturnType<Obj[Key]> };
457export function applySpec<T>(obj: any): (...args: unknown[]) => T;
458
459/**
460 * Takes a value and applies a function to it.
461 *
462 * This function is also known as the `thrush` combinator.
463 *
464 * @example
465 * ```typescript
466 * const t42 = R.applyTo(42);
467 * t42(R.identity); //=> 42
468 * t42(R.add(1)); //=> 43
469 * ```
470 */
471export function applyTo<T, U>(el: T, fn: (t: T) => U): U;
472export function applyTo<T>(el: T): <U>(fn: (t: T) => U) => U;
473
474/**
475 * Makes an ascending comparator function out of a function that returns a value that can be compared with `<` and `>`.
476 *
477 * See also {@link descend}.
478 *
479 * @example
480 * ```typescript
481 * const byAge = R.ascend(R.prop<number>('age'));
482 * const people = [
483 * { name: 'Emma', age: 70 },
484 * { name: 'Peter', age: 78 },
485 * { name: 'Mikhail', age: 62 },
486 * ];
487 * const peopleByYoungestFirst = R.sort(byAge, people);
488 * //=> [{ name: 'Mikhail', age: 62 },{ name: 'Emma', age: 70 }, { name: 'Peter', age: 78 }]
489 * ```
490 */
491export function ascend<T>(fn: (obj: T) => Ord, a: T, b: T): Ordering;
492export function ascend<T>(fn: (obj: T) => Ord): (a: T, b: T) => Ordering;
493
494/**
495 * Makes a shallow clone of an object, setting or overriding the specified property with the given value.
496 *
497 * @note This copies and flattens prototype properties onto the new object as well.
498 * All non-primitive properties are copied by reference.
499 *
500 * See also {@link dissoc}, {@link pick}.
501 *
502 * @example
503 * ```typescript
504 * R.assoc('c', 3, {a: 1, b: 2}); //=> {a: 1, b: 2, c: 3}
505 * ```
506 */
507export 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>;
508export 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>;
509export function assoc<U, K extends string>(prop: K, __: Placeholder, obj: U): <T>(val: T) => Record<K, T> & Omit<U, K>;
510export function assoc<K extends keyof U, U>(prop: K, val: U[K], obj: U): U;
511export function assoc<T, U, K extends string>(prop: K, val: T, obj: U): Record<K, T> & Omit<U, K>;
512export function assoc<T, K extends string>(prop: K, val: T): <U>(obj: U) => Record<K, T> & Omit<U, K>;
513export function assoc<K extends string>(prop: K): AssocPartialOne<K>;
514
515/**
516 * Makes a shallow clone of an object,
517 * setting or overriding the nodes required to create the given path,
518 * and placing the specific value at the tail end of that path.
519 *
520 * @note This copies and flattens prototype properties onto the new object as well.
521 * All non-primitive properties are copied by reference.
522 *
523 * See also {@link dissocPath}.
524 *
525 * @example
526 * ```typescript
527 * R.assocPath(['a', 'b', 'c'], 42, {a: {b: {c: 0}}}); //=> {a: {b: {c: 42}}}
528 *
529 * // Any missing or non-object keys in path will be overridden
530 * R.assocPath(['a', 'b', 'c'], 42, {a: 5}); //=> {a: {b: {c: 42}}}
531 * ```
532 */
533export function assocPath<T, U>(__: Placeholder, val: T, obj: U): (path: Path) => U;
534export function assocPath<T, U>(path: Path, __: Placeholder, obj: U): (val: T) => U;
535export function assocPath<T, U>(path: Path, val: T, obj: U): U;
536export function assocPath<T, U>(path: Path, val: T): (obj: U) => U;
537export function assocPath<T, U>(path: Path): _.F.Curry<(a: T, b: U) => U>;
538
539/**
540 * Wraps a function of any arity (including nullary) in a function that accepts exactly 2
541 * parameters. Any extraneous parameters will not be passed to the supplied function.
542 *
543 * See also {@link nAry}, {@link unary}.
544 *
545 * @example
546 * ```typescript
547 * const takesThreeArgs = function(a: number, b: number, c: number) {
548 * return [a, b, c];
549 * };
550 * takesThreeArgs.length; //=> 3
551 * takesThreeArgs(1, 2, 3); //=> [1, 2, 3]
552 *
553 * const takesTwoArgs = R.binary(takesThreeArgs);
554 * takesTwoArgs.length; //=> 2
555 * // Only 2 arguments are passed to the wrapped function
556 * // @ts-expect-error TypeScript is designed to not let you do this
557 * takesTwoArgs(1, 2, 3); //=> [1, 2, undefined]
558 * ```
559 */
560export function binary<T extends AnyFunction>(fn: T): (...arg: _.T.Take<Parameters<T>, '2'>) => ReturnType<T>;
561
562/**
563 * Creates a function that is bound to a context.
564 *
565 * @note `R.bind` does not provide the additional argument-binding capabilities of `Function.prototype.bind`.
566 *
567 * @example
568 * ```typescript
569 * const log = R.bind(console.log, console);
570 * R.pipe(R.assoc('a', 2), R.tap(log), R.assoc('a', 3))({a: 1}); //=> {a: 3}
571 * // logs {a: 2}
572 * ```
573 */
574export function bind<F extends AnyFunction, T>(fn: F, thisObj: T): (...args: Parameters<F>) => ReturnType<F>;
575export function bind<F extends AnyFunction, T>(fn: F): (thisObj: T) => (...args: Parameters<F>) => ReturnType<F>;
576
577/**
578 * A function which calls the two provided functions and returns the `&&` of the
579 * results. It returns the result of the first function if it is falsy and
580 * the result of the second function otherwise.
581 *
582 * @note This is short-circuited,
583 * meaning that the second function will not be invoked if the first returns a falsy value.
584 *
585 * In addition to functions, `R.both` also accepts any fantasy-land compatible applicative functor.
586 *
587 * See also {@link either}, {@link and}.
588 *
589 * @example
590 * ```typescript
591 * const gt10 = R.gt(R.__, 10)
592 * const lt20 = R.lt(R.__, 20)
593 * const f = R.both(gt10, lt20);
594 * f(15); //=> true
595 * f(30); //=> false
596 * ```
597 */
598export function both<T, TF1 extends T, TF2 extends T>(
599 pred1: PredTypeguard<T, TF1>,
600 pred2: PredTypeguard<T, TF2>,
601): (a: T) => a is TF1 & TF2;
602export function both<T extends Pred>(pred1: T, pred2: T): T;
603export function both<T extends Pred>(pred1: T): (pred2: T) => T;
604
605// NOTE: It is currently difficult to use it as a converging function for `R.converge`
606/**
607 * Returns the result of calling its first argument with the remaining arguments.
608 * This is occasionally useful as a converging function for {@link converge `R.converge`}:
609 * the first branch can produce a function
610 * while the remaining branches produce values to be passed to that function as its arguments.
611 *
612 * See also {@link apply}.
613 *
614 * @example
615 * ```typescript
616 * R.call<(a: number, b: number) => number>(R.add, 1, 2); //=> 3
617 *
618 * const indentN = R.pipe(
619 * R.repeat(' '),
620 * R.join(''),
621 * R.replace(/^(?!$)/gm)
622 * );
623 * ```
624 */
625export function call<T extends AnyFunction>(fn: T, ...args: Parameters<T>): ReturnType<T>;
626
627/**
628 * `chain` maps a function over a list and concatenates the results. `chain` is also known as `flatMap` in some libraries.
629 *
630 * Dispatches to the `chain` method of the second argument, if present, according to the FantasyLand Chain spec.
631 *
632 * If second argument is a function, `chain(f, g)(x)` is equivalent to `f(g(x), x)`.
633 *
634 * Acts as a transducer if a transformer is given in list position.
635 *
636 * See also {@link transduce}.
637 *
638 * @example
639 * ```typescript
640 * const duplicate = <T>(n: T) => [n, n];
641 * R.chain(duplicate, [1, 2, 3]); //=> [1, 1, 2, 2, 3, 3]
642 *
643 * R.chain(R.append, R.head)([1, 2, 3]); //=> [1, 2, 3, 1]
644 * ```
645 */
646export function chain<A, B, T = never>(fn: (n: A) => readonly B[], list: readonly A[]): B[];
647export function chain<A, B, T = never>(fn: (n: A) => readonly B[]): (list: readonly A[]) => B[];
648
649export function chain<A, Ma extends { chain: (fn: (a: A) => Mb) => Mb }, Mb>(fn: (a: A) => Mb, monad: Ma): Mb;
650export function chain<A, Ma extends { chain: (fn: (a: A) => Mb) => Mb }, Mb>(fn: (a: A) => Mb): (monad: Ma) => Mb;
651
652export function chain<A, B, R>(aToMb: (a: A, r: R) => B, Ma: (r: R) => A): (r: R) => B;
653export function chain<A, B, R>(aToMb: (a: A, r: R) => B): (Ma: (r: R) => A) => (r: R) => B;
654
655/**
656 * Restricts a number to be within a range.
657 * Also works for other ordered types such as strings and `Date`s.
658 *
659 * @example
660 * ```typescript
661 * R.clamp(1, 10, -5) // => 1
662 * R.clamp(1, 10, 15) // => 10
663 * R.clamp(1, 10, 4) // => 4
664 * ```
665 */
666export function clamp<T>(min: T, max: T, value: T): T;
667export function clamp<T>(min: T, max: T): (value: T) => T;
668export function clamp<T>(min: T): (max: T, value: T) => T;
669export function clamp<T>(min: T): (max: T) => (value: T) => T;
670
671/**
672 * Creates a deep copy of the source that can be used in place of the source object without retaining any references to it.
673 * The source object may contain (nested) `Array`s and `Object`s, numbers, strings, booleans and `Date`s.
674 * `Functions` are assigned by reference rather than copied.
675 *
676 * Dispatches to a `clone` method if present.
677 *
678 * Note that if the source object has multiple nodes that share a reference,
679 * the returned object will have the same structure,
680 * but the references will be pointed to the location within the cloned value.
681 *
682 * @example
683 * ```typescript
684 * const objects = [{}, {}, {}];
685 * const objectsClone = R.clone(objects);
686 * objects === objectsClone; //=> false
687 * objects[0] === objectsClone[0]; //=> false
688 * ```
689 */
690export function clone<T>(value: T): T;
691export function clone<T>(value: readonly T[]): T[];
692
693/**
694 * Splits a list into sub-lists,
695 * based on the result of calling a key-returning function on each element,
696 * and grouping the results according to values returned.
697 *
698 * See also {@link groupBy}, {@link partition}.
699 *
700 * @example
701 * ```typescript
702 * R.collectBy(R.prop('type'), [
703 * {type: 'breakfast', item: '☕️'},
704 * {type: 'lunch', item: '🌯'},
705 * {type: 'dinner', item: '🍝'},
706 * {type: 'breakfast', item: '🥐'},
707 * {type: 'lunch', item: '🍕'}
708 * ]);
709 *
710 * // [ [ {type: 'breakfast', item: '☕️'},
711 * // {type: 'breakfast', item: '🥐'} ],
712 * // [ {type: 'lunch', item: '🌯'},
713 * // {type: 'lunch', item: '🍕'} ],
714 * // [ {type: 'dinner', item: '🍝'} ] ]
715 * ```
716 */
717export function collectBy<T, K extends PropertyKey>(keyFn: (value: T) => K, list: readonly T[]): T[][];
718export function collectBy<T, K extends PropertyKey>(keyFn: (value: T) => K): (list: readonly T[]) => T[][];
719
720/**
721 * Makes a comparator function out of a function that reports whether the first element is less than the second.
722 *
723 * @example
724 * ```typescript
725 * type Person = { name: string; age: number; };
726 *
727 * const byAge = R.comparator<Person>((a, b) => a.age < b.age);
728 * const people = [
729 * { name: 'Emma', age: 70 },
730 * { name: 'Peter', age: 78 },
731 * { name: 'Mikhail', age: 62 },
732 * ];
733 * const peopleByIncreasingAge = R.sort(byAge, people);
734 * //=> [{ name: 'Mikhail', age: 62 },{ name: 'Emma', age: 70 }, { name: 'Peter', age: 78 }]
735 * ```
736 */
737export function comparator<T>(pred: (a: T, b: T) => boolean): (x: T, y: T) => Ordering;
738
739/**
740 * Takes a function `f` and returns a function `g` such that
741 * if called with the same arguments
742 * when `f` returns a truthy value, `g` returns `false`
743 * and when `f` returns a falsy value `g` returns `true`.
744 *
745 * `R.complement` may be applied to any functor.
746 *
747 * See also {@link not}.
748 *
749 * @example
750 * ```typescript
751 * const isNotNil = R.complement(R.isNil);
752 * R.isNil(null); //=> true
753 * isNotNil(null); //=> false
754 * R.isNil(7); //=> false
755 * isNotNil(7); //=> true
756 * ```
757 */
758export function complement<T, TFiltered extends T>(
759 pred: (value: T) => value is TFiltered,
760): (value: T) => value is Exclude<T, TFiltered>;
761export function complement<TArgs extends any[]>(pred: (...args: TArgs) => unknown): (...args: TArgs) => boolean;
762
763/**
764 * Performs right-to-left function composition.
765 * The rightmost function may have any arity;
766 * the remaining functions must be unary.
767 *
768 * @note The result of `R.compose` is not automatically curried.
769 *
770 * See also {@link pipe}.
771 *
772 * @example
773 * ```typescript
774 * const classyGreeting = (firstName: string, lastName: string) => "The name's " + lastName + ", " + firstName + " " + lastName
775 * const yellGreeting = R.compose(R.toUpper, classyGreeting);
776 * yellGreeting('James', 'Bond'); //=> "THE NAME'S BOND, JAMES BOND"
777 *
778 * R.compose(Math.abs, R.add(1), R.multiply(2))(-4) //=> 7
779 * ```
780 */
781export function compose<TArgs extends any[], R1, R2, R3, R4, R5, R6, R7, TResult>(
782 ...func: [
783 fnLast: (a: any) => TResult,
784 ...func: Array<(a: any) => any>,
785 f7: (a: R6) => R7,
786 f6: (a: R5) => R6,
787 f5: (a: R4) => R5,
788 f4: (a: R3) => R4,
789 f3: (a: R2) => R3,
790 f2: (a: R1) => R2,
791 f1: (...args: TArgs) => R1,
792 ]
793): (...args: TArgs) => TResult; // fallback overload if number of composed functions greater than 7
794export function compose<TArgs extends any[], R1, R2, R3, R4, R5, R6, R7>(
795 f7: (a: R6) => R7,
796 f6: (a: R5) => R6,
797 f5: (a: R4) => R5,
798 f4: (a: R3) => R4,
799 f3: (a: R2) => R3,
800 f2: (a: R1) => R2,
801 f1: (...args: TArgs) => R1,
802): (...args: TArgs) => R7;
803export function compose<TArgs extends any[], R1, R2, R3, R4, R5, R6, R7>(
804 f7: (a: R6) => R7,
805 f6: (a: R5) => R6,
806 f5: (a: R4) => R5,
807 f4: (a: R3) => R4,
808 f3: (a: R2) => R3,
809 f2: (a: R1) => R2,
810 f1: (...args: TArgs) => R1,
811): (...args: TArgs) => R7;
812export function compose<TArgs extends any[], R1, R2, R3, R4, R5, R6>(
813 f6: (a: R5) => R6,
814 f5: (a: R4) => R5,
815 f4: (a: R3) => R4,
816 f3: (a: R2) => R3,
817 f2: (a: R1) => R2,
818 f1: (...args: TArgs) => R1,
819): (...args: TArgs) => R6;
820export function compose<TArgs extends any[], R1, R2, R3, R4, R5>(
821 f5: (a: R4) => R5,
822 f4: (a: R3) => R4,
823 f3: (a: R2) => R3,
824 f2: (a: R1) => R2,
825 f1: (...args: TArgs) => R1,
826): (...args: TArgs) => R5;
827export function compose<TArgs extends any[], R1, R2, R3, R4>(
828 f4: (a: R3) => R4,
829 f3: (a: R2) => R3,
830 f2: (a: R1) => R2,
831 f1: (...args: TArgs) => R1,
832): (...args: TArgs) => R4;
833export function compose<TArgs extends any[], R1, R2, R3>(
834 f3: (a: R2) => R3,
835 f2: (a: R1) => R2,
836 f1: (...args: TArgs) => R1,
837): (...args: TArgs) => R3;
838export function compose<TArgs extends any[], R1, R2>(
839 f2: (a: R1) => R2,
840 f1: (...args: TArgs) => R1,
841): (...args: TArgs) => R2;
842export function compose<TArgs extends any[], R1>(f1: (...args: TArgs) => R1): (...args: TArgs) => R1;
843
844/**
845 * Performs right-to-left function composition using transforming function.
846 * The last function may have any arity; the remaining functions must be unary.
847 *
848 * @note The result of `R.composeWith` is not automatically curried.
849 * The transforming function is not used on the last argument.
850 *
851 * See also {@link compose}, {@link pipeWith}.
852 *
853 * @example
854 * ```typescript
855 * const composeWhileNotNil = R.composeWith((f, res) => R.isNil(res) ? res : f(res));
856 *
857 * composeWhileNotNil([R.inc, R.prop('age')])({age: 1}) //=> 2
858 * ```
859 */
860export function composeWith<TArgs extends any[], TResult>(
861 transformer: (fn: AnyFunction, intermediatResult: any) => any,
862 fns: AtLeastOneFunctionsFlowFromRightToLeft<TArgs, TResult>,
863): (...args: TArgs) => TResult;
864export function composeWith(
865 transformer: (fn: AnyFunction, intermediatResult: any) => any,
866): <TArgs extends any[], TResult>(
867 fns: AtLeastOneFunctionsFlowFromRightToLeft<TArgs, TResult>,
868) => (...args: TArgs) => TResult;
869
870/**
871 * Returns the result of concatenating the given lists or strings.
872 *
873 * @note `R.concat` expects both arguments to be of the same type,
874 * unlike the native `Array.prototype.concat` method.
875 * It will throw an error if you concat an `Array` with a non-`Array` value.
876 *
877 * Dispatches to the `concat` method of the first argument, if present.
878 * Can also concatenate two members of a fantasy-land compatible semigroup.
879 *
880 * @example
881 * ```typescript
882 * R.concat('ABC', 'DEF'); // 'ABCDEF'
883 * R.concat([4, 5, 6], [1, 2, 3]); //=> [4, 5, 6, 1, 2, 3]
884 * R.concat([], []); //=> []
885 * ```
886 */
887export function concat(
888 placeholder: Placeholder,
889): (<L1 extends any[], L2 extends any[]>(list1: L1, list2: L2) => [...L1, ...L2]) &
890 (<S1 extends string, S2 extends string>(s1: S1, s2: S2) => `${S1}${S2}`);
891export function concat<L2 extends any[]>(
892 placeholder: Placeholder,
893 list2: L2,
894): <L1 extends any[]>(list1: L1) => [...L1, ...L2];
895export function concat<S2 extends string>(
896 placeholder: Placeholder,
897 s2: S2,
898): <S1 extends string>(s1: S1) => `${S1}${S2}`;
899export function concat<L1 extends any[]>(list1: L1): <L2 extends any[]>(list2: L2) => [...L1, ...L2];
900export function concat<S1 extends string>(s1: S1): <S2 extends string>(s2: S2) => `${S1}${S2}`;
901export function concat<L1 extends any[], L2 extends any[]>(list1: L1, list2: L2): [...L1, ...L2];
902export function concat<S1 extends string, S2 extends string>(s1: S1, s2: S2): `${S1}${S2}`;
903export function concat(s1: string, s2: string): string;
904export function concat(s1: string): (s2: string) => string;
905
906/**
907 * Returns a function, `fn`, which encapsulates `if/else, if/else, ...` logic.
908 * `R.cond` takes a list of [predicate, transformer] pairs. All of the arguments
909 * to `fn` are applied to each of the predicates in turn until one returns a
910 * "truthy" value, at which point `fn` returns the result of applying its
911 * arguments to the corresponding transformer. If none of the predicates
912 * matches, `fn` returns undefined.
913 *
914 * @note This is not a direct substitute for a `switch` statement.
915 * Remember that both elements of every pair passed to `cond` are *functions*,
916 * and `cond` returns a function.
917 *
918 * @note When using this function with a typeguard as predicate,
919 * **all** predicates in all pairs must be typeguards.
920 *
921 * See also {@link ifElse}, {@link unless}, {@link when}.
922 *
923 * @example
924 * ```typescript
925 * const fn = R.cond([
926 * [R.equals(0), R.always('water freezes at 0°C')],
927 * [R.equals(100), R.always('water boils at 100°C')],
928 * [R.T, temp => 'nothing special happens at ' + temp + '°C']
929 * ]);
930 * fn(0); //=> 'water freezes at 0°C'
931 * fn(50); //=> 'nothing special happens at 50°C'
932 * fn(100); //=> 'water boils at 100°C'
933 * ```
934 */
935export function cond<T, TF1 extends T, R>(pairs: [CondPairTypeguard<T, TF1, R>]): (value: T) => R;
936export function cond<T, TF1 extends T, TF2 extends T, R>(
937 pairs: [CondPairTypeguard<T, TF1, R>, CondPairTypeguard<T, TF2, R>],
938): (value: T) => R;
939export function cond<T, TF1 extends T, TF2 extends T, TF3 extends T, R>(
940 pairs: [CondPairTypeguard<T, TF1, R>, CondPairTypeguard<T, TF2, R>, CondPairTypeguard<T, TF3, R>],
941): (value: T) => R;
942export function cond<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, R>(
943 pairs: [
944 CondPairTypeguard<T, TF1, R>,
945 CondPairTypeguard<T, TF2, R>,
946 CondPairTypeguard<T, TF3, R>,
947 CondPairTypeguard<T, TF4, R>,
948 ],
949): (value: T) => R;
950export function cond<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T, R>(
951 pairs: [
952 CondPairTypeguard<T, TF1, R>,
953 CondPairTypeguard<T, TF2, R>,
954 CondPairTypeguard<T, TF3, R>,
955 CondPairTypeguard<T, TF4, R>,
956 CondPairTypeguard<T, TF5, R>,
957 ],
958): (value: T) => R;
959export function cond<T, TF1 extends T, TF2 extends T, TF3 extends T, TF4 extends T, TF5 extends T, TF6 extends T, R>(
960 pairs: [
961 CondPairTypeguard<T, TF1, R>,
962 CondPairTypeguard<T, TF2, R>,
963 CondPairTypeguard<T, TF3, R>,
964 CondPairTypeguard<T, TF4, R>,
965 CondPairTypeguard<T, TF5, R>,
966 CondPairTypeguard<T, TF6, R>,
967 ],
968): (value: T) => R;
969export function cond<
970 T,
971 TF1 extends T,
972 TF2 extends T,
973 TF3 extends T,
974 TF4 extends T,
975 TF5 extends T,
976 TF6 extends T,
977 TF7 extends T,
978 R,
979>(
980 pairs: [
981 CondPairTypeguard<T, TF1, R>,
982 CondPairTypeguard<T, TF2, R>,
983 CondPairTypeguard<T, TF3, R>,
984 CondPairTypeguard<T, TF4, R>,
985 CondPairTypeguard<T, TF5, R>,
986 CondPairTypeguard<T, TF6, R>,
987 CondPairTypeguard<T, TF7, R>,
988 ],
989): (value: T) => R;
990export function cond<
991 T,
992 TF1 extends T,
993 TF2 extends T,
994 TF3 extends T,
995 TF4 extends T,
996 TF5 extends T,
997 TF6 extends T,
998 TF7 extends T,
999 TF8 extends T,
1000 R,
1001>(
1002 pairs: [
1003 CondPairTypeguard<T, TF1, R>,
1004 CondPairTypeguard<T, TF2, R>,
1005 CondPairTypeguard<T, TF3, R>,
1006 CondPairTypeguard<T, TF4, R>,
1007 CondPairTypeguard<T, TF5, R>,
1008 CondPairTypeguard<T, TF6, R>,
1009 CondPairTypeguard<T, TF7, R>,
1010 CondPairTypeguard<T, TF8, R>,
1011 ],
1012): (value: T) => R;
1013export function cond<
1014 T,
1015 TF1 extends T,
1016 TF2 extends T,
1017 TF3 extends T,
1018 TF4 extends T,
1019 TF5 extends T,
1020 TF6 extends T,
1021 TF7 extends T,
1022 TF8 extends T,
1023 TF9 extends T,
1024 R,
1025>(
1026 pairs: [
1027 CondPairTypeguard<T, TF1, R>,
1028 CondPairTypeguard<T, TF2, R>,
1029 CondPairTypeguard<T, TF3, R>,
1030 CondPairTypeguard<T, TF4, R>,
1031 CondPairTypeguard<T, TF5, R>,
1032 CondPairTypeguard<T, TF6, R>,
1033 CondPairTypeguard<T, TF7, R>,
1034 CondPairTypeguard<T, TF8, R>,
1035 CondPairTypeguard<T, TF9, R>,
1036 ],
1037): (value: T) => R;
1038export function cond<
1039 T,
1040 TF1 extends T,
1041 TF2 extends T,
1042 TF3 extends T,
1043 TF4 extends T,
1044 TF5 extends T,
1045 TF6 extends T,
1046 TF7 extends T,
1047 TF8 extends T,
1048 TF9 extends T,
1049 TF10 extends T,
1050 R,
1051>(
1052 pairs: [
1053 CondPairTypeguard<T, TF1, R>,
1054 CondPairTypeguard<T, TF2, R>,
1055 CondPairTypeguard<T, TF3, R>,
1056 CondPairTypeguard<T, TF4, R>,
1057 CondPairTypeguard<T, TF5, R>,
1058 CondPairTypeguard<T, TF6, R>,
1059 CondPairTypeguard<T, TF7, R>,
1060 CondPairTypeguard<T, TF8, R>,
1061 CondPairTypeguard<T, TF9, R>,
1062 CondPairTypeguard<T, TF10, R>,
1063 ],
1064): (value: T) => R;
1065export function cond<T extends any[], R>(pairs: ReadonlyArray<CondPair<T, R>>): (...args: T) => R;
1066
1067/**
1068 * Wraps a constructor function inside a curried function that can be called with the same arguments and returns the same type.
1069 *
1070 * See also {@link invoker}.
1071 *
1072 * @example
1073 * ```typescript
1074 * // Constructor function
1075 * class Animal {
1076 * constructor(public kind: string) {}
1077 *
1078 * sighting() {
1079 * return "It's a " + this.kind + "!";
1080 * }
1081 * }
1082 *
1083 * const AnimalConstructor = R.construct(Animal)
1084 *
1085 * // Notice we no longer need the 'new' keyword:
1086 * AnimalConstructor('Pig'); //=> {"kind": "Pig", "sighting": function (){...}};
1087 *
1088 * const animalTypes = ["Lion", "Tiger", "Bear"];
1089 * const animalSighting = R.invoker(0, 'sighting');
1090 * const sightNewAnimal = R.compose(animalSighting, AnimalConstructor);
1091 * R.map(sightNewAnimal, animalTypes); //=> ["It's a Lion!", "It's a Tiger!", "It's a Bear!"]
1092 * ```
1093 */
1094export function construct<A extends any[], T>(
1095 constructor: { new (...args: A): T } | ((...args: A) => T),
1096): _.F.Curry<(...args: A) => T>;
1097
1098// NOTE: Example doesn't work with this typing
1099/**
1100 * Wraps a constructor function inside a curried function that can be called with the same arguments and returns the same type.
1101 * The arity of the function returned is specified to allow using variadic constructor functions.
1102 */
1103export function constructN<A extends any[], T, N extends number>(
1104 n: N,
1105 constructor: { new (...args: A): T } | ((...args: A) => T),
1106): _.F.Curry<(...args: mergeArrWithLeft<Tuple<any, N>, A>) => T>;
1107
1108// NOTE: Example doesn't work with this typing
1109/**
1110 * Accepts a converging function and a list of branching functions and returns a new function.
1111 * When invoked, this new function is applied to some arguments,
1112 * each branching function is applied to those same arguments.
1113 * The results of each branching function are passed as arguments to the converging function
1114 * to produce the return value.
1115 *
1116 * See also {@link useWith}.
1117 */
1118export function converge<
1119 TResult,
1120 FunctionsList extends ReadonlyArray<Fn> &
1121 IfFunctionsArgumentsDoNotOverlap<_Fns, 'Functions arguments types must overlap'>,
1122 _Fns extends ReadonlyArray<Fn> = FunctionsList,
1123>(
1124 converging: (...args: ReturnTypesOfFns<FunctionsList>) => TResult,
1125 branches: FunctionsList,
1126): _.F.Curry<(...args: LargestArgumentsList<FunctionsList>) => TResult>;
1127export function converge<
1128 CArgs extends ReadonlyArray<any>,
1129 TResult,
1130 FunctionsList extends readonly [
1131 ...{
1132 [Index in keyof CArgs]: (...args: ReadonlyArray<any>) => CArgs[Index];
1133 },
1134 ] &
1135 IfFunctionsArgumentsDoNotOverlap<_Fns, 'Functions arguments types must overlap'>,
1136 _Fns extends ReadonlyArray<Fn> = FunctionsList,
1137>(
1138 converging: (...args: CArgs) => TResult,
1139 branches: FunctionsList,
1140): _.F.Curry<(...args: LargestArgumentsList<FunctionsList>) => TResult>;
1141
1142/**
1143 * Returns the number of items in a given `list` matching the predicate `f`.
1144 *
1145 * @example
1146 * ```typescript
1147 * const even = (x: number) => x % 2 == 0;
1148 *
1149 * R.count(even, [1, 2, 3, 4, 5]); // => 2
1150 * R.map(R.count(even), [[1, 1, 1], [2, 3, 4, 5], [6]]); // => [0, 2, 1]
1151 * ```
1152 */
1153export function count<T>(fn: (a: T) => boolean, list: readonly T[]): number;
1154export function count<T>(fn: (a: T) => boolean): (list: readonly T[]) => number;
1155
1156/**
1157 * Counts the elements of a list according to how many match each value of a key generated by the supplied function.
1158 * Returns an object mapping the keys produced by `fn` to the number of occurrences in the list.
1159 * Note that all keys are coerced to strings because of how JavaScript objects work.
1160 *
1161 * Acts as a transducer if a transformer is given in list position.
1162 *
1163 * See also {@link transduce}.
1164 *
1165 * @example
1166 * ```typescript
1167 * const numbers = [1.0, 1.1, 1.2, 2.0, 3.0, 2.2];
1168 * R.countBy(Math.floor)(numbers); //=> {'1': 3, '2': 2, '3': 1}
1169 *
1170 * const letters = ['a', 'b', 'A', 'a', 'B', 'c'];
1171 * R.countBy(R.toLower)(letters); //=> {'a': 3, 'b': 2, 'c': 1}
1172 * ```
1173 */
1174export function countBy<T>(fn: (a: T) => string | number, list: readonly T[]): { [index: string]: number };
1175export function countBy<T>(fn: (a: T) => string | number): (list: readonly T[]) => { [index: string]: number };
1176
1177/**
1178 * Returns a curried equivalent of the provided function.
1179 *
1180 * See also {@link curryN}, {@link partial}.
1181 *
1182 * The curried function has two unusual capabilities.
1183 *
1184 * First, its arguments needn't be provided one at a time.
1185 * If `f` is a ternary function and `g` is `R.curry(f)`, the following are equivalent:
1186 * - `g(1)(2)(3)`
1187 * - `g(1)(2, 3)`
1188 * - `g(1, 2)(3)`
1189 * - `g(1, 2, 3)`
1190 *
1191 * Secondly, the special placeholder value `R.__` may be used to specify "gaps",
1192 * allowing partial application of any combination of arguments,
1193 * regardless of their positions.
1194 * If `g` is as above and `_` is `R.__`, the following are equivalent:
1195 * - `g(1, 2, 3)`
1196 * - `g(_, 2, 3)(1)`
1197 * - `g(_, _, 3)(1)(2)`
1198 * - `g(_, _, 3)(1, 2)`
1199 * - `g(_, 2)(1)(3)`
1200 * - `g(_, 2)(1, 3)`
1201 * - `g(_, 2)(_, 3)(1)`
1202 *
1203 * @example
1204 * ```typescript
1205 * const addFourNumbers = (a: number, b: number, c: number, d: number) => a + b + c + d;
1206 *
1207 * const curriedAddFourNumbers = R.curry(addFourNumbers);
1208 * const f = curriedAddFourNumbers(1, 2);
1209 * const g = f(3);
1210 * g(4); //=> 10
1211 * ```
1212 */
1213export function curry<F extends AnyFunction>(f: F): _.F.Curry<F>;
1214
1215/**
1216 * Returns a curried equivalent of the provided function, with the specified arity.
1217 *
1218 * See also {@link curry}.
1219 *
1220 * The curried function has two unusual capabilities.
1221 *
1222 * First, its arguments needn't be provided one at a time.
1223 * If `f` is a ternary function and `g` is `R.curry(f)`, the following are equivalent:
1224 * - `g(1)(2)(3)`
1225 * - `g(1)(2, 3)`
1226 * - `g(1, 2)(3)`
1227 * - `g(1, 2, 3)`
1228 *
1229 * Secondly, the special placeholder value `R.__` may be used to specify "gaps",
1230 * allowing partial application of any combination of arguments,
1231 * regardless of their positions.
1232 * If `g` is as above and `_` is `R.__`, the following are equivalent:
1233 * - `g(1, 2, 3)`
1234 * - `g(_, 2, 3)(1)`
1235 * - `g(_, _, 3)(1)(2)`
1236 * - `g(_, _, 3)(1, 2)`
1237 * - `g(_, 2)(1)(3)`
1238 * - `g(_, 2)(1, 3)`
1239 * - `g(_, 2)(_, 3)(1)`
1240 *
1241 * @example
1242 * ```typescript
1243 * const sumArgs = (...args: number[]) => R.sum(args);
1244 *
1245 * const curriedAddFourNumbers = R.curryN(4, sumArgs);
1246 * const f = curriedAddFourNumbers(1, 2);
1247 * const g = f(3);
1248 * g(4); //=> 10
1249 * ```
1250 */
1251export function curryN<N extends number, F extends AnyFunction>(
1252 length: N,
1253 fn: F,
1254): _.F.Curry<(...args: _.T.Take<Parameters<F>, _.N.NumberOf<N>>) => ReturnType<F>>;
1255export function curryN<N extends number>(
1256 length: N,
1257): <F extends AnyFunction>(fn: F) => _.F.Curry<(...args: _.T.Take<Parameters<F>, _.N.NumberOf<N>>) => ReturnType<F>>;
1258
1259/**
1260 * Decrements its argument.
1261 *
1262 * See also {@link inc}.
1263 *
1264 * @example
1265 * ```typescript
1266 * R.dec(42); //=> 41
1267 * ```
1268 */
1269export function dec(n: number): number;
1270
1271/**
1272 * Returns the second argument if it is not `null`, `undefined` or `NaN`; otherwise the first argument is returned.
1273 *
1274 * @example
1275 * ```typescript
1276 * const defaultTo42 = R.defaultTo(42);
1277 *
1278 * defaultTo42(null); //=> 42
1279 * defaultTo42(undefined); //=> 42
1280 * defaultTo42(false); //=> false
1281 * defaultTo42('Ramda'); //=> 'Ramda'
1282 * // parseInt('string') results in NaN
1283 * defaultTo42(parseInt('string')); //=> 42
1284 * ```
1285 */
1286export function defaultTo<T, U>(a: T, b: U | null | undefined): T | U;
1287export function defaultTo<T>(a: T): <U>(b: U | null | undefined) => T | U;
1288
1289/**
1290 * Makes a descending comparator function out of a function that returns a value that can be compared with `<` and `>`.
1291 *
1292 * See also {@link ascend}.
1293 *
1294 * @example
1295 * ```typescript
1296 * type Person = { name: string; age: number; };
1297 *
1298 * const byAge = R.descend<Person>(R.prop('age'));
1299 * const people = [
1300 * { name: 'Emma', age: 70 },
1301 * { name: 'Peter', age: 78 },
1302 * { name: 'Mikhail', age: 62 },
1303 * ];
1304 * const peopleByOldestFirst = R.sort(byAge, people);
1305 * //=> [{ name: 'Peter', age: 78 }, { name: 'Emma', age: 70 }, { name: 'Mikhail', age: 62 }]
1306 * ```
1307 */
1308export function descend<T>(fn: (obj: T) => Ord, a: T, b: T): Ordering;
1309export function descend<T>(fn: (obj: T) => Ord): (a: T, b: T) => Ordering;
1310
1311/**
1312 * Finds the set (i.e. no duplicates) of all elements in the first list not contained in the second list.
1313 * `Object`s and `Array`s are compared in terms of value equality, not reference equality.
1314 *
1315 * See also {@link differenceWith}, {@link symmetricDifference}, {@link symmetricDifferenceWith}, {@link without}.
1316 *
1317 * @example
1318 * ```typescript
1319 * R.difference([1,2,3,4], [7,6,5,4,3]); //=> [1,2]
1320 * R.difference([7,6,5,4,3], [1,2,3,4]); //=> [7,6,5]
1321 * R.difference<{ a: number; } | { b: number; } | { c: number; }>([{a: 1}, {b: 2}], [{a: 1}, {c: 3}]) //=> [{b: 2}]
1322 * ```
1323 */
1324export function difference<T>(list1: readonly T[], list2: readonly T[]): T[];
1325export function difference<T>(list1: readonly T[]): (list2: readonly T[]) => T[];
1326
1327/**
1328 * Finds the set (i.e. no duplicates) of all elements in the first list not contained in the second list.
1329 * Duplication is determined according to the value returned
1330 * by applying the supplied predicate to two list elements.
1331 *
1332 * See also See also {@link difference}, {@link symmetricDifference}, {@link symmetricDifferenceWith}.
1333 *
1334 * @example
1335 * ```typescript
1336 * const cmp = (x: { a: number; }, y: { a: number; }) => x.a === y.a;
1337 * const l1 = [{a: 1}, {a: 2}, {a: 3}];
1338 * const l2 = [{a: 3}, {a: 4}];
1339 * R.differenceWith(cmp, l1, l2); //=> [{a: 1}, {a: 2}]
1340 * ```
1341 */
1342export function differenceWith<T1, T2>(
1343 pred: (a: T1, b: T2) => boolean,
1344 list1: readonly T1[],
1345 list2: readonly T2[],
1346): T1[];
1347export function differenceWith<T1, T2>(
1348 pred: (a: T1, b: T2) => boolean,
1349): (list1: readonly T1[], list2: readonly T2[]) => T1[];
1350export function differenceWith<T1, T2>(
1351 pred: (a: T1, b: T2) => boolean,
1352 list1: readonly T1[],
1353): (list2: readonly T2[]) => T1[];
1354
1355/**
1356 * Returns a new object that does not contain the given property.
1357 *
1358 * See also {@link assoc}, {@link omit}.
1359 *
1360 * @example
1361 * ```typescript
1362 * R.dissoc('b', {a: 1, b: 2, c: 3}); //=> {a: 1, c: 3}
1363 * ```
1364 */
1365export function dissoc<T extends object, K extends keyof T>(prop: K, obj: T): Omit<T, K>;
1366export function dissoc<K extends string | number>(prop: K): <T extends object>(obj: T) => Omit<T, K>;
1367
1368/**
1369 * Makes a shallow clone of an object, omitting the property at the given path.
1370 *
1371 * @note This copies and flattens prototype properties onto the new object as well.
1372 * All non-primitive properties are copied by reference.
1373 *
1374 * @example
1375 * ```typescript
1376 * R.dissocPath(['a', 'b', 'c'], {a: {b: {c: 42}}}); //=> {a: {b: {}}}
1377 * ```
1378 */
1379export function dissocPath<T>(path: Path, obj: any): T;
1380export function dissocPath<T>(path: Path): (obj: any) => T;
1381
1382/**
1383 * Divides two numbers. Equivalent to `a / b` but curried.
1384 *
1385 * See also {@link multiply}.
1386 *
1387 * @example
1388 * ```typescript
1389 * R.divide(71, 100); //=> 0.71
1390 *
1391 * const half = R.divide(R.__, 2);
1392 * half(42); //=> 21
1393 *
1394 * const reciprocal = R.divide(1);
1395 * reciprocal(4); //=> 0.25
1396 * ```
1397 */
1398export function divide(__: Placeholder, b: number): (a: number) => number;
1399export function divide(__: Placeholder): (b: number, a: number) => number;
1400export function divide(a: number, b: number): number;
1401export function divide(a: number): (b: number) => number;
1402
1403/**
1404 * Returns all but the first `n` elements of the given list, string, or transducer/transformer.
1405 *
1406 * Dispatches to the `drop` method of the second argument, if present.
1407 *
1408 * See also {@link take}, {@link transduce}, {@link dropLast}, {@link dropWhile}.
1409 *
1410 * @example
1411 * ```typescript
1412 * R.drop(1, ['foo', 'bar', 'baz']); //=> ['bar', 'baz']
1413 * R.drop(2, ['foo', 'bar', 'baz']); //=> ['baz']
1414 * R.drop(3, ['foo', 'bar', 'baz']); //=> []
1415 * R.drop(4, ['foo', 'bar', 'baz']); //=> []
1416 * R.drop(3, 'ramda'); //=> 'da'
1417 * ```
1418 */
1419export function drop<T>(n: number, xs: readonly T[]): T[];
1420export function drop(n: number, xs: string): string;
1421export function drop<T>(n: number): {
1422 (xs: string): string;
1423 (xs: readonly T[]): T[];
1424};
1425
1426/**
1427 * Returns a list containing all but the last `n` elements of the given list.
1428 *
1429 * Acts as a transducer if a transformer is given in list position.
1430 *
1431 * See also {@link takeLast}, {@link drop}, {@link dropWhile}, {@link dropLastWhile}, {@link transduce}.
1432 *
1433 * @example
1434 * ```typescript
1435 * R.dropLast(1, ['foo', 'bar', 'baz']); //=> ['foo', 'bar']
1436 * R.dropLast(2, ['foo', 'bar', 'baz']); //=> ['foo']
1437 * R.dropLast(3, ['foo', 'bar', 'baz']); //=> []
1438 * R.dropLast(4, ['foo', 'bar', 'baz']); //=> []
1439 * R.dropLast(3, 'ramda'); //=> 'ra'
1440 * ```
1441 */
1442export function dropLast<T>(n: number, xs: readonly T[]): T[];
1443export function dropLast(n: number, xs: string): string;
1444export function dropLast<T>(n: number): {
1445 (xs: readonly T[]): T[];
1446 (xs: string): string;
1447};
1448
1449/**
1450 * Returns a new list excluding all the tailing elements of a given list which satisfy the supplied predicate function.
1451 * It passes each value from the right to the supplied predicate function,
1452 * skipping elements until the predicate function returns a falsy value.
1453 *
1454 * Acts as a transducer if a transformer is given in list position.
1455 *
1456 * See also {@link takeLastWhile}, {@link addIndex}, {@link drop}, {@link dropWhile}, {@link transduce}.
1457 *
1458 * @example
1459 * ```typescript
1460 * const lteThree = (x: number) => x <= 3;
1461 *
1462 * R.dropLastWhile(lteThree, [1, 2, 3, 4, 3, 2, 1]); //=> [1, 2, 3, 4]
1463 *
1464 * R.dropLastWhile(x => x !== 'd', 'Ramda'); //=> 'Ramd'
1465 * ```
1466 */
1467export function dropLastWhile<T>(fn: (a: T) => boolean, list: readonly T[]): T[];
1468export function dropLastWhile<T>(fn: (a: T) => boolean): (list: readonly T[]) => T[];
1469
1470/**
1471 * Returns a new list without any consecutively repeating elements.
1472 * {@link equals `R.equals`} is used to determine equality.
1473 *
1474 * Acts as a transducer if a transformer is given in list position.
1475 *
1476 * See also {@link transduce}.
1477 *
1478 * @example
1479 * ```typescript
1480 * R.dropRepeats([1, 1, 1, 2, 3, 4, 4, 2, 2]); //=> [1, 2, 3, 4, 2]
1481 * ```
1482 */
1483export function dropRepeats<T>(list: readonly T[]): T[];
1484