@thalesrc/js-utils

Javascript utility functions for web development


Motivation

Collecting commonly used utility functions in a package.

Goals

* Typescript support
* Tree-shaking
* No dependencies
* High performance
* Documentation
* High test coverage
* Static/Prototype method support

Installation

* npm: npm install @thalesrc/js-utils --save
* yarn: yarn add @thalesrc/js-utils
* pnpm: pnpm i -S @thalesrc/js-utils

Documentation

See: thalesrc.github.io/js-utils

Functions

$3

#### Async Map
Maps an array asynchronously

``typescript
import { asyncMap } "@thalesrc/js-utils/array";

const array = [1, 2, 3];

const result = await asyncMap(array, async value => {
return await addOneAfterASecond(value);
});

console.log(result); // [2, 3, 4]
`

#### Compact
Filters falsy values of an array

`typescript
import { compact } from "@thalesrc/js-utils/array";

const arr = [undefined, "", false, 0, 1, "1", null];
const compacted = compact(arr); // [1, "1"];
`

#### Difference
Gets the difference of the two arrays or sets

`typescript
import { difference } from "@thalesrc/js-utils/array";

const base = ["a", "b", "c", "d", "a", "b", "c", "d"];

difference(base, ["a", "b"]); // ["c", "d", "c", "d"]
difference(base, ["a", "b"], true); // ["c", "d", "a", "b", "c", "d"]
`

#### Find By Key
Finds an object in an array by matching the value set on the key

`typescript
import { findByKey } from "@thalesrc/js-utils/array";

const array = [{a: 1}, {a: 2}, {a: 3}];

findByKey(array, "a", 2); // {a: 2}
`

#### Intersection
Gets the intersection of the two arrays or sets

`typescript
import { intersection } from "@thalesrc/js-utils/array";

const base = ["a", "b", "c", "d", "a", "b", "c", "d"];

intersection(base, ["a", "b", "x"]); // ["a", "b", "a", "b"]
intersection(base, ["a", "b", "x"], false); // ["a", "b"]
`

#### Limit
Returns first n children of an array

`typescript
import { limit } from "@thalesrc/js-utils/array";

const array = ["a", "b", "c", "d", "e", "f"];

limit(array, 3); // ["a", "b", "c"]
`

#### Remove
Removes an item from an array

`typescript
import { remove } from "@thalesrc/js-utils/array";

const array = ["a", "b", "c", "a", "b", "c"];

remove(array, "b"); // ["a", "c", "a", "b", "c"]
remove(array, "b", true); // ["a", "c", "a", "c"]
`

#### Replace
Replaces an item with passed one of an array

`typescript
import { replace } from "@thalesrc/js-utils/array";

const array = ["a", "b", "c", "a", "b", "c"];

replace(array, "b", "x"); // ["a", "x", "c", "a", "b", "c"]
replace(array, {startingIndex: 3, deleteCount: 1, itemsToReplace: ['x', 'y']}); // ["a", "b", "c", "x", "y", "b", "c"];

const config = new Map();
config.set("a", "x")
config.set("b", "y");

replace(array, {itemsToReplace: config}); // ["x", "y", "c", "a", "b", "c"];
replace(array, {itemsToReplace: config, multi: true}); // ["x", "y", "c", "x", "y", "c"];
`

#### Uniquify
Removes repeated items from the array

`typescript
import { uniquify } "@thalesrc/js-utils/array";

const array = ["a", "b", "c", "a", "b", "c"];

uniquify(array); // ["a", "b", "c"]
`

#### Uniquify By Key
Removes objects from the array which the value of its specifed key included before by another

`typescript
import { uniquifyByKey } "@thalesrc/js-utils/array";

const array = [{a: 1}, {a: 1}, {a: 2}, {a: 3}, {a: 3}, {a: 4}];

uniquifyByKey(array, 'a'); // [{a: 1}, {a: 2}, {a: 3}, {a: 4}]
`

$3

#### Mixin
Creates a class that combines two classes using the mixin pattern

`typescript
import { mixin } from "@thalesrc/js-utils/class";

