A set of JavaScript string helpers

JavaScript strings already contains lots of useful and convenient methods built-in, however, it still misses tons of commonly used features like "capitalizing the first letter of a string" or "slugifying a string" etc... .

This package aims to bridge the gap a little by providing a set of JavaScript string "helper" functions inspired by Laravel's string helpers and some built-in PHP string functions.

Here's a quick example:

import str from '@vicgutt/strjs';

const string = 'Quote:the-eyes-are_useless_when_the-mind-is-blind!!!s';

str(string).after(':').replaceMany(['-', '_'], ' ').upperFirst().trimEnd('s').finish('!');
// The eyes are useless when the mind is blind!

// or

str.finish(str.trimEnd(str.upperFirst(str.replaceMany(['-', '_'], ' ', str.after(string, ':'))), 's'), '!');
// The eyes are useless when the mind is blind!

// or (enables tree-shaking)
import strFinish from '@vicgutt/strjs/strFinish';
import strTrimEnd from '@vicgutt/strjs/strTrimEnd';
import strUpperFirst from '@vicgutt/strjs/strUpperFirst';
import strReplaceMany from '@vicgutt/strjs/strReplaceMany';
import strAfter from '@vicgutt/strjs/strAfter';

strFinish(strTrimEnd(strUpperFirst(strReplaceMany(['-', '_'], ' ', strAfter(string, ':'))), 's'), '!');
// The eyes are useless when the mind is blind!

Installation

Install the plugin via NPM (or yarn):

npm i @vicgutt/strjs

yarn add @vicgutt/strjs

Note: This library is very "future facing" in the code that is distributed (dist folder), meaning it requires at least Node14+ and ES2020/ES2021 support from your JS compiler/bundler or browser.

Having access to the `str*` functions

The str* functions can be accessed in three different ways:

Import the function directly (ex.: import strAfter from '@vicgutt/strjs/strAfter')
Use the static properties available from the str function directly (ex.: str.after(...))
Or invoke the str function, which will retun an instance of Stringable and use the instance methods (ex.: str(...).after(...))

Available functions

• str.after / strAfter (Source | Tests)

Return the remainder of a string after the first occurrence of a given value. The entire string will be returned if the value does not exist within the string.

Signature

/**
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @param {string} search - The value being searched for, otherwise known as the needle
 * @returns {string}
 */
function strAfter(subject: string, search: string): string;

Example

strAfter('This is the way', 'This is'); // ' the way'
strAfter('This is the way', 'nope'); // 'This is the way'

• str.afterLast / strAfterLast (Source | Tests)

Return the remainder of a string after the last occurrence of a given value. The entire string will be returned if the value does not exist within the string.

Signature

/**
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @param {string} search - The value being searched for, otherwise known as the needle
 * @returns {string}
 */
function strAfterLast(subject: string, search: string): string;

Example

strAfterLast('do you no da wae', 'o'); // ' da wae'
strAfterLast('do you no da wae', 'nope'); // 'do you no da wae'

• str.append / strAppend (Source | Tests)

Append the given values to the string.

Signature

/**
 * @param {string} value - The string to append the values on
 * @param {string[]} ...values - The values to be appended to the value
 * @returns {string}
 */
function strAppend(value: string, ...values: string[]): string;

Example

strAppend('Hello', ' beautiful,', ' awesome,', ' incredible', ' world', '!'); // 'Hello beautiful, awesome, incredible world!'

• str.basename / strBasename (Source | Tests)

Get the trailing name component of the path.

Signature

/**
 * @param {string} value - The path on which we want to get the trailing name component
 * @param {string} [suffix=''] - A "suffix", if provided, will be removed from the trailing name component
 * @returns {string}
 */
function strBasename(value: string, suffix: string = ''): string;

Example

strBasename('/home/hello/dir/otherDir/lastDir/filename.txt'); // 'filename.txt'
strBasename('/home/hello/dir/otherDir/lastDir/filename.txt', '.txt'); // 'filename'

• str.before / strBefore (Source | Tests)

Get the portion of a string before the first occurrence of a given value. The entire string will be returned if the value does not exist within the string.

Signature

/**
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @param {string} search - The value being searched for, otherwise known as the needle
 * @returns {string}
 */
function strBefore(subject: string, search: string): string;

Example

strBefore('This is the way', 'the way'); // 'This is '
strBefore('This is the way', 'nope'); // 'This is the way'

• str.beforeLast / strBeforeLast (Source | Tests)

Get the portion of a string before the last occurrence of a given value. The entire string will be returned if the value does not exist within the string.

Signature

/**
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @param {string} search - The value being searched for, otherwise known as the needle
 * @returns {string}
 */
function strBeforeLast(subject: string, search: string): string;

Example

