Module strings

General-purpose string operations.

Declaring Text and Markdown Content

Record whether a string carries markup, either as a type annotation on an API or as a template tag that also realigns the literal:

import { markdown, text, type Markdown, type Text } from '@metreeca/core/strings';

function describe(label: Text, notes: Markdown): void { }

describe(text`
    one
      two
`, markdown`
    # Title

    Body
`);
Copy

Clipping Text

Shorten a string to a budget of code points, leaving an ellipsis to report that content was dropped, so that a value quoted in a log entry or a diagnostic message can't overrun it:

import { clip } from '@metreeca/core/strings';

clip("a very long value", 8); // "a very …"
Copy

Tidying Whitespace

Collapse the whitespace of a string to single spaces and drop what sits at either end, either folding the whole string to the single line a label or a message expects, or tidying each line on its own where the line structure matters:

import { tidy } from '@metreeca/core/strings';

tidy(`
    one
      two
`);       // "one two"

tidy(`
    one
      two
`, true); // "one\ntwo"
Copy

Splitting Separated Values

Break a string into the values it lists, tidying the whitespace of each and dropping the empty ones stray separators leave behind, taking the values to be separated by whitespace or by a separator of your own:

import { split } from '@metreeca/core/strings';

split("one  two\nthree");           // ["one", "two", "three"]
split("one, two  x ,, three", ","); // ["one", "two x", "three"]
Copy

Filling Template Placeholders

Complete a template from values computed elsewhere, replacing each {key} placeholder with the value a record or a lookup function assigns to its key, percent-encoding what must travel safely inside a URL and leaving #-marked placeholders unfilled for a later pass:

import { fill } from '@metreeca/core/strings';

fill("hello {name}", { name: "world" });    // "hello world"
fill("/search?q=%{term}", { term: "a b" }); // "/search?q=a%20b"
fill("#{name}={name}", { name: "value" });  // "{name}=value"
Copy

Dedenting Indented Text

Remove the leading whitespace shared by every non-blank line of a block of text, either as a plain function or as a template tag:

import { dedent } from '@metreeca/core/strings';

dedent(`
    one
      two
`); // "one\n  two"

dedent`
    one
      two
`; // "one\n  two"
Copy

Escaping Text for String Literals

Rewrite as escapes the characters a JSON string literal may not carry, ready to sit between quotation marks, or target a syntax of your own by supplying the pattern that selects the characters and the short forms it defines:

import { escape } from '@metreeca/core/strings';

escape("line\nbreak"); // the break is rewritten as a two-character escape
escape("a\uD800b");    // the isolated surrogate is rewritten as a four-digit escape

escape("a😀b", /\P{ASCII}/gu);                         // the emoji takes the eight-digit form
escape("a<b", /[<>]/gu, { "<": "&lt;", ">": "&gt;" }); // the angle brackets take the supplied short forms
Copy

Matching Names Against Glob Patterns

Decide whether a slash-separated name matches a wildcard pattern, taking ? for a single character, * for a run within one segment and ** for a run across segments, with everything else read literally:

import { glob } from '@metreeca/core/strings';

glob("*.txt").test("notes.txt");        // true
glob("*.txt").test("docs/notes.txt");   // false
glob("docs/**").test("docs/notes.txt"); // true
Copy

Checking and Repairing UTF-16 Text

Report whether a string is well-formed UTF-16 text, free of the isolated surrogates that denote no Unicode character, or replace those surrogates with the Unicode replacement character:

import { isWellFormed, toWellFormed } from '@metreeca/core/strings';

isWellFormed("a😀");     // true
isWellFormed("a\uD800"); // false

toWellFormed("a\uD800"); // "a\uFFFD"
Copy