atomic-fns 1.2.0 → 2.0.0

package/dist/string/case.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Converts a string to camel case: the words of {@link words}, without apostrophes, the first
+ * lowercased and each later one with its first code point uppercased.
+ * @param s The string to convert.
+ * @returns The camel-cased string.
+ * @example
+ * ```ts
+ * camelCase('Foo Bar') // 'fooBar'
+ * camelCase('--foo-bar--') // 'fooBar'
+ * ```
+ */
+export declare function camelCase(s: unknown): string;
+/**
+ * Converts a string to Pascal case: as {@link camelCase}, with the first word capitalized too.
+ * Each first code point is uppercased, as lodash's `upperFirst` does, not titlecased: `džemal`
+ * becomes `DŽemal`.
+ * @param s The string to convert.
+ * @returns The Pascal-cased string.
+ * @example
+ * ```ts
+ * pascalCase('foo bar') // 'FooBar'
+ * ```
+ */
+export declare function pascalCase(s: unknown): string;
+/**
+ * Converts a string to snake case: the lowercased words joined with `_`.
+ * @param s The string to convert.
+ * @returns The snake-cased string.
+ * @example
+ * ```ts
+ * snakeCase('fooBar') // 'foo_bar'
+ * ```
+ */
+export declare function snakeCase(s: unknown): string;
+/**
+ * Converts a string to kebab case: the lowercased words joined with `-`.
+ * @param s The string to convert.
+ * @returns The kebab-cased string.
+ * @example
+ * ```ts
+ * kebabCase('fooBar') // 'foo-bar'
+ * ```
+ */
+export declare function kebabCase(s: unknown): string;
+/**
+ * Converts a string to start case: the words joined with spaces, each with its first code point
+ * uppercased and the rest kept, as lodash does. Uppercased, not titlecased: `džemal` becomes
+ * `DŽemal`, where {@link capitalize} gives `Džemal`.
+ * @param s The string to convert.
+ * @returns The start-cased string.
+ * @example
+ * ```ts
+ * startCase('--foo-bar--') // 'Foo Bar'
+ * startCase('fooBar') // 'Foo Bar'
+ * startCase('__FOO_BAR__') // 'FOO BAR'
+ * ```
+ */
+export declare function startCase(s: unknown): string;
+/**
+ * Converts the first code point to Unicode title case and the rest to lower case. Digraphs take
+ * their titlecase form (`dž` becomes `Dž`), and a final sigma lowercases in context. The mapping is
+ * the locale-independent Unicode default, so the result is the same on every host.
+ * @param s The string to capitalize.
+ * @returns The capitalized string.
+ * @example
+ * ```ts
+ * capitalize('FRED') // 'Fred'
+ * capitalize('džemal') // 'Džemal'
+ * ```
+ */
+export declare function capitalize(s: unknown): string;

package/dist/string/case.js

