@rashedmakkouk/dev-utils

Dev Utils

Utility library.

v0.15.0

Notable changes in v0.15.0:

• Added decimal and precision options support to number type in random helper.
• Updated random usage instructions in README.md.
• Renamed toNumber option to parseNumber in toArray helper (Breaking change).
• Refactored date argument to accept empty value in timestamp, defaults to Now.
• Added keyExtractor helper usage instructions in README.md.
• Added abs support to math option in toNumeric.
• Added precision option in toNumeric.
• Added function @returns tag and description to all helpers.
• Code updates and enhancements.

Check out CHANGELOG.md for a full list of changes.

Installation

Install package in your project.

# NPM
npm install @rashedmakkouk/dev-utils

# Yarn
yarn add @rashedmakkouk/dev-utils

Usage

This package can be used in both the browser and Node.js projects.

Using ES6 module syntax

import { module } from '@rashedmakkouk/dev-utils';

module();

Using CommonJS syntax

const { module } = require('@rashedmakkouk/dev-utils');

module();

Methods

autolinks

Parses a text string and returns links matching:

• Hashtag #
• Mention @
• URL http

Builds on autolinker with custom configuration and output.

Parameters

Param	Type	Required	Default	Description
text	string	No	''	Text to parse.

Returns

• (Object.links): Array of unique words links (e.g. mention, hashtag, url).
• (Object.matches): Array of all matched links metadata.

Example

autolinks('The #quick brown @fox.');
// Result.
{
  links: [
    "#quick",
    "@fox"
  ],
  matches: [
    {
      "__jsduckDummyDocProp": null,
      matchedText: "#quick",
      offset: 4,
      tagBuilder: {
        newWindow: true,
        truncate: {
          length: null,
          location: "end"
        },
        className: ""
      },
      serviceName: "twitter",
      hashtag: "quick"
    },
    {
      "__jsduckDummyDocProp": null,
      matchedText: "@fox",
      offset: 17,
      tagBuilder: {
        newWindow: true,
        truncate: {
          length: null,
          location: "end"
        },
        className: ""
      },
      serviceName: "twitter",
      mention: "fox"
    }
  ]
}

delay (Promise)

Delays executions of a specified piece of code.

Parameters

Param	Type	Required	Default	Description
ms	number	Yes	-	Duration to delay in milliseconds.
race	boolean	No	false	If true, returns a Promise object that is rejected with status 408 Request Timeout.

Returns

• (Object): Returns Promise Object,.

Rejects

• (Object): Rejects { status: 408, statusCode: 408 }.

Example

try {
  await delay(1000, true);
} catch (error) {
  // Handle rejected Promise.
}

escape

Sanitizes and formats SQL input data for safe use in MySQL query statements.

A sqlstring wrapper for convenience.

Parameters

Param	Type	Required	Default	Description
value	Any	Yes	-	Data to escape.
options	object	No	-	Custom options to apply.
options.escapeId	boolean	No	false	Escapes Identifiers such as database table column names and reserved words.
options.parseInteger	boolean	No	false	Parses values such as LIMIT and OFFSET.
options.stripQuote	boolean	No	false	Removes quotes from result; useful for RegExp or query conditions e.g. ASC.

Returns

• (string): Returns escaped string.

Example

escape('abc', { stripQuote: true });
// Result.
abc

initials

Extracts the first character from the first and last words in a string.

Splits at: Splits at: white space, comma, dot, pipe, underscore, dash.

Parameters

Param	Type	Required	Default	Description
text	string	No	''	Text to extract characters from.

Returns

• (string): Returns extracted characters as string.

Example

initials('John Unknown-Doe');
// Result.
'JD'

isBase64

Validates if supplied mime type and/or base64 string are valid.

Parameters

Param	Type	Required	Default	Description
value	string	Yes	-	Base64 value.
options	object	No	-	Custom options to apply.
options.allowEmpty	boolean	No	false	Returns true if value is empty.
options.allowMime	boolean	No	false	String may include mime type.
options.mimeRequired	boolean	No	false	String should include mime type.
options.urlSafe	boolean	No	false	See Base64URL.

Returns

• (boolean): Returns 'true' if supplied string passes checks, else 'false'.

Example

isBase64('data:image/png;base64,<code>', { mimeRequired: true });
// Result.
true

isValid

Verifies if supplied payload is valid by defined type.