strBeforeLast('do you no da wae', 'o'); // 'do you n'
strBeforeLast('do you no da wae', 'nope'); // 'do you no da wae'

• str.between / strBetween (Source | Tests)

Get the portion of a string between two given values.

Signature

/**
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @param {string} from - The value from which to start the search
 * @param {string} to - The value until which to end the search
 * @returns {string}
 */
function strBetween(subject: string, from: string, to: string): string;

Example

strBetween('I no da wae broda', 'no', 'broda'); // ' da wae '
strBetween('I no da wae broda', 'nope', 'broda'); // 'I no da wae '
strBetween('I no da wae broda', 'no', 'nope'); // ' da wae broda'

• str.camel / strCamel (Source | Tests)

Convert a value to "camelCase".

Signature

/**
 * @param {string} value - The string to be converted
 * @returns {string}
 */
function strCamel(value: string): string;

Example

strCamel('loLL-i_pop'); // 'loLLIPop'
strCamel('Will the real Slim Shady please stand up?'); // 'willTheRealSlimShadyPleaseStandUp?'

• str.contains / strContains (Source | Tests)

Determine if a given string contains a given substring.

Performs a case-sensitive check indicating if any of the needles are contained in haystack.

Signature

/**
 * @param {string} haystack - The string to search in
 * @param {string | string[]} needles - The substring/substrings to search for in the haystack
 * @returns {boolean}
 */
function strContains(haystack: string, needles: string | string[]): boolean;

Example

strContains('Victor', 'Vic'); // true
strContains('Victor', 'Vix'); // false
strContains('Victor', ''); // false
strContains('Victor', ['Vic', 'tor']); // true
strContains('Victor', ['Vix', 'tor']); // true
strContains('Victor', ['Vix', 'torx']); // false

• str.containsAll / strContainsAll (Source | Tests)

Determine if a given string contains all array values.

Performs a case-sensitive check indicating if all of the needles are contained in haystack.

Signature

/**
 * @param {string} haystack - The string to search in
 * @param {string[]} needles - The substrings to search for in the haystack
 * @returns {boolean}
 */
function strContainsAll(haystack: string, needles: string[]): boolean;

Example

strContainsAll('Victor', ['Vic']); // true
strContainsAll('Victor', ['Vix']); // false
strContainsAll('Victor', ['']); // false
strContainsAll('Victor', ['Vic', 'tor']); // true
strContainsAll('Victor', ['Vix', 'tor']); // false
strContainsAll('Victor', ['Vix', 'torx']); // false

• str.dirname / strDirname (Source | Tests)

Get the parent directory's path.

Given a string containing the path of a file or directory, this function will return the parent directory's path that is levels up from the current directory.

Signature

/**
 * @param {string} value - A path of a file or directory
 * @param {number} [levels=1] - The number of parent directories to go up _(must be an integer greater than 0)_
 * @param {string | null} [DIRECTORY_SEPARATOR=null] - The directory path separator to use. If null, the function
                                                    will attempt to determine if the OS being used is Windows and if true,
                                                    will use `\` as a separator, otherwise, it will use `/`
 * @returns {string}
 */
function strDirname(value: string, levels: number = 1, DIRECTORY_SEPARATOR: string | null = null): string;

Example

strDirname('/grand-parent/parent/child'); // '/grand-parent/parent' (on Windows : '\\grand-parent\\parent')
strDirname('/grand-parent/parent/child', 1); // '/grand-parent/parent' (on Windows : '\\grand-parent\\parent')
strDirname('/grand-parent/parent/child', 2); // '/grand-parent' (on Windows : '\\grand-parent')
strDirname('/grand-parent/parent/child', 3); // '/' (on Windows : '\\')
strDirname('/grand-parent/parent/child', 4); // '/' (on Windows : '\\')

• str.endsWith / strEndsWith (Source | Tests)

Determine if a given string ends with a given substring.

Performs a case-sensitive check indicating if the haystack ends in any of the needles.

Signature

/**
 * @param {string} haystack - The string to search in
 * @param {string | string[]} needles - The substrings to be searched for at the end of haystack
 * @param {number} [length] - If provided, it is used as the length of haystack. Defaults to `haystack.length`
 * @returns {boolean}
 */
function strEndsWith(haystack: string, needles: string | string[], length?: number): boolean;

Example

strEndsWith('Get to the choppa', 'choppa'); // true
strEndsWith('Get to the choppa', 'Choppa'); // false
strEndsWith('Get to the choppa', ['choppa', 'nope']); // true
strEndsWith('Get to the choppa', 'choppa', 'Get to the choppa'.length); // true
strEndsWith('Get to the choppa', 'choppa', 'Get to the choppa'.length + 1); // true
strEndsWith('Get to the choppa', 'choppa', 'Get to the choppa'.length - 1); // false