class Timestamped {
timestamp = Date.now();
getAge() {
return Date.now() - this.timestamp;
}
}

class User {
constructor(public name: string) {}
greet() {
return Hello, ${this.name};
}
}

class TimestampedUser extends mixin(User, Timestamped) {}

const user = new TimestampedUser(['John'], []);
console.log(user.greet()); // "Hello, John"
console.log(user.getAge()); // Time since creation
`

$3

#### Debounce
Debounces a function that delays invoking until after configured time have elapsed since the last time the debounced function was invoked

`typescript
import { debounce } from "@thalesrc/js-utils/promise";

function foo() {
console.log("hello");
}

for (let i = 0; i < 10; i++) {
debounce(foo);
}

// logs "hello" only once
`

#### Defer
Delays the execution of the passed function

`typescript
import { defer } from "@thalesrc/js-utils/function";

const result = await defer(() => aFunctionToDeferThatReturnsHello());

console.log(result); // 'hello'
`

#### Noop
Noop function

`typescript
import { noop } from "@thalesrc/js-utils/function";

noop();
`

#### Of
Creates a function which returns the specified value

`typescript
import { of } from "@thalesrc/js-utils/function";

const base = [1, 2, 5, {}, "x", "y"];

base.map(of('hi')); // ["hi", "hi", "hi", "hi", "hi", "hi"]
`

$3

#### Merge
Merges two maps

`typescript
import { merge } from "@thalesrc/js-utils/map";

const first = new Map();
first.set("a", 1);

const second = new Map();
second.set("b", 2);
merge(first, second); // [{key: "a", value: 1}, {key: "b", value: 2}]
`

$3

#### Min-Max
Limits the value by specified range

`typescript
import { minMax } from "@thalesrc/js-utils/math";

const limitedValue = minMax(200, 300, Math.random() * 1000); // Outputs between 200-300
`

$3

#### Clone
A function to deep clone anything (recursively)

`typescript
import { clone } from "@thalesrc/js-utils/object";

const object = {a: 1, b: {c: true, d: ["x", "y"]}};

const clonedObject = clone(object);
// {a: 1, b: {c: true, d: ["x", "y"]}}
// object.b.d === clonedObject.b.d // false
`

#### Compact
Removes null and undefined values and their keys from an object

`typescript
import { compact } from "@thalesrc/js-utils/object";

const a = {
x: null,
y: undefined,
z: 20
};

compact(a); // {z: 20}
`

#### Deepest
Get deepest value in an object chain

`typescript
import { deepest } from "@thalesrc/js-utils/object";

const a = {x: null};
const b = {x: a};
const c = {x: b};

deepest(c, 'x'); // {x: null} (a)
`

$3

#### Chain
Chains promises in a sequential order

`typescript
import { chain } from '@thalesrc/js-utils/promise';

const lastResult = await chain([() => getUserDetails(), ({photoUrl}) => getUserPhoto(photoUrl)]);
`

#### Never
A promise which never resolves

`typescript
import { never, NEVER } from '@thalesrc/js-utils/promise';

function foo(promise = never()) {
promise.then(val => {
...
});
}

// or

function foo(promise = NEVER) {
promise.then(val => {
...
});
}
`

#### Revert
Exchanges resolve state with rejection of a promise

`typescript
import { revert } from "@thalesrc/js-utils/promise";

const errorPromise = Promise.reject(new Error('foo'));

revert(errorPromise)
.then(err => {
console.log("this will be logged", err);
})
.catch(res => {
console.log("this won't be logged", res);
});
`

#### Timeout
Returns a promise which resolves after specified time

`typescript
import { timeout } from "@thalesrc/js-utils/promise";

timeout(1000)
.then(() => console.log("will be logged after a second"));
`

#### Try Catch
Merges result and error in the same callback

`typescript
import { tryCatch } from "@thalesrc/js-utils/promise";