Parameters

Param	Type	Required	Default	Description
isTypeof	string	Yes	-	string, array, number, object, jsonStr.
value	Any	No	-	Data to validate.
options	object	No	-	Custom options to apply.
options.allowEmpty	boolean	No	false	If true, validates empty, null, undefined and 0 values as valid.

Returns

• (boolean): Returns true if supplied payload passes checks, else false.

Example

isValid('string', 'undefined');
// Result.
false

isValid('string', '', { allowEmpty: true });
// Result.
true

isValid('number', 'abc');
// Result.
false

isValid('number', '123');
// Result.
false

isValid('number', 0, { allowEmpty: true });
// Result.
true

isValid('number', 0);
// Result.
false

isValid('object', ['abc']);
// Result.
false

isValid('object', {}, { allowEmpty: true });
// Result.
true

joinPath

Joins a list of absolute and relative paths as a string.

Parameters

Param	Type	Required	Default	Description
segments	Array	Yes	-	List of paths to join.
options	object	No	-	Custom options to apply.
options.resolve	boolean	No	false	If true, tries to resolve segments into an absolute path.

Returns

• (string): Returns joined path string.

Example

joinPath(['/foo', 'bar', 'baz\\abc', './def', '..']);
// Result.
'/foo/bar/baz/abc'

keyExtractor

For applications where unique keys need to be generated for elements in an array (e.g. React Native FlatList).

Parameters

Param	Type	Required	Default	Description
key	string | number	Yes	-	Can be any value (e.g. id, title).
index	number	Yes	-	Element array index.

Returns

• (string): Returns concatenated 'key-index' string.

Example

keyExtractor('post', 2);
// Result.
'post-2'

letterCase

See Start Case for more details.

Formats supplied string to defined case.

Parameters

Param	Type	Required	Default	Description
text	string	Yes	-	Text to format.
options	object	Yes	-	Custom options to apply.
options.letterCase	string	Yes	-	lower, upper, sentence, kebab, title.
options.separators	Array	No	-	Replaces specified symbols with white space.

Returns

• (string): Returns formatted string.

Example

letterCase('_the   quiCK--brown     FOx_!', { letterCase: 'sentence' });
// Result.
'_The   quick--brown     fox_!'

letterCase('the #quiCK brown FOx!', { letterCase: 'kebab' });
// Result.
'the-quick-brown-fox'

// Applies custom separators if supplied, else defaults to: [_-\s]+
letterCase('_the   quiCK--brown     FOx_!', { letterCase: 'title' });
// Result.
'The Quick Brown Fox!'

ms

Parses a number representation or a string time period (e.g. 1h, 2d) to Unix Timestamp.

• ms: millisecond.
• s: second.
• m: minute.
• h: hour.
• d: day.
• w: week.
• y: year.

Parameters

Param	Type	Required	Default	Description
span	string | number	Yes	-	ms, s, m, h, d, w, y.

Returns

• (number): Returns time representation in milliseconds, else parses value as integer.

Example

ms('1hr');
// Result.
3600

ms('1000');
// Result.
1000

normalize

Normalizes payload by defined object attribute.

Payload data needs to be consistent and has similar data structure to avoid unexpected results, specifically defined idAttribute (e.g. results from a database query).

Parameters

Param	Type	Required	Default	Description
key	string	Yes	-	Object property name to move records to.
payload	Array | object	Yes	-	Data to normalize.
options	object	No	-	Custom options to apply.
options.idAttribute	string	No	id	Object property name to normalize records based on.

Returns

• (Object.entities): Normalized records by 'key'.
• (Object.result): Array or single value of data 'idAttributes'.

Example

// Array payload.
normalize('posts', [{ id: 1, title: 'abc' }, { id: 2, title: 'def' }], { idAttribute: 'uid' });
// Result.
{
  entities: {
    posts: {
      1: { uid: 1, title: 'abc' },
      2: { uid: 2, title: 'def' }
    },
  },
  result: [1,2]
}

// Object payload.
normalize('posts', { id: 1, title: 'abc' });
// Result.
{
  entities: {
    posts: {
      1: { id: 1, title: 'abc' }
    },
  },
  result: 1
}

parseUrl

Parses URL string segments including query string values, if any.

A url-parse wrapper for convenience and extensibility.

Parameters

Param	Type	Required	Default	Description
url	string	Yes	-	URL to parse.