• str.escapeHtml / strEscapeHtml (Source | Tests)

Convert certain characters that have special significance in HTML to HTML entities.

Signature

/**
 * @param {string} value - The string to be converted
 * @returns {string}
 */
function strEscapeHtml(value: string): string;

Example

strEscapeHtml('<div>Hey</div>'); // '&lt;div&gt;Hey&lt;/div&gt;'
strEscapeHtml('a && b'); // 'a &amp;&amp; b'
strEscapeHtml('"foo"'); // '&quot;foo&quot;'

• str.escapeHtmlComment / strEscapeHtmlComment (Source | Tests)

Strip out HTML comment symbols.

Signature

/**
 * @param {string} value - The string to be stripped out
 * @returns {string}
 */
function strEscapeHtmlComment(value: string): string;

Example

strEscapeHtmlComment('<!-- -->'); // ' '
strEscapeHtmlComment('<!- ->'); // '<!- ->'
strEscapeHtmlComment('<!-->'); // '>'
strEscapeHtmlComment('<!-- Comment -->'); // 'Comment'
strEscapeHtmlComment('<!- Comment ->'); // '<!- Comment ->'

• str.finish / strFinish (Source | Tests)

Cap a string with a single instance of a given value.

This function adds a single instance of the given value to a string if it does not already end with that value.

Signature

/**
 * @param {string} value - The target string
 * @param {string} cap - The value the target should end with
 * @returns {string}
 */
function strFinish(value: string, cap: string): string;

Example

strFinish('this/string', '/'); // 'this/string/'
strFinish('this/string/', '/'); // 'this/string/'
strFinish('this/string////', '/'); // 'this/string/'

• str.is / strIs (Source | Tests)

Determine if a given string matches a given pattern.

This function determines if a given string matches a given pattern. Asterisks may be used as wildcard values.

Signature

/**
 * @param {string | string[]} pattern - The pattern to be matched against
 * @param {string} value - The value the match against the pattern
 * @returns {boolean}
 */
function strIs(pattern: string | string[], value: string): boolean;

Example

strIs('foo/*', 'foo/bar/baz'); // true
strIs('*bar*', 'foo/bar/baz'); // true
strIs('*Bar*', 'foo/bar/baz'); // false
strIs('foo', 'foo/bar/baz'); // false
strIs(['foo/*', 'nope'], 'foo/bar/baz'); // true

• str.isAscii / strIsAscii (Source | Tests)

Determine if a given string is 7 bit ASCII.

Signature

/**
 * @param {string} value - The string being checked
 * @returns {boolean}
 */
function strIsAscii(value: string): boolean;

Example

strIsAscii('Gutt'); // true
strIsAscii('Gütt'); // false
strIsAscii('ü'); // false

• str.isUuid / strIsUuid (Source | Tests)

Determine if a given string is a valid UUID.

Signature

/**
 * @param {unknown} value - The string being checked
 * @returns {boolean}
 */
function strIsUuid(value: unknown): boolean;

Example

strIsUuid('a0a2a2d2-0b87-4a18-83f2-2529882be2de'); // true
strIsUuid('ff6f8cb0-c57da-51e1-9b21-0800200c9a66'); // false

• str.kebab / strKebab (Source | Tests)

Convert a string to "kebab-case".

Signature

/**
 * @param {string} value - The string to be converted
 * @returns {string}
 */
function strKebab(value: string): string;

Example

strKebab('loLLIPop'); // 'lo-l-l-i-pop'
strKebab('Will the real Slim Shady please stand up?'); // 'will-the-real-slim-shady-please-stand-up?'

• str.lcfirst / strLcfirst (Source | Tests)

Make a string's first character lowercase.

Signature

/**
 * @param {string} value - The target string
 * @returns {string}
 */
function strLcfirst(value: string): string;

Example

strLcfirst('Victoria'); // 'victoria'

• str.limit / strLimit (Source | Tests)

Limit the number of characters in a string. This function truncates the given string to the specified length.

Signature

/**
 * @param {string} value - The string to be truncated
 * @param {number} [limit=100] - The maximum truncated length
 * @param {string} [end='...'] - The string that will be appended to the end of the truncated string
 * @returns {string}
 */
function strLimit(value: string, limit: number = 100, end: string = '...'): string;

Example

strLimit("It's a new dawn, it's a new day, it's a new life for me, And I'm feelin' good", 15); // "It's a new dawn..."
strLimit("It's a new dawn, it's a new day, it's a new life for me, And I'm feelin' good", 15, ' (...)'); // "It's a new dawn (...)"

• str.lowerFirst / strLowerFirst (Source | Tests)

This function is an alias of the strLcfirst function.

