JS-RESOURCES

A small set of utility functions and classes.

Array
- arrayAverage
- arrayChunk
- arrayGroup
- arrayLast
- arrayMax
- arrayMin
- arrayRandomPick
- arrayShuffle
- arraySortAlpha
- arraySortNum
- arraySum
- arrayUniq
- asArray
- range
Boolean
- parseBoolean
Error
- withErr
Object
Promise
- PromisePool
Time
- sleep
- withTime

Array

This package provides a set of utility functions to work with arrays.
They are all available in 3 forms:

As functions:
```
import {
    range,
    arrayChunk,
    arrayShuffle,
    ...
} from 'js-resources';
```
Note: functions are prefixed with the word array (except the ones provided as static methods in BoostedArray or the boosted native Array [asArray, range])

As methods in BoostedArray class (a class extending Array):

import { BoostedArray } from 'js-resources';
new BoostedArray(1, 2, 3, 4, 5).chunk(2);

As methods in the native Array class, but only if you import the boost-native-array module:
```
import 'js-resources/lib/boost-native-array';
[1, 2, 3, 4, 5].chunk(2);
```

Only functions are documented here, but signatures are almost identical for the 3 forms (except instance methods do not take an array to process as first parameter and BoostedArray methods return a BoostedArray instance instead of Array).

arrayAverage

▸ arrayAverage<T>(array, valueGetter?): number

Returns average value of array items or values returned by valueGetter

Type parameters

Name
`T`

Parameters

Name	Type
`array`	`T`[]
`valueGetter?`	`ValueGetter`<`T`>

Returns

number

Example

arrayAverage([7, 20, 3]); // -> 10
arrayAverage([{amount: 5}, {amount: 7}, {amount: 12}], (item) => item.amount); // -> 8

Defined in

array/average/average.ts:10

arrayChunk

▸ arrayChunk<T>(array, chunksLength?): T[][]

Chunks input array in sub arrays of length chunksLength (default to 1)

Type parameters

Name
`T`

Parameters

Name	Type	Default value
`array`	`T`[]	`undefined`
`chunksLength`	`number`	`1`

Returns

T[][]

Example

arrayChunk([1, 2, 3, 4, 5], 3); // -> [[1, 2, 3], [4, 5]]

Defined in

array/chunk/chunk.ts:6

arrayGroup

▸ arrayGroup<T>(array, valueGetter): Object

Groups array items in the property (of the returned object) matching their valueGetter return value

Type parameters

Name
`T`

Parameters

Name	Type
`array`	`T`[]
`valueGetter`	`ValueGetter`<`T`>

Returns

Object

Example

arrayGroup([{
     ref: 'foo',
     prop: 'bar',
}, {
     ref: 'fuu',
     prop: 'ber',
}, {
     ref: 'foo',
     prop: 'baz',
}], (item) => item.ref);
// returns:  
// {
//   foo: [{
//       ref: 'foo',
//        prop: 'bar',
//    },{
//        ref: 'foo',
//        prop: 'baz',
//    }],
//    fuu: [{
//        ref: 'fuu',
//        prop: 'ber',
//    }],
// }

Defined in

array/group/group.ts:33

arrayLast

▸ arrayLast<T>(array): undefined | T

Returns the last item of the array

Type parameters

Name
`T`

Parameters

Name	Type
`array`	`T`[]

Returns

undefined | T

Example

arrayLast(['foo', 'bar', 'fuu']); // -> 'fuu'

Defined in

array/last/last.ts:7

arrayMax

▸ arrayMax<T>(array, valueGetter?): number

Returns the item with the highest value, or the highest value returned by valueGetter if provided

Type parameters

Name
`T`

Parameters

Name	Type
`array`	`T`[]
`valueGetter?`	`ValueGetter`<`T`>

Returns

number

Example

arrayMax([5, 7, 3]); // -> 7
arrayMax([{amount: 5}, {amount: 7}, {amount: 3}], (item) => item.amount); // -> 7

Defined in

array/max/max.ts:10

arrayMin

▸ arrayMin<T>(array, valueGetter?): number