Returns

• (Object): Returns parsed URL object.

Example

parseUrl('https://localhost:8000/foo/bar?firstName=John&lastName=Doe');
// Result.
{
  slashes: true,
  protocol: "https:",
  hash: "",
  query: {
    firstName: "John",
    lastName: "Doe"
  },
  pathname: "/foo/bar",
  auth: "",
  host: "localhost:8000",
  port: "8000",
  hostname: "localhost",
  password: "",
  username: "",
  origin: "https://localhost:8000",
  href: "https://localhost:8000/foo/bar?firstName=John&lastName=Doe"
}

random

Generates a random string or number with customizable options.

• filename: File names stored in databases.
• number: Number between defined min and max (See Math.random).
• temp: File names stored in temporary or cache locations.
• title: Content or post random title.
• uuid: v4.

This helper uses uuid to generate UUIDs in options filename, temp and uuid; for known issues, see Duplicate UUIDs (Googlebot).

Usage

If you are using this package in a React Native/Expo project:

• Install react-native-get-random-values polyfill.
• Add import 'react-native-get-random-values' as the first line in your index/entry point. See more details here.

Parameters

Param	Type	Required	Default	Description
type	string	Yes	-	filename, number, title, temp, uuid.
options	object	No	-	Custom options to apply.

Options: number

Param	Type	Required	Default	Description
options.min	number	No	0	If type is number, minimum value to start from.
options.max	number	No	1	If type is number, maximum value to end at.
options.decimal	boolean	No	false	Generate a random number with decimals.
options.precision	number	No	0	Limit generated number decimal places.

Options: filename, temp, title

Param	Type	Required	Default	Description
options.prefix	string	No	-	Text to add to the beginning of the result.
options.suffix	string	No	-	Text to add to the end of the result.

Options: uuid

Param	Type	Required	Default	Description
options	undefined	-	-	Argument not available for 'uuid' option.

Returns

• (string|number): Returns generated string or number.

Example

random('number', { min: 1000, max: 2000 });
// Result.
1784

random('number', { decimal: true, min: 10, max: 200, precision: 2 });
// Result.
97.13

random('filename', { prefix: 'post' });
// Result.
'post_2018-01-01_12-00-00_7f2a79ba-962e-4b35-96d0-28xf1d025107'

random('temp');
// Result.
'2018-01-01_12-00-00_efc7438f-0a4d-4538-af87-b6984xe04688'

random('title', { suffix: 'post' });
// Result.
'2018-01-01_12-00-00_post'

random('uuid');
// Result.
'7e0ea78d-c170-4449-93fb-f5caxb952752'

sanitize

Trims extra whitespace and removes HTML tags.

Uses: trimWhitespace

Parameters

Param	Type	Required	Default	Description
text	string	Yes	-	Text to trim.

Returns

• (string): Returns sanitized string.

Example

sanitize('<script>"the__   #quicK-- BROWN     @foX_".js</script> <html><div>Html code</div></html>');
// Result.
'the__ #quicK-- BROWN @foX_.js Html code'

singular

Trims last character if ends with 's' or replaces 'ies' with 'y'.

Not an ideal solution, but does the job for most cases.

Parameters

Param	Type	Required	Default	Description
text	string	Yes	-	Text to convert.

Returns

• (string): Returns trimmed text.

Example

singular('posts');
// Result.
'post'

singular('commodities');
// Result.
'commodity'

splitArray

Splits any array to chunks by supplied size.

Parameters

Param	Type	Required	Default	Description
array	Array	Yes	-	Data array to split.
size	number	No	-	Size of each array chunk; bypasses split if empty.

Returns

• (Array): Returns new array chunks.

Example

splitArray([{ id: 1, title: 'abc' }, { id: 2, title: 'def' }]);
// Result.
[
  { "id": 1, "title": "name1" },
  { "id": 2, "title": "name2" }
]

splitArray([{ id: 1, title: 'abc' }, { id: 2, title: 'def' }], 1);
// Result.
[
  [{ "id": 1, "title": "name1" }],
  [{ "id": 2, "title": "name2" }]
]

timestamp

Parses any date value to a timestamp with predefined or custom format.

• datetime: dddd, MMMM D at h:mA.
• fromNow: Relative time.
• short: ddd, MMM D.
• sql: YYYY-MM-DD HH:mm:ss.