• str.ltrim / strLtrim (Source | Tests)

Trim the left side (start) of a string of the given characters.

Signature

/**
 * @param {string} value - The target string
 * @param {string | string[]} [characters=[' ', '\t', '\r', '\n', '\r\n', '\f', '\v', '\0']] - The characters to be trimmed off
 * @returns {string}
 */
function strLtrim(
    value: string,
    characters: string | string[] = [' ', '\t', '\r', '\n', '\r\n', '\f', '\v', '\0']
): string;

Example

strLtrim(' yolo'); // 'yolo'
strLtrim('/yolo', '/'); // 'yolo'

• str.padBoth / strPadBoth (Source | Tests)

Pad both sides of a string with another.

This function adds padding to both sides of a string with another string until the final string reaches the desired length.

Signature

/**
 * @param {string} value - The string to add padding to
 * @param {number} length - The desired length the final string should reach
 * @param {string} [pad=' '] - The string to pad the current string with
 * @returns {string}
 */
function strPadBoth(value: string, length: number, pad: string = ' '): string;

Example

strPadBoth("Feelin' good", 17); // "  Feelin' good   "
strPadBoth("Feelin' good", 17, '*'); // "**Feelin' good***"

• str.parseCallback / strParseCallback (Source | Tests)

Parse a Class[@]method style callback into class and method.

Signature

/**
 * @param {string} callback - The string representing a "Class"
 * @param {string | null} [fallback=null] - The string representing a "method"
 * @returns {(string | null)[]}
 */
function strParseCallback(callback: string, fallback: string | null = null): (string | null)[];

Example

strParseCallback('Class@method', 'foo'); // ['Class', 'method']
strParseCallback('Class', 'foo'); // ['Class', 'foo']
strParseCallback('Class'); // ['Class', null]
strParseCallback('@method'); // ['', 'method']
strParseCallback('Class@method@hey', 'foo'); // ['Class', 'method']

• str.portion / strPortion (Source | Tests)

Get the portion of a string before the first/last occurrence of a given value, or return the remainder of a string after the first/last occurrence of a given value. The entire string will be returned if the value does not exist within the string.

Signature

/**
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @param {string} search - The value being searched for, otherwise known as the needle
 * @param {boolean} before - Should we get the portion of a string before or after a given value
 * @param {boolean} firstOccurrence - Should we get the first or the last occurence of the found value
 * @returns {string}
 */
function strPortion(subject: string, search: string, before: boolean, firstOccurrence: boolean): string;

Example

strPortion('hannah', 'n', true, true); // 'ha' | Same as: `strBefore('hannah', 'n');`
strPortion('yvette', 't', true, false); // 'yvet' | Same as: `strBeforeLast('yvette', 't');`
strPortion('hannah', 'n', false, true); // 'nah' | Same as: `strAfter('hannah', 'n');`
strPortion('yvette', 't', false, false); // 'e' | Same as: `strAfterLast('yvette', 't');`

• str.prepend / strPrepend (Source | Tests)

Prepend the given values to the string.

Signature

/**
 * @param {string} value - The string to prepend the values on
 * @param {string[]} ...values - The values to be prepended to the value
 * @returns {string}
 */
function strPrepend(value: string, ...values: string[]): string;

Example

strPrepend('world!', 'Hello', ' beautiful,', ' awesome,', ' incredible '); // 'Hello beautiful, awesome, incredible world!'

• str.random / strRandom (Source | Tests)

Generates a "pseudo" random string of the specified length. Note: This implementation uses Math.random under the hood.

Signature

/**
 * @param {number} [length=16] - The maximum characters to generate
 * @returns {string}
 */
function strRandom(length: number = 16): string;

Example

strRandom(); // Randomly generates a string similar to 'dabFOpWqY8utbKz9'
strRandom(20); // Randomly generates a string similar to 'trUmxY0iWjrhu1IKmkcT'

• str.remove / strRemove (Source | Tests)

Remove any occurrence of the given string in the subject.

Signature

/**
 * @param {string | string[]} search - The value being searched for, otherwise known as the needle
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @param {boolean} [caseSensitive=true] - Should the search be case-sensitive
 * @returns {string}
 */
function strRemove(search: string | string[], subject: string, caseSensitive: boolean = true): string;

Example

strRemove('e', 'Peter Piper picked a peck of pickled peppers.'); // 'Ptr Pipr pickd a pck of pickld ppprs.'

• str.replaceArray / strReplaceArray (Source | Tests)

Replace a given value in the string sequentially with an array.

Signature

/**
 * @param {string} search - The value being searched for, otherwise known as the needle
 * @param {string[]} replace - The replacement value that replaces found search values
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @returns {string}
 */
function strReplaceArray(search: string, replace: string[], subject: string): string;

