atomic-fns 1.1.7 → 2.0.0

package/dist/string/index.js

@@ -1,229 +1,9 @@
 /**
- * This module includes utilities for working with strings.
- *
+ * String helpers: `words`, the case converters `camelCase`, `pascalCase`, `snakeCase`,
+ * `kebabCase`, `startCase` and `capitalize`, and `deburr`, `slugify` and `truncate`.
  * @module string
  */
-const WORDS_REGEX = // eslint-disable-next-line no-control-regex
- /[A-Z\xc0-\xd6\xd8-\xde]?[a-z\xdf-\xf6\xf8-\xff]+(?:['’](?:d|ll|m|re|s|t|ve))?(?=[\xac\xb1\xd7\xf7\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xbf\u2000-\u206f \t\x0b\f\xa0\ufeff\n\r\u2028\u2029\u1680\u180e\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u202f\u205f\u3000]|[A-Z\xc0-\xd6\xd8-\xde]|$)|(?:[A-Z\xc0-\xd6\xd8-\xde]|[^\ud800-\udfff\xac\xb1\xd7\xf7\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xbf\u2000-\u206f \t\x0b\f\xa0\ufeff\n\r\u2028\u2029\u1680\u180e\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u202f\u205f\u3000\d+\u2700-\u27bfa-z\xdf-\xf6\xf8-\xffA-Z\xc0-\xd6\xd8-\xde])+(?:['’](?:D|LL|M|RE|S|T|VE))?(?=[\xac\xb1\xd7\xf7\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xbf\u2000-\u206f \t\x0b\f\xa0\ufeff\n\r\u2028\u2029\u1680\u180e\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u202f\u205f\u3000]|[A-Z\xc0-\xd6\xd8-\xde](?:[a-z\xdf-\xf6\xf8-\xff]|[^\ud800-\udfff\xac\xb1\xd7\xf7\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xbf\u2000-\u206f \t\x0b\f\xa0\ufeff\n\r\u2028\u2029\u1680\u180e\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u202f\u205f\u3000\d+\u2700-\u27bfa-z\xdf-\xf6\xf8-\xffA-Z\xc0-\xd6\xd8-\xde])|$)|[A-Z\xc0-\xd6\xd8-\xde]?(?:[a-z\xdf-\xf6\xf8-\xff]|[^\ud800-\udfff\xac\xb1\xd7\xf7\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xbf\u2000-\u206f \t\x0b\f\xa0\ufeff\n\r\u2028\u2029\u1680\u180e\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u202f\u205f\u3000\d+\u2700-\u27bfa-z\xdf-\xf6\xf8-\xffA-Z\xc0-\xd6\xd8-\xde])+(?:['’](?:d|ll|m|re|s|t|ve))?|[A-Z\xc0-\xd6\xd8-\xde]+(?:['’](?:D|LL|M|RE|S|T|VE))?|\d*(?:1ST|2ND|3RD|(?![123])\dTH)(?=\b|[a-z_])|\d*(?:1st|2nd|3rd|(?![123])\dth)(?=\b|[A-Z_])|\d+|(?:[\u2700-\u27bf]|(?:\ud83c[\udde6-\uddff]){2}|[\ud800-\udbff][\udc00-\udfff])[\ufe0e\ufe0f]?(?:[\u0300-\u036f\ufe20-\ufe2f\u20d0-\u20ff]|\ud83c[\udffb-\udfff])?(?:\u200d(?:[^\ud800-\udfff]|(?:\ud83c[\udde6-\uddff]){2}|[\ud800-\udbff][\udc00-\udfff])[\ufe0e\ufe0f]?(?:[\u0300-\u036f\ufe20-\ufe2f\u20d0-\u20ff]|\ud83c[\udffb-\udfff])?)*/g;
-/**
- * Converts only the first character of the given string to upper case. Note that the rest of the characters are preserved.
- * @param {string} s The string
- * @returns {string} Returns the sentence string.
- * @example
-```js
-sentenceCase('a test')
-// 'A test'
-
-sentenceCase('TEST')
-// 'TEST'
-```
- * @see {@link capitalize}
- */
-export function sentenceCase(s) {
-    return `${(s[0] || '').toLocaleUpperCase()}${s.substring(1) || ''}`;
-}
-/**
- * Converts the first character of the given string to upper case and the rest to lower case.
- * @param {string} s The string to capitalize
- * @returns {string} Returns the capitalized string.
- * @example
-```js
-capitalize('TEST')
-// 'Test'
-```
- * @see {@link titleCase}
- */
-export function capitalize(s) {
-    return `${(s[0] || '').toLocaleUpperCase()}${(s.substring(1) || '').toLocaleLowerCase()}`;
-}
-/**
- * Split a string into an array of its words.
- * @param {string} s The string to split
- * @param {RegExp | string} [pattern] The pattern to match words
- * @returns {string[]} Returns the words array.
- * @example
-```js
-words('lord of the rings')
-// ['lord', 'of', 'the', 'rings']
-```
- */
-export function words(s, pattern) {
-    if (pattern != null)
-        return s.split(pattern);
-    return s.match(WORDS_REGEX) || [];
-}
-/**
- * Create a new string which is the concatenation of the words in the given input.
- * @param {string} s The string to join
- * @param {string} [sep=' '] The separator to use
- * @returns {string} Returns the joined string.
- * @example
-```js
-join('Lord Of The Rings', '-')
-// 'Lord-Of-The-Rings'
-```
- */
-export function join(s, sep = ' ') {
-    return words(s).join(sep);
-}
-/**
- * Checks if a string contains only alphanumeric characters.
- * @param {string} s The string
- * @returns {boolean} Returns `true` if the string contains only alphanumeric.
- * @example
-```js
-isAlnum('alpha1234')
-// true
-
-isAlnum('oops!')
-// false
-```
- */
-export function isAlnum(s) {
-    return /^[\p{L}\p{N}]+$/gu.test(s);
-}
-/**
- * Checks if a string contains only alphabetic characters.
- * @param {string} s The string
- * @returns {boolean} Returns `true` if the string contains only alphabetic.
- * @example
-```js
-isAlpha('alpha1234')
-// false
-
-isAlpha('letters')
-// true
-```
- */
-export function isAlpha(s) {
-    return /^[\p{L}]+$/gu.test(s);
-}
-/**
- * Checks if a string contains only numeric characters.
- * @param {string} s The string
- * @returns {boolean} Returns `true` if the string contains only numeric.
- * @example
-```js
-isNumeric('alpha1234')
-// false
-
-isNumeric('1234')
-// true
-```
- */
-export function isNumeric(s) {
-    return /^[\p{N}]+$/gu.test(s);
-}
-/**
- * Returns a new string with only valid ASCII characters
- * @param {string} s The string
- * @returns {string} The ASCII characters in the given string
- * @example
-```js
-asciify('äÄçÇéÉêPHP-MySQLöÖÐþúÚ')
-// 'PHP-MySQL'
-```
- */
-export function asciify(s) {
-    // eslint-disable-next-line no-control-regex
-    return s.replace(/[^\x00-\x7F]/g, '');
-}
-/**
- * Replaces any accent characters in the string with non accents.
- * @param {string} s The string
- * @returns {string} The new string without accents
- * @example
-```js
-removeAccents('Antoine de Saint-Exupéry')
-// 'Antoine de Saint-Exupery'
-```
- */
-export function removeAccents(s) {
-    return s.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
-}
-/**
- * Capitalizes the first letter of every word in the string.
- * @param {string} s The string to capitalize
- * @returns {string} Returns the title cased string.
- * @example
-```js
-titleCase('lord of the rings')
-// 'Lord Of The Rings'
-```
-@see {@link capitalize}
- */
-export function titleCase(s) {
-    return words(s)
-        .map((word) => capitalize(word))
-        .join(' ');
-}
-/**
- * Converts the string to camel case.
- * @param {string} s The string to convert
- * @returns {string} Returns the camel cased string.
- * @example
-```js
-camelCase('Equipment class name')
-// 'equipmentClassName'
-```
- */
-export function camelCase(s) {
-    return words(s).reduce((acc, next) => `${acc}${!acc ? next.toLowerCase() : next[0].toUpperCase() + next.slice(1).toLowerCase()}`, '');
-}
-/**
- * Converts the string to Pascal case.
- * @param {string} s The string to convert
- * @returns {string} Returns the Pascal cased string.
- * @example
-```js
-pascalCase('equipment class name')
-// 'EquipmentClassName'
-```
- */
-export function pascalCase(s) {
-    return sentenceCase(camelCase(s));
-}
-/**
- * Converts the string to snake case.
- * @param {string} s The string to convert
- * @returns {string} Returns the snake cased string.
- * @example
-```js
-snakeCase('Equipment Class Name')
-// 'equipment_class_name'
-```
- */
-export function snakeCase(s) {
-    return join(s, '_').toLowerCase();
-}
-/**
- * Converts a string to kebab case.
- * @param {string} s The string
- * @returns {string} Returns the kebab cased string.
- * @example
-```js
-kebabCase('Equipment Class Name')
-// 'equipment-class-name'
-
-kebabCase('equipment_class_name')
-// 'equipment-class-name'
-```
- */
-export function kebabCase(s) {
-    return join(s, '-').toLowerCase();
-}
-/**
- * Returns a url-safe slug for the given string. Note that by default it will preserve any capitalization in the given string.
- * @param {string} s The string
- * @returns {string} A url-safe slug version of the string
- * @example
-```js
-slugify('Antoine de Saint-Exupéry')
-// 'Antoine-de-Saint-Exupery'
-```
- */
-export function slugify(s) {
-    const slug = join(removeAccents(s), '-');
-    const urlSafe = slug.replace(/[^a-zA-Z0-9-_]/g, '');
-    return urlSafe;
-}
+export { camelCase, capitalize, kebabCase, pascalCase, snakeCase, startCase } from './case.js';
+export { deburr, slugify } from './fold.js';
+export { truncate } from './truncate.js';
+export { words } from './words.js';

