string-process-comma-separated^4.0.3

Installation

Quick Take

Purpose

Imagine, you need to extract and validate 50% and 50% of HTML attribute values: <FRAMESET rows="50%, 50%">.

The first algorithm idea seems simple:

str
  .split(",")
  .forEach(oneOfValues => {
    ...
  })

But in real life, the proper extraction is quite complex and you need to cover all error cases:

• There might be surrounding whitespace <FRAMESET rows=" 50%, 50% ">
• There might be spaces after the comma — it might be OK or not — <FRAMESET rows=" 50%, 50% ">
• Plain errors like leading comma — <FRAMESET rows=" ,, 50%, 50% ">
• There might be non-space characters that look like space like NBSP

This program helps to extract chunks of strings from potentially comma-separated list of string (it might be a single value, without commas).

Separator is configurable via opts.separator, so it might be not comma if you wish.

Errors are pinged to a separate callback function.

Usage

Same thing like in Array.forEach, we use callbacks, which allows you to tailor what happens with the values that the program gives you.

Here is quite a contrived example, too crazy to be real, but it shows the capabilities of the algorithm:

Instead of expected,

<frameset rows="50%,50%"></frameset>

we have:

<frameset rows=" ,,\t50% ,    50% ,\t\t,"></frameset>

The program above extracts both values 50% (string index ranges are fed to the callback, [20, 23] and [27, 30]) and reports all rogue spaces, tabs, non-breaking space and commas.

This program saves you time from having to tackle all those possible error cases: rogue separators, consecutive separators and spaces.

API — processCommaSep()

The main function processCommaSep() is imported like this:

It’s a function which takes three input arguments:

The Obligatory Options Object has the following shape:

The main thing — you must pass the callbacks in the options object, cb and errCb:

The function will return undefined because it has a callback API.

API — opts.cb

opts is a plain object. Its key’s cb value must be a function.

Like in the example above — processCommaSeparated is a function, the second argument is the options object. Below, we set an arrow function to be cb value (you could pass a “normal”, declared function as well).

const gatheredChunks = [];
...
processCommaSeparated(
  `<FRAMESET...`,
  {
    ...
    cb: (idxFrom, idxTo) => {
      gatheredChunks.push([idxFrom, idxTo]);
    },
    ...
  }
);

The program will pass two arguments to the callback function you pass:

For example, if you passed the whole string abc,def (we assume it’s whole HTML attribute’s value, already extracted) and didn’t give opts.from and opts.to and thus, program traversed the whole string, it would ping your callback function with two ranges: [0, 3] and [4, 7]. Full code:

import { processCommaSep } from "string-process-comma-separated";
const gatheredChunks = [];
processCommaSeparated("abc,def", {
  cb: (idxFrom, idxTo) => {
    gatheredChunks.push([idxFrom, idxTo]);
  },
});
console.log(JSON.stringify(gatheredChunks, null, 4));
// => [
//      [0, 3],
//      [4, 7]
//    ],

We omitted the error callback for brevity (opts.errCb, see its API below), here would be no errors anyway.

API — opts.errCb

Similar to opts.cb, here two arguments are passed into the callback function, only this time first one is ranges, second-one is message string.

import { processCommaSep } from "string-process-comma-separated";
const gatheredChunks = [];
const gatheredErrors = [];
processCommaSep(`<FRAMESET rows="50%, 50%">`, {
  from: 16,
  to: 24,
  cb: (idxFrom, idxTo) => {
    gatheredChunks.push([idxFrom, idxTo]);
  },
  errCb: (ranges, message) => {
    gatheredErrors.push({ ranges, message });
  },
});
console.log(JSON.stringify(gatheredChunks, null, 4));
// => [
//      [16, 19],
//      [21, 24]
//    ]
console.log(JSON.stringify(gatheredErrors, null, 4));
// => [
//      {
//        ranges: [[20, 21]],
//        message: "Remove the whitespace."
//      }
//    ]

A quick primer on ranges — each range is an array of two or three elements. First two match String.slice indexes. If an optional third is present, it means what to add instead. Two element range array — only deletion. Three element range array — replacement.

We have made more range processing libraries.

opts.innerWhitespaceAllowed

Sometimes comma-separated values are keywords — then we don’t want to allow any whitespace between characters:

<input accept=".jpg,.g if,.png">
                      ^

But sometimes it’s fine, like in media queries:

<link rel="stylesheet" media="screen and (max-width: 100px)" href="zzz.css" />
                                                    ^

Setting opts.innerWhitespaceAllowed by default doesn’t allow inner whitespace within split chunk but you can turn it off.

API — version

You can import version:

Changelog