js-toolbox

Useful JavaScript utilities (with TypeScript typings).

1$ npm i @xcmats/js-toolbox

Works in node.js and browser environments (use webpack or Rollup to bundle it with your project).

index

• documentation
• play in your browser
• use the package
  • install
  • play in node.js
  • example use in ES6 modules code
• use the source
• namespaces
  • array
  • async
  • codec
  • func
  • math
  • string
  • struct
  • type
  • utils
• examples
  • array manipulation
  • asynchronous programming
  • base64 encoding and decoding
  • hex encoding and decoding
  • byte array manipulation
  • functional programming
  • simple math
  • operating on strings
  • data structure manipulation
  • type primitives
• notes
• license

documentation

API Reference

play in your browser

RunKit with @xcmats/js-toolbox

• list member functions (link):

  1var jsToolbox = require("@xcmats/js-toolbox")
  2
  3Object.keys(jsToolbox).sort()

  1[ "Y",
  2  "access",
  3  "add",
  4  "ap",
  5  "app",
  6  "array",
  7  "arrayDifference",
  8  "arrayIntersection",
  9  "arrayIsSubset",
  10  "arraySetEqual",
  11  "asciiLetters",
  12  "asciiLowercase",
  13  "asciiUppercase",
  14  "assign",
  15  "async",
  16  "asyncMap",
  17  "asyncRace",
  18  "asyncReduce",
  19  "asyncRepeat",
  20  "average",
  21  "b64ToHex",
  22  ... ]

• play with shuffle and range (link):

  1jsToolbox.shuffle(jsToolbox.range(16))

  1[ 14, 12, 15, 8, 13, 4, 5, 6, 1, 7, 10, 0, 2, 3, 9, 11 ]

• do all other things shown in examples section below

use the package

install

1$ mkdir playground
2$ cd playground/
3$ npm init
4...
5$ npm i @xcmats/js-toolbox
6...

play in node.js

1$ node
2>

1t = require("@xcmats/js-toolbox")

1{ ...
2array:
3 { ... },
4...
5utils:
6 { ... } }

example use in ES6 modules code

1import { range } from "@xcmats/js-toolbox/array";
2import { stringToB64 } from "@xcmats/js-toolbox/codec";
3import { flow } from "@xcmats/js-toolbox/func";
4import { random } from "@xcmats/js-toolbox/string";
5
6const b64stringify = flow(
7    JSON.stringify,
8    stringToB64,
9);
10
11let spam = b64stringify({
12    tenNumbers: range(10),
13    randomLetters: random(20),
14});
15
16console.log("Stringified and b64-encoded object: ", spam);

use the source

1$ git clone git@github.com:drmats/js-toolbox.git
2Cloning into 'js-toolbox'...
3$ cd js-toolbox
4$ npm i
5$ npm start
6Copying type declarations and module configs ...
7OK.
8Generating type declarations from .ts files.
9Compiling for 'commonjs' ...
10Successfully compiled 47 files with Babel (1709ms).
11>

namespaces

If you're experimenting via RunKit then prepend all namespaces with "jsToolbox." and if you're experimenting inside node.js console with npm package (as described above) then prepend all namespaces with "t.". If you're using the source and have launched node.js session via npm start then you're good to go ( ¯\_(ツ)_/¯ ).

array utilities

1array

1{ append: [Function: append],
2  countBy: [Function: countBy],
3  difference: [Function: difference],
4  draw: [Function: draw],
5  drop: [Function: drop],
6  dropLast: [Function: dropLast],
7  findDuplicates: [Function: findDuplicates],
8  flatten: [Function: flatten],
9  head: [Function: head],
10  init: [Function: init],
11  intersection: [Function: intersection],
12  isContinuous: [Function: isContinuous],
13  isSorted: [Function: isSorted],
14  isSubset: [Function: isSubset],
15  last: [Function: last],
16  range: [Function: range],
17  removeDuplicates: [Function],
18  setEqual: [Function: setEqual],
19  shuffle: [Function: shuffle],
20  sparse: [Function: sparse],
21  tail: [Function: tail],
22  take: [Function: take],
23  takeEvery: [Function: takeEvery],
24  takeLast: [Function: takeLast],
25  zipWith: [Function: zipWith],
26  zip: [Function] }

