functional-commons

A set of functional functions that everybody needs.

Install

npm install @applitools/functional-commons

Usage

Example using range:

const {range} = require('@applitools/functional-commons')

for (const i of range(0, 3)) {
  console.log(i)
}
// ==> outputs 0, 1, 2

API

range(from, to, [step])

Returns an array with the numbers from...to - 1 (and skips step numbers)

from (Number)

The first number in the array

to (Number)

The last number in the array will be smaller thanto

step (Number)

The delta to skip when creating the numbers in the array (default is 1)

Example

range(4, 7) // ==> [4, 5, 6]
range(4, 11, 2) // ==> [4, 6, 8, 10]

cacheFunctionSync(f)

Returns a function with same signature as f, but which memoizes the return value according to the arguments passed

f

Any function. The arguments passed to the function will be JSON.string-ified to enable caching.

returns function

The function will have the same signature as f, and which will return the same return value given similar arguments, but calling this function repeatedly with the same arguments will generate only one call to f.

Example

function square(x) {
  console.log('called')

  return x ** 2
}

const memoizedSquare = cacheFunctionSync(square)

console.log(memoizedSquare(4)) // prints "called" and "16"
console.log(memoizedSquare(4)) // prints only "16"
console.log(memoizedSquare(5)) // prints "called" and "25"

cacheFunctionAsync(f, [options])

Returns a function with same signature as f, but which memoizes the return value according to the arguments passed. f is an async function (returns a Promise)

f

Any async function. The arguments passed to the function will be JSON.string-ified to enable caching.

options

expireAfterMs

The cached value will expire after expireAfterMs milliseconds. Default is to never expire (udefined).

nowService

(Used for testing purposes) An object with a now function that returns milliseconds since Epoch time. The default is just Date, which makes it return the current time in milliseconds.

returns

The function will have the same signature as f, and which will return the same return value given similar arguments, but calling this function repeatedly with the same arguments will generate only one call to f.

Example

async function square(x) {
  console.log('called')

  return x ** 2
}

const memoizedSquare = cacheFunctionAsync(square)

console.log(await memoizedSquare(4)) // prints "called" and "16"
console.log(await memoizedSquare(4)) // prints only "16"
console.log(await memoizedSquare(5)) // prints "called" and "25"

throws_(err)

A function that throws err. Nice in places where you want an arrow function to just throw.

err

Any type. Usually inherits from Error, though.

returns

This function never returns. It always throws.

objectFromEntries(entries)

Turns an array of [key, value] pairs into an object.

entries

An array of 2-value arrays (also called "entries"), where the first value in the pair is the key, and the second is the value.

returns

An object whose properties correspond to the entries given

Example

console.log(objectFromEntries([['a', 4, 'b' , 5]])) // prints {a: 4, b: 5}

mapObject(object, mapFunc)

Returns a new object where all the entries in the input object are mapped using mapFunc.

object

Any object.

mapFunc

A function that maps an entry "pair" (an 2-element array where the first element is the key of the property, and the second is the value) to another entry.

returns

An object (prototyped from Object) with mapped properties.

Example

console.log(mapObject({a: 4, b: 5}, ([key, value]) => [key.toUpperCase(), value * 2])) // prints {A: 8, B: 10}

mapValues(object, mapFunc)

Returns a new object where all the values in the input object are mapped using mapFunc.

object

Any object.

mapFunc

A function that maps a value to another value

returns

An object (prototyped from Object) with mapped property values.

Example

console.log(mapObject({a: 4, b: 5}, (value) => value * 2)) // prints {a: 8, b: 10}

filterKeys(object, filterFunc)

Filters an object using a filter function that gets the key. Immutable.

object

Any JavaScript object that needs properties filtered.

filterFunc

A function that accepts the property name and returns a boolean of whether to keep the property or not (true means keep the property)

returns