Returns the item with the lowest value, or the lowest value returned by valueGetter if provided

Type parameters

Name
`T`

Parameters

Name	Type
`array`	`T`[]
`valueGetter?`	`ValueGetter`<`T`>

Returns

number

Example

arrayMin([5, 3, 7]); // -> 3
arrayMin([{amount: 5}, {amount: 3}, {amount: 7}], (item) => item.amount); // -> 3

Defined in

array/min/min.ts:10

arrayRandomPick

▸ arrayRandomPick<T>(array): undefined | T

Return random item from array

Type parameters

Name
`T`

Parameters

Name	Type
`array`	`T`[]

Returns

undefined | T

Example

arrayRandomPick(['foo', 'fuu', 'bar']); // -> who knows???

Defined in

array/random-pick/random-pick.ts:6

arrayShuffle

▸ arrayShuffle<T>(array): T[]

Returns a copy of the array with items in random order

Type parameters

Name
`T`

Parameters

Name	Type
`array`	`T`[]

Returns

T[]

Example

arrayShuffle(['foo', 'bar', 'baz']); // -> [who knows???]

Defined in

array/shuffle/shuffle.ts:6

arraySortAlpha

▸ arraySortAlpha<T>(array, order?, valueGetter?): T[]

Sorts array items alphabetically, in ascending (default) or descending order, based on their value, or valueGetter return value if provided

Type parameters

Name
`T`

Parameters

Name	Type	Default value
`array`	`T`[]	`undefined`
`order`	`SortingOrder`	`'ascending'`
`valueGetter?`	`ValueGetter`<`T`>	`undefined`

Returns

T[]

Example

arraySortAlpha(['abc', 'bac', 'aaa']); // -> ['aaa', 'abc', 'bac']
arraySortAlpha(['abc', 'bac', 'aaa'], 'descending'); // -> ['bac', 'abc', 'aaa']
const arr = [{
    ref: 'abc',
}, {
    ref: 'bac',
}, {
    ref: 'aaa',
}];
arraySortAlpha(arr, 'descending', (item) => item.ref);
// returns
// [{
//     ref: 'bac',
// }, {
//     ref: 'abc',
// }, {
//     ref: 'aaa',
// }]

Defined in

array/sort-alpha/sort-alpha.ts:25

arraySortNum

▸ arraySortNum<T>(array, order?, valueGetter?): T[]

Sorts array items numerically, in ascending (default) or descending order, based on their value, or valueGetter return value if provided

Type parameters

Name
`T`

Parameters

Name	Type	Default value
`array`	`T`[]	`undefined`
`order`	`SortingOrder`	`'ascending'`
`valueGetter?`	`ValueGetter`<`T`>	`undefined`

Returns

T[]

Example

arraySortNum([1, 3, 2, 0, -3]); // -> [-3, 0, 1, 2, 3]
arraySortNum([1, 3, 2, 0, -3], 'descending'); // -> [3, 2, 1, 0, -3]
const arr = [{
    amount: 0,
}, {
    amount: -3,
}, {
    amount: 3,
}];
arraySortNum(arr, 'descending', (item) => item.amount);
// returns
// [{
//     amount: 3,
// }, {
//     amount: 0,
// }, {
//     amount: -3,
// }]

Defined in

array/sort-num/sort-num.ts:25

arraySum

▸ arraySum<T>(array, valueGetter?): number

Returns the sum of the array item values, or valueGetter return values if provided

Type parameters

Name
`T`

Parameters

Name	Type
`array`	`T`[]
`valueGetter?`	`ValueGetter`<`T`>

Returns

number

Example

arraySum([5, 7, 3]); // -> 15
const arr = [{
    amount: 5,
}, {
    amount: 7,
}, {
    amount: 3,
}];
arraySum(arr, (item) => item.amount); // -> 15

Defined in

array/sum/sum.ts:16

arrayUniq

▸ arrayUniq<T>(array, valueGetter?): T[]

Returns a copy of the array without duplicate items, based on their value or valueGetter return value if provided