asynchronous programming helpers

1async

1{ ap: [Function ap],
2  bind: [Function bind],
3  cancellable: [Function: cancellable],
4  createMutex: [Function: createMutex],
5  createTimedBarrier: [Function: createTimedBarrier],
6  delay: [Function: delay],
7  interval: [Function: interval],
8  liftr: [Function: liftr],
9  map: [Function: map],
10  parMap: [Function: parMap],
11  promisePool: [Function: promisePool],
12  race: [Function: race],
13  rbind: [Function: rbind],
14  reduce: [Function: reduce],
15  repeat: [Function: repeat],
16  timeout: [Function: timeout],
17  unit: [Function: unit] }

TypedArray coders/decoders

1codec

1{ concatBytes: [Function: concatBytes],
2  compareBytes: [Function: compareBytes],
3  stringToBytes: [Function],
4  bytesToString: [Function],
5  csv: [Function],
6  hexToBytes: [Function: hexToBytes],
7  bytesToHex: [Function: bytesToHex],
8  b64dec: [Function],
9  b64enc: [Function],
10  b64ToString: [Function],
11  stringToB64: [Function],
12  b64ToHex: [Function],
13  hexToB64: [Function],
14  random: [AsyncFunction],
15  timestamp: [Function: timestamp] }

functional programming tools

1func

1{ app: [Function: app],
2  choose: [Function: choose],
3  compose: [Function: compose],
4  curry: [Function: curry],
5  curryN: [Function: curryN],
6  curryThunk: [Function: curryThunk],
7  flow: [Function: flow],
8  handleException: [Function: handleException],
9  identity: [Function: identity],
10  lazyish: [Function: lazyish],
11  locker: [Function: locker],
12  local: [Function: local],
13  partial: [Function: partial],
14  pipe: [Function: pipe],
15  rearg: [Function: rearg],
16  Y: [Function: Y] }

basic math

1math

1{ add: [Function],
2  average: [Function: average],
3  clamp: [Function: clamp],
4  dec: [Function],
5  degrees: [Function],
6  div: [Function],
7  inc: [Function],
8  interpolate: [Function],
9  inv: [Function],
10  log10: [Function: log10],
11  log2: [Function: log2],
12  mod: [Function],
13  mul: [Function],
14  neg: [Function],
15  pow: [Function],
16  product: [Function: product],
17  radians: [Function],
18  randomInt: [Function: randomInt],
19  remainder: [Function],
20  roundIfClose: [Function: roundIfClose],
21  sub: [Function],
22  sum: [Function: sum] }

option monad

1option

1{ bind: [Function: bind],
2  hasValue: [Function: hasValue],
3  JUST: [Function: JUST],
4  NOTHING: { [Symbol(__maybe)]: false },
5  optionalize: [Function: optionalize],
6  rbind: [Function: rbind] }

string utilities

1string

1{ asciiLetters: [Function: asciiLetters],
2  asciiLowercase: [Function: asciiLowercase],
3  asciiUppercase: [Function: asciiUppercase],
4  big: [Function],
5  camelToPascal: [Function: camelToPascal],
6  camelToSnake: [Function: camelToSnake],
7  capitalize: [Function: capitalize],
8  digits: [Function: digits],
9  ellipsis: { [Function: ellipsis] BEGIN: 0, MIDDLE: 1, END: 2 },
10  empty: [Function: empty],
11  space: [Function: space],
12  nl: [Function: nl],
13  tab: [Function: tab],
14  padLeft: [Function: padLeft],
15  padRight: [Function: padRight],
16  pascalToCamel: [Function: pascalToCamel],
17  pascalToSnake: [Function: pascalToSnake],
18  quote: [Function: quote],
19  random: [Function: random],
20  shorten: { [Function: shorten] BEGIN: 0, MIDDLE: 1, END: 2 },
21  snakeToCamel: [Function: snakeToCamel],
22  snakeToPascal: [Function: snakeToPascal],
23  wrap: [Function: wrap] }

data structure manipulation tools

1struct

