Rambda

Rambda is TypeScript-focused utility library similar to Remeda, Ramda and Radashi.

Initially it started as faster alternative to functional programming library Ramda, but in order to address many TypeScript issues, now Rambda takes a separate path. - Documentation

❯ Example use

import { pipe, map, filter } from 'rambda'

const result = pipe(
    [1, 2, 3, 4],
  filter(x => x > 2),
  map(x => x * 2),
)
// => [6, 8]

You can test this example in Rambda's REPL

• API
• Changelog

❯ Rambda's features

❯ Goals

Typescript focus

Mixing Functional Programming and TypeScript is not easy.

One way to solve this is to focus what can be actually achieved and refrain from what is not possible.

R.pipe as the main way to use Rambda

• All methods are meant to be used as part of R.pipe chain

• This is the main purpose of functional programming, i.e. to pass data through a chain of functions.

• Having R.pipe(input, ...fns) helps TypeScript to infer the types of the input and the output.

Here is one example why R.pipe is better than Ramda.pipe:

const list = [1, 2, 3];

it('within pipe', () => {
    const result = pipe(
        list,
        filter((x) => {
            x; // $ExpectType number
            return x > 1;
        }),
    );
    result; // $ExpectType number[]
});
it('within Ramda.pipe requires explicit types', () => {
    Ramda.pipe(
        (x) => x,
        filter<number>((x) => {
            x; // $ExpectType number
            return x > 1;
        }),
        filter((x: number) => {
            x; // $ExpectType number
            return x > 1;
        }),
    )(list);
});

Keep only the most useful methods

The idea is to give TypeScript users only the most useful methods and let them implement the rest. No magic logic methods that are hard to remember. You shouldn't need to read the documentation to understand what a method does. Its name and signature should be enough.

• Methods that are simply to remember only by its name. Complex logic shouldn't be part of utility library, but part of your codebase.

• Keep only methods which are both useful and which behaviour is obvious from its name. For example, R.innerJoin is kept, but R.identical, R.move is removed. Methods such as R.toLower, R.length provide little value. Such method are omitted from Rambda on purpose.

• Some generic methods such as curry and assoc is not easy to be expressed in TypeScript. For this reason Rambda omits such methods.

• No R.cond or R.ifElse as they make the chain less readable.

• No R.length as it adds very little value.

• No R.difference as user must remember the order of the inputs, i.e. which is compared to and which is compared against.

One way to use each method

Because of the focus on R.pipe, there is only one way to use each method. This helps with testing and also with TypeScript definitions.

• All methods that 2 inputs, will have to be called with R.methodName(input1)(input2)
• All methods that 3 inputs, will have to be called with R.methodName(input1, input2)(input3)

Deno support

import * as R from "https://deno.land/x/rambda/mod.ts";

R.filter(x => x > 1)([1, 2, 3])

Dot notation for R.path

Standard usage of R.path is R.path(['a', 'b'])({a: {b: 1} }).

In Rambda you have the choice to use dot notation(which is arguably more readable):

R.path('a.b')({a: {b: 1} })

Please note that since path input is turned into array, i.e. if you want R.path(['a','1', 'b'])({a: {'1': {b: 2}}}) to return 2, you will have to pass array path, not string path. If you pass a.1.b, it will turn path input to ['a', 1, 'b'].

Comma notation for R.pick and R.omit

Similar to dot notation, but the separator is comma(,) instead of dot(.).

R.pick('a,b', {a: 1 , b: 2, c: 3} })
// No space allowed between properties

Fast performance compared to Ramda

Since Rambda methods doesn't use so many internals, it is faster than Ramda. Prior to version 10, benchmark summary was included, but now the main selling point is the TypeScript focus, not performance so this is no longer included.

Differences between Rambda and Ramda

Up until version 9.4.2, the aim of Rambda was to match as much as possible the Ramda API.

Documentation site of Rambda version 9.4.2 is available here.

From version 10.0.0 onwards, Rambda will start to diverge from Ramda in order to address some of the issues that Ramda has.

Currently, Rambda includes 32 methods that differ from Ramda and shares 83 methods with it.

API

addProp

addProp<T extends object, P extends PropertyKey, V extends unknown>(
    prop: P,
    value: V
): (obj: T) => MergeTypes<T & Record<P, V>>

It adds new key-value pair to the object.

const result = R.pipe(
    { a: 1, b: 'foo' }, 
    R.addProp('c', 3)
)
// => { a: 1, b: 'foo', c: 3 }

Try this R.addProp example in Rambda REPL

addPropToObjects

addPropToObjects<
  T extends object,
  K extends string,
  R
>(
    property: K,
  fn: (input: T) => R
): (list: T[]) => MergeTypes<T & { [P in K]: R }>[]

It receives list of objects and add new property to each item.

The value is based on result of fn function, which receives the current object as argument.

