string-collapse-white-space^5.2.31

Efficient collapsing of white space with optional outer- and/or line-trimming and HTML tag recognition

Install globally, via npm

npm i string-collapse-white-space

The default is exported, so instead of "collapse" below, you can name the consumed function however you want.

Consume via a require():

const collapse = require("string-collapse-white-space");

or as an ES Module:

import collapse from "string-collapse-white-space";

Install as a script, via CDN

Put this in your HTML:

<script src="https://cdn.jsdelivr.net/npm/string-collapse-white-space/dist/string-collapse-white-space.umd.js">

Then, you’ll get a global variable stringCollapseWhiteSpace in your Global object and you consume it like this:

const collapse = stringCollapseWhiteSpace;

This collapse is your main function. See its API in the main section.

Trivia

This program has 11,548 assertions in its unit tests. That's more than all unit test assertions' median (52) and more than geometric mean (71).

In monorepo, one other package, string-collapse-white-space, consumes this package.

§ Quick Take

import { strict as assert } from "assert";
import collapse from "string-collapse-white-space";

assert.equal(
  collapse("  aaa     bbb    ccc   dddd  "),
  "aaa bbb ccc dddd"
);

assert.equal(
  collapse("   \t\t\t   aaa   \t\t\t   "),
  "aaa"
);

assert.equal(
  collapse("   aaa   bbb  \n    ccc   ddd   ", {
    trimLines: false,
  }),
  "aaa bbb \n ccc ddd"
);

assert.equal(
  collapse("   aaa   bbb  \n    ccc   ddd   ", {
    trimLines: true,
  }),
  "aaa bbb\nccc ddd"
);

// \xa0 is an unencoded non-breaking space:
assert.equal(
  collapse(
    "     \xa0    aaa   bbb    \xa0    \n     \xa0     ccc   ddd   \xa0   ",
    { trimLines: true, trimnbsp: true }
  ),
  "aaa bbb\nccc ddd"
);

⬆ back to top

§ Whitespace Collapsing

Take string. First trim the outsides, then collapse two and more spaces into one.

'    aaa    bbbb    ' -> 'aaa bbbb'

When trimming, any whitespace will be collapsed, including tabs, line breaks and so on. When collapsing, only spaces are collapsed. Non-space whitespace within text won't be collapsed.

'   \t\t\t   aaa     \t     bbbb  \t\t\t\t  ' -> 'aaa \t bbbb'

(Optional, on by default) Collapse more aggressively within recognised HTML tags:

'text <   span   >    contents   <  /  span   > more text' -> 'text <span> contents </span> more text'

(Optional, off by default) Trim each line:

'   aaa   \n   bbb   ' -> 'aaa\nbbb'

(Optional, off by default) Delete empty or whitespace-only rows:

'a\n\n\nb' -> 'a\nb'

⬆ back to top

§ API

collapse (string, [opts])

Input:

the first argument - string only or will throw.
the second argument - optional options object. Anything else than undefined, null or a plain object will throw.

⬆ back to top

§ Optional Options Object's API:

`options` object's key	Type	Obligatory?	Default	Description
`trimStart`	Boolean	no	`true`	if `false`, leading whitespace will be just collapsed. That might a single space, for example, if there are bunch of leading spaces.
`trimEnd`	Boolean	no	`true`	if `false`, trailing whitespace will be just collapsed.
`trimLines`	Boolean	no	`false`	if `true`, every line will be trimmed (spaces, tabs, line breaks of all kinds will be deleted, also non-breaking spaces, if `trimnbsp` is set to `true`)
`trimnbsp`	Boolean	no	`false`	when trimming, do we delete non-breaking spaces (if set to `true`, answer would be "yes"). This setting also affects `trimLines` setting above.
`recogniseHTML`	Boolean	no	`true`	if `true`, the space directly within recognised 118 HTML tag brackets will be collapsed tightly: `< div >` -> `<div>`. It will not touch any other brackets such as string `a > b`.
`removeEmptyLines`	Boolean	no	`false`	if any line can be trimmed to empty string, it will be removed.
`returnRangesOnly`	Boolean	no	`false`	if enabled, ranges array (array of arrays) or `null` (if there was nothing to collapse) will be returned instead
`limitConsecutiveEmptyLinesTo`	Natural number or zero	no	`0`	Set to 1 or more to allow that many blank lines between content

Defaults:

{
  trimStart: true, // otherwise, leading whitespace will be collapsed to a single space
  trimEnd: true, // otherwise, trailing whitespace will be collapsed to a single space
  trimLines: false, // activates trim per-line basis
  trimnbsp: false, // non-breaking spaces are trimmed too
  recogniseHTML: true, // collapses whitespace around HTML brackets
  removeEmptyLines: false, // if line trim()'s to an empty string, it's removed
  returnRangesOnly: false, // if on, only ranges array is returned
  limitConsecutiveEmptyLinesTo: 0 // zero lines are allowed (if opts.removeEmptyLines is on)
}

⬆ back to top

§ Algorithm

Traverse the string once, gather a list of ranges indicating white space indexes, delete them all in one go and return the new string.

This library traverses the string only once and performs the deletion only once. It recognises Windows, Unix and Linux line endings.

Optionally (on by default), it can recognise (X)HTML tags (any out of 118) and for example collapse < div.. → <div...

This algorithm does not use regexes.

⬆ back to top

§ Smart bits

There are some sneaky false-positive cases, for example:

Equations: a < b and c > d, for example.

Notice the part < b and c > almost matches the HTML tag description - it's wrapped with brackets, starts with legit HTML tag name (one out of 118, for example, b) and even space follows it. The current version of the algorithm will detect false-positives by counting amount of space, equal, double quote and line break characters within suspected tag (string part between the brackets).

The plan is: if there are spaces, this means this suspect tag has got attributes. In that case, there has to be at least one equal sign or equal count of unescaped double quotes. Otherwise, nothing will be collapsed/deleted from that particular tag.

⬆ back to top