truncateString

A function to shorten strings with options.

Table of contents

• Install
• How to use
• API
  • string
  • length
  • options
    • appendix
    • cutChars
    • threshold
    • trim
    • verbose
• Dev Notes
• License

Install

$ npm install truncatestring --save

How to use

Importing:

// ES5 Minified
var truncateString = require('truncatestring');

// ES5 Non-Minified
var truncateString = require('truncatestring/dist/truncateString');

// ES2015
import truncateString from 'truncatestring/src/truncateString';

Minimal usage:

truncateString('Lorem ipsum dolor est sit amet!', 8);
// => "Lorem ip…"

Usage with default options:

truncateString('Lorem ipsum dolor est sit amet!', 8, {
  appendix: '…',
  cutChars: [],
  threshold: 8, // Default equals second parameter
  trim: true,
  verbose: false
});
// => "Lorem ip…"

API

truncateString(string, length, [options])

string

Type: string

The string to shorten.

length

Type: number

The length to shorten the string to. If string.length is smaller or equal to length (or options.threshold) it will be returned without any modification. If string.length is larger than length it will be cropped to have the length of length (can change slightly if options.cutChars is used). Before returning an ellipsis (…) will be appended to it (See options.appendix).

options

Type: object

(Optional) This object can contain some options to change the way the string is shortened.

options.appendix

Type: string

Can be any string to append to a shortened string. By default it is an ellipsis (…).

options.cutChars

Type: string or array of single chars

By default, the string is cut at the positon length without checking if the cut will slice right through a word. You can prevent word-slicing by defining chars as markers where cuts are allowed. In most cases this would just be a space:

truncateString('Lorem ipsum-dolor sit.', 8, { cutChars: ' ' });
// => "Lorem…"

truncateString('Lorem ipsum-dolor sit.', 15, { cutChars: ' ' });
// => "Lorem ipsum-dolor…"

So, what happend here? The intended cut in the first case would be Lorem ip/sum-dolor sit.. That cut is closer to the space between "Lorem" and "ipsum" than it is to the space between "dolor" and "sit", so the cut is moved to the left space. In the second example the intended cut Lorem ipsum-dol/or sit. is closer to the space on its right, so the cut is made there.

You can also pass an array of chars like so:

truncateString('Lorem ipsum-dolor sit.', 10, { cutChars: [' ', '-'] });
// => "Lorem ipsum-…"

The same rules apply here but with more chars that mark potential cut-positons.

The intended cut Lorem ipsu/m-dolor sit. is moved to the closest char. In this case it is the dash to its right. Note, that the char that was marking the cut-position is not removed. The cut-position-char will stay attached to the returned string.

The space in the first two examples was removed because option.trim is true by default.

Doing this will preserve the space:

truncateString('Lorem ipsum-dolor sit.', 8, { cutChars: ' ', trim: false });
// => "Lorem …"

options.threshold

Type: number

By default options.threshold equals the length parameter. If options.threshold differs from length, string.length has to surpass options.threshold to then be cut of to the length.

With this you can make sure to cut off a reasonable amount from the string.

Consider this:

truncateString('I am a tiny sentence.', 20);
// => "I am a tiny sentence…"

The string is just one char to long (21) and just the period is cut off, replaced by an ellipsis. You may want to prevent those cases. So you can do this:

truncateString('I am a tiny sentence.', 20, { threshold: 30 });
// => "I am a tiny sentence."

The strings length is lower than 30, so it will be returned unchanged even if it is longer than the length.

truncateString('I am a tiny sentence.', 10, { threshold: 20 });
// => "I am a tin…"

The strings length is 21, so the threshold is surpassed and the string is shortened to the length of 10, cutting of a reasonable amount.

options.trim

Type: boolean

This is true by default and will trim all spaces after the cut was made at the cut off end of the string. The untouched ends of the string will stay as they were.

Normal use-case:

truncateString('Lorem ipsum', 6);
// => "Lorem…"

truncateString('Lorem ipsum', 6, { trim: false });
// => "Lorem …"

And with a couple extra spaces, 'cause why not?

truncateString('  Lorem   ipsum  ', 10);
// => "  Lorem…"

truncateString('  Lorem   ipsum  ', 10, { trim: false });
// => "  Lorem   …"

options.verbose

Type: boolean

By default this is false and the return value of this function will always be a string.

If this is true though, the return value will be an object with more information about the result. It will contain the following properties:

| key | type | value | |-------------- |--------------------| --------------| | result | string | The string that would have been returned if options.verbose was false. | | parts | array of strings | If the string was not cut, this contains the string as its only item. If the string was cut into two parts, this will contain those two parts of the string without an appendix. | | wasCut | boolean | If a cut was made, this is true, otherwise false. |

Dev notes

Fork this repo and run:

$npm install

Then work in src/truncateString.js and then run:

$npm run build

This will do some linting, transpile (to dist/truncateString.js), minify (to dist/truncateString.min.js) and run tests (on the dist/truncateString.min.js).

Make sure that all Tests are successful and check the coverage/index.html for 100% test-coverage.

Also, no dependencies, please! devDependencies are OK of course.

License

MIT © Michael Janssen