const result = R.pipe(
    [
        {a: 1, b: 2},
        {a: 3, b: 4},
    ],
    R.addPropToObjects(
        'c',
        (x) => String(x.a + x.b),
    )
)
// => [{a: 1, b: 2, c: '3'}, {a: 3, b: 4, c: '7'}]

Try this R.addPropToObjects example in Rambda REPL

all

all<T>(predicate: (x: T) => boolean): (list: T[]) => boolean

It returns true, if all members of array list returns true, when applied as argument to predicate function.

const list = [ 0, 1, 2, 3, 4 ]
const predicate = x => x > -1

const result = R.pipe(
    list,
    R.all(predicate)
) // => true

Try this R.all example in Rambda REPL

allPass

allPass<F extends (...args: any[]) => boolean>(predicates: readonly F[]): F

It returns true, if all functions of predicates return true, when input is their argument.

const list = [[1, 2, 3, 4], [3, 4, 5]]
const result = R.pipe(
    list,
    R.filter(R.allPass([R.includes(2), R.includes(3)]))
) // => [[1, 2, 3, 4]]

Try this R.allPass example in Rambda REPL

any

any<T>(predicate: (x: T) => boolean): (list: T[]) => boolean

It returns true, if at least one member of list returns true, when passed to a predicate function.

const list = [1, 2, 3]
const predicate = x => x * x > 8
R.any(fn)(list)
// => true

Try this R.any example in Rambda REPL

anyPass

anyPass<T, TF1 extends T, TF2 extends T>(
  predicates: [(a: T) => a is TF1, (a: T) => a is TF2],
): (a: T) => a is TF1 | TF2

It accepts list of predicates and returns a function. This function with its input will return true, if any of predicates returns true for this input.

const isBig = x => x > 20
const isOdd = x => x % 2 === 1
const input = 11

const fn = R.anyPass(
  [isBig, isOdd]
)

const result = fn(input) 
// => true

Try this R.anyPass example in Rambda REPL

append

append<T>(el: T): (list: T[]) => T[]

It adds element x at the end of iterable.

const x = 'foo'

const result = R.append(x, ['bar', 'baz'])
// => ['bar', 'baz', 'foo']

Try this R.append example in Rambda REPL

ascend

ascend<T>(fn: (obj: T) => Ord): (a: T, b: T)=> Ordering

Helper function to be used with R.sort to sort list in ascending order.

const result = R.pipe(
    [{a: 1}, {a: 2}, {a: 0}],
    R.sort(R.ascend(R.prop('a')))
)
// => [{a: 0}, {a: 1}, {a: 2}]

Try this R.ascend example in Rambda REPL

assertType

assertType<T, U extends T>(fn: (x: T) => x is U) : (x: T) => U

It helps to make sure that input is from specific type. Similar to R.convertToType, but it actually checks the type of the input value. If fn input returns falsy value, then the function will throw an error.

checkObjectWithSpec

checkObjectWithSpec<T>(spec: T): <U>(testObj: U) => boolean

It returns true if all each property in conditions returns true when applied to corresponding property in input object.

const condition = R.checkObjectWithSpec({
  a : x => typeof x === "string",
  b : x => x === 4
})
const input = {
  a : "foo",
  b : 4,
  c : 11,
}

const result = condition(input) 
// => true

Try this R.checkObjectWithSpec example in Rambda REPL

compact

compact<T>(list: T[]): Array<StrictNonNullable<T>>

It removes null and undefined members from list or object input.

const result = R.pipe(
    {
        a: [ undefined, '', 'a', 'b', 'c'],
        b: [1,2, null, 0, undefined, 3],
        c: { a: 1, b: 2, c: 0, d: undefined, e: null, f: false },
    },
    x => ({
        a: R.compact(x.a),
        b: R.compact(x.b),
        c: R.compact(x.c)
    })
)
// => { a: ['a', 'b', 'c'], b: [1, 2, 3], c: { a: 1, b: 2, c: 0, f: false } }

Try this R.compact example in Rambda REPL

complement

complement<T extends any[]>(predicate: (...args: T) => unknown): (...args: T) => boolean

It returns inverted version of origin function that accept input as argument.

The return value of inverted is the negative boolean value of origin(input).

const fn = x => x > 5
const inverted = complement(fn)

const result = [
  fn(7),
  inverted(7)
] => [ true, false ]

Try this R.complement example in Rambda REPL

concat

concat<T>(x: T[]): (y: T[]) => T[]

It returns a new string or array, which is the result of merging x and y.

R.concat([1, 2])([3, 4]) // => [1, 2, 3, 4]
R.concat('foo')('bar') // => 'foobar'

Try this R.concat example in Rambda REPL

convertToType

convertToType<T>(x: unknown) : T

It helps to convert a value to a specific type. It is useful when you have to overcome TypeScript's type inference.