1{ access: [Function: access],
2  assign: [Function: assign],
3  clone: [Function],
4  hashAccessor: [Function: hashAccessor],
5  keyAccessor: [Function: keyAccessor],
6  dfs: [Function: dfs],
7  dict: [Function: dict],
8  isBasicData: [Function: isBasicData],
9  isBasicDataOrUndefined: [Function: isBasicDataOrUndefined],
10  objectMap: [Function: objectMap],
11  objectReduce: [Function: objectReduce],
12  rewrite: [Function: rewrite],
13  swap: [Function: swap] }

type helpers

1type

1{ isArray: [Function: isArray],
2  isBoolean: [Function: isBoolean],
3  isDate: [Function: isDate],
4  isFunction: [Function: isFunction],
5  isNumber: [Function: isNumber],
6  isObject: [Function: isObject],
7  isRegExp: [Function: isRegExp],
8  isString: [Function: isString],
9  lazyNullishCoalesce: [Function: lazyNullishCoalesce],
10  maxInt: 9007199254740991,
11  minInt: -9007199254740991,
12  nullToUndefined: [Function: nullToUndefined],
13  toBool: [Function: toBool],
14  undefinedToNull: [Function: undefinedToNull] }

uncategorized utilities

1utils

1{ btquote: [Function: btquote],
2  devEnv: [Function: devEnv],
3  getLibConfig: [Function: getLibConfig],
4  getProcess: [Function: getProcess],
5  isBrowser: [Function: isBrowser],
6  rgb: [Function: rgb],
7  rgba: [Function: rgba],
8  run: [Function: run],
9  timing: [Function: timing],
10  timeUnit: { ... },
11  to_: [Function: to_],
12  url: [Function: url] }

examples

array manipulation

• Find the lenghts of the words in a given sentence and count how many of them exists in each length group.

  1array.countBy(
  2    'exemplo plus quam ratione vivimus'.split(' '),
  3    w => w.length,
  4);

  1{ '4': 2, '7': 3 }

• Choose a random element from a given array (or a random character from a given string).

  1array.draw(string.asciiLetters());

  1'S'

• Find duplicates in a given array.

  1array.findDuplicates(['one', 'two', 'one', 'six', 'two', 'two']);

  1[ 'one', 'two' ]

• Flatten passed array, i.e. transform [[1, 2,], ..., [3, 4,],] to [1, 2, ..., 3, 4,].

  1array.flatten(Object.entries({ a: 'b', c: 'd', e: 'f' }));

  1[ 'a', 'b', 'c', 'd', 'e', 'f' ]

• Return a list containing an arithmetic progression. range(i, j) returns [i, i+1, i+2, ..., j-1]. Possible invocations are: range(stop), range(start, stop), range(start, stop, step). When start is omitted it defaults to 0. When step is given, it specifies the increment (or decrement).

  1array.range(10);

  1[ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]

  1array.range(-128, -256, -16);

  1[ -128, -144, -160, -176, -192, -208, -224, -240 ]

