@poppinss/string

A collection of helpers to perform operations on/related to a string value.

[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] [![license-image]][license-url]

Installation

Install the package from the npm package registry.

# Npm
npm i @poppinss/string

# Yarn
yarn add @poppinss/string

# Pnpm
pnpm add @poppinss/string

Usage

Import the package as follows to access the helpers.

import string from '@poppinss/string'

Table of Contents

• excerpt
  • OPTIONS
• truncate
  • OPTIONS
• slug
• interpolate
• toUnixSlash
• plural
• singular
• pluralize
• isPlural
• isSingular
• camelCase
  • EXAMPLES
• capitalCase
  • EXAMPLES
• dashCase
  • EXAMPLES
• dotCase
  • EXAMPLES
• noCase
  • EXAMPLES
• pascalCase
  • EXAMPLES
• sentenceCase
  • EXAMPLES
• snakeCase
  • EXAMPLES
• titleCase
  • EXAMPLES
• wordWrap
  • OPTIONS
• htmlEscape
  • EXAMPLES
• justify
• random
• uuid
• toSentence
• condenseWhitespace
• ordinal
• seconds.parse
• seconds.format
• milliseconds.parse
• milliseconds.format
• bytes.parse
• bytes.format
  • OPTIONS
• String builder
  • Contributing
  • Code of Conduct
  • License

excerpt

Generate an excerpt from content up to a certain length. If the input contains HTML tags, they will be stripped from the output.

import string from '@poppinss/string'

const html = `<p>AdonisJS is a Node.js framework, and hence it requires Node.js to be installed on your computer. To be precise, we need at least the latest release of <code>Node.js v14</code>.</p>`

console.log(string.excerpt(html, 70))
// AdonisJS is a Node.js framework, and hence it requires Node.js to be i...

OPTIONS

The following is the list of options you may provide as the 3rd parameter.

string.excerpt(html, 70, {
  completeWords: true,
  suffix: '<a href="">Read more</a>',
})

completeWords

When set to true, the truncation will occur only after complete words. This option might exceed the defined character limit.

suffix

Value to append after the truncated string. Defaults to three dots ....

truncate

Truncate a string value to a certain length. The method is the same as the excerpt method, but it does not remove any HTML tags.

import string from '@poppinss/string'

const text = `AdonisJS is a Node.js framework, and hence it requires Node.js to be installed on your computer. To be precise, we need at least the latest release of Node.js 14.`

console.log(string.truncate(text, 70))
// AdonisJS is a Node.js framework, and hence it requires Node.js to be i...

OPTIONS

Following is the list of options you may provide as the 3rd parameter.

string.truncate(text, 70, {
  completeWords: true,
  suffix: '<a href="">Read more</a>',
})

completeWords

When set to true, the truncation will occur only after complete words. This option might exceed the defined character limit.

suffix

Value to append after the truncated string. Defaults to three dots ....

slug

Generate a slug for a value.

The method is exported directly from the slugify package. Therefore, please check the package documentation for available options.

import string from '@poppinss/string'

console.log(string.slug('hello ♥ world'))
// hello-love-world

You can define custom replacements for Unicode values as follows.

import string from '@poppinss/string'

string.slug.extend({ '☢': 'radioactive' })
console.log(string.slug('unicode ♥ is ☢'))
// unicode-love-is-radioactive

interpolate

Interpolate variables specified inside double curly braces ({{}}).

import string from '@poppinss/string'

string.interpolate('hello {{ user.username }}', {
  user: { username: 'virk' },
})

// hello virk

You may replace array values using the array index.

import string from '@poppinss/string'

string.interpolate('hello {{ users.0 }}', { users: ['virk'] })

// hello virk