Type parameters

Name
`T`

Parameters

Name	Type
`array`	`T`[]
`valueGetter?`	`ValueGetter`<`T`>

Returns

T[]

Example

arrayUniq([1, 2, 1, 3, 3, 4, 5]); // -> [1, 2, 3, 4, 5]
const arr = [{
    id: 1,
}, {
    id: 2,
}, {
    id: 1,
}];
arrayUniq(arr, (item) => item.id);
// returns
// [{
//     id: 1,
// }, {
//     id: 2,
// }]

Defined in

array/uniq/uniq.ts:22

asArray

▸ asArray<T>(value): T extends any[] ? T[number] : T[]

Returns input value if it is an array, otherwise returns it wrapped in an array.

Type parameters

Name
`T`

Parameters

Name	Type
`value`	`T`

Returns

T extends any[] ? T[number] : T[]

Example

asArray(['foo']); // -> ['foo']
asArray('foo'); // -> ['foo']

Defined in

array/as-array/as-array.ts:7

range

▸ range(stop): number[]

Returns an array of numbers from 0, to stop, incrementing by 1

Parameters

Name	Type
`stop`	`number`

Returns

number[]

Example

range(5); // -> [0, 1, 2, 3, 4];
const n = 5;
for (const i of range(5)) { ... }

Defined in

array/range/range.ts:8

▸ range(start, stop): number[]

Returns an array of numbers from start, to stop, incrementing by 1 if start < stop or -1 otherwise.

Parameters

Name	Type
`start`	`number`
`stop`	`number`

Returns

number[]

Example

range(1, 5); // -> [1, 2, 3, 4];
range(5, 1); // -> [5, 4, 3, 2];

Defined in

array/range/range.ts:15

▸ range(start, stop, step): number[]

Returns an array of numbers from start, to stop, incrementing by step.
Throws an error if start < stop and step < 0, or if start > stop and step > 0.

Parameters

Name	Type
`start`	`number`
`stop`	`number`
`step`	`number`

Returns

number[]

Example

range(1, 10, 2); // -> [1, 3, 5, 7, 9];
range(10, 1, -2); // -> [10, 8, 6, 4, 2];

Defined in

array/range/range.ts:23

Boolean

parseBoolean

▸ parseBoolean(value): boolean

Takes in a value and returns true if it is true or a stringified true. Returns false otherwise.

Parameters

Name	Type
`value`	`any`

Returns

boolean

Example

parseBoolean(true); // true
parseBoolean('true'); // true
parseBoolean('True'); // true
parseBoolean(' true'); // true
parseBoolean('foo'); // false
parseBoolean(false); // false
parseBoolean('false'); // false
parseBoolean(0); // false
parseBoolean(1); // false
parseBoolean(null); // false

Defined in

boolean/parse-boolean/parse-boolean.ts:15

Error

withErr

▸ withErr<T>(fn): ReturnType<T> extends Promise<infer R> ? Promise<[R | null, Error | null]> : [ReturnType<T> | null, Error | null]

Returns a tuple containing the return value of input fn function (or the resolved value of its returned promise) and null if no error is thrown, otherwise a tuple of null and the thrown error

Type parameters

Name	Type
`T`	extends (...`args`: `any`[]) => `any`

Parameters

Name	Type
`fn`	`T`

Returns

ReturnType<T> extends Promise<infer R> ? Promise<[R | null, Error | null]> : [ReturnType<T> | null, Error | null]

Example

const [value, err] = withErr(() => 'foo'); // -> ['foo', null]
const [value, err] = withErr(() => throw new Error('error...')); // -> [null, Error]
const myAsyncFn = async () => {
     // ...
     return 'bar';
};
const [value, err] = await withErr(myAsyncFn); // -> ['bar', null]
const myAsyncThrowingFn = async () => {
     // ...
     throw new Error('error...');
};
const [value, err] = await withErr(myAsyncFn); // -> [null, Error]

Defined in

error/with-err/with-err.ts:17

Object

defaultProperties

▸ defaultProperties<T>(object, defaultProperties): Partial<T> & T