• Randomly shuffle all elements in the given array (Durstenfeld's modification to the Fisher-Yates shuffle algorithm). The operation is taken in-place.

  1array.shuffle(array.range(12));

  1[ 9, 7, 0, 8, 2, 10, 3, 1, 11, 4, 5, 6 ]

• Generate sparse array of distinct integers. sparse(stop, size) returns array of size distinct integers in range [0..stop-1]. sparse(start, stop, size) returns array of size distinct integers in range [start..stop-1].

  1array.sparse(1024, 8);

  1[ 6, 34, 170, 422, 530, 643, 855, 862 ]

• "Zip" given arrays using provided f operator.

  1array.zipWith((a, b) => a + b) ([1, 2, 3, 4], [10, 20, 30, 40]);

  1[ 11, 22, 33, 44 ]

• Take every 3rd element from a given array.

  1array.takeEvery(3) ([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);

  1[0, 3, 6, 9]

asynchronous programming

• Delay current async execution by time miliseconds.

  1(async () => {
  2    await async.delay();
  3    console.log('Hello ...');
  4    await async.delay();
  5    console.log('... world');
  6}) ();

  1Promise { <pending> }
  2Hello ...
  3... world

• Invoke a sequence of asynchronous operations on an array of elements.

  1(async () => {
  2    let x = await async.map(
  3        array.range(10),
  4        (x) => async.timeout(() => {
  5            console.log(4*x);
  6            return 4*x;
  7        }, array.head(array.sparse(1000, 1))),
  8    );
  9    console.log(`Result: ${x}`);
  10}) ();

  1Promise { <pending> }
  20
  34
  48
  512
  616
  720
  824
  928
  1032
  1136
  12Result: 0,4,8,12,16,20,24,28,32,36

• Paralelly execute operation on each element of the array.

  1(async () => {
  2    let x = await async.parMap(
  3        array.range(10),
  4        (x) => async.timeout(() => {
  5            console.log(4*x);
  6            return 4*x;
  7        }, array.head(array.sparse(1000, 1))),
  8    );
  9    console.log(`Result: ${x}`);
  10}) ()

  1Promise { <pending> }
  224
  38
  416
  512
  628
  720
  80
  936
  1032
  114
  12Result: 0,4,8,12,16,20,24,28,32,36

• Accumulate value over an array of elements using asynchronous operation.

  1(async () => {
  2    let x = await async.reduce(
  3        array.range(10),
  4        (acc, x) => async.timeout(() => {
  5            console.log(acc+x);
  6            return acc+x;
  7        }, 100*x),
  8    );
  9    console.log(`Accumulated value: ${x}`);
  10}) ()

  1Promise { <pending> }
  20
  31
  43
  56
  610
  715
  821
  928
  1036
  1145
  12Accumulated value: 45

base64 encoding and decoding

• Convert UTF-8 string into an array of bytes.

  1codec.stringToBytes('Koń: 🐎');

  1Uint8Array [ 75, 111, 197, 132, 58, 32, 240, 159, 144, 142 ]

• Convert array of bytes into a UTF-8 string.

  1data = Uint8Array.from([70, 111, 120, 58, 32, 240, 159, 166, 138]);

  1Uint8Array [ 70, 111, 120, 58, 32, 240, 159, 166, 138 ]

  1codec.bytesToString(data);

  1'Fox: 🦊'

• Encode given byte array to Base64. Base64 encoding in browser and node.js.

  1data = Uint8Array.from([240, 159, 142, 169, 240, 159, 144, 176]);

  1Uint8Array [ 240, 159, 142, 169, 240, 159, 144, 176 ]

  1codec.b64enc(data);

  1'8J+OqfCfkLA='

• Decode given Base64 string to byte array. Base64 decoding in browser and node.js.

  1data = codec.b64dec('8J+OqfCfkLA=');

  1Uint8Array [ 240, 159, 142, 169, 240, 159, 144, 176 ]

  1codec.bytesToString(data);

  1'🎩🐰'

hex encoding and decoding

• Convert hex-encoded string to a byte representation.

  1codec.hexToBytes('cabafa87');

  1Uint8Array [ 202, 186, 250, 135 ]

  1codec.hexToBytes('0x1234567890ABCDEF');

  1Uint8Array [ 18, 52, 86, 120, 144, 171, 205, 239 ]

• Convert byte representation to a hex-encoded string.

  1codec.bytesToHex(Uint8Array.from([31, 63, 127, 255]));

  1'1f3f7fff'

byte array manipulation

• Concatenate contents of a given byte arrays.

  1codec.concatBytes(
  2    Uint8Array.from([255, 255, 0, 0]),
  3    codec.stringToBytes('🌍'),
  4    Uint8Array.from([128, 64]),
  5);

  1Uint8Array [ 255, 255, 0, 0, 240, 159, 140, 141, 128, 64 ]

• Compare two byte arrays.

  1codec.compareBytes(
  2    codec.stringToBytes('𝓬𝓸𝓭𝓮'.normalize('NFC')),
  3    codec.stringToBytes('𝐜𝐨𝐝𝐞'.normalize('NFC')),
  4);

  1false

  1codec.compareBytes(codec.hexToBytes('0xFF'), Uint8Array.from([255]));

  1true

functional programming

• Function composition.

  1func.compose(
  2    string.quote,
  3    string.shorten,
  4) (
  5    "When I find myself in times of trouble",
  6    20, string.shorten.END,
  7);

  1'"When I find myself …"'

  1stringToHex = func.flow(codec.stringToBytes, codec.bytesToHex);

  1[Function]

  1stringToHex('Kaboom! 💥');

  1'4b61626f6f6d2120f09f92a5'

  1func.pipe('4b61626f6f6d2120f09f92a5') (
  2    codec.hexToBytes, codec.bytesToString
  3);

  1'Kaboom! 💥'

• Translate the evaluation of function f taking multiple arguments into an evaluation of sequence of functions, each with a single argument.

  1addition = (a, b, c) => a + b + c;

  1[Function: addition]

  1func.curry(addition) (1) (2) (3);

  16

• Function arguments rearrangement.

  1console.log('a', 'b', 'c', 'd', 'e');

  1a b c d e

  1revConsole = rearg(console.log) (4, 3, 2, 1, 0);
  2revConsole('a', 'b', 'c', 'd', 'e');

  1e d c b a

  1revConsole('f') ('g', 'h') ('i') ('j');

  1j i h g f

• Y-combinator - returns fixed point of a higher-order function passed as f. Anonymous recursion in Javascript.

  1factorial = func.Y((r) => (n) => n <= 0  ?  1  :  n * r(n - 1));

  1[Function]

  1factorial(5);

  1120

simple math

• Compute mathematical average of array of numbers.

  1math.average([1, 2, 3, 4, 5]);

  13

• Base 2 logarithm.

  1math.log2(2**32);

  132

• Base 10 logarithm.

  1math.log10(1e9);

  19

• Sum of numbers in passed array.

  1math.sum([5, 6, 7, 8, 9, 10]);

  145

operating on strings

• Allocate a big string (of size 2^n).

  1string.big(5);

  1'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

• Convert camelText to snake_text.

  1string.camelToSnake('someNightsIStayUpCashingInMyBadLuck');

  1'some_nights_i_stay_up_cashing_in_my_bad_luck'

• Quote text.

  1string.quote('div', '<>');

  1'<div>'

• Construct random string of desired length.

  1string.random(16);

  1'MxWGe8MoOss0yUAP'

• Shorten a given string to the desired length.

  1string.shorten('abcdefghijklmnopqrstuvwxyz', 15);

  1'abcdefg…tuvwxyz'

  1string.shorten(
  2    'To be, or not to be, that is the question',
  3    20,
  4    string.shorten.END,
  5);

  1'To be, or not to be…'

• Convert snake_text to camelText.

  1string.snakeToCamel('some_nights_i_call_it_a_draw');

  1'someNightsICallItADraw'

data structure manipulation

• Apply path to an object.

  1struct.access({ a: { b: { c: 42 } } }, ['a', 'b', 'c']);

  142

• Construct Object from the result of Object.entries() call. entries = [[k1, v1,], ..., [kn, vn,]]

  1struct.dict([['a', 'b'], ['c', 'd'], ['e', 'f']]);

  1{ a: 'b', c: 'd', e: 'f' }

• Shallow map (iteration) on objects.

  1struct.objectMap(
  2    { what: 'od', i: '?rof dnats' },
  3    ([k, v,]) => [
  4        string.capitalize(k),
  5        v.split('').reverse().join(''),
  6    ],
  7);

  1{ What: 'do', I: 'stand for?' }

• Swap keys with values in a given Object.

  1struct.swap({ a: 'b', c: 'd', e: 'f' });

  1{ b: 'a', d: 'c', f: 'e' }

type primitives

• Determine if a given value is a proper Number (not NaN and not Infinity).

  1[type.isNumber(NaN), type.isNumber(-Infinity), type.isNumber(1234.5678)]

  1[ false, false, true ]

• Determine if a given value is an Object (not null, not undefined and not Array).

  1[type.isObject(null), type.isObject([]), type.isObject({})]

  1[ false, false, true ]

notes

This library is suitable to use in server and browser environments and it is being used as such. Go ahead and file an issue or submit a fresh PR if you found a bug 🐞.

support

You can support this project via stellar network:

• Payment address: xcmats*keybase.io
• Stellar account ID: GBYUN4PMACWBJ2CXVX2KID3WQOONPKZX2UL4J6ODMIRFCYOB3Z3C44UZ

license

js-toolbox is released under the Apache License, Version 2.0. See the LICENSE for more details.