package/dist/string/truncate.d.ts

@@ -0,0 +1,25 @@
+/** Options for {@link truncate}. */
+export interface TruncateOptions {
+    /**
+     * Most graphemes in the result, `omission` included (default 30), unless `omission` alone is
+     * at least as long, in which case the result is `omission`.
+     */
+    length?: number;
+    /** What marks the cut (default `'...'`). */
+    omission?: string;
+}
+/**
+ * Shortens a string to at most `length` graphemes, ending with `omission` when it cuts. Lengths
+ * count user-perceived characters, so an emoji family or a letter with its marks is never split.
+ * When `omission` alone is at least as long as `length`, the result is `omission`, as in lodash.
+ * @param s The string to shorten.
+ * @param options `length` and `omission`.
+ * @returns The shortened string.
+ * @throws {RangeError} when `length` is not a non-negative integer.
+ * @example
+ * ```ts
+ * truncate('hi-diddly-ho there, neighborino', { length: 24 }) // 'hi-diddly-ho there, n...'
+ * truncate('👨‍👩‍👧👨‍👩‍👧👨‍👩‍👧', { length: 2, omission: '' }) // '👨‍👩‍👧👨‍👩‍👧'
+ * ```
+ */
+export declare function truncate(s: unknown, options?: TruncateOptions): string;