Example

strReplaceArray('?', ['7:00', '15:30'], 'My flight spans from ? to ?'); // 'My flight spans from 7:00 to 15:30'

• str.replaceFirst / strReplaceFirst (Source | Tests)

Replace the first occurrence of a given value in the string.

Signature

/**
 * @param {string} search - The value being searched for, otherwise known as the needle
 * @param {string} replace - The replacement value that replaces found search values
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @returns {string}
 */
function strReplaceFirst(search: string, replace: string, subject: string): string;

Example

strReplaceFirst('father', 'dad', 'The father of the father is the grand-father'); // 'The dad of the father is the grand-father'

• str.replaceLast / strReplaceLast (Source | Tests)

Replace the last occurrence of a given value in the string.

Signature

/**
 * @param {string} search - The value being searched for, otherwise known as the needle
 * @param {string} replace - The replacement value that replaces found search values
 * @param {string} subject - The string being searched on, otherwise known as the haystack
 * @returns {string}
 */
function strReplaceLast(search: string, replace: string, subject: string): string;

Example

strReplaceLast('father', 'dad', 'The father of the father is the grand-father'); // 'The father of the father is the grand-dad'

• str.replaceMany / strReplaceMany (Source | Tests)

Replace all occurrences of the search string with the replacement string.

This function is inspired by PHP's "str_replace" function but has some key differences:

It doesn't throw an error when replace is not an array but search is
The 4th parameter is to control the casing but the 5th is to get the replace count
In order to get the replace count we must pass the function an object with a "value" property

Signature

/**
 * @param {string | string[]} search - The value being searched for, otherwise known as the needle
 * @param {string | string[]} replace - The replacement value that replaces found search values
 * @param {string | string[]} subject - The value being searched on, otherwise known as the haystack.
                                     If subject is an array, then the search and replace is performed with
                                     every entry of subject, and the return value is an array as well.
 * @param {boolean} [caseSensitive=true] - Should the search be case-sensitive
 * @param {Object} [replacedCount={ value: 0 }] - If passed, the value will be set to the number of replacements performed
 * @returns {string | string[]}
 */
function strReplaceMany(
    search: string | string[],
    replace: string | string[],
    subject: string | string[],
    caseSensitive: boolean = true,
    replacedCount: Object = { value: 0 }
): string | string[];

Example

strReplaceMany('o', '', 'Foobar'); // 'Fbar'
strReplaceMany(['o', 'a'], '', 'Foobar'); // 'Fbr'
strReplaceMany('o', ['x', '-'], 'Foobar'); // 'Fxxbar'
strReplaceMany(['o', 'a'], ['x', '-'], 'Foobar'); // 'Fxxb-r'
strReplaceMany(['B', ' '], ['#B', ''], 'Black Lives Matter'); // '#BlackLivesMatter'
strReplaceMany(['B', ' '], ['#B', ''], ['Black Lives Matter']); // ['#BlackLivesMatter']
strReplaceMany(['B', ' '], ['#B', ''], ['Black Lives Matter', 'Be Better Bruh']); // ['#BlackLivesMatter', '#Be#Better#Bruh']

• str.rtrim / strRtrim (Source | Tests)

Trim the right side (end) of a string of the given characters.

Signature

/**
 * @param {string} value - The target string
 * @param {string | string[]} [characters=[' ', '\t', '\r', '\n', '\r\n', '\f', '\v', '\0']] - The characters to be trimmed off
 * @returns {string}
 */
function strRtrim(
    value: string,
    characters: string | string[] = [' ', '\t', '\r', '\n', '\r\n', '\f', '\v', '\0']
): string;

Example

strRtrim('yolo '); // 'yolo'
strRtrim('yolo/', '/'); // 'yolo'

• str.sanitize / strSanitize (Source | Tests)

"Sanitize" a string. Only allow [a-zA-Z0-9] characters, plus "-" and "_".

Signature

/**
 * @param {string} value - The string to be converted
 * @returns {string}
 */
function strSanitize(value: string): string;

Example

strSanitize('abc~def#t--123@456à0'); // 'abcdeft--1234560'

• str.slug / strSlug (Source | Tests)

Generate a URL friendly "slug" from a given string.

Signature

/**
 * @param {string} value - The string to be converted
 * @param {string} [separator='-'] - A string used to separate each word
 * @returns {string}
 */
function strSlug(value: string, separator: string = '-'): string;

Example

strSlug('loL#LI_Pöp'); // 'lolli-pop'
strSlug('loL#LI-Pöp', '_'); // 'lolli_pop'
strSlug('loL@LI_Pöp'); // 'lol-at-li-pop'
strSlug('Will the real Slim Shady please stand up?'); // 'will-the-real-slim-shady-please-stand-up'