Returns a copy of input object with specified default properties

Type parameters

Name
`T`

Parameters

Name	Type
`object`	`T`
`defaultProperties`	`Partial`<`T`>

Returns

Partial<T> & T

Example

function foo(options) {
     options = defaultProperties(options, {
         prop1: true,
         prop2: 100,
         ...
     });
}

Defined in

object/default-properties/default-properties.ts:13

deleteProperties

▸ deleteProperties<T>(object, propertiesToDelete, options?): T

Returns a copy (unless copy options is set to false) of input object without specified properties

Type parameters

Name
`T`

Parameters

Name	Type
`object`	`T`
`propertiesToDelete`	keyof `T`[]
`options`	`Object`
`options.copyInputObject?`	`boolean`

Returns

T

Example

const obj = { prop1: 'value1', prop2: 'value2', prop3: 'value3' };
const sanitizedObj = deleteProperties(obj, ['prop1', 'prop3']); // -> { prop2: 'value2' }
console.log(sanitizedObj); // -> { prop2: 'value2' }
console.log(obj); // -> { prop1: 'value1', prop2: 'value2', prop3: 'value3' }
/////////////////////////////////////////////////////////////////////
const obj = { prop1: 'value1', prop2: 'value2', prop3: 'value3' };
deleteProperties(obj, ['prop1', 'prop3'], { copyInputObject: false }); // -> { prop2: 'value2' }
console.log(obj); // -> { prop2: 'value2' }

Defined in

object/delete-properties/delete-properties.ts:16

getProperty

▸ getProperty<T>(object, path, fallbackValue): any

Returns object property at specified path.
path can be a string or an array of valid object keys. Array indexes can also be used.
If the path does not exists, fallbackValue will be returned.

Type parameters

Name
`T`

Parameters

Name	Type
`object`	`T`
`path`	`string` \| (`string` \| `number` \| `symbol`)[]
`fallbackValue`	`any`

Returns

any

Example

const value = getProperty({
    prop: 'foo',
    nested: {
        nestedProp: 'bar',
    },
}, 'nested.nestedProp'); // -> 'bar'
//////////////////////////////////////
const value = getProperty({ prop: 'foo' }, ['prop2', 'nestedProp'], 'fallback'); // -> 'fallback'

Defined in

object/get-property/get-property.ts:15

objectWalk

▸ objectWalk(object, callback): void

Walks through object recursively and triggers callback for each of its properties.
Walking is stopped whenever callback returns false.

Parameters

Name	Type
`object`	`any`
`callback`	(`props`: { `currObject`: `any` ; `key`: `string` \| `number` \| `symbol` ; `level`: `number` ; `path`: (`string` \| `number` \| `symbol`)[] ; `value`: `any` }) => `undefined` \| `boolean`

Returns

void

Example