package/dist/string/truncate.js

@@ -0,0 +1,44 @@
+/**
+ * Grapheme-safe truncation on `Intl.Segmenter`.
+ * @module
+ */
+import { toText } from '../internal/text.js';
+/** Lazy: Intl.Segmenter at module load fails where Intl is incomplete. */
+let graphemeSegmenter;
+function getGraphemeSegmenter() {
+    graphemeSegmenter ??= new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+    return graphemeSegmenter;
+}
+/**
+ * Shortens a string to at most `length` graphemes, ending with `omission` when it cuts. Lengths
+ * count user-perceived characters, so an emoji family or a letter with its marks is never split.
+ * When `omission` alone is at least as long as `length`, the result is `omission`, as in lodash.
+ * @param s The string to shorten.
+ * @param options `length` and `omission`.
+ * @returns The shortened string.
+ * @throws {RangeError} when `length` is not a non-negative integer.
+ * @example
+ * ```ts
+ * truncate('hi-diddly-ho there, neighborino', { length: 24 }) // 'hi-diddly-ho there, n...'
+ * truncate('👨‍👩‍👧👨‍👩‍👧👨‍👩‍👧', { length: 2, omission: '' }) // '👨‍👩‍👧👨‍👩‍👧'
+ * ```
+ */
+export function truncate(s, options) {
+    const text = toText(s);
+    const length = options?.length ?? 30;
+    const omission = toText(options?.omission ?? '...');
+    if (!Number.isSafeInteger(length) || length < 0) {
+        throw new RangeError('length must be a non-negative integer');
+    }
+    const segmenter = getGraphemeSegmenter();
+    const keep = Math.max(length - [...segmenter.segment(omission)].length, 0);
+    let count = 0;
+    let cut = 0;
+    for (const { index } of segmenter.segment(text)) {
+        if (count === keep)
+            cut = index;
+        if (++count > length)
+            return text.slice(0, cut) + omission;
+    }
+    return text;
+}

