@steveush/utils
Advanced tools
Utility methods and classes
NOTE
Any version below 1.0.0 is considered experimental and is subject to change.
This package was created for my personal use, and so is provided as is.
npm i @steveush/utils --save-dev
Import the entire package and make use of features. This is not recommended as you may lose the benefit of tree-shaking.
import * as utils from "@steveush/utils";
Instead, import the specific util.
import { isString } from "@steveush/utils";
Import the entire package and make use of features.
const utils = require( "@steveush/utils" );
Import a specific util.
const { isString } = require( "@steveush/utils" );
clamp( value: number, min?: number, max?: number ): numberClamp a number value within a given range.
Params
value: any
The number to clamp. If the value supplied is not a number, the min value is returned.
min: number optional
The minimum allowed value for the number. If not supplied Number.MIN_SAFE_INTEGER is used.
max: number optional
The maximum allowed value for the number. If not supplied Number.MAX_SAFE_INTEGER is used.
Returns
numbermin and max values. If the number was smaller than the min or larger than the max, their respective values are instead returned.Example
clamp( -1, 0, 2 ); // => 0
clamp( 0, 0, 2 ); // => 0
clamp( 1, 0, 2 ); // => 1
clamp( 2, 0, 2 ); // => 2
clamp( 3, 0, 2 ); // => 2
isNumberNotZero( value: string | number ): booleanCheck if a value is a number and not zero.
Params
anyparseFloat method.Returns
booleantrue if the value is a number and not zero, otherwise false.Example
isNumberNotZero( 0 ); // => false
isNumberNotZero( 1 ); // => true
isNumberNotZero( "0px" ); // => false
isNumberNotZero( "1px" ); // => true
isNumberNotZero( "0.0em" ); // => false
isNumberNotZero( "0.1em" ); // => true
isNumberWithin( value: number, min: number, max: number ): booleanCheck if a value is a number within the inclusive range of min to max.
Params
value: any
The value to check.
min: number
The inclusive minimum value for the range.
max: number
The inclusive maximum value for the range.
Returns
booleantrue if the value is a number within the specified range, otherwise false.Example
isNumberWithin( -1, 0, 2 ); // => false
isNumberWithin( 0, 0, 2 ); // => true
isNumberWithin( 1, 0, 2 ); // => true
isNumberWithin( 2, 0, 2 ); // => true
isNumberWithin( 3, 0, 2 ); // => false
cleanObject( value: object | any ): object | undefinedClean an object by removing any keys explicitly set to undefined.
If after cleaning the object is empty, undefined itself is returned.
Params
object | anyundefined will be returned.Returns
object | undefinedundefined.Example
cleanObject( {} ); // => undefined
cleanObject( { empty: undefined } ); // => undefined
cleanObject( { empty: undefined, notEmpty: true } ); // => { notEmpty: true }
clone( target: any ): anyCreates a clone of the supplied target.
Note: This method will clone arrays and plain objects, all other types are set by reference.
Params
anyReturns
anycombine( arr1: any[], arr2: any[], comparator?: ( ( a: any, b: any ) => boolean ) ): any[]Combine two arrays and return a new array containing no duplicate elements.
Params
arr1: any[]
The first array to combine.
arr2: any[]
The second array to combine.
comparator: ( a: any, b: any ) => boolean optional
The function used to determine element equality when removing duplicates. Defaults to a strict equality
check (a === b).
Returns
any[]If both arr1 and arr2 are not arrays an empty array is returned.
If arr1 is not an array a shallow copy of arr2 is returned.
If arr2 is not an array a shallow copy of arr1 is returned.
If both arr1 and arr2 are arrays they are combined and a new array containing distinct elements is returned.
Example
combine(
[ 1, 2 ],
[ 2, 3 ]
); // => [ 1, 2, 3 ]
combine(
[ { id: 1 }, { id: 2 } ],
[ { id: 2 }, { id: 3 } ]
); // => [ { id: 1 }, { id: 2 }, { id: 2 }, { id: 3 } ]
combine(
[ { id: 1 }, { id: 2 } ],
[ { id: 2 }, { id: 3 } ],
( a, b ) => a.id === b.id
); // => [ { id: 1 }, { id: 2 }, { id: 3 } ]
distinct( array: any[] ): any[]Return the distinct elements of an array.
Params
any[]Returns
any[]Example
distinct( [ 1, 2, 2, 3 ] ); // => [ 1, 2, 3 ]
getProperty( target: object, path: string ): anyGet a property value from an object using a path string ("child.prop").
Params
target: object
The array or object to get the value from.
path: string
The path on the target where the value will be fetched from.
Returns
anyundefined.Example
Passing an object as the target.
const obj = {
name: "root",
child: {
name: "child"
},
children: [
{ name: "first" },
{ name: "second" }
]
};
getProperty( obj, "name" ); // => "root"
getProperty( obj, "child.name" ); // => "child"
getProperty( obj, "children[0].name" ); // => "first"
getProperty( obj, "children.0.name" ); // => "first"
getProperty( obj, "children[1].name" ); // => "second"
getProperty( obj, "children.1.name" ); // => "second"
Passing an array as the target.
const arr = [
{ name: "first" },
{ name: "second" }
];
getProperty( arr, "[0].name" ); // => "first"
getProperty( arr, "0.name" ); // => "first"
getProperty( arr, "[1].name" ); // => "second"
getProperty( arr, "1.name" ); // => "second"
hasKeys( target: object, keys?: string | string[] | Record<string, ( ( value: any ) => boolean )> ): booleanCheck if an object has keys.
Params
target: object
The object to check.
keys: string | string[] | Record<string, ( ( value: any ) => boolean )> optional
A string key name, string array of key names, or an object containing key names to type check methods. If not supplied
and the target contains any keys, true is returned.
Returns
booleantrue if the target has all the keys, otherwise false.Example
const obj = {
name: "string",
checked: true
};
hasKeys( obj ); // => true
hasKeys( obj, "name" ); // => true
hasKeys( obj, "never" ); // => false
hasKeys( obj, [ "name", "checked" ] ); // => true
hasKeys( obj, [ "name", "checked", "never" ] ); // => false
hasKeys( obj, { name: isString, checked: isBoolean } ); // => true
hasKeys( obj, { name: isString, checked: isString } ); // => false
merge( target: object, ...source: object[] ): objectRecursively merge the properties of multiple source objects into the target.
Note: This method does not merge arrays. Any array properties of the target are replaced with shallow copies from the sources.
Params
target: object
The object to receive the properties.
...source: object[]
Any number of source objects to merge into the target.
Returns
objectExample
merge(
{ prop1: "one", prop2: false },
{ prop2: true, prop3: 2 },
{ prop1: "three", prop3: 3 }
); // => { prop1: "three", prop2: true, prop3: 3 }
If the target is not a plain object a new object is created.
merge(); // => {}
merge( undefined, { prop1: "one" } ); // => { prop1: "one" }
If a source is not a plain object it is ignored.
merge( { prop1: "one" }, undefined ); // => { prop1: "one" }
merge( { prop1: "one" }, "oops" ); // => { prop1: "one" }
merge( { prop1: "one" }, undefined, { prop2: "two" } ); // => { prop1: "one", prop2: "two" }
pluck( target: object, keys: string | string[] | ( ( value: any, key: string: iter: object ) => boolean ) ): objectPluck key-value pairs from one object into a new object.
Params
target: object
The object to pluck key-value pairs from.
keys: string | string[] | ( ( value: any, key: string: iter: object ) => boolean )
A string key name, string array of key names, or a predicate that determines if the key-value pair should be plucked.
Returns
objectExample
const obj = {
prop1: "string1",
prop2: true,
prop3: 3,
prop4: "string2"
};
pluck( obj, "prop1" ); // => { prop1: "string1" }
pluck( obj, [ "prop2", "prop3" ] ); // => { prop2: true, prop3: 3 }
pluck( obj, value => isString( value ) ); // => { prop1: "string1", prop4: "string2" }
setProperty( target: object, path: string, value: any, create?: boolean ): voidSet a value of an object using a path string ("child.prop").
Params
target: object
The array or object to set the value on.
path: string
The path on the target where the value will be set.
value: any
The value to assign to the path.
create: boolean optional
Whether to create the path on the target if it does not exist. Defaults to false.
Example
Given the following object:
const obj = {
name: "root",
child: {
name: "child"
},
children: [
{ name: "first" },
{ name: "second" }
]
};
We can change the value of various existing properties.
setProperty( obj, "name", "update_root" );
// obj => {
// name: "update_root",
// child: {
// name: "child"
// },
// children: [
// { name: "first" },
// { name: "second" }
// ]
// }
setProperty( obj, "child.name", "update_child" );
// obj => {
// name: "root",
// child: {
// name: "update_child"
// },
// children: [
// { name: "first" },
// { name: "second" }
// ]
// }
setProperty( obj, "children[0].name", "update_children_first" );
// obj => {
// name: "root",
// child: {
// name: "child"
// },
// children: [
// { name: "update_children_first" },
// { name: "second" }
// ]
// }
Note: By default, if the path does not exist on the target, no property is set.
setProperty( {}, "newProp", "never" );
// obj => {}
If you want to change this behavior and allow new properties to be created, then you must pass true for the create
parameter.
setProperty( obj, "newProp", "created", true );
// obj => { newProp: "created" }
someKeys( target: object, keys?: string | string[] | Record<string, ( ( value: any ) => boolean )> ): booleanCheck if an object has some keys.
Params
target: object
The object to check.
keys: string | string[] | Record<string, ( ( value: any ) => boolean )> optional
A string key name, string array of key names, or an object containing key names to type check methods. If not supplied
and the target contains any keys, true is returned.
Returns
booleantrue if the target has any of the keys, otherwise false.Example
const obj = {
name: "string",
checked: true
};
someKeys( obj ); // => true
someKeys( obj, "name" ); // => true
someKeys( obj, "never" ); // => false
someKeys( obj, [ "name", "never" ] ); // => true
someKeys( obj, { name: isString, checked: isString } ); // => true
someKeys( obj, { name: isBoolean, checked: isString } ); // => false
bisect( str: string, searchString: string, trim?: boolean ): [ string, string ]Split a string on the first occurrence of the specified search string.
Params
str: string
The string to split.
searchString: string
The value used to split the string.
trim: boolean optional
Whether the resulting parts should be trimmed. Defaults to false.
Returns
[ string, string ]The first element is the string value from before the searchString, or the original value if the searchString was
not found.
The second element is the string value from after the searchString, or an empty string if the searchString was not
found.
Example
bisect( "split on first space", " " ); // => [ "split", "on first space" ]
bisect( "split - on first - dash", "-" ); // => [ "split ", " on first - dash" ]
bisect( "split - on first - dash", "-", true ); // => [ "split", "on first - dash" ]
capitalize( str: string ): stringCapitalize the first character of a string.
Params
stringReturns
stringExample
capitalize(); // => ""
capitalize( "test" ); // => "Test"
capitalize( "TEST" ); // => "Test"
escapeHTML( str: string ): stringConvert the special characters &, <, >, ", and ' in a string to HTML entities.
Params
stringReturns
stringExample
escapeHTML( `<img src="..." title="Jack's Pub" />` ); // => "<img src="..." title="Jack's Pub" />"
propertyPath( path: string ): stringConvert an array notated property path to a dot notated one.
The only difference between array and dot notated paths is how array indexes are described. In array notation they are encapsulated within square brackets, whilst in dot notation they are simply prefixed with a period like other property names.
This method is used internally by the getProperty and setProperty methods to normalize the supplied path parameter.
Params
stringReturns
stringExample
propertyPath( "[0].name" ); // => "0.name"
propertyPath( "arr[0].name" ); // => "arr.0.name"
propertyPath( "arr[0]" ); // => "arr.0"
strim( str: string, separator: string | RegExp ): string[]Split a string into an ordered list of trimmed, non-empty, substrings.
Params
str: string
The string to split.
separator: string | RegExp
The pattern describing where each split should occur.
Returns
string[]Example
strim( "key1: value1; key2: value2;", ";" ); // => [ "key1: value1", "key2: value2" ]
toCamelCase( str: string, uppercase?: string[], force?: boolean ): stringConvert a string to camelCase.
Params
str: string
The string to convert.
uppercase: string[] optional
An array of strings to convert to uppercase. Defaults to [].
force: boolean optional
Whether to allow uppercase strings to appear at the start of a string. Defaults to false.
Returns
stringExample
toCamelCase( "camelCase" ); // => "camelCase"
toCamelCase( "PascalCase" ); // => "pascalCase"
toCamelCase( "kebab-case" ); // => "kebabCase"
toCamelCase( "snake_case" ); // => "snakeCase"
toCamelCase( "with spaces" ); // => "withSpaces"
If you need specific parts of the string to be uppercased you can supply them as the second parameter.
toCamelCase( "camelCase", [ "case" ] ); // => "camelCASE"
toCamelCase( "PascalCase", [ "case" ] ); // => "pascalCASE"
toCamelCase( "kebab-case", [ "case" ] ); // => "kebabCASE"
toCamelCase( "snake_case", [ "case" ] ); // => "snakeCASE"
If the string starts with one of the uppercase strings, by default it is left as lowercase.
toCamelCase( "case-at-start", [ "case" ] ); // => caseAtStart
However, this can be overridden by specifying the force parameter as true.
toCamelCase( "case-at-start", [ "case" ], true ); // => CASEAtStart
toKebabCase( str: string ): stringConvert a string to kebab-case.
Params
stringReturns
stringExample
toKebabCase( "camelCase" ); // => "camel-case"
toKebabCase( "PascalCase" ); // => "pascal-case"
toKebabCase( "kebab-case" ); // => "kebab-case"
toKebabCase( "snake_case" ); // => "snake-case"
toKebabCase( "with spaces" ); // => "with-spaces"
toPascalCase( str: string, uppercase?: string[] ): stringConvert a string to PascalCase.
Params
str: string
The string to convert.
uppercase: string[] optional
An array of strings to convert to uppercase. Defaults to [].
Returns
stringExample
toPascalCase( "camelCase" ); // => "CamelCase"
toPascalCase( "PascalCase" ); // => "PascalCase"
toPascalCase( "kebab-case" ); // => "KebabCase"
toPascalCase( "snake_case" ); // => "SnakeCase"
toPascalCase( "with spaces" ); // => "WithSpaces"
If you need specific parts of the string to be uppercased you can supply them as the second parameter.
toPascalCase( "camelCase", [ "case" ] ); // => "CamelCASE"
toPascalCase( "PascalCase", [ "case" ] ); // => "PascalCASE"
toPascalCase( "kebab-case", [ "case" ] ); // => "KebabCASE"
toPascalCase( "snake_case", [ "case" ] ); // => "SnakeCASE"
toSnakeCase( str: string ): stringConvert a string to snake_case.
Params
stringReturns
stringExample
toSnakeCase( "camelCase" ); // => "camel_case"
toSnakeCase( "PascalCase" ); // => "pascal_case"
toSnakeCase( "kebab-case" ); // => "kebab_case"
toSnakeCase( "snake_case" ); // => "snake_case"
toSnakeCase( "with spaces" ); // => "with_spaces"
toPartsLowerCase( str: string ): string[]Convert a string into an array of its component parts.
Used to provide a consistent base for the various string case methods to work from.
Params
stringReturns
string[]Example
toPartsLowerCase( "camelCase" ); // => [ "camel", "case" ]
toPartsLowerCase( "PascalCase" ); // => [ "pascal", "case" ]
toPartsLowerCase( "kebab-case" ); // => [ "kebab", "case" ]
toPartsLowerCase( "snake_case" ); // => [ "snake", "case" ]
toPartsLowerCase( "with spaces" ); // => [ "with", "spaces" ]
toString( value: any ): stringConvert a value to a string using the Object.prototype.toString() method.
Params
anyReturns
stringExample
toString( "str" ); // => "[object String]"
toString( true ); // => "[object Boolean]"
toString( Symbol.toStringTag ); // => "[object Symbol]"
unescapeHTML( str: string ): stringConvert the HTML entities &, <, >, " and ' in a string back to their original characters.
Params
stringReturns
stringExample
escapeHTML( `<img src="..." title="Jack's Pub" />` ); // => "<img src="..." title="Jack's Pub" />"
isArray( value: any, notEmpty?: boolean, predicate?: ( value: any, index: number, iter: any[] ) => boolean ): booleanCheck if a value is an array.
Params
value: any
The value to check.
notEmpty: boolean optional
If true the array must not be empty. Defaults to false.
predicate: ( value: any, index: number, iter: any[] ) => boolean optional
If supplied every entry in the array must satisfy this predicate.
Returns
booleantrue if the value is an array and satisfies the optional checks, otherwise false.Example
isArray( [] ); // => true
isArray( [], true ); // => false
isArray( [ 1 ], true, value => isNumber( value ) ); // => true
isArray( [ 1, "2" ], true, value => isNumber( value ) ); // => false
isBoolean( value: any ): booleanCheck if a value is a boolean.
Params
anyReturns
booleantrue if the value is a boolean, otherwise false.isFunction( value: any ): booleanCheck if a value is a function.
Params
anyReturns
booleantrue if the value is a function, otherwise false.Example
function named() {
}
isFunction( named ); // => true
const arrow = () => "returns";
isFunction( arrow ); // => true
isNonNullable( value: any ): booleanCheck if a value is not null or undefined.
Params
anyReturns
booleantrue if the value is not null or undefined, otherwise false.isNull( value: any ): booleanCheck if a value is null.
Params
anyReturns
booleantrue if the value is null, otherwise false.isNumber( value: any ): booleanCheck if a value is a number.
Params
anyReturns
booleantrue if the value is a number, otherwise false.isObject( value: any, notEmpty?: boolean, predicate?: ( ( value: any, key: string, iter: object ) => boolean ) ): booleanCheck if a value is an object.
This method returns true for arrays, functions, objects and classes like Date, Error and RegExp.
If notEmpty is true the value must return a non-empty array from a call to Object.entries.
If a predicate is supplied every entry in the object must satisfy it.
Params
value: any
The value to check.
notEmpty: boolean optional
If true the object must not be empty. Defaults to false.
predicate: ( value: any, key: string, iter: object ) => boolean optional
If supplied every entry in the object must satisfy this predicate.
Returns
booleantrue if the value is an object and satisfies the optional checks, otherwise false.Example
isObject( [] ); // => true
isObject( {} ); // => true
isObject( () => 'returns' ); // => true
Checking for empty values.
isObject( [], true ); // => false
isObject( {}, true ); // => false
isObject( () => 'returns', true ); // => false
// note functions will only be not-empty if it has properties defined.
const fn = () => 'returns';
fn.prop = true;
isObject( fn, true ); // => true
Ensuring each key-value pair satisfies a condition.
isObject( [ 1, 2, 3 ], true, value => isNumber( value ) ); // => true
isObject( [ 1, 2, 3 ], true, value => isString( value ) ); // => false
isObject( { prop1: 1, prop2: 2 }, true, value => isNumber( value ) ); // => true
isObject( { prop1: 1, prop2: 2 }, true, value => isString( value ) ); // => false
isPlainObject( value: any, notEmpty?: boolean, predicate?: ( ( value: any, key: string, iter: object ) => boolean ) ): booleanCheck if a value is a plain old JavaScript object.
Params
value: any
The value to check.
notEmpty: boolean optional
If true the object must not be empty. Defaults to false.
predicate: ( value: any, key: string, iter: object ) => boolean optional
If supplied every entry in the object must satisfy this predicate.
Returns
booleantrue if the value is a plain old JavaScript object and satisfies the optional checks, otherwise false.Example
isPlainObject( [] ); // => false
isPlainObject( {} ); // => true
isPlainObject( () => 'returns' ); // => false
Checking for empty values.
isPlainObject( {}, true ); // => false
isPlainObject( { prop: 1 }, true ); // => true
Ensuring each key-value pair satisfies a condition.
isPlainObject( { prop1: 1, prop2: 2 }, true, value => isNumber( value ) ); // => true
isPlainObject( { prop1: 1, prop2: 2 }, true, value => isString( value ) ); // => false
isRegExp( value: any ): booleanCheck if a value is a regular expression.
Params
anyReturns
booleantrue if the value is a regular expression, otherwise false.isString( value: any, notEmpty?: boolean ): booleanCheck if a value is a string.
A string is empty if it has a length of 0 or contains only whitespace.
Params
value: any
The value to check.
notEmpty: boolean optional
If true the string must not be empty. Defaults to false.
Returns
booleantrue if the value is a string and satisfies the optional check, otherwise false.isSymbol( value: any ): booleanCheck if a value is a symbol.
Params
anyReturns
booleantrue if the value is a symbol, otherwise false.isUndefined( value: any ): booleanCheck if a value is undefined.
Params
anyReturns
booleantrue if the value is undefined, otherwise false.To get the project up and running for development should just require running npm install and then npm run develop.
For more information on the configuration check out the DEV.md readme.
| Version | Description |
|---|---|
| 0.0.1 | Initial release |
| 0.0.2 | Relaxed the value checks for hasKeys, someKeys and pluck methods to allow any object instead of just plain objects. Added the cleanObject, clone, distinct, clamp, isNumberNotZero, isNumberWithin, capitalize and strim methods. |
FAQs
Utility methods and classes.
The npm package @steveush/utils receives a total of 0 weekly downloads. As such, @steveush/utils popularity was classified as not popular.
We found that @steveush/utils demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.