curriable

Curry any function with placeholder support

Table of contents

• curriable
  • Table of contents
  • Summary
  • Usage
  • API
    • curry
    • uncurry
      • Using placeholders
      • Rest parameters
      • Default parameters
      • Generics
  • Benchmarks
    • Passing each parameter in curried calls
    • Passing all parameters in one call
    • Using placeholder parameters in curried calls

Summary

curriable provides a curry method that is highly performant with a small footprint (582 bytes minified+gzipped). You can call the method with any combination of parameters (one at a time, all at once, or any number in between), and placeholders are supported.

If fn is the curried function and _ is the placeholder value, the following are all equivalent:

• fn(1)(2)(3)
• fn(1)(2, 3)
• fn(1, 2)(3)
• fn(1, 2, 3)
• fn(_, 2, 3)(1)
• fn(_, _, 3)(1)(2)
• fn(_, _, 3)(1, 2)
• fn(_, 2)(1)(3)
• fn(_, 2)(1, 3)
• fn(_, 2)(_, 3)(1)

Usage

import { __, curry, uncurry } from 'curriable';

const fn = curry((a, b, c) => [a, b, c]);

console.log(fn('a', __, 'c')('b')); // ["a", "b", "c"]

const original = uncurry(fn);

console.log(original('a')); // ["a", undefined, undefined]

API

curry

Curry the fn provided for any combination of arguments passed, until all required arguments have been passed.

import { curry } from 'curriable';

function curry<Fn extends (...args: any[]) => any>(
    fn: Fn,
    arity: number = fn.length
) => Curried<Fn>;

arity defaults to be the length provided by fn.length, but be aware this can cause unusual behavior with default parameters or use of rest parameters. See the documentation on Function.length for more details.

Using placeholders

If you want to apply curried arguments out of order, you can use the placeholder when applying curried values.

import { __, curry } from 'curriable';

const fn = curry((a, b, c) => [a, b, c]);
const pendingB = fn('a', __, 'c');

console.log(pendingB('b')); // ["a", "b", "c"]

Please note that applying the placeholder will only "skip" the argument for that given call. For example, when applied as an individual argument, it still waits for the "next" argument:

import { __, curry } from 'curriable';

const fn = curry((a, b, c) => [a, b, c]);
const pendingB = fn('a')(__)('c');

console.log(pendingB('b')); // ["a", "c", "b"] <- order of actual arguments passed

However, you can apply them as preceeding arguments to any curried method, so this would work as expected:

import { __, curry } from 'curriable';

const fn = curry((a, b, c) => [a, b, c]);
const pendingBC = fn('a');
const pendingB = pendingBC(__, 'c');

console.log(pendingB('b')); // ["a", "b", "c"]

Rest parameters

console.log((...args) => args.length); // 0 arity computed

When using rest with curried functions, you should pass a second parameter to explicitly declare the correct arity:

const fn = (...args) => [a, b, c];
const curried = curry(fn, 3);

console.log(curried('a')('b')('c')); // ["a", "b", "c"]

Default parameters

console.log(function (a, b = 1, c) {}.length); // 1 arity computed

Default parameters are very rare use-case with curried functions, but it is possible to trigger them if you declare an explicit arity and explicitly pass undefined for that parameter:

const fn = (a, b, c = 1) => [a, b, c];
const curried = curry(fn, 3);

console.log(curried('a')('b')(undefined)); // ["a", "b", 1]

Yes, this is weird, but it is very difficult (impossible?) to distinguish between a parameter being undefined through not being called yet in the curry chain vs being undefined by not being provided an explicit value. Explicitly passing undefined provides that distinction.

Another option is to keep the arity limited and pass the value as an extra argument to the final curried method:

const fn = (a, b, c = 1) => [a, b, c];
const curried = curry(fn);

console.log(curried('a')('b', 5)); // ["a", "b", 5]

Generics

curriable will produce a new function that can extra the arguments and return value from the function passed, however a known gap in TS is that doing so will widen any types narrowed by the use of generics.

const fn = <T extends number | string>(t: T, exact: boolean): T;
const curried = curry(fn);
const foo = curried('foo')(true); // `foo` is `number|string` instead of just `string`

This is intrinsic to TS as a language, so unfortunately it cannot be avoided.

uncurry

import { uncurry } from 'curriable';

Get the underlying standard method that was curried using `curry`.

function uncurry<Fn extends (...args: any[]) => any>(
    fn: Curried<Fn>
) => Fn;

Benchmarks

All values provided are the number of operations per second (ops/sec) calculated by the Benchmark suite. The same function was curried and tested passing each parameter individually, passing all at once, and using placeholders.

Benchmarks were performed on an i9 16-core Arch Linux laptop with 64GB of memory using NodeJS version 24.8.0.

Passing each parameter in curried calls

┌───────────┬────────────────┐
│ Name      │ Ops / sec      │
├───────────┼────────────────┤
│ curriable │ 7124353.607986 │
├───────────┼────────────────┤
│ ramda     │ 4764809.934737 │
├───────────┼────────────────┤
│ lodash    │ 342433.581292  │
└───────────┴────────────────┘
Fastest was "curriable".

Passing all parameters in one call

┌───────────┬─────────────────┐
│ Name      │ Ops / sec       │
├───────────┼─────────────────┤
│ curriable │ 12350527.161373 │
├───────────┼─────────────────┤
│ ramda     │ 9607895.768301  │
├───────────┼─────────────────┤
│ lodash    │ 9153661.59519   │
└───────────┴─────────────────┘
Fastest was "curriable".

Using placeholder parameters in curried calls

┌───────────┬────────────────┐
│ Name      │ Ops / sec      │
├───────────┼────────────────┤
│ curriable │ 7889269.76134  │
├───────────┼────────────────┤
│ ramda     │ 5396093.483594 │
├───────────┼────────────────┤
│ lodash    │ 447202.272784  │
└───────────┴────────────────┘
Fastest was "curriable".