@@ -0,0 +1,152 @@
+import { toText } from '../internal/text.js';
+import { words } from './words.js';
+/** The words of `s` without apostrophes, as lodash's compound converters read them. */
+function toParts(s) {
+    return words(s).map((w) => w.replace(/['’]/g, ''));
+}
+/** The lowercased words of `s` joined with `separator`. */
+function joinLower(s, separator) {
+    return toParts(s)
+        .map((w) => w.toLowerCase())
+        .join(separator);
+}
+/** Uppercases the part's first code point and lowercases the rest, so `dž` and `İ` stay one letter. */
+function upperFirstLowerRest(part) {
+    const [first = ''] = part;
+    return first.toUpperCase() + part.toLowerCase().slice(first.toLowerCase().length);
+}
+/**
+ * Converts a string to camel case: the words of {@link words}, without apostrophes, the first
+ * lowercased and each later one with its first code point uppercased.
+ * @param s The string to convert.
+ * @returns The camel-cased string.
+ * @example
+ * ```ts
+ * camelCase('Foo Bar') // 'fooBar'
+ * camelCase('--foo-bar--') // 'fooBar'
+ * ```
+ */
+export function camelCase(s) {
+    return toParts(s)
+        .map((w, i) => (i === 0 ? w.toLowerCase() : upperFirstLowerRest(w)))
+        .join('');
+}
+/**
+ * Converts a string to Pascal case: as {@link camelCase}, with the first word capitalized too.
+ * Each first code point is uppercased, as lodash's `upperFirst` does, not titlecased: `džemal`
+ * becomes `DŽemal`.
+ * @param s The string to convert.
+ * @returns The Pascal-cased string.
+ * @example
+ * ```ts
+ * pascalCase('foo bar') // 'FooBar'
+ * ```
+ */
+export function pascalCase(s) {
+    return toParts(s).map(upperFirstLowerRest).join('');
+}
+/**
+ * Converts a string to snake case: the lowercased words joined with `_`.
+ * @param s The string to convert.
+ * @returns The snake-cased string.
+ * @example
+ * ```ts
+ * snakeCase('fooBar') // 'foo_bar'
+ * ```
+ */
+export function snakeCase(s) {
+    return joinLower(s, '_');
+}
+/**
+ * Converts a string to kebab case: the lowercased words joined with `-`.
+ * @param s The string to convert.
+ * @returns The kebab-cased string.
+ * @example
+ * ```ts
+ * kebabCase('fooBar') // 'foo-bar'
+ * ```
+ */
+export function kebabCase(s) {
+    return joinLower(s, '-');
+}
+/**
+ * Converts a string to start case: the words joined with spaces, each with its first code point
+ * uppercased and the rest kept, as lodash does. Uppercased, not titlecased: `džemal` becomes
+ * `DŽemal`, where {@link capitalize} gives `Džemal`.
+ * @param s The string to convert.
+ * @returns The start-cased string.
+ * @example
+ * ```ts
+ * startCase('--foo-bar--') // 'Foo Bar'
+ * startCase('fooBar') // 'Foo Bar'
+ * startCase('__FOO_BAR__') // 'FOO BAR'
+ * ```
+ */
+export function startCase(s) {
+    return toParts(s)
+        .map((part) => {
+        const [first = ''] = part;
+        return first.toUpperCase() + part.slice(first.length);
+    })
+        .join(' ');
+}
+/** Unicode titlecase forms, keyed by lowercase, that no uppercase or range rule can derive. */
+const TITLECASE_FIRST = Object.freeze({
+    '\u0149': '\u02BCN',
+    '\u01C6': '\u01C5',
+    '\u01C9': '\u01C8',
+    '\u01CC': '\u01CB',
+    '\u01F3': '\u01F2',
+    '\u1FB2': '\u1FBA\u0345',
+    '\u1FB3': '\u1FBC',
+    '\u1FB4': '\u0386\u0345',
+    '\u1FB7': '\u0391\u0342\u0345',
+    '\u1FC2': '\u1FCA\u0345',
+    '\u1FC3': '\u1FCC',
+    '\u1FC4': '\u0389\u0345',
+    '\u1FC7': '\u0397\u0342\u0345',
+    '\u1FF2': '\u1FFA\u0345',
+    '\u1FF3': '\u1FFC',
+    '\u1FF4': '\u038F\u0345',
+    '\u1FF7': '\u03A9\u0342\u0345'
+});
+/** Georgian Mkhedruli has an uppercase (Mtavruli), but a letter's titlecase is itself. */
+const IS_MKHEDRULI = /^[\u10D0-\u10FF]$/;
+/** Greek letters with ypogegrammeni (U+1F80-U+1FAF): each titlecase form is the lowercase plus 8. */
+const YPOGEGRAMMENI_FIRST = 0x1f80;
+const YPOGEGRAMMENI_LAST = 0x1faf;
+const YPOGEGRAMMENI_TITLECASE_OFFSET = 8;
+function titleCaseFirstChar(ch) {
+    if (IS_MKHEDRULI.test(ch))
+        return ch;
+    const lower = ch.toLowerCase();
+    const listed = TITLECASE_FIRST[lower];
+    if (listed !== undefined)
+        return listed;
+    const cp = lower.codePointAt(0);
+    if (cp !== undefined && cp >= YPOGEGRAMMENI_FIRST && cp <= YPOGEGRAMMENI_LAST) {
+        return String.fromCodePoint(cp + YPOGEGRAMMENI_TITLECASE_OFFSET);
+    }
+    const upper = ch.toUpperCase();
+    // Multi-char uppercase (e.g. ß -> SS): titlecase is first upper + rest lower.
+    return upper.length > 1 ? upper[0] + upper.slice(1).toLowerCase() : upper;
+}
+/**
+ * Converts the first code point to Unicode title case and the rest to lower case. Digraphs take
+ * their titlecase form (`dž` becomes `Dž`), and a final sigma lowercases in context. The mapping is
+ * the locale-independent Unicode default, so the result is the same on every host.
+ * @param s The string to capitalize.
+ * @returns The capitalized string.
+ * @example
+ * ```ts
+ * capitalize('FRED') // 'Fred'
+ * capitalize('džemal') // 'Džemal'
+ * ```
+ */
+export function capitalize(s) {
+    const text = toText(s);
+    const [first = ''] = text;
+    // Lowercasing the whole string lets a final sigma see the letter before it.
+    const rest = text.toLowerCase().slice(first.toLowerCase().length);
+    return `${titleCaseFirstChar(first)}${rest}`;
+}

package/dist/string/fold.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Removes accents from Latin letters with a subset of the Unicode CLDR Latin-ASCII transform:
+ * combining marks after Latin letters and digits, and the common letter folds (`ß` to `ss`,
+ * `Æ` to `AE`, `ø` to `o`). Marks on other scripts and variation selectors stay (`й`, `が`,
+ * `1️⃣`), the result is NFC, and a run of marks is cut to 30 so normalizing stays linear.
+ * @param s The string to fold.
+ * @returns The folded string.
+ * @example
+ * ```ts
+ * deburr('déjà vu') // 'deja vu'
+ * deburr('Œuvre ß ø') // 'OEuvre ss o'
+ * ```
+ */
+export declare function deburr(s: unknown): string;
+/** Options for {@link slugify}. */
+export interface SlugifyOptions {
+    /** Lowercase the slug (default `true`); `false` keeps the case of the input. */
+    lower?: boolean;
+}
+/**
+ * Returns a URL slug: {@link deburr}, lowercased unless `lower` is `false`, default-ignorable
+ * code points (soft hyphen, ZWNJ, variation selectors, Hangul fillers) and apostrophes inside
+ * words dropped, then runs of Unicode letters, marks and digits joined with `-`. Letters of other
+ * scripts stay.
+ * @param s The string to slugify.
+ * @param options `lower`.
+ * @returns The slug.
+ * @example
+ * ```ts
+ * slugify('Antoine de Saint-Exupéry') // 'antoine-de-saint-exupery'
+ * slugify("Don't Stop", { lower: false }) // 'Dont-Stop'
+ * slugify('Café Привет') // 'cafe-привет'
+ * ```
+ */
+export declare function slugify(s: unknown, options?: SlugifyOptions): string;

package/dist/string/fold.js

@@ -0,0 +1,100 @@
+import { isAsciiString, toText } from '../internal/text.js';
+/** Letter folds from a subset of the Unicode CLDR Latin-ASCII transform. */
+const CLDR_LATIN_ASCII_FOLDS = Object.freeze({
+    '\u00C6': 'AE',
+    '\u00D0': 'D',
+    '\u00D8': 'O',
+    '\u00DE': 'TH',
+    '\u00DF': 'ss',
+    '\u00E6': 'ae',
+    '\u00F0': 'd',
+    '\u00F8': 'o',
+    '\u00FE': 'th',
+    '\u0110': 'D',
+    '\u0111': 'd',
+    '\u0126': 'H',
+    '\u0127': 'h',
+    '\u0131': 'i',
+    '\u0132': 'IJ',
+    '\u0133': 'ij',
+    '\u0138': 'q',
+    '\u013F': 'L',
+    '\u0140': 'l',
+    '\u0141': 'L',
+    '\u0142': 'l',
+    '\u0149': "'n",
+    '\u014A': 'N',
+    '\u014B': 'n',
+    '\u0152': 'OE',
+    '\u0153': 'oe',
+    '\u0166': 'T',
+    '\u0167': 't',
+    '\u017F': 's',
+    '\u1E9E': 'SS'
+});
+/**
+ * A run of more than 30 marks, past the UAX #15 Stream-Safe limit that keeps `normalize` linear.
+ * Matched from the start of the run only, so each mark is read once.
+ */
+const EXCESS_MARKS = /(?<!\p{M})(\p{M}{30})\p{M}+/gu;
+/** One forward pass, so a long run of marks after another script is never rescanned. */
+const MARK_RUN_AFTER_LATIN = /(?<=[\p{Script=Latin}0-9])\p{Mn}+/gu;
+/** Variation selectors are Mn but pick a presentation, such as VS16 in the keycap `1️⃣`. */
+const NOT_VARIATION_SELECTOR = /\P{Variation_Selector}/gu;
+const FOLDABLE_LETTER = /[\u00C6-\u017F\u1E9E]/g;
+/**
+ * Removes accents from Latin letters with a subset of the Unicode CLDR Latin-ASCII transform:
+ * combining marks after Latin letters and digits, and the common letter folds (`ß` to `ss`,
+ * `Æ` to `AE`, `ø` to `o`). Marks on other scripts and variation selectors stay (`й`, `が`,
+ * `1️⃣`), the result is NFC, and a run of marks is cut to 30 so normalizing stays linear.
+ * @param s The string to fold.
+ * @returns The folded string.
+ * @example
+ * ```ts
+ * deburr('déjà vu') // 'deja vu'
+ * deburr('Œuvre ß ø') // 'OEuvre ss o'
+ * ```
+ */
+export function deburr(s) {
+    const text = toText(s);
+    if (isAsciiString(text))
+        return text;
+    return text
+        .replace(EXCESS_MARKS, '$1')
+        .normalize('NFD')
+        .replace(MARK_RUN_AFTER_LATIN, (marks) => marks.replace(NOT_VARIATION_SELECTOR, ''))
+        .normalize('NFC')
+        .replace(FOLDABLE_LETTER, (ch) => CLDR_LATIN_ASCII_FOLDS[ch] ?? ch);
+}
+/** Bounded so a long two-byte run cannot overflow the regexp stack; `-+` merges the chunks. */
+const SEPARATORS = /[^\p{L}\p{M}\p{N}]{1,1024}/gu;
+/** Invisible, so dropped as UTS #46 drops them: no word splits on one and no slug hides one. */
+const DEFAULT_IGNORABLE = /\p{Default_Ignorable_Code_Point}/gu;
+/** Mark runs are cut to 30 by {@link deburr}, so the lookbehind stays bounded. */
+const MID_WORD_APOSTROPHE = /(?<=[\p{L}\p{N}]\p{M}*)['\u2019](?=[\p{L}\p{N}])/gu;
+const ORPHAN_MARKS = /(^|-)\p{M}+/gu;
+/**
+ * Returns a URL slug: {@link deburr}, lowercased unless `lower` is `false`, default-ignorable
+ * code points (soft hyphen, ZWNJ, variation selectors, Hangul fillers) and apostrophes inside
+ * words dropped, then runs of Unicode letters, marks and digits joined with `-`. Letters of other
+ * scripts stay.
+ * @param s The string to slugify.
+ * @param options `lower`.
+ * @returns The slug.
+ * @example
+ * ```ts
+ * slugify('Antoine de Saint-Exupéry') // 'antoine-de-saint-exupery'
+ * slugify("Don't Stop", { lower: false }) // 'Dont-Stop'
+ * slugify('Café Привет') // 'cafe-привет'
+ * ```
+ */
+export function slugify(s, options) {
+    const folded = deburr(s);
+    return (options?.lower === false ? folded : folded.toLowerCase())
+        .replace(DEFAULT_IGNORABLE, '')
+        .replace(MID_WORD_APOSTROPHE, '')
+        .replace(SEPARATORS, '-')
+        .replace(ORPHAN_MARKS, '$1')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}

package/dist/string/index.d.ts

@@ -1,190 +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
  */
-/**
- * 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 declare function sentenceCase(s: string): string;
-/**
- * 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 declare function capitalize(s: string): string;
-/**
- * Split a string into an array of its words.
- * @param {string} s The string to split
- * @param {RegExp | string} [pattern] The separator to split on, instead of matching words
- * @returns {string[]} Returns the words array.
- * @example
-```js
-words('lord of the rings')
-// ['lord', 'of', 'the', 'rings']
-```
- */
-export declare function words(s: string, pattern?: RegExp | string): string[];
-/**
- * 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 declare function join(s: string, sep?: string): string;
-/**
- * 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 declare function isAlnum(s: string): boolean;
-/**
- * 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 declare function isAlpha(s: string): boolean;
-/**
- * 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 declare function isNumeric(s: string): boolean;
-/**
- * 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 declare function asciify(s: string): string;
-/**
- * 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 declare function removeAccents(s: string): string;
-/**
- * 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 declare function titleCase(s: string): string;
-/**
- * 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 declare function camelCase(s: string): string;
-/**
- * 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 declare function pascalCase(s: string): string;
-/**
- * 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 declare function snakeCase(s: string): string;
-/**
- * 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 declare function kebabCase(s: string): string;
-/**
- * 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 declare function slugify(s: string): string;
+export { camelCase, capitalize, kebabCase, pascalCase, snakeCase, startCase } from './case.js';
+export { deburr, type SlugifyOptions, slugify } from './fold.js';
+export { type TruncateOptions, truncate } from './truncate.js';
+export { words } from './words.js';