You can use 'format' option to provide custom date/time format.

Parameters

Param	Type	Required	Default	Description
date	string | number | object	No	Date.now()	Date string, Date object, Unix Timestamp.
options	object	No	-	Custom options to apply.
options.format	string	No	DD/MM/YYYY	datetime, fromNow, short, sql, Moment.

Returns

• (string): Returns formatted timestamp.

Example

timestamp();
// Result.
'31/12/2022' // Date.now()

timestamp(new Date('12/31/2022'), { format: 'datetime' });
// Result.
'Saturday, December 31 at 12:00AM'

timestamp(Date(), { format: 'fromNow' });
// Result.
'a few seconds ago'

timestamp(moment('12/31/2022'), { format: 'short' });
// Result.
'Sat, Dec 31 12:00AM'

timestamp('12/31/2022 12:00', { format: 'sql' });
// Result.
'2022-12-31 12:00:00'

toArray

Converts any value to array.

Useful for multi value fields as 'group_concat'.

Uses: trimWhitespace

Parameters

Param	Type	Required	Default	Description
value	Any	Yes	-	Data to convert.
options	object	No	-	Custom options to apply.
options.separator	string	No	,	The pattern where the split should occur.
options.parseNumber	boolean	No	false	If true, maps array values as Number.

Returns

• (Array): Returns new array based on supplied options.

Example

toArray('1', { parseNumber: true });
// Result.
[1]

toArray(['a', 'b', 'c']);
// Result.
['a', 'b', 'c']

toArray({ id: 1, title: 'name-1' });
// Result.
[{ id: 1, title: 'name-1' }]

toArray('1,2,3');
// Result.
['1', '2', '3']

toArray('  a-2-3  -', { parseNumber: true, separator: '-' });
// Result.
[NaN, 2, 3]

toNumeric

Converts value to and validates as 'number'.

Parameters

Param	Type	Required	Default	Description
value	number | string	Yes	-	Number representation; if null, returns 0.
options	object	No	-	Custom options to apply.
options.decimal	boolean	No	true	If true, retains decimal point.
options.math	string	No	-	'abs', 'ceil', 'floor', 'round', 'trunc'.
options.precision	number	No	-	If supplied, limits number decimal places.

Returns

• (number): Returns formatted number.

Example

toNumeric('1.3');
// Result.
1.3

toNumeric(1.3);
// Result.
1.3

toNumeric('1.3', { decimal: false });
// Result.
1

toNumeric('1.3456', { precision: 2 });
// Result.
1.35

toNumeric('1.3446', { precision: 2 });
// Result.
1.34

toNumeric('1.3', { math: 'ceil' });
// Result.
2

toNumeric(1.3, { math: 'floor' });
// Result.
1

toNumeric(['1.3', 1], { math: 'floor' });
// Result.
NaN

toNumeric({ 0: 1 });
// Result.
NaN

toRGBa

Converts color from 'keyword' (e.g. green) or 'hex' (e.g. #00FF00) to RGBa value. Useful when there is a need to apply color opacity.

Parameters

Param	Type	Required	Default	Description
color	string	Yes	-	Can be Name or HEX code (e.g. white, #DDD).
alpha	number	No	1	Set color opacity value.

Returns

• (string): Returns RGBa value for valid colors else 'rgba(0,0,0,alpha)'.

Example

toRGBa('purple');
// Result.
'rgba(128,0,128,1)'

toRGBa('#DDD', 0.5);
// Result.
'rgba(221,221,221,0.5)'

toRGBa('invalidColor', 0.3);
// Result.
'rgba(0,0,0,0.3)'

trimWhitespace

Removes leading and trailing spaces and replaces multiple white spaces, tabs and newlines with one space.

Parameters

Param	Type	Required	Default	Description
text	string	Yes	-	Text to trim.

Returns

• (string): Returns trimmed text.

Example

trimWhitespace('   _the   quiCK--brown     FOx !');
// Result.
'_the quiCK--brown FOx !'

Changelog

Check out CHANGELOG.md for a full list of changes.

Community

Head over to Discussions where you can ask questions, request new features or voice your ideas and suggestions.

• Ideas
• Q&A

Found a bug or you have an improvement recommendation, head over to Issues and submit a new request.

License

This package is available under the BSD 3-Clause license. It also includes external libraries that are available under a variety of licenses. See LICENSE for the full license text.