package/dist/string/words.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Unicode-aware word splitting on `Intl.Segmenter` with identifier case rules.
+ * @module
+ */
+declare function fromSegments(s: string): string[];
+/** Word extraction forced through Intl.Segmenter, for path-equivalence tests. */
+export { fromSegments as segmenterWords };
+/**
+ * Splits a string into words. Without `pattern`, it uses `Intl.Segmenter` word boundaries plus
+ * identifier case rules: `fooBar` and `HTTPServer` split at case changes, ordinals (`11th`) and
+ * plural acronyms (`IDs`) stay whole, digits split from letters, emoji stay whole, and bidi
+ * controls separate words. With a `pattern`, every match of it is a word, even when the pattern
+ * is not global, and capture groups are ignored; lodash returns only the first match and its
+ * groups for a non-global pattern. A `null` pattern means no pattern, where lodash matches
+ * `'null'`. `null` and `undefined` read as `''`, and other values go through `String`.
+ * @param s The string to split.
+ * @param pattern A regular expression that matches each word.
+ * @throws {TypeError} When `pattern` is neither a `RegExp` nor `null` or `undefined`.
+ * @returns The words, in order.
+ * @example
+ * ```ts
+ * words('fooBar_baz qux') // ['foo', 'Bar', 'baz', 'qux']
+ * words('HTTPServer2xx') // ['HTTP', 'Server', '2', 'xx']
+ * words('fred, barney, & pebbles', /[^, ]+/g) // ['fred', 'barney', '&', 'pebbles']
+ * ```
+ */
+export declare function words(s: unknown, pattern?: RegExp | null): string[];

package/dist/string/words.js