Curly braces can be escaped from interpolation using two backslashes ('\').

import string from '@poppinss/string'

string.interpolate('hello \\{{ users.0 }}', {})

// hello {{ users.0 }}

toUnixSlash

Convert OS-specific file paths to Unix file paths. Credits https://github.com/sindresorhus/slash

import string from '@poppinss/string'

const value = path.join('foo', 'bar')
// Unix    => foo/bar
// Windows => foo\\bar

string.toUnixSlash(value) // foo/bar

plural

Convert a word to its plural form. The method is exported directly from the pluralize package.

import string from '@poppinss/string'

string.plural('test')
// tests

singular

Convert a word to its singular form. The method is exported directly from the pluralize package.

import string from '@poppinss/string'

string.singular('tests')
// test

pluralize

Convert value to its plural or singular form based on the count.

import string from '@poppinss/string'

let errorsCount = 10
const message = `There ${string.pluralize('is', errorsCount)} ${errorsCount} ${string.pluralize('error', errorsCount)}`
// There are 10 errors

errorsCount = 1
// There is 1 error

// title: More examples
string.pluralize('box', 1) // box
string.pluralize('box', 2) // boxes
string.pluralize('box', 0) // boxes

string.pluralize('boxes', 1) // box
string.pluralize('boxes', 2) // boxes
string.pluralize('boxes', 0) // boxes

The addPluralRule, addSingularRule, addIrregularRule, and addUncountableRule methods exposed by the pluralize package can be used as follows.

string.pluralize.addUncountableRule('paper')
string.pluralize.addSingularRule(/singles$/i, 'singular')

isPlural

Find if a word is already in plural form. The method is exported directly from the pluralize package.

import string from '@poppinss/string'

string.isPlural('tests') // true

isSingular

Find if a word is already in a singular form. The method is exported directly from the pluralize package.

import string from '@poppinss/string'

string.isSingular('test') // true

camelCase

Convert value to camel case.

import string from '@poppinss/string'

string.camelCase('user_name') // userName

EXAMPLES

capitalCase

Convert value to capital case.

import string from '@poppinss/string'

string.capitalCase('helloWorld') // Hello World

EXAMPLES

dashCase

Convert value to dash case.

import string from '@poppinss/string'

string.dashCase('helloWorld') // hello-world

Optionally, you can capitalize the first letter of each word.

import string from '@poppinss/string'

string.dashCase('helloWorld', { capitalize: true }) // Hello-World

EXAMPLES

dotCase

Convert value to dot case.

import string from '@poppinss/string'

string.dotCase('helloWorld') // hello.World

Optionally, you can also convert the first letter of all the words to lowercase.

import string from '@poppinss/string'

string.dotCase('helloWorld', { lowerCase: true }) // hello.world

EXAMPLES

noCase

Remove all sorts of casing from a string value.

import string from '@poppinss/string'

string.noCase('helloWorld') // hello world

EXAMPLES

pascalCase

Convert value to pascal case.

import string from '@poppinss/string'

string.pascalCase('user team') // UserTeam

EXAMPLES

sentenceCase

Convert value to a sentence.

import string from '@poppinss/string'

string.sentenceCase('getting-started-with-adonisjs')
// Getting started with adonisjs

EXAMPLES

snakeCase

Convert value to snake case.

import string from '@poppinss/string'

string.snakeCase('user team') // user_team

EXAMPLES

titleCase

Convert value to title case.

import string from '@poppinss/string'

string.titleCase('small word ends on')
// Small Word Ends On

EXAMPLES

wordWrap

Wrap words in a sentence after a specific character count. The sentence is always split after a word finishes. Therefore, some lines may exceed or stay smaller than the provided length.

import string from '@poppinss/string'

const sentence = `Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.

It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged.

It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.`

const output = string.wordWrap(sentence, { width: 40 })

/**
Lorem Ipsum is simply dummy text of the
printing and typesetting industry. Lorem
Ipsum has been the industry's standard
dummy text ever since the 1500s, when an
unknown printer took a galley of type
and scrambled it to make a type specimen
book.

It has survived not only five centuries,
but also the leap into electronic
typesetting, remaining essentially
unchanged.

It was popularised in the 1960s with the
release of Letraset sheets containing
Lorem Ipsum passages, and more recently
with desktop publishing software like
Aldus PageMaker including versions of
Lorem Ipsum.
*/

You may also indent preceding lines with a given character. In the following example, we indent lines with 2 spaces.

const output = string.wordWrap(sentence, {
  width: 40,
  indent: '  ',
})

/**
Lorem Ipsum is simply dummy text of the
  printing and typesetting industry. Lorem
  Ipsum has been the industry's standard
  dummy text ever since the 1500s, when an
  unknown printer took a galley of type
  and scrambled it to make a type specimen
  book.

  It has survived not only five centuries,
  but also the leap into electronic
  typesetting, remaining essentially
  unchanged.

  It was popularised in the 1960s with the
  release of Letraset sheets containing
  Lorem Ipsum passages, and more recently
  with desktop publishing software like
  Aldus PageMaker including versions of
  Lorem Ipsum.
*/

OPTIONS

The following options can be specified as the 2nd parameter.

indent

Character(s) to use for indenting text after the first line

width

Number of characters after which to split the line

newLine

Specify the new line character to use for splitting lines. default=\n

escape

Specify a function to escape the contents. The method will be once for each line.

htmlEscape

Escape special characters in a string value, such that it can be used in HTML content. The ", ', &, <, and > characters are escaped.

import string from '@poppinss/string'

string.htmlEscape('&foo <> bar "fizz" l\'a')
// Output: &amp;foo &lt;&gt; bar &quot;fizz&quot; l&#39;a

EXAMPLES

justify

Justify the text of multiple columns as per the defined max-width. Columns smaller than the provided max width will be padded with empty spaces or the provided indent char.

import string from '@poppinss/string'

const output = string.justify(['help', 'serve', 'make:controller'], {
  width: 20,
})

/**
[
  'help                ',
  'serve               ',
  'make:controller     ',
]
*/

By default, the columns are left-aligned. However, they can also be right-aligned using the align option.

const output = string.justify(['help', 'serve', 'make:controller'], {
  width: 20,
  align: 'right',
})

/**
[
  '                help',
  '               serve',
  '     make:controller',
]
*/

If the columns contain ANSI escape sequences, you must specify a custom getLength method to compute the column length without counting the ANSI escape sequences.

import stringWidth from 'string-width'

const output = string.justify(['help', 'serve', 'make:controller'], {
  width: 20,
  align: 'right',
  /**
   * The `string-width` package returns the length of the string
   * without accounting for ANSI escape sequences
   */
  getLength: (chunk) => stringWidth(chunk),
})

random

Generate a cryptographically secure random string of a given length. The output value is a URL-safe base64-encoded string.

import string from '@poppinss/string'

string.random(32)
// 8mejfWWbXbry8Rh7u8MW3o-6dxd80Thk

You can replace the random generator using the random.use method and restore the original implementation using the random.restore method.

// Custom generator
string.random.use((size) => {
  return 'a'.repeat(size)
})

string.random(10) // aaaaaaaaaa

// Restore original implementation
string.random.restore()

uuid

Generate a UUID v4 value. The uuid method uses the crypto.randomUUID under the hood. However, it does allow you to replace the original implementation with a custom method.

import string from '@poppinss/string'

string.uuid()
// 1a7989bf-a176-42fb-97ef-1368f2466027

// Custom generator
string.uuid.use(() => {
  return 'xxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
})

string.uuid() // 'xxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

// Restore original implementation
string.uuid.restore()

toSentence

Convert an array of words to a comma-separated sentence.

import string from '@poppinss/string'

string.toSentence(['routes', 'controllers', 'middleware'])
// routes, controllers, and middleware

You can replace the and with an or by specifying the options.lastSeparator property.

import string from '@poppinss/string'

string.toSentence(['routes', 'controllers', 'middleware'], {
  lastSeparator: ', or ',
})

In the following example, the two words are combined using the and separator, not the comma. However, you can use a custom separator for a pair of words.

import string from '@poppinss/string'

string.toSentence(['routes', 'controllers'])
// routes and controllers

string.toSentence(['routes', 'controllers'], {
  pairSeparator: ', and ',
})
// routes, and controllers

condenseWhitespace

Replace multiple whitespaces in a string with a single whitespace.

import string from '@poppinss/string'

string.condenseWhitespace('hello  world')
// hello world

string.condenseWhitespace('  hello  world  ')
// hello world

ordinal

Get the ordinal letter for a given number.

import string from '@poppinss/string'

string.ordinal(1) // 1st
string.ordinal(2) // '2nd'
string.ordinal(3) // '3rd'
string.ordinal(4) // '4th'

string.ordinal(23) // '23rd'
string.ordinal(24) // '24th'

seconds.parse

Parse a human-readable time expression to seconds. If the unit value is a number, it will be returned as it is. Otherwise, the string expression will be converted to a number representing seconds. An Error is thrown when the input cannot be parsed.

import string from '@poppinss/string'

string.seconds.parse('10h') // 36000
string.seconds.parse('1 day') // 86400

string.seconds.parse(180) // 180

You can enforce strict time expression using the PrettyTime type.

import string from '@poppinss/string'
import { PrettyTime } from '@poppinss/string/types'

function toSeconds(value: PrettyTime) {
  return string.seconds.parse(value)!
}

toSeconds('1 hour') // works
toSeconds('1hr') // works
toSeconds('1 heure') // type error

seconds.format

Formats seconds to a human-readable string value.

import string from '@poppinss/string'

string.seconds.format(36000) // 10h
string.seconds.format(36000, true) // 10 hours

milliseconds.parse

Parse a human-readable time expression to milliseconds. If the unit value is a number, it will be returned as it is. Otherwise, the string expression will be converted to a number representing milliseconds. An Error is thrown when the input cannot be parsed.

import string from '@poppinss/string'

string.milliseconds.parse('1 h') // 3.6e6
string.milliseconds.parse('1 day') // 8.64e7

string.milliseconds.parse(180) // 180

milliseconds.format

Formats milliseconds to a human-readable string value.

import string from '@poppinss/string'

string.milliseconds.format(3.6e6) // 1h
string.milliseconds.format(3.6e6, true) // 1 hour

bytes.parse

Parse a human-readable string expression to bytes. If the unit value is a number, it will be returned as it is. Otherwise, the string expression will be converted to a number representing bytes. A null value is returned when the input cannot be parsed.

Supported units and abbreviations are as follows and are case-insensitive:

• b for bytes
• kb for kilobytes
• mb for megabytes
• gb for gigabytes
• tb for terabytes
• pb for petabytes

import string from '@poppinss/string'

string.bytes.parse('1KB') // 1024
string.bytes.parse('1MB') // 1048576

You can enforce strict bytes expression using the PrettyBytes type.

import string from '@poppinss/string'
import { PrettyBytes } from '@poppinss/string/types'

function toBytes(value: PrettyBytes) {
  return string.bytes.parse(value)!
}

toBytes('1 KB') // works
toBytes('1 kilobytes') // type error

bytes.format

Formats bytes to a human-readable string value. When input cannot be formatted, the null value is returned.

import string from '@poppinss/string'

string.bytes.format(1048576) // 1MB
string.bytes.format(1024 _ 1024 _ 1000) // 1000MB
string.bytes.format(1024 _ 1024 _ 1000, { thousandsSeparator: ',' }) // 1,000MB

string.bytes.format(1048576, { unitSeparator: ' ' }) // 1 MB
string.bytes.format(1048576, { unit: 'KB' }) // 1024KB

OPTIONS

decimalPlaces

A maximum number of decimal places to include in the output. default=2.

fixedDecimals

Whether to always display the maximum number of decimal places. default=false.

thousandsSeparator

Specify the separator for thousands. default=''.

unit

The unit in which the result will be returned. It could be B/KB/MB/GB/TB. The default behavior is to auto-detect based on the input.

unitSeparator

The separator between the value and the unit. default=''.

String builder

The string builder offers a fluent API for applying a set of transforms on a string value. You can create an instance of the string builder as follows.

import StringBuilder from '@poppinss/string/builder'
const builder = new StringBuilder('userController')

const value = builder
  .removeSuffix('controller') // user
  .plural() // users
  .snakeCase() // users
  .suffix('_controller') // users_controller
  .ext('ts') // users_controller.ts
  .toString()

assert(value === 'users_controller.ts')

Contributing

One of the primary goals of Poppinss is to have a vibrant community of users and contributors who believe in the principles of the framework.

Before contributing to the framework, we encourage you to read the contribution guide.

Code of Conduct

To ensure that the Poppinss community is welcoming to all, please review and abide by the Code of Conduct.

License

Poppinss string is open-sourced software licensed under the MIT license.

[gh-workflow-url]: https://github.com/poppinss/string/actions/workflows/checks.yml 'Github action'

[npm-url]: https://npmjs.org/package/@poppinss/string 'npm'

[license-url]: LICENSE.md 'license'