@rashedmakkouk/dev-utils v0.15.2
Dev Utils
Utility library.
v0.15.0
Notable changes in v0.15.0
:
- Added
decimal
andprecision
options support to number type inrandom
helper. - Updated random usage instructions in
README.md
. - Renamed
toNumber
option toparseNumber
in toArray helper (Breaking change). - Refactored
date
argument to accept empty value in timestamp, defaults toNow
. - Added keyExtractor helper usage instructions in
README.md
. - Added
abs
support tomath
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)
: Returnstrue
if supplied payload passes checks, elsefalse
.
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.
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.