const promise = anAsyncCall();

const [error, result] = await tryCatch(promise);
`

#### Try One By One
Tries a set of promises one by one with given order. Breaks the call when a promise resolved. Otherwise keeps trying incoming promises until the list is finished.

`typescript
import { tryOneByOne } from "@thalesrc/js-utils/promise";

async function fooFunction() {
const foo = await tryOneByOne([
() => someCall(),
(err) => anotherCall(),
(err) => fooPromise()
]);

// do stuff
}
`

$3

#### Limit
Limits the string to n character

`typescript
import { limit } from "@thalesrc/js-utils/string";

const str = 'foobarbaz';

limit(str, 3); // 'foo'
`

$3

#### Arrayize
Encapsulates a non array value with an array that contains it unless the value is already an array

`typescript
import { arrayize } from "@thalesrc/js-utils";

const foo = 'foo';
const bar = ['bar'];
const fooArr = arrayize(foo); // ['foo'];
const barArr = arrayize(bar); // ['bar'];
`

#### Compact
Filters falsy values of the given array
Removes null and undefined values and their keys from an object

`typescript
import { compact } from "@thalesrc/js-utils";

const arr = [undefined, "", false, 0, 1, "1"];
const compacted = compact(arr); // [1, "1"];

const object = {
x: null,
y: undefined,
z: 20
};

const compacted = compact(object); // {z: 20}
`

#### Is Falsy
Returns whether the entered value is falsy

`typescript
import { isFalsy } from "@thalesrc/js-utils";

isFalsy(undefined); // true
isFalsy(true); // false
`

#### Is Truthy
Returns whether the entered value is truthy

`typescript
import { isTruthy } from "@thalesrc/js-utils";

isTruthy(undefined); // false
isTruthy(true); // true
`

#### Limit
Limits the string or array to n character

`typescript
import { limit } from "@thalesrc/js-utils";

const str = 'foobarbaz';
const array = ["a", "b", "c", "d", "e", "f"];

limit(str, 3); // 'foo'
limit(array, 3); // ["a", "b", "c"]
`

#### Open Promise
A promise constructor to resolve or reject from outside

`typescript
import { OpenPromise } from "@thalesrc/js-utils";

const aPromiseWillBeResolvedLater = new OpenPromise();

aPromiseWillBeResolvedLater.then(val => console.log(val));

aPromiseWillBeResolvedLater.resolve({x: 1});
// logs {x: 1}
`

#### Smart Map
Like WeakMap but can also store values using primitive keys

See: WeakMap

`typescript
import { SmartMap } from "@thalesrc/js-utils";

const aMap = new SmartMap();

aMap.set("foo", "foo");
aMap.set(1, "thales rocks");
console.log(aMap.size) // 2

aMap.set({}, "thales rocks again");
console.log(aMap.size) // 2

const anObject = {};
aMap.set(anObject, "thales rocks again and again");
console.log(aMap.size) // 3
console.log(aMap.get(anObject)) // "thales rocks again and again"
`

#### Unique Id
Starts a new counter for every unique prefix and if a prefix is given, returns the id by prefixing it, otherwise returns the id as number

`typescript
import { uniqueId } from "@thalesrc/js-utils";

uniqueId(); // 0
uniqueId(); // 1
uniqueId("some-str"); // "some-str-0";
uniqueId("some-str"); // "some-str-1";
uniqueId(); // 3
`

Static/Prototype Methods

You may use any of these methods by adding them to the constructors or prototypes to native objects in main file.

Prototype Example:

`typescript
// main.ts
import "@thalesrc/js-utils/array/proto/compact";

// somewhere else
const arr = [undefined, "", false, 0, 1, "1", null];
const compacted = arr.compact(); // [1, "1"];

`

Static Example:

`typescript
// main.ts
import "@thalesrc/js-utils/promise/static/timeout";

// somewhere else
Promise.timeout(1000)
.then(() => console.log("will be logged after a second"));
``

License

MIT