@@ -0,0 +1,241 @@
+/**
+ * Unicode-aware word splitting on `Intl.Segmenter` with identifier case rules.
+ * @module
+ */
+import { isAsciiString, toText } from '../internal/text.js';
+/** Lazy: Intl.Segmenter at module load fails where Intl is incomplete. */
+let wordSegmenter;
+function getWordSegmenter() {
+    wordSegmenter ??= new Intl.Segmenter(undefined, { granularity: 'word' });
+    return wordSegmenter;
+}
+const IS_UPPER = /^[\p{Lu}\p{Lt}]$/u;
+const IS_LOWER = /^\p{Ll}$/u;
+const IS_OTHER_LETTER = /^[\p{Lo}\p{Lm}]$/u;
+const IS_NUMBER = /^\p{N}$/u;
+/** Format characters the segmenter keeps inside a word, but that must not reach a slug or key. */
+const IS_BIDI_CONTROL = /^[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]$/u;
+const IS_MARK_OR_FORMAT = /^[\p{M}\p{Cf}]$/u;
+const HAS_LETTER_OR_NUMBER = /[\p{L}\p{N}]/u;
+const ZWJ_EMOJI = /\u200D\p{ExtPict}/u;
+const RGI_EMOJI_AT = /\p{RGI_Emoji}/vy;
+const COMBINING_ENCLOSING_KEYCAP = 0x20e3;
+const ORDINAL_LOWER = new Set(['st', 'nd', 'rd', 'th']);
+const ORDINAL_UPPER = new Set(['ST', 'ND', 'RD', 'TH']);
+function isAsciiDigit(code) {
+    return code >= 0x30 && code <= 0x39;
+}
+function classifyAscii(cp) {
+    if (cp >= 0x41 && cp <= 0x5a)
+        return 'U';
+    if (cp >= 0x61 && cp <= 0x7a)
+        return 'L';
+    if (isAsciiDigit(cp))
+        return 'D';
+    if (cp === 0x27)
+        return 'A';
+    return 'X';
+}
+function classifyNonAscii(ch) {
+    if (ch === '\u2019')
+        return 'A';
+    if (IS_UPPER.test(ch))
+        return 'U';
+    if (IS_LOWER.test(ch))
+        return 'L';
+    if (IS_OTHER_LETTER.test(ch))
+        return 'O';
+    if (IS_NUMBER.test(ch))
+        return 'D';
+    if (IS_BIDI_CONTROL.test(ch))
+        return 'X';
+    if (IS_MARK_OR_FORMAT.test(ch))
+        return 'K';
+    return 'X';
+}
+/** ASCII takes a few compares; only the regexp-based non-ASCII classes are worth caching. */
+function classifyCp(cp, cache) {
+    if (cp < 0x80)
+        return classifyAscii(cp);
+    let cls = cache.get(cp);
+    if (cls === undefined) {
+        cls = classifyNonAscii(String.fromCodePoint(cp));
+        cache.set(cp, cls);
+    }
+    return cls;
+}
+/** The code point at UTF-16 index `i`, which the caller keeps below `s.length`. */
+function codePointAt(s, i) {
+    return s.codePointAt(i);
+}
+/** The class of the code point at UTF-16 index `i`, or `undefined` past the end. */
+function classAt(s, i, cache) {
+    return i < s.length ? classifyCp(codePointAt(s, i), cache) : undefined;
+}
+function isLetter(cls) {
+    return cls === 'U' || cls === 'L' || cls === 'O';
+}
+/** `IDs`, `APIs`: an `s` at `sIndex`, then the end, a non-letter or a new capital. */
+function isPluralAcronym(s, sIndex, cache) {
+    if (s[sIndex] !== 's')
+        return false;
+    const afterCls = classAt(s, sIndex + 1, cache);
+    return afterCls === undefined || !isLetter(afterCls) || afterCls === 'U';
+}
+/** `11th`, `1stPlace`, `1ST`: an ordinal suffix at `start`, then the end, a non-letter or a capital. */
+function isOrdinalSuffix(s, start, cache) {
+    const two = s.slice(start, start + 2);
+    const lower = ORDINAL_LOWER.has(two);
+    if (!lower && !ORDINAL_UPPER.has(two))
+        return false;
+    const afterCls = classAt(s, start + 2, cache);
+    return afterCls === undefined || !isLetter(afterCls) || (afterCls === 'U' && lower);
+}
+/** A camel boundary right after a mid-word apostrophe strands it; it belongs to neither word. */
+function endBeforeApostrophe(s, end) {
+    const last = s[end - 1];
+    return last === "'" || last === '\u2019' ? end - 1 : end;
+}
+/**
+ * Splits one word-like run at case and letter-digit changes, keeping ordinals, plural acronyms
+ * and digit keycaps whole. Walks UTF-16 indices, so it allocates only the words.
+ */
+function splitRun(s, cache) {
+    const out = [];
+    let wordStart = -1;
+    let prev;
+    let prevStart = -1;
+    let i = 0;
+    const flush = (end) => {
+        if (wordStart >= 0 && end > wordStart)
+            out.push(s.slice(wordStart, end));
+        wordStart = -1;
+        prev = undefined;
+    };
+    while (i < s.length) {
+        const cp = codePointAt(s, i);
+        const end = i + (cp > 0xffff ? 2 : 1);
+        const cls = classifyCp(cp, cache);
+        if (cls === 'K') {
+            if (cp === COMBINING_ENCLOSING_KEYCAP &&
+                prev === 'D' &&
+                isAsciiDigit(s.charCodeAt(prevStart))) {
+                // The segmenter puts `1️⃣2️⃣` in one Numeric segment; each keycap is its own word.
+                flush(prevStart);
+                out.push(s.slice(prevStart, end));
+            }
+            // A mark extends the current word; after a flush it has no word to attach to and is dropped.
+            i = end;
+            continue;
+        }
+        if (cls === 'X') {
+            flush(i);
+            i = end;
+            continue;
+        }
+        if (cls === 'A') {
+            const nextCls = classAt(s, end, cache);
+            // Mid-word apostrophe: wordStart is already set whenever prev is a letter.
+            if (!(prev !== undefined && isLetter(prev) && nextCls !== undefined && isLetter(nextCls))) {
+                flush(i);
+            }
+            i = end;
+            continue;
+        }
+        let boundary = false;
+        if (prev !== undefined) {
+            if ((prev === 'L' || prev === 'O') && cls === 'U') {
+                boundary = true;
+            }
+            else if (prev === 'U' && cls === 'U') {
+                boundary = classAt(s, end, cache) === 'L' && !isPluralAcronym(s, end, cache);
+            }
+            else if (isLetter(prev) && cls === 'D') {
+                boundary = true;
+            }
+            else if (prev === 'D' && isLetter(cls)) {
+                boundary = !isOrdinalSuffix(s, i, cache);
+            }
+        }
+        if (boundary)
+            flush(endBeforeApostrophe(s, i));
+        if (wordStart < 0)
+            wordStart = i;
+        prev = cls;
+        prevStart = i;
+        i = end;
+    }
+    flush(s.length);
+    return out;
+}
+/** Steps one emoji at a time: `\p{RGI_Emoji}+` overflows the regexp stack on a long segment. */
+function isRgiEmojiRun(s) {
+    RGI_EMOJI_AT.lastIndex = 0;
+    while (RGI_EMOJI_AT.lastIndex < s.length) {
+        if (!RGI_EMOJI_AT.test(s))
+            return false;
+    }
+    return true;
+}
+function fromSegments(s) {
+    const out = [];
+    const cache = new Map();
+    const pushWords = (run) => {
+        for (const part of splitRun(run, cache))
+            out.push(part);
+    };
+    const pushEmoji = (run) => {
+        if (isRgiEmojiRun(run))
+            out.push(run);
+    };
+    const pushNonWord = (segment) => {
+        if (!HAS_LETTER_OR_NUMBER.test(segment)) {
+            pushEmoji(segment);
+            return;
+        }
+        // ICU glues `word ZWJ emoji` into one segment and calls it non-word-like.
+        const glue = segment.search(ZWJ_EMOJI);
+        pushWords(glue < 0 ? segment : segment.slice(0, glue));
+        if (glue >= 0)
+            pushEmoji(segment.slice(glue + 1));
+    };
+    for (const { segment, isWordLike } of getWordSegmenter().segment(s)) {
+        if (isWordLike)
+            pushWords(segment);
+        else if (segment.length > 1 || segment.charCodeAt(0) > 0x7f)
+            pushNonWord(segment);
+    }
+    return out;
+}
+/** Word extraction forced through Intl.Segmenter, for path-equivalence tests. */
+export { fromSegments as segmenterWords };
+/**
+ * Splits a string into words. Without `pattern`, it uses `Intl.Segmenter` word boundaries plus
+ * identifier case rules: `fooBar` and `HTTPServer` split at case changes, ordinals (`11th`) and
+ * plural acronyms (`IDs`) stay whole, digits split from letters, emoji stay whole, and bidi
+ * controls separate words. With a `pattern`, every match of it is a word, even when the pattern
+ * is not global, and capture groups are ignored; lodash returns only the first match and its
+ * groups for a non-global pattern. A `null` pattern means no pattern, where lodash matches
+ * `'null'`. `null` and `undefined` read as `''`, and other values go through `String`.
+ * @param s The string to split.
+ * @param pattern A regular expression that matches each word.
+ * @throws {TypeError} When `pattern` is neither a `RegExp` nor `null` or `undefined`.
+ * @returns The words, in order.
+ * @example
+ * ```ts
+ * words('fooBar_baz qux') // ['foo', 'Bar', 'baz', 'qux']
+ * words('HTTPServer2xx') // ['HTTP', 'Server', '2', 'xx']
+ * words('fred, barney, & pebbles', /[^, ]+/g) // ['fred', 'barney', '&', 'pebbles']
+ * ```
+ */
+export function words(s, pattern) {
+    const text = toText(s);
+    if (pattern != null) {
+        if (!(pattern instanceof RegExp))
+            throw new TypeError('words expects pattern to be a RegExp');
+        const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
+        return Array.from(text.matchAll(new RegExp(pattern.source, flags)), (match) => match[0]);
+    }
+    // On ASCII the segmenter breaks only where splitRun splits too, so ASCII text skips it.
+    return isAsciiString(text) ? splitRun(text, new Map()) : fromSegments(text);
+}