• str.snake / strSnake (Source | Tests)

Convert a string to "snake_case".

Signature

/**
 * @param {string} value - The string to be converted
 * @param {string} [delimiter='-'] - A string used to separate each word
 * @returns {string}
 */
function strSnake(value: string, delimiter: string = '-'): string;

Example

strSnake('loLL-i_pop'); // 'lo_l_l-i_pop'
strSnake('loLL-i_pop', '-'); // 'lo-l-l-i_pop'
strSnake('Will the real Slim Shady please stand up?'); // 'will_the_real_slim_shady_please_stand_up?'

• str.start / strStart (Source | Tests)

Begin a string with a single instance of a given value.

This function adds a single instance of the given value to a string if it does not already start with that value.

Signature

/**
 * @param {string} value - The target string
 * @param {string} prefix - The value the target should start with
 * @returns {string}
 */
function strStart(value: string, prefix: string): string;

Example

strStart('test/string', '/'); // '/test/string'
strStart('/test/string', '/'); // '/test/string'
strStart('//test/string', '/'); // '/test/string'

• str.startsWith / strStartsWith (Source | Tests)

Determine if a given string starts with a given substring.

Performs a case-sensitive check indicating if the haystack starts in any of the needles.

Signature

/**
 * @param {string} haystack - The string to search in
 * @param {string | string[]} needles - The substrings to be searched for at the start of haystack
 * @param {number} [position] - The position in haystack at which to begin searching for the needles
 * @returns {boolean}
 */
function strStartsWith(haystack: string, needles: string | string[], position?: number): boolean;

Example

strStartsWith('Get to the choppa', 'Get to'); // true
strStartsWith('Get to the choppa', 'get to'); // false
strStartsWith('Get to the choppa', ['Get to', 'nope']); // true
strStartsWith('Get to the choppa', 'Get to', 1); // false

• str.stripHtml / strStripHtml (Source | Tests)

Strip HTML tags from a string.

Signature

/**
 * @param {string} value - The value to be stripped out
 * @returns {string}
 */
function strStripHtml(value: string): string;

Example

strStripHtml('<div>Hey</div>'); // 'Hey'
strStripHtml('<b>sample</b> text with <div>tags</div>'); // 'sample text with tags'

• str.studly / strStudly (Source | Tests)

Convert a value to "StudlyCase".

Signature

/**
 * @param {string} value - The string to be converted
 * @returns {string}
 */
function strStudly(value: string): string;

Example

strStudly('loLL-i_pop'); // 'LoLLIPop'
strStudly('Will the real Slim Shady please stand up?'); // 'WillTheRealSlimShadyPleaseStandUp?'

• str.substrCount / strSubstrCount (Source | Tests)

Returns the number of substring occurrences.

Signature

/**
 * @param {string} haystack - The string to search in
 * @param {string} needle - The substring to search for
 * @param {number} [offset] - The offset where to start counting.
                             If the offset is negative, counting starts from the end of the string.
 * @param {number} [length] - The maximum length after the specified offset to search for the substring.
 * @returns {number}
 */
function strSubstrCount(haystack: string, needle: string, offset?: number, length?: number): number;

Example

strSubstrCount('You Only Live Once', 'o'); // 1

• str.title / strTitle (Source | Tests)

Convert the given string to "Title Case".

Signature

/**
 * @param {string} value - The string to be converted
 * @returns {string}
 */
function strTitle(value: string): string;

Example

strTitle('loLLIPop'); // 'Lollipop'
strTitle('Will the real Slim Shady please stand up?'); // 'Will The Real Slim Shady Please Stand Up?'

• str.trim / strTrim (Source | Tests)

Trim the string of the given characters.

Signature

/**
 * @param {string} value - The target string
 * @param {string | string[]} [characters=[' ', '\t', '\r', '\n', '\r\n', '\f', '\v', '\0']] - The characters to be trimmed off
 * @param {'left' | 'right' | 'both'} [side='both'] - The side of a string to be trimmed off
 * @returns {string}
 */
function strTrim(
    value: string,
    characters: string | string[] = [' ', '\t', '\r', '\n', '\r\n', '\f', '\v', '\0'],
    side: 'left' | 'right' | 'both' = 'both'
): string;

Example

strTrim(' yolo '); // 'yolo'
strTrim('/yolo/', '/'); // 'yolo'

• str.trimEnd / strTrimEnd (Source | Tests)

This function is an alias of the strRtrim function.

• str.trimStart / strTrimStart (Source | Tests)

This function is an alias of the strLtrim function.

• str.ucfirst / strUcfirst (Source | Tests)

Make a string's first character uppercase.

Signature

/**
 * @param {string} value - The target string
 * @returns {string}
 */