const obj = {
    prop1: {
        prop1_nestedLevel1: {
            prop1_nestedLevel2: {
                prop1_nestedLevel3: 'foo',
            }
        }
    },
    prop2: {
        prop2_nestedLevel1: 'bar',
        prop2_nestedLevel1_bis: {
            prop2_nestedLevel2: 7,
        },
    },
};
const objectWalkReport = [];
objectWalk(obj, ({
    value,
    key,
    currObject,
    level,
    path,
}) => {
    objectWalkReport.push({
        value,
        key,
        currObject,
        level,
        path,
    });
});
console.log(objectWalkReport);
// Logs:
// [{
//     value: obj.prop1,
//     key: 'prop1',
//     currObject: obj,
//     level: 0,
//     path: ['prop1'],
// }, {
//     value: obj.prop1.prop1_nestedLevel1,
//     key: 'prop1_nestedLevel1',
//     currObject: obj.prop1,
//     level: 1,
//     path: ['prop1', 'prop1_nestedLevel1'],
// }, {
//     value: obj.prop1.prop1_nestedLevel1.prop1_nestedLevel2,
//     key: 'prop1_nestedLevel2',
//     currObject: obj.prop1.prop1_nestedLevel1,
//     level: 2,
//     path: ['prop1', 'prop1_nestedLevel1', 'prop1_nestedLevel2'],
// }, {
//     value: obj.prop1.prop1_nestedLevel1.prop1_nestedLevel2.prop1_nestedLevel3,
//     key: 'prop1_nestedLevel3',
//     currObject: obj.prop1.prop1_nestedLevel1.prop1_nestedLevel2,
//     level: 3,
//     path: ['prop1', 'prop1_nestedLevel1', 'prop1_nestedLevel2', 'prop1_nestedLevel3'],
// }, {
//     value: obj.prop2,
//     key: 'prop2',
//     currObject: obj,
//     level: 0,
//     path: ['prop2'],
// }, {
//     value: obj.prop2.prop2_nestedLevel1,
//     key: 'prop2_nestedLevel1',
//     currObject: obj.prop2,
//     level: 1,
//     path: ['prop2', 'prop2_nestedLevel1'],
// }, {
//     value: obj.prop2.prop2_nestedLevel1_bis,
//     key: 'prop2_nestedLevel1_bis',
//     currObject: obj.prop2,
//     level: 1,
//     path: ['prop2', 'prop2_nestedLevel1_bis'],
// }, {
//     value: obj.prop2.prop2_nestedLevel1_bis.prop2_nestedLevel2,
//     key: 'prop2_nestedLevel2',
//     currObject: obj.prop2.prop2_nestedLevel1_bis,
//     level: 2,
//     path: ['prop2', 'prop2_nestedLevel1_bis', 'prop2_nestedLevel2'],
// }]

Defined in

object/walk/walk.ts:97

setProperty

▸ setProperty<T>(object, path, value): void

Sets object property at specified path with specified value.
path can be a string or an array of valid object keys. Array indexes can also be used.
Non existing properties will be created.

Type parameters

Name
`T`

Parameters

Name	Type
`object`	`T`
`path`	`string` \| (`string` \| `number` \| `symbol`)[]
`value`	`any`

Returns

void

Example

const obj = { prop: 'foo' };
setProperty(obj, 'prop', 'bar');
console.log(obj): // -> { prop: 'bar' }
setProperty(obj, ['newProp', 'nested'], 'fuu');
console.log(obj): // -> { prop: 'bar', newProp: { nested: 'fuu' } }

Defined in

object/set-property/set-property.ts:12

Promise

Class: PromisePool

A simple Promise pool to handle concurrency

Example

const pool = new PromisePool()
     .setConcurrency(3)
     .onTaskDone((result) => console.log(result));
const results = await pool.run([
     asyncFn,
     asyncFn,
     asyncFn,
     asyncFn,
     asyncFn,
]);
/////////////////////////////////////////////////
const pool = new PromisePool(2)
     .setTaskMapper((value) => {
         // async stuffs...
     }) // -> Used to tranform 'tasks' passed in `run` method
     .onTaskDone((_, index, nbTasks) => console.log(Math.round((index + 1) / nbTasks * 100)), '%');
const results = await pool.run([
     {ref: 'foo'},
     {ref: 'fuu'},
     {ref: 'bar'},
     {ref: 'baz'},
]);
/////////////////////////////////////////////////
const pool = new PromisePool(1);
(async function fn1() {
     const result = await pool.run(asyncFn);
})();
(async function fn2() {
     const result = await pool.run(asyncFn); // -> Won't be triggered before fn1 run ends
})();

Constructors

constructor

Methods

Constructors

constructor

• new PromisePool(concurrency?)

Parameters

Name	Type	Default value	Description
`concurrency`	`number`	`5`	Must be between 0 (paused) and Infinity (no limit). Default is 5.

Defined in

promise/pool/pool.ts:45

Methods

onTaskDone

▸ onTaskDone<T>(callback): PromisePool

Registers a function to be called a tasks is finished.

Type parameters

Name
`T`

Parameters

Name	Type
`callback`	`OnTaskDoneCallback`<`T`>

Returns

PromisePool

Defined in

promise/pool/pool.ts:170

pause

▸ pause(): PromisePool