count

count<T>(predicate: (x: T) => boolean): (list: T[]) => number

It counts how many times predicate function returns true, when supplied with iteration of list.

const list = [{a: 1}, 1, {a:2}]
const result = R.count(x => x.a !== undefined)(list)
// => 2

Try this R.count example in Rambda REPL

countBy

countBy<T>(fn: (x: T) => string | number): (list: T[]) => { [index: string]: number }

It counts elements in a list after each instance of the input list is passed through transformFn function.

const list = [ 'a', 'A', 'b', 'B', 'c', 'C' ]

const result = countBy(x => x.toLowerCase())( list)
const expected = { a: 2, b: 2, c: 2 }
// => `result` is equal to `expected`

Try this R.countBy example in Rambda REPL

createObjectFromKeys

createObjectFromKeys<const K extends readonly PropertyKey[], V>(
    fn: (key: K[number]) => V
): (keys: K) => { [P in K[number]]: V }

const result = R.createObjectFromKeys(
    (x, index) => `${x}-${index}`
)(['a', 'b', 'c'])
// => {a: 'a-0', b: 'b-1', c: 'c-2'}

Try this R.createObjectFromKeys example in Rambda REPL

defaultTo

defaultTo<T>(defaultValue: T): (input: unknown) => T

It returns defaultValue, if all of inputArguments are undefined, null or NaN.

Else, it returns the first truthy inputArguments instance(from left to right).

:boom: Typescript Note: Pass explicit type annotation when used with R.pipe/R.compose for better type inference

R.defaultTo('foo')('bar') // => 'bar'
R.defaultTo('foo'))(undefined) // => 'foo'

// Important - emtpy string is not falsy value
R.defaultTo('foo')('') // => 'foo'

Try this R.defaultTo example in Rambda REPL

descend

descend<T>(fn: (obj: T) => Ord): (a: T, b: T)=> Ordering

Helper function to be used with R.sort to sort list in descending order.

const result = R.pipe(
    [{a: 1}, {a: 2}, {a: 0}],
    R.sort(R.descend(R.prop('a')))
)
// => [{a: 2}, {a: 1}, {a: 0}]

Try this R.descend example in Rambda REPL

drop

drop<T>(howMany: number): (list: T[]) => T[]

It returns howMany items dropped from beginning of list.

R.drop(2)(['foo', 'bar', 'baz']) // => ['baz']

Try this R.drop example in Rambda REPL

dropLast

dropLast<T>(howMany: number): (list: T[]) => T[]

It returns howMany items dropped from the end of list.

dropLastWhile

dropLastWhile<T>(predicate: (x: T, index: number) => boolean): (list: T[]) => T[]

const list = [1, 2, 3, 4, 5];
const predicate = x => x >= 3

const result = dropLastWhile(predicate)(list);
// => [1, 2]

Try this R.dropLastWhile example in Rambda REPL

dropRepeatsBy

dropRepeatsBy<T, U>(fn: (x: T) => U): (list: T[]) => T[]

const result = R.dropRepeatsBy(
  Math.abs,
  [1, -1, 2, 3, -3]
)
// => [1, 2, 3]

Try this R.dropRepeatsBy example in Rambda REPL

dropRepeatsWith

dropRepeatsWith<T>(predicate: (x: T, y: T) => boolean): (list: T[]) => T[]

const list = [{a:1,b:2}, {a:1,b:3}, {a:2, b:4}]
const result = R.dropRepeatsWith(R.prop('a'))(list)

// => [{a:1,b:2}, {a:2, b:4}]

Try this R.dropRepeatsWith example in Rambda REPL

dropWhile

dropWhile<T>(predicate: (x: T, index: number) => boolean): (list: T[]) => T[]

const list = [1, 2, 3, 4]
const predicate = x => x < 3
const result = R.dropWhile(predicate)(list)
// => [3, 4]

Try this R.dropWhile example in Rambda REPL

eqBy

eqBy<T>(fn: (x: T) => unknown, a: T): (b: T) => boolean

const result = R.eqBy(Math.abs, 5)(-5)
// => true

Try this R.eqBy example in Rambda REPL

eqProps

eqProps<T, K extends keyof T>(prop: K, obj1: T): (obj2: T) => boolean

It returns true if property prop in obj1 is equal to property prop in obj2 according to R.equals.

const obj1 = {a: 1, b:2}
const obj2 = {a: 1, b:3}
const result = R.eqProps('a', obj1)(obj2)
// => true

Try this R.eqProps example in Rambda REPL

equals

equals<T>(x: T, y: T): boolean

It deeply compares x and y and returns true if they are equal.

:boom: It doesn't handle cyclical data structures and functions

R.equals(
  [1, {a:2}, [{b: 3}]],
  [1, {a:2}, [{b: 3}]]
) // => true

Try this R.equals example in Rambda REPL