A new object (who's prototype will be Object) with the same properties as object, minus the filtered ones.

Example

console.log(filterKeys({a: 4, b: 5}, key => key === 'b')) // prints {a: 4}

filterValues(object, filterFunc)

Filters an object using a filter function that gets the value. Immutable.

object

Any JavaScript object that needs properties filtered.

filterFunc

A function that accepts the property value and returns a boolean of whether to keep the property or not (true means keep the property)

returns

A new object (who's prototype will be Object) with the same properties as object, minus the filtered ones.

Example

console.log(filterKeys({a: 4, b: 5}, key => value === '5')) // prints {a: 4}

filterEntries(object, filterFunc)

Filters an object using a filter function that gets the entries. Immutable.

object

Any JavaScript object that needs properties filtered.

filterFunc

A function that accepts a 2-element array of [key, value] and returns a boolean of whether to keep the property or not (true means keep the property)

returns

A new object (who's prototype will be Object) with the same properties as object, minus the filtered ones.

Example

console.log(filterKeys({a: 4, b: 5}, ([key, value]) =>  key === 'b' && value === 5)) // prints {a: 4}

failAfter(ms, errFactory)

throws errFactory() after ms milliseconds

ms

The number of milliseconds to wait before throwing

errFactory

A function that when called returns the value that will be thrown

returns

Nothing. It always throws

Example

try {
  await failAfter(1000, () => new Error('oops'))
} catch(err) {
  console.log(err.message)
}

// prints 'oops' after a second

presult(promise)

Turns a Promise from a promise that is resolved or rejected, to a promise that is always resolved, but returns the err and result as a tuple, Scala/Go/Rust-style.

promise

A promise that will either be resolved or rejected

returns

A promise that always resolved to a 2-tuple:

• If the oroginal promise is resolved with value, will resolve to [undefined, value]
• If the oroginal promise is rejected with err, will resolve to [err, undefined]

Example

const [err, value] = await presult(Promise.resolve(4))
console.log(value) // prints '4'

const [err2, value2] = await presult(Promise.reject(new Error('oops')))
console.log(err2.message) // prints 'oops'

delay

An async function that delays a specific time

ms

The time to delay, in milliseconds

returns

returns undefined

Example

await delay(100) // waits for 100ms

ptimeoutWithValue(promiseOrPromiseFunc, timeout, value)

A function that races between a given promise, and a value that returns after a timeout.

promiseOrPromiseFunc

A promise, or a function that returns a promise, which will be called to get the promise.

If the value is a function, it will be called and passed a function (usually called hasAborted), which, if called, will return true if the timeout has already happened, and you can abort this function.

timeout

The number of milliseconds to timeout.

value

The value to return from this function if the timeout happened before the promise resolved.

Example

console.log(await ptimeoutWithValue(delay(10).then(_ => 43), 100, 42)) // prints "43"
console.log(await ptimeoutWithValue(delay(100).then(_ => 43), 10, 42)) // prints "42"

ptimeoutWithError(promiseOrPromiseFunc, timeout, error)

A function that races between a given promise, and throwing an exception after a timeout.

promiseOrPromiseFunc

A promise, or a function that returns a promise, which will be called to get the promise.

If the value is a function, it will be called and passed a function (usually called hasAborted), which, if called, will return true if the timeout has already happened, and you can abort this function.

timeout

The number of milliseconds to timeout.

error

The error to be thrown from this function if the timeout happened before the promise resolved.

Example

console.log(await ptimeoutWithError(delay(10).then(_ => 43), 100, new Error('oops'))) // prints "43"
console.log(await ptimeoutWithError(delay(100).then(_ => 43), 10, new Error('oops'))) // throws 'oops' error

ptimeoutWithFunction(promiseOrPromiseFunc, timeout, func)

A function that races between a given promise, and a value (created from function) that returns after a timeout.

promiseOrPromiseFunc

A promise, or a function that returns a promise, which will be called to get the promise.

If the value is a function, it will be called and passed a function (usually called hasAborted), which, if called, will return true if the timeout has already happened, and you can abort this function.

timeout

The number of milliseconds to timeout.

func

An async function that will be called to get the value to be returned if the timeout occured

Example

console.log(await ptimeoutWithValue(delay(10).then(_ => 43), 100, 42)) // prints "43"
console.log(await ptimeoutWithValue(delay(100).then(_ => 43), 10, 42)) // prints "42"

makeError(error, properties)

A function that adds properties to an error

error

The error to be modified. Note that this function mutabl changes this error.

If error is a string, then an Error is created with this string as the message.

properties

Additional properties that will be added to the error object, in a mutable way

returns

The error object passed, or if the error was a string, the newly generated error.

Example

console.log(Object.entries(makeError('oops', {code: 'OOPS', status: 500}))) // prints {code: 'OOPS', status: 500}

zip(...arrays)

Regular functional zip of arrays.

arrays

list of arrays to zip

returns

An array of arrays, that are the zip of the arrays gotten.

Example

console.log(zip([1, 2, 3], [4, 5, 6])) // prints [[1, 4], [2, 5], [3, 6]]

`flatMap(array, [mapperFunction])

flattens array (one level), along with mapping the values

array

An array of values, or arrays or values.

mapperFunction

A function that maps a value to another. Optional.

returns

The array flattened (one level only), and it's values mapped if there was a mapperFunction.

Example

console.log(flatMap([4, [5, 6], 7])) // prints [4, 5, 6, 7]
console.log(flatMap([4, [5, 6], 7], x => x * 2)) // prints [8, 10, 12, 14]

makeThrottledFunction(func, [options])

returns a function that is a proxy to func, except that calling it will throttle the calls to func.

func

The original function.

`options

maxCallsPerTimeSpan

The maximum number of calls allowed in the time span timeSpan. Default is 120.

timeSpan

The timeSpan we throttle for.

nowService

(Used for testing purposes) An object with a now function that returns milliseconds since Epoch time. The default is just Date, which makes it return the current time in milliseconds.