function strUcfirst(value: string): string;

Example

strUcfirst('victoria'); // 'Victoria'

• str.ucwords / strUcwords (Source | Tests)

Uppercase the first character of each word in a string.

Signature

/**
 * @param {string} value - The target string
 * @param {string | string[]} [separators=[' ', '\t', '\r', '\n', '\r\n', '\f', '\v']] - The characters used to separate words
 * @returns {string}
 */
function strUcwords(value: string, separators: string | string[] = [' ', '\t', '\r', '\n', '\r\n', '\f', '\v']): string;

Example

strUcwords('hello world!'); // 'Hello World!'
strUcwords('hello|world!'); // 'Hello|world!'
strUcwords('hello|world!', '|'); // 'Hello|World!'
strUcwords("mike o'hara"); // "Mike O'hara"
strUcwords("mike o'hara", "'"); // "Mike o'Hara"
strUcwords("mike o'hara", [' ', "'"]); // "Mike O'Hara"

• str.upperFirst / strUpperFirst (Source | Tests)

This function is an alias of the strUcfirst function.

• str.upperWords / strUpperWords (Source | Tests)

This function is an alias of the strUcwords function.

• str.when / strWhen (Source | Tests)

Apply the callback's string changes if the given "value" is truthy.

Signature

/**
 * @param {boolean | unknown} condition - Determine if the callback should be called
 * @param {unknown} instance - The target value
 * @param {function} callback - The function to be called upon the condition truthyness
 * @param {function} [fallback] - The function to be called upon the condition falsyness
 * @returns {unknown}
 */
function strWhen(condition: boolean | unknown, instance: unknown, callback: function, fallback?: function): unknown;

Example

strWhen(true, 'hello', (instance, condition) => {
    console.log(instance, condition); // 'hello', true
}); // 'hello'

strWhen(true, 'hello', (instance, condition) => {
    return 'bye';
}); // 'bye'

strWhen(
    false,
    'hello',
    (instance, condition) => {
        return 'bye';
    },
    (instance, condition) => {
        return 'from fallback';
    }
); // 'from fallback'

• str.whenEmpty / strWhenEmpty (Source | Tests)

Execute the given callback if the string is empty.

Signature

/**
 * @param {string} value - The value's emptyness to be checked
 * @param {unknown} instance - The target value
 * @param {function} callback - The function to be called when the string has a `length` of 0
 * @returns {unknown}
 */
function strWhenEmpty(value: string, instance: unknown, callback: function): unknown;

Example

strWhenEmpty('', 'hello', (instance) => {
    console.log(instance); // 'hello'
}); // 'hello'

strWhenEmpty('', 'hello', (instance) => {
    return 'bye';
}); // 'bye'

• str.words / strWords (Source | Tests)

Limit the number of words in a string.

Signature

/**
 * @param {string} value - The string to be truncated
 * @param {number} [words=100] - The maximum words
 * @param {string} [end='...'] - The string that will be appended to the end of the truncated string
 * @returns {string}
 */
function strWords(value: string, words: number = 100, end: string = '...'): string;

Example

strWords("It's a new dawn, it's a new day, it's a new life for me, And I'm feelin' good", 4); // "It's a new dawn, ..."
strWords("It's a new dawn, it's a new day, it's a new life for me, And I'm feelin' good", 4, ' (...)'); // "It's a new dawn, (...)"

Stringable

The Stringable class provides a more fluent and more readable syntax for working with string values; allowing you to chain multiple string operations together.

The Stringable class also extends the base String object and therefore has access to all the native string methods and properties and behaviors.

Example:

str('hello').length; // 5
str('hello') + ' world'; // 'hello world'
+str('7'); // 7

Note: It's important to note that some inherited methods may have been altered to either be a little more convenient or to simply return an instance of Stringable instead of String where appropriate. Read more.

`str*` methods mapping

All previously listed str* functions are available from the Stringable class, minus the str prefix.

Here's some quick mapping examples:

str('my string').prepend('This ', 'is ').raw(); // 'This is my string'
str('This is my string').slug('*').raw(); // 'this*is*my*string'
str(
    'Our ability to reach unity in diversity will be the beauty and the test of our civilization. ~Mahatma Gandhi'
).contains(['unity', 'diversity']); // true

Base `String` method overrides

As previously stated, some methods inherited from the base String object may have been overriden in order to be a little more convenient or to simply return an instance of Stringable instead of String where appropriate.

The following methods have the exact same behavior but return an instance or instances of Stringable:

charAt
concat
normalize
padEnd
padStart
repeat
replace
slice
split
substr
substring
toLocaleLowerCase
toLocaleUpperCase
toLowerCase
toUpperCase

The following methods have been sligthly altered and mapped to a corresponding str* function:

