@ack_inc/utils

node-utils

A collection of utility functions I find myself needing across multiple projects

Functions can be required individually like so: const fn = require('@ack_inc/utils/lib/<fn-name-in-kebab-case>')

Docs

generateRandomString(nChars, constraints)

Generates a string of length nChars that satisfies constraints

Use case: password or temporary token generation

Parameters

Name	Type	Required?	Description	Default	Comments
nChars	number	Y	The length of the string to generate		Must be a whole number.
constraints	object	N	Object specifying what characters can be in the generated string.	{}

constraints may have the following keys:

Key	Type	Effect
lowercase	Boolean	If true, include lowercase characters
uppercase	Boolean	If true, include uppercase chracters
digits	Boolean	If true, include digits
symbols	Boolean	If true, include symbols

If constraints has none of the above keys, it is assumed that all characters are allowed

Look in lib/generate-random-string.js for the full list of symbols used

Return value

Type	Description
string	The random string

Usage

const { generateRandomString: rsg } = require('@ack_inc/utils');
console.log(rsg(<anything but a whole number>)); //=> throws TypeError
console.log(rsg(0)); //=> ""
console.log(rsg(5)); //=> "3`8aE"
console.log(rsg(5, { lowercase: true })); //=> "fewjk"
console.log(rsg(5, { lowercase: true, uppercase: true, digits: true, symbols: true })); //=> "%q31G"

---

groupByMultiKeys(records, getKeys)

Group an array of records into an array of sub-arrays of records. Records go into the same sub-array ("group") if any of the keys generated by getKeys are === equal

Use case: you have an array of records (of people, say); the records are from multiple sources, and you want to merge records (for belonging to the same person) if any of several different "identifiers" (email, phone number, social media handle, etc.) match

Parameters

Name	Type	Required?	Description	Default	Comments
records	Array<object>	Y	Array of records to group		A TypeError is thrown if records is not an array with at least one element
getKeys	Function	Y	Function to generate keys for each record		Should take a record as the sole param, and return a single key or array of keys; signature is getKeys(record: object): Array<T>

Return value

Type	Description
Array<Array<object>>	Each element of the returned array is a group of records for which at least one key matched

It may not be the case that there is a common key for all the records in a group. Further, there may be two records in a group that have no keys in common. For example, the following three records will be in the same group, through A and C do not have a common key, because they each have a key in common with another record in the group:

• Record A with keys ['a', 'b']
• Record B with keys ['b', 'c']
• Record C with keys ['c', 'd']

Usage

See the tests in lib/group-by-multi-keys.test.js for usage examples

---

formatMobileNumber(mobileNumber, formatString)

Format a mobile number (must include country code) in different ways

Parameters

Name	Type	Required?	Description	Default	Comments
mobileNumber	string	Y	The mobile number to be formatted		An error is thrown if mobileNumber does not contain country code
formatString	string	N	String describing how the provided mobile number should be formatted	"+CASR"

In formatString, only the following characters will be transformed:

Character	Transformed into
C	country code
A	area code (first 3 digits after country code)
S	subscriber number (next 3 digits)
R	remaining digits

Any other characters will appear as-is in the returned string

Return value

Type	Description
string	The formatted mobile number

Usage

const { formatMobileNumber: format } = require('@ack_inc/utils');
console.log(format(<anything but a mobile number with country code>)); //=> throws Error

const mobile = "[phone]";
expect(format(mobile)).toEqual("[phone]");
expect(format(mobile, "+CASR")).toEqual("[phone]");
expect(format(mobile, "+C A S R")).toEqual("[phone]");
expect(format(mobile, "+C (A) S-R")).toEqual("[phone]");

---

buildArr(n, generatorFn)

Format a mobile number (must include country code) in different ways

Parameters

Name	Type	Required?	Description	Default	Comments
n	number	Y	The number of elements in the created array
generatorFn	function	N	Function that controls the values of the elements in the created array	x => x

Return value

Type	Description
array	The built array

Usage

const { buildArr } = require('@ack_inc/utils');

expect(buildArr(0)).toEqual([]);
expect(buildArr(2)).toEqual([0, 1]);
expect(buildArr(2, idx => idx + 1)).toEqual([1, 2]);

---

groupBy(records, groupFn)

Group records according to groupFn

Parameters

Name	Type	Required?	Description	Default	Comments
records	Array<record>	Y	The records to be grouped
groupFn	function	N	Function that determines whether two records belong in the same group	(a, b) => false

A record is any object with an id key

Return value

Type	Description
Array<Array<record>>	Each sub-array in the returned array is one group

Usage

• See group-by.test.js

To Do

• Automated documentation generation

• Improve generateRandomString

  • Constraint: whitelisted chars
  • Constraint: blacklisted chars
  • Constraint: symbols that can be part of a url-component (See SO answer)