Stops processing tasks by setting concurrency to 0.

Returns

PromisePool

Defined in

promise/pool/pool.ts:136

resume

▸ resume(): PromisePool

Resumes tasks processing by setting concurrency to its previous value.

Returns

PromisePool

Defined in

promise/pool/pool.ts:145

run

▸ run<T>(tasks): Promise<T>

Runs provided tasks according to PromisePool instance settings.
tasks can be an array or a single job, and each of them can be a function or any other type.
If an array is provided, an array of results will be returned.
Otherwise, the result of the single task will be returned.

Type parameters

Name
`T`

Parameters

Name	Type
`tasks`	`any`

Returns

Promise<T>

Defined in

promise/pool/pool.ts:181

setConcurrency

▸ setConcurrency(concurrency): PromisePool

Sets concurrency with the provided number.
Must be between 0 (paused) and Infinity (no limit). Default is 5.

Parameters

Name	Type
`concurrency`	`number`

Returns

PromisePool

Defined in

promise/pool/pool.ts:127

setTaskFilter

▸ setTaskFilter<T>(predicate): PromisePool

A function that will be called on each task.
A task is removed if the callback return value is falsy.

Type parameters

Name
`T`

Parameters

Name	Type
`predicate`	`TaskFilterPredicate`<`T`>

Returns

PromisePool

Defined in

promise/pool/pool.ts:154

setTaskMapper

▸ setTaskMapper<T>(callback): PromisePool

Set a mapper function that will be called on each task. Each of them will be tranformed according to the callback return value.

Type parameters

Name
`T`

Parameters

Name	Type
`callback`	`TaskMapperCallback`<`T`>

Returns

PromisePool

Defined in

promise/pool/pool.ts:162

Time

sleep

▸ sleep(milliseconds?): Promise<number>

Returns a promise resolving after given number of milliseconds.
Promise resolves to this number of milliseconds.

Parameters

Name	Type	Default value
`milliseconds`	`number`	`0`

Returns

Promise<number>

Example

await sleep(1000); // returns 1000 after 1000 milliseconds

Defined in

time/sleep/sleep.ts:8

withTime

▸ withTime<T>(fn): ReturnType<T> extends Promise<infer R> ? Promise<[R, number]> : [ReturnType<T>, number]

Returns a tuple containing the return value of input fn function (or the resolved value of its returned promise) and the time (in milliseconds) it took to complete

Type parameters

Name	Type
`T`	extends (...`args`: `any`[]) => `any`

Parameters

Name	Type
`fn`	`T`

Returns

ReturnType<T> extends Promise<infer R> ? Promise<[R, number]> : [ReturnType<T>, number]

Example

const [value, time] = withTime(() => 'foo'); // -> ['foo', 1]
const myAsyncFn = async () => {
     await new Promise((res) => setTimeout(res, 3000));
     return 'bar';
};
const [value, time] = await withTime(myAsyncFn); // -> ['bar', 3007]

Defined in

time/with-time/with-time.ts:11

js-resources

JS-RESOURCES

Table of contents

Array

arrayAverage

Type parameters

Parameters

Returns

Defined in

arrayChunk

Type parameters

Parameters

Returns

Defined in

arrayGroup

Type parameters

Parameters

Returns

Defined in

arrayLast

Type parameters

Parameters

Returns

Defined in

arrayMax

Type parameters

Parameters

Returns

Defined in

arrayMin

Type parameters

Parameters

Returns

Defined in

arrayRandomPick

Type parameters

Parameters

Returns

Defined in

arrayShuffle

Type parameters

Parameters

Returns

Defined in

arraySortAlpha

Type parameters

Parameters

Returns

Defined in

arraySortNum

Type parameters

Parameters

Returns

Defined in

arraySum

Type parameters

Parameters

Returns

Defined in

arrayUniq

Type parameters

Parameters

Returns

Defined in

asArray

Type parameters

Parameters

Returns

Defined in

range

Parameters

Returns

Defined in

Parameters

Returns

Defined in

Parameters

Returns

Defined in

Boolean