endsWith -> strEndsWith
startsWith -> strStartsWith
trim -> strTrim
trimEnd -> rtrim
trimStart -> ltrim

Own methods

The following methods are only available from a Stringable instance:

/**
 * Determine if the string is an exact match with the given value.
 */
exactly(value: string): boolean

/**
 * Determine if the given string is empty.
 */
isEmpty(): boolean

/**
 * Determine if the given string is not empty.
 */
isNotEmpty(): boolean

/**
 * Determine if the given string is empty after being trimmed.
 */
isBlank(): boolean

/**
 * Determine if the given string is not empty after being trimmed.
 */
isNotBlank(): boolean

/**
 * Determine if the given string is not empty after being trimmed.
 * @alias isNotBlank This method is an alias of the `isNotBlank` method.
 */
isFilled(): boolean

/**
 * Dump (console.log) the string.
 */
dump(): Stringable

/**
 * Dump (console.log) the string and end the script.
 */
dd(): void

/**
 * Convert the given string to lowercase.
 *
 * @alias toLowerCase This method is an alias of the `toLowerCase` method.
 */
lower(): Stringable

/**
 * Get the raw string value.
 */
raw(): string

/**
 * Convert the given string to uppercase.
 *
 * @alias toUpperCase This method is an alias of the `toUpperCase` method.
 */
upper(): Stringable

Contributing

If you're interested in contributing to the project, please read our contributing docs before submitting a pull request.

The "Available functions" portion of this README is generated by parsing each function's jsDoc.

License

The MIT License (MIT). Please see License File for more information.

@vicgutt/strjs

A set of JavaScript string helpers

Installation

Having access to the str* functions

Available functions

• str.after / strAfter (Source | Tests)

• str.afterLast / strAfterLast (Source | Tests)

• str.append / strAppend (Source | Tests)

• str.basename / strBasename (Source | Tests)

• str.before / strBefore (Source | Tests)

• str.beforeLast / strBeforeLast (Source | Tests)

• str.between / strBetween (Source | Tests)

• str.camel / strCamel (Source | Tests)

• str.contains / strContains (Source | Tests)

• str.containsAll / strContainsAll (Source | Tests)

• str.dirname / strDirname (Source | Tests)

• str.endsWith / strEndsWith (Source | Tests)

• str.escapeHtml / strEscapeHtml (Source | Tests)

• str.escapeHtmlComment / strEscapeHtmlComment (Source | Tests)

• str.finish / strFinish (Source | Tests)

• str.is / strIs (Source | Tests)

• str.isAscii / strIsAscii (Source | Tests)

• str.isUuid / strIsUuid (Source | Tests)

• str.kebab / strKebab (Source | Tests)

• str.lcfirst / strLcfirst (Source | Tests)

• str.limit / strLimit (Source | Tests)

• str.lowerFirst / strLowerFirst (Source | Tests)

• str.ltrim / strLtrim (Source | Tests)

• str.padBoth / strPadBoth (Source | Tests)

• str.parseCallback / strParseCallback (Source | Tests)

• str.portion / strPortion (Source | Tests)

• str.prepend / strPrepend (Source | Tests)

• str.random / strRandom (Source | Tests)

• str.remove / strRemove (Source | Tests)

• str.replaceArray / strReplaceArray (Source | Tests)

• str.replaceFirst / strReplaceFirst (Source | Tests)

• str.replaceLast / strReplaceLast (Source | Tests)

• str.replaceMany / strReplaceMany (Source | Tests)

• str.rtrim / strRtrim (Source | Tests)

• str.sanitize / strSanitize (Source | Tests)

• str.slug / strSlug (Source | Tests)

• str.snake / strSnake (Source | Tests)

• str.start / strStart (Source | Tests)

• str.startsWith / strStartsWith (Source | Tests)

• str.stripHtml / strStripHtml (Source | Tests)

• str.studly / strStudly (Source | Tests)

• str.substrCount / strSubstrCount (Source | Tests)

• str.title / strTitle (Source | Tests)

• str.trim / strTrim (Source | Tests)

• str.trimEnd / strTrimEnd (Source | Tests)

• str.trimStart / strTrimStart (Source | Tests)

• str.ucfirst / strUcfirst (Source | Tests)

• str.ucwords / strUcwords (Source | Tests)

• str.upperFirst / strUpperFirst (Source | Tests)

• str.upperWords / strUpperWords (Source | Tests)

• str.when / strWhen (Source | Tests)

• str.whenEmpty / strWhenEmpty (Source | Tests)

• str.words / strWords (Source | Tests)

Stringable

str* methods mapping

Base String method overrides

Own methods

Contributing

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Having access to the `str*` functions

`str*` methods mapping

Base `String` method overrides

Weekly Downloads