functional-commons

A set of functional functions that everybody needs.

Install

``sh
npm install @applitools/functional-commons
`

Usage

Example using range:

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

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

API

$3

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

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

$3

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

`js
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"
`

$3

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

`js
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"
`

$3

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.

$3

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

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

$3

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

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

$3

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

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

$3

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

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

$3

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

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

$3

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

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

$3

throws errFactory() after ms milliseconds

#### ms

The number of milliseconds to wait before throwing

$3

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

$3

Nothing. It always throws

#### Example

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

// prints 'oops' after a second
`

$3

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.

$3

A promise that will either be resolved or rejected

$3

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

`js
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'
`

$3

An async function that delays a specific time

$3

The time to delay, in milliseconds

$3

returns undefined

$3

`js
await delay(100) // waits for 100ms
`

$3

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

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

$3

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

`js
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
`

$3

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

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

$3

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

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

$3

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

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

$3

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

`js
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]
`

$3

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.