Have ideas to improve npm?Join in the discussion! »

    truncatestring

    2.2.0 • Public • Published

    truncateString

    A function to shorten strings with options.

    Table of contents

    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

    Install

    npm i truncatestring

    DownloadsWeekly Downloads

    10

    Version

    2.2.0

    License

    MIT

    Last publish

    Collaborators

    • avatar