§ Quick Take

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

  collapse("  aaa     bbb    ccc   dddd  ").result,
  "aaa bbb ccc dddd"

  collapse("   \t\t\t   aaa   \t\t\t   ").result,

  collapse("   aaa   bbb  \n    ccc   ddd   ", {
    trimLines: false,
  "aaa bbb \n ccc ddd"

  collapse("   aaa   bbb  \n    ccc   ddd   ", {
    trimLines: true,
  "aaa bbb\nccc ddd"

// \xa0 is an unencoded non-breaking space:
    "     \xa0    aaa   bbb    \xa0    \n     \xa0     ccc   ddd   \xa0   ",
    { trimLines: true, trimnbsp: true }
  "aaa bbb\nccc ddd"

§ Examples


collapse(str, [opts])

In other words, it's a function which takes two input arguments, second-one being optional (marked by square brackets).

§ API - Input

Input argumentTypeObligatory?Description
strStringyesSource string to work upon
optsSomething falsy or a Plain objectnoThe Optional Options Object, see below for its API

§ API - Output

Function returns a plain object, for example:

result: "abc click me def",
ranges: [
[3, 6, " "],
[14, 18, " "],

It has the following keys:

Key's nameKey value's typeDescription
resultStringThe string output where all ranges were applied to it.
rangesranges: an array of one or more arrays containing from-to string index ranges OR nullFor example, if characters from index 0 to 5 and 30 to 35 were deleted, that would be [[0, 5], [30, 35]]. Another example, if nothing was found, it would put here null.

§ Optional Options Object

opts is a plain object. Here are all its keys:

options object's keyTypeObligatory?DefaultDescription
trimStartBooleannotrueif false, leading whitespace will be just collapsed.
trimEndBooleannotrueif false, trailing whitespace will be just collapsed.
trimLinesBooleannofalseif true, every line will be trimmed (all whitespace characters except line breaks CR and LF will be deleted, also non-breaking spaces will be deleted, if trimnbsp is set to true)
trimnbspBooleannofalsewhen trimming, do we delete non-breaking spaces (if set to true, answer would be "yes"). This setting also affects trimLines setting above.
removeEmptyLinesBooleannofalseif any line can be trimmed to empty string, it will be removed.
limitConsecutiveEmptyLinesToNatural number or zerono0Set to 1 or more to allow that many blank lines between content
enforceSpacesOnlyBooleannofalseIf enabled, not only consecutive space character chunks will be collapsed but any whitespace character chunks (except line breaks).
cbFunctionnosee belowAll output and every whitespace chunk (including single spaces) is fed to it. Whatever you return, gets written to resulting ranges.

Here is the Optional Options Object in one place (in case you ever want to copy it whole):

trimStart: true,
trimEnd: true,
trimLines: false,
trimnbsp: false,
removeEmptyLines: false,
limitConsecutiveEmptyLinesTo: 0,
enforceSpacesOnly: false,
cb: ({ suggested, whiteSpaceStartsAt, whiteSpaceEndsAt, str }) => suggested,

§ opts.cb

This program implements a callback interface - every reported range is fed to the callback. The default callback is ({ suggested }) => suggested but you can tweak it.

See examples.

When nothing is to be removed, callback will ping suggested key value as null. You can still return any string index range and it will be deleted (array of two elements) or replaced (array of three elements). Learn more about ranges notation.

§ Changelog

See it in the monorepo opens in a new tab, on GitHub.

§ Contributing

To report bugs or request features or assistance, raise an issue on GitHub opens in a new tab.

Any code contributions welcome! All Pull Requests will be dealt promptly.

§ Licence

MIT opens in a new tab

Copyright © 2010–2021 Roy Revelt and other contributors

Related packages:

📦 detergent 7.1.0
Extracts, cleans and encodes text
📦 string-uglify 1.5.0
Shorten sets of strings deterministically, to be git-friendly
📦 string-convert-indexes 4.1.0
Convert between native JS string character indexes and grapheme-count-based indexes
📦 string-apostrophes 1.5.0
Comprehensive, HTML-entities-aware tool to typographically-correct the apostrophes and single/double quotes
📦 string-fix-broken-named-entities 5.4.0
Finds and fixes common and not so common broken named HTML entities, returns ranges array of fixes
📦 string-overlap-one-on-another 2.1.0
Lay one string on top of another, with an optional offset
📦 string-split-by-whitespace 2.1.0
Split string into array by chunks of whitespace