@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/Str.d.ts

@@ -1,293 +1,744 @@
 /**
- * Capitalizes the first character of a string and lowercases the rest.
+ * Options for `slugify()`.
+ */
+export type SlugifyOptions = {
+    /**
+     * Placed between words. Defaults to `"-"`.
+     */
+    separator?: string | undefined;
+    /**
+     * Lowercase the result. Defaults to `true`.
+     */
+    lower?: boolean | undefined;
+    /**
+     * Maximum length, cut on a word boundary when possible.
+     */
+    maxLength?: number | undefined;
+};
+/**
+ * Options for `truncate()`.
+ */
+export type TruncateOptions = {
+    /**
+     * Added where the text is cut, and counted in the length. Defaults to `"…"`.
+     */
+    omission?: string | undefined;
+    /**
+     * Cut at the previous space rather than inside a word, when the end is what gets cut.
+     */
+    words?: boolean | undefined;
+    /**
+     * Where the text is cut. `"middle"` keeps both ends, which suits paths and ids. Defaults to `"end"`.
+     */
+    position?: "end" | "middle" | "start" | undefined;
+};
+/**
+ * Options for `template()`.
+ */
+export type TemplateOptions = {
+    /**
+     * Opening delimiter. Defaults to `"{"`.
+     */
+    open?: string | undefined;
+    /**
+     * Closing delimiter. Defaults to `"}"`.
+     */
+    close?: string | undefined;
+    /**
+     * Used for missing values. Without it, their placeholders stay as they are.
+     */
+    fallback?: string | undefined;
+};
+/**
+ * Options for `wrap()`.
+ */
+export type WrapOptions = {
+    /**
+     * Maximum visible characters per line. Defaults to `80`.
+     */
+    width?: number | undefined;
+    /**
+     * Added at the start of every line.
+     */
+    indent?: string | undefined;
+    /**
+     * Break words longer than `width` instead of letting them overflow.
+     */
+    cut?: boolean | undefined;
+    /**
+     * Line separator. Defaults to `"\n"`.
+     */
+    newline?: string | undefined;
+};
+/**
+ * Options for `mask()`.
+ */
+export type MaskOptions = {
+    /**
+     * Characters left visible at the start. Defaults to `0`.
+     */
+    start?: number | undefined;
+    /**
+     * Characters left visible at the end. Defaults to `4`.
+     */
+    end?: number | undefined;
+    /**
+     * Mask character. Defaults to `"*"`.
+     */
+    char?: string | undefined;
+    /**
+     * Leave spaces and dashes visible, nice for card numbers.
+     */
+    keepSpaces?: boolean | undefined;
+};
+/**
+ * The word forms for `plural()`. Only `other` is required; add the others
+ * when your language needs them.
+ */
+export type PluralForms = {
+    /**
+     * The general plural, like `"files"`.
+     */
+    other: string;
+    /**
+     * Used for `0` in any language, like `"no files"`.
+     */
+    zero?: string | undefined;
+    /**
+     * The singular, like `"file"`. French also uses it for 0.
+     */
+    one?: string | undefined;
+    /**
+     * Dual form (Arabic, Hebrew, Slovenian...).
+     */
+    two?: string | undefined;
+    /**
+     * "Few" form (Polish, Czech, Russian...).
+     */
+    few?: string | undefined;
+    /**
+     * "Many" form (Polish, Russian, Arabic...).
+     */
+    many?: string | undefined;
+};
+/**
+ * Options for `plural()`.
+ */
+export type PluralOptions = {
+    /**
+     * Language whose plural rules apply. Defaults to `"en"`.
+     */
+    locale?: string | undefined;
+    /**
+     * Put the formatted count before the word. Defaults to `true`.
+     */
+    includeCount?: boolean | undefined;
+    /**
+     * Use ordinal rules (1st, 2nd, 3rd).
+     */
+    ordinal?: boolean | undefined;
+};
+/**
+ * Options for `compare()`.
+ */
+export type CompareOptions = {
+    /**
+     * Language used for alphabetical order. Defaults to the system's.
+     */
+    locale?: string | undefined;
+    /**
+     * Sort numbers naturally, `"file2"` before `"file10"`. Defaults to `true`.
+     */
+    numeric?: boolean | undefined;
+    /**
+     * Which differences count. `"base"` ignores accents and case. Defaults to `"variant"`.
+     */
+    sensitivity?: "base" | "accent" | "case" | "variant" | undefined;
+};
+/**
+ * Options for `closest()`.
+ */
+export type ClosestOptions = {
+    /**
+     * Minimum similarity (0 to 1) to accept a match. Defaults to `0.4`.
+     */
+    threshold?: number | undefined;
+    /**
+     * Take case into account.
+     */
+    caseSensitive?: boolean | undefined;
+};
+/**
+ * Options for `random()`.
+ */
+export type RandomStringOptions = {
+    /**
+     * Characters to pick from. Defaults to letters and digits.
+     */
+    charset?: string | undefined;
+};
+/**
+ * Uppercases the first character and lowercases the rest.
+ *
+ * @example
+ * str.capitalize("hELLO wORLD"); // "Hello world"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function capitalize(input: unknown): string;
+/**
+ * Uppercases the first character and leaves the rest alone.
+ *
+ * @example
+ * str.upperFirst("userName"); // "UserName"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function upperFirst(input: unknown): string;
+/**
+ * Lowercases the first character and leaves the rest alone.
+ *
+ * @example
+ * str.lowerFirst("UserName"); // "userName"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function lowerFirst(input: unknown): string;
+/**
+ * Turns an identifier into a label people can read. Acronyms stay as they are.
+ *
+ * @example
+ * str.humanize("user_first_name"); // "User first name"
+ * str.humanize("createdAt");       // "Created at"
+ * str.humanize("userID");          // "User ID"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function humanize(input: unknown): string;
+/**
+ * Uppercases the first letter of each word and leaves the rest alone.
+ *
+ * @example
+ * str.titleCase("the quick brown fox"); // "The Quick Brown Fox"
+ * str.titleCase("élodie o'neil");       // "Élodie O'neil"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function titleCase(input: unknown): string;
+/**
+ * Lowercases everything, then capitalizes the start of each sentence.
+ *
+ * @example
+ * str.sentenceCase("hELLO WORLD. how ARE you?"); // "Hello world. How are you?"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function sentenceCase(input: unknown): string;
+/**
+ * Converts to `camelCase`.
+ *
+ * @example
+ * str.camelCase("user_first-name"); // "userFirstName"
+ * str.camelCase("XMLHttpRequest");  // "xmlHttpRequest"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function camelCase(input: unknown): string;
+/**
+ * Converts to `PascalCase`.
+ *
+ * @example
+ * str.pascalCase("hello world"); // "HelloWorld"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function pascalCase(input: unknown): string;
+/**
+ * Converts to `snake_case`.
+ *
+ * @example
+ * str.snakeCase("helloWorld"); // "hello_world"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function snakeCase(input: unknown): string;
+/**
+ * Converts to `kebab-case`.
  *
  * @example
- * nodeComfort.str.capitalize("hELLO"); // "Hello"
+ * str.kebabCase("helloWorld"); // "hello-world"
  *
- * @param {string} str - Input string.
- * @returns {string} The capitalized string.
+ * @param {unknown} input
+ * @returns {string}
  */
-export function capitalize(str: string): string;
+export function kebabCase(input: unknown): string;
 /**
- * Uppercases the first character of each word (Title Case), leaving the rest untouched.
+ * Converts to `CONSTANT_CASE`.
  *
  * @example
- * nodeComfort.str.titleCase("the quick brown fox"); // "The Quick Brown Fox"
+ * str.constantCase("helloWorld"); // "HELLO_WORLD"
  *
- * @param {string} str - Input string.
- * @returns {string} The title-cased string.
+ * @param {unknown} input
+ * @returns {string}
  */
-export function titleCase(str: string): string;
+export function constantCase(input: unknown): string;
 /**
- * Converts a string to `camelCase`.
+ * Converts to `dot.case`.
  *
  * @example
- * nodeComfort.str.camelCase("hello world");  // "helloWorld"
- * nodeComfort.str.camelCase("foo-bar_baz");  // "fooBarBaz"
+ * str.dotCase("userFirstName"); // "user.first.name"
  *
- * @param {string} str - Input string.
- * @returns {string} The camelCased string.
+ * @param {unknown} input
+ * @returns {string}
  */
-export function camelCase(str: string): string;
+export function dotCase(input: unknown): string;
 /**
- * Converts a string to `PascalCase`.
+ * Splits text into words. Understands camelCase, snake_case, kebab-case,
+ * dots, spaces and punctuation.
  *
  * @example
- * nodeComfort.str.pascalCase("hello world"); // "HelloWorld"
+ * str.words("helloWorld-foo_bar"); // ["hello", "World", "foo", "bar"]
  *
- * @param {string} str - Input string.
- * @returns {string} The PascalCased string.
+ * @param {unknown} input
+ * @returns {string[]}
  */
-export function pascalCase(str: string): string;
+export function words(input: unknown): string[];
 /**
- * Converts a string to `snake_case`.
+ * Removes accents (`é` becomes `e`) and spells out special Latin letters
+ * (`ß` becomes `ss`, `æ` becomes `ae`).
  *
  * @example
- * nodeComfort.str.snakeCase("helloWorld"); // "hello_world"
+ * str.deburr("Crème brûlée"); // "Creme brulee"
+ * str.deburr("Straße");       // "Strasse"
  *
- * @param {string} str - Input string.
- * @returns {string} The snake_cased string.
+ * @param {unknown} input
+ * @returns {string}
  */
-export function snakeCase(str: string): string;
+export function deburr(input: unknown): string;
 /**
- * Converts a string to `kebab-case`.
+ * Turns text into a URL slug: no accents, lowercase, words joined by dashes.
  *
  * @example
- * nodeComfort.str.kebabCase("helloWorld"); // "hello-world"
+ * str.slugify("Héllo, World!");                      // "hello-world"
+ * str.slugify("Crème Brûlée", { separator: "_" });   // "creme_brulee"
+ * str.slugify("A very long title", { maxLength: 8 }); // "a-very"
  *
- * @param {string} str - Input string.
- * @returns {string} The kebab-cased string.
+ * @param {unknown} input
+ * @param {SlugifyOptions} [options]
+ * @returns {string} The slug, possibly empty.
  */
-export function kebabCase(str: string): string;
+export function slugify(input: unknown, options?: SlugifyOptions): string;
 /**
- * Converts a string to `CONSTANT_CASE`.
+ * Collapses runs of whitespace into single spaces and trims the ends.
  *
  * @example
- * nodeComfort.str.constantCase("helloWorld"); // "HELLO_WORLD"
+ * str.squish("  hello \n\t world  "); // "hello world"
  *
- * @param {string} str - Input string.
- * @returns {string} The CONSTANT_CASED string.
+ * @param {unknown} input
+ * @returns {string}
  */
-export function constantCase(str: string): string;
+export function squish(input: unknown): string;
 /**
- * Converts a string into a URL-friendly slug.
+ * Removes HTML tags and keeps the text. This is not a sanitizer: to show
+ * untrusted text in HTML, use `escapeHTML()`.
  *
- * Accents/diacritics are stripped, non-alphanumeric runs become the separator.
+ * @example
+ * str.stripTags("<p>Hello <b>world</b></p>"); // "Hello world"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function stripTags(input: unknown): string;
+/**
+ * Escapes `& < > " '` so the text is safe inside HTML content and attributes.
  *
  * @example
- * nodeComfort.str.slugify("Héllo, World!");            // "hello-world"
- * nodeComfort.str.slugify("A B C", { separator: "_" }); // "a_b_c"
+ * str.escapeHTML('<a href="x">Tom & Jerry</a>');
+ * // "&lt;a href=&quot;x&quot;&gt;Tom &amp; Jerry&lt;/a&gt;"
  *
- * @param {string} str - Input string.
- * @param {{ separator?: string, lower?: boolean }} [options] - Slug options.
- * @returns {string} The slug.
+ * @param {unknown} input
+ * @returns {string}
  */
-export function slugify(str: string, options?: {
-    separator?: string;
-    lower?: boolean;
-}): string;
+export function escapeHTML(input: unknown): string;
 /**
- * Truncates a string to a maximum length, appending an ellipsis if cut.
+ * Decodes HTML entities: named ones like `&amp;` and `&nbsp;`, and numeric
+ * ones like `&#233;`.
  *
  * @example
- * nodeComfort.str.truncate("Hello world", 8);                 // "Hello…"
- * nodeComfort.str.truncate("Hello world", 8, { omission: "..." }); // "Hello..."
+ * str.unescapeHTML("Tom &amp; Jerry &#x1F600;"); // "Tom & Jerry 😀"
  *
- * @param {string} str - Input string.
- * @param {number} length - Maximum length of the result (including the omission).
- * @param {{ omission?: string, words?: boolean }} [options] - Truncation options.
- * @returns {string} The truncated string.
+ * @param {unknown} input
+ * @returns {string}
  */
-export function truncate(str: string, length: number, options?: {
-    omission?: string;
-    words?: boolean;
-}): string;
+export function unescapeHTML(input: unknown): string;
 /**
- * Pads a string on the left (start) to a target length.
+ * Escapes regex special characters so the text matches literally.
  *
- * @param {string} str - Input string.
- * @param {number} length - Target total length.
- * @param {string} [char=" "] - Padding character(s).
- * @returns {string} The padded string.
+ * @example
+ * new RegExp(str.escapeRegExp("1+1=2?")).test("1+1=2?"); // true
+ *
+ * @param {unknown} input
+ * @returns {string}
  */
-export function padStart(str: string, length: number, char?: string): string;
+export function escapeRegExp(input: unknown): string;
 /**
- * Pads a string on the right (end) to a target length.
+ * Counts visible characters. Unlike `.length`, an emoji or an accented
+ * letter counts as one.
+ *
+ * @example
+ * "👨‍👩‍👧".length;         // 8
+ * str.length("👨‍👩‍👧");     // 1
  *
- * @param {string} str - Input string.
- * @param {number} length - Target total length.
- * @param {string} [char=" "] - Padding character(s).
- * @returns {string} The padded string.
+ * @param {unknown} input
+ * @returns {number}
  */
-export function padEnd(str: string, length: number, char?: string): string;
+export function length(input: unknown): number;
 /**
- * Centers a string within a target length by padding both sides.
+ * Size of the text in bytes once encoded, UTF-8 by default. Useful when a
+ * limit is in bytes, like a database column or an HTTP header.
  *
  * @example
- * nodeComfort.str.center("hi", 6);        // "  hi  "
- * nodeComfort.str.center("hi", 6, "*");   // "**hi**"
+ * str.byteLength("é");  // 2
+ * str.byteLength("😀"); // 4
  *
- * @param {string} str - Input string.
- * @param {number} length - Target total length.
- * @param {string} [char=" "] - Padding character.
- * @returns {string} The centered string.
+ * @param {unknown} input
+ * @param {BufferEncoding} [encoding="utf8"]
+ * @returns {number}
  */
-export function center(str: string, length: number, char?: string): string;
+export function byteLength(input: unknown, encoding?: BufferEncoding): number;
 /**
- * Reverses a string (Unicode code-point aware, so emojis stay intact).
+ * Counts how many times `search` appears, without overlaps.
  *
  * @example
- * nodeComfort.str.reverse("abc"); // "cba"
+ * str.count("banana", "a"); // 3
+ * str.count("aaaa", "aa");  // 2
  *
- * @param {string} str - Input string.
- * @returns {string} The reversed string.
+ * @param {unknown} input
+ * @param {string} search An empty string gives `0`.
+ * @returns {number}
  */
-export function reverse(str: string): string;
+export function count(input: unknown, search: string): number;
 /**
- * Collapses all runs of whitespace into single spaces and trims the ends.
+ * Shortens text to `length` visible characters, ending with `…` when cut.
  *
  * @example
- * nodeComfort.str.squish("  hello   world \n"); // "hello world"
+ * str.truncate("Hello world", 8);                        // "Hello w…"
+ * str.truncate("Hello world", 8, { omission: "..." });   // "Hello..."
+ * str.truncate("Hello big world", 12, { words: true });  // "Hello big…"
+ *
+ * @param {unknown} input
+ * @param {number} length Maximum length, omission included.
+ * @param {TruncateOptions} [options]
+ * @returns {string}
+ */
+export function truncate(input: unknown, length: number, options?: TruncateOptions): string;
+/**
+ * Splits text into pieces of `size` visible characters. The last one can be
+ * shorter.
+ *
+ * @example
+ * str.chunk("4242424242424242", 4).join(" "); // "4242 4242 4242 4242"
  *
- * @param {string} str - Input string.
- * @returns {string} The normalized string.
+ * @param {unknown} input
+ * @param {number} size
+ * @returns {string[]}
  */
-export function squish(str: string): string;
+export function chunk(input: unknown, size: number): string[];
 /**
- * Removes all HTML tags from a string.
+ * Returns the text between `start` and the next `end`, or `undefined` if a
+ * marker is missing.
  *
  * @example
- * nodeComfort.str.stripTags("<b>Hi</b> there"); // "Hi there"
+ * str.between("Hello [world]!", "[", "]"); // "world"
  *
- * @param {string} str - Input string.
- * @returns {string} The string with tags removed.
+ * @param {unknown} input
+ * @param {string} start
+ * @param {string} end
+ * @returns {string | undefined}
  */
-export function stripTags(str: string): string;
+export function between(input: unknown, start: string, end: string): string | undefined;
 /**
- * Escapes HTML-sensitive characters (`& < > " '`).
+ * Splits at the first occurrence of `separator` only.
  *
  * @example
- * nodeComfort.str.escapeHTML('<a href="x">'); // "&lt;a href=&quot;x&quot;&gt;"
+ * str.splitOnce("key=value=more", "="); // ["key", "value=more"]
+ * str.splitOnce("novalue", "=");        // ["novalue", undefined]
  *
- * @param {string} str - Input string.
- * @returns {string} The escaped string.
+ * @param {unknown} input
+ * @param {string} separator
+ * @returns {[string, string | undefined]}
  */
-export function escapeHTML(str: string): string;
+export function splitOnce(input: unknown, separator: string): [string, string | undefined];
 /**
- * Reverses {@link escapeHTML}: turns HTML entities back into characters.
+ * Splits text into lines, whatever the line endings.
+ *
+ * @example
+ * str.lines("a\r\nb\nc"); // ["a", "b", "c"]
  *
- * @param {string} str - Input string.
- * @returns {string} The unescaped string.
+ * @param {unknown} input
+ * @returns {string[]}
  */
-export function unescapeHTML(str: string): string;
+export function lines(input: unknown): string[];
 /**
- * Escapes a string for safe use inside a `RegExp`.
+ * Pads the start until the text is `length` characters long.
  *
  * @example
- * new RegExp(nodeComfort.str.escapeRegExp("a.b")); // matches literal "a.b"
+ * str.padStart("7", 3, "0"); // "007"
  *
- * @param {string} str - Input string.
- * @returns {string} The escaped string.
+ * @param {unknown} input
+ * @param {number} length
+ * @param {string} [char=" "]
+ * @returns {string}
  */
-export function escapeRegExp(str: string): string;
+export function padStart(input: unknown, length: number, char?: string): string;
 /**
- * Counts the number of non-overlapping occurrences of a substring.
+ * Pads the end until the text is `length` characters long.
  *
  * @example
- * nodeComfort.str.count("banana", "a"); // 3
+ * str.padEnd("ab", 5, "."); // "ab..."
  *
- * @param {string} str - Input string.
- * @param {string} sub - Substring to count.
- * @returns {number} Number of occurrences.
+ * @param {unknown} input
+ * @param {number} length
+ * @param {string} [char=" "]
+ * @returns {string}
  */
-export function count(str: string, sub: string): number;
+export function padEnd(input: unknown, length: number, char?: string): string;
 /**
- * Ensures a string starts with a given prefix (adds it only if missing).
+ * Centers text within `length` characters. An odd leftover goes to the right.
  *
  * @example
- * nodeComfort.str.ensurePrefix("example.com", "https://"); // "https://example.com"
+ * str.center("hi", 7, "*"); // "**hi***"
  *
- * @param {string} str - Input string.
- * @param {string} prefix - Prefix to ensure.
- * @returns {string} The string with the prefix guaranteed.
+ * @param {unknown} input
+ * @param {number} length
+ * @param {string} [char=" "]
+ * @returns {string}
  */
-export function ensurePrefix(str: string, prefix: string): string;
+export function center(input: unknown, length: number, char?: string): string;
 /**
- * Ensures a string ends with a given suffix (adds it only if missing).
+ * Indents every non-empty line.
  *
  * @example
- * nodeComfort.str.ensureSuffix("path", "/"); // "path/"
+ * str.indent("a\nb", 2);    // "  a\n  b"
+ * str.indent("a\nb", "> "); // "> a\n> b"
  *
- * @param {string} str - Input string.
- * @param {string} suffix - Suffix to ensure.
- * @returns {string} The string with the suffix guaranteed.
+ * @param {unknown} input
+ * @param {number | string} [prefix=2] A number of spaces, or the prefix itself.
+ * @returns {string}
  */
-export function ensureSuffix(str: string, suffix: string): string;
+export function indent(input: unknown, prefix?: number | string): string;
 /**
- * Removes a prefix from a string if present.
+ * Removes the indentation shared by all lines, and blank first and last
+ * lines. Works as a template tag, so multi-line strings can follow your
+ * code's indentation.
  *
- * @param {string} str - Input string.
- * @param {string} prefix - Prefix to remove.
- * @returns {string} The string without the prefix.
+ * @example
+ * const sql = str.dedent`
+ *   SELECT *
+ *     FROM users
+ *    WHERE id = ${id}
+ * `;
+ * // "SELECT *\n  FROM users\n WHERE id = 42"
+ *
+ * @param {unknown} input
+ * @param {...unknown} values
+ * @returns {string}
  */
-export function removePrefix(str: string, prefix: string): string;
+export function dedent(input: unknown, ...values: unknown[]): string;
 /**
- * Removes a suffix from a string if present.
+ * Wraps text so no line is longer than `width` visible characters. Existing
+ * line breaks are kept.
+ *
+ * @example
+ * str.wrap("The quick brown fox jumps over the lazy dog", 16);
+ * // "The quick brown\nfox jumps over\nthe lazy dog"
  *
- * @param {string} str - Input string.
- * @param {string} suffix - Suffix to remove.
- * @returns {string} The string without the suffix.
+ * @param {unknown} input
+ * @param {WrapOptions | number} [options] Options, or just the width.
+ * @returns {string}
  */
-export function removeSuffix(str: string, suffix: string): string;
+export function wrap(input: unknown, options?: WrapOptions | number): string;
 /**
- * Renders a template, replacing `{key}` placeholders with values from `data`.
+ * Reverses text without breaking emoji or accents.
  *
- * Missing keys are left as-is by default. Nested paths (`{user.name}`) are supported.
+ * @example
+ * str.reverse("añ👍🏽"); // "👍🏽ña"
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function reverse(input: unknown): string;
+/**
+ * Hides part of a string, like a card number or a token.
+ *
+ * @example
+ * str.mask("4242424242424242");                           // "************4242"
+ * str.mask("4242 4242 4242 4242", { keepSpaces: true });   // "**** **** **** 4242"
+ * str.mask("secret-token", { start: 2, end: 2, char: "•" }); // "se••••••••en"
+ *
+ * @param {unknown} input
+ * @param {MaskOptions} [options]
+ * @returns {string}
+ */
+export function mask(input: unknown, options?: MaskOptions): string;
+/**
+ * The initials of a name, in uppercase.
  *
  * @example
- * nodeComfort.str.template("Hi {name}, you have {count} msgs", { name: "Jo", count: 3 });
- * // "Hi Jo, you have 3 msgs"
+ * str.initials("Ada Lovelace");       // "AL"
+ * str.initials("jean-luc picard", 3); // "JLP"
  *
- * @param {string} str - Template string.
- * @param {Record<string, any>} data - Replacement values.
- * @param {{ open?: string, close?: string, fallback?: string }} [options] - Delimiters / fallback.
- * @returns {string} The rendered string.
+ * @param {unknown} input
+ * @param {number} [max=2] Maximum number of letters.
+ * @returns {string}
  */
-export function template(str: string, data: Record<string, any>, options?: {
-    open?: string;
-    close?: string;
-    fallback?: string;
-}): string;
+export function initials(input: unknown, max?: number): string;
 /**
- * Splits a string into an array of "words" (camelCase / snake / kebab aware).
+ * Picks the right plural for a count, following the rules of the language,
+ * and puts the formatted count in front.
  *
  * @example
- * nodeComfort.str.words("helloWorld-foo_bar"); // ["hello", "World", "foo", "bar"]
+ * str.plural(1, { one: "file", other: "files" });                           // "1 file"
+ * str.plural(1234, { one: "item", other: "items" });                        // "1,234 items"
+ * str.plural(0, { zero: "no files", one: "file", other: "files" });         // "no files"
+ * str.plural(0, { one: "fichier", other: "fichiers" }, { locale: "fr" });   // "0 fichier"
+ *
+ * @param {number} value
+ * @param {PluralForms} forms
+ * @param {PluralOptions} [options]
+ * @returns {string}
+ */
+export function plural(value: number, forms: PluralForms, options?: PluralOptions): string;
+/**
+ * Fills `{placeholders}` with values. Dotted paths like `{user.name}` work,
+ * and missing values are left alone unless you give a `fallback`.
  *
- * @param {string} str - Input string.
- * @returns {string[]} The words.
+ * @example
+ * str.template("Hi {name}, you have {count} messages", { name: "Jo", count: 3 });
+ * // "Hi Jo, you have 3 messages"
+ * str.template("Hello {{ user.name }}", { user: { name: "Ada" } }, { open: "{{", close: "}}" });
+ * // "Hello Ada"
+ *
+ * @param {unknown} input
+ * @param {Record<string, any>} data
+ * @param {TemplateOptions} [options]
+ * @returns {string}
  */
-export function words(str: string): string[];
+export function template(input: unknown, data: Record<string, any>, options?: TemplateOptions): string;
 /**
- * Returns the visible length of a string in code points (emoji-safe).
+ * Adds `prefix` unless the text already starts with it.
  *
  * @example
- * "😀".length;                    // 2
- * nodeComfort.str.length("😀");   // 1
+ * str.ensurePrefix("example.com", "https://"); // "https://example.com"
  *
- * @param {string} str - Input string.
- * @returns {number} The number of code points.
+ * @param {unknown} input
+ * @param {string} prefix
+ * @returns {string}
  */
-export function length(str: string): number;
+export function ensurePrefix(input: unknown, prefix: string): string;
 /**
- * Generates a random alphanumeric string of a given length.
+ * Adds `suffix` unless the text already ends with it.
  *
- * Note: uses `Math.random` and is **not** cryptographically secure.
- * For tokens/IDs use `nodeComfort.id.token()` instead.
+ * @example
+ * str.ensureSuffix("path/to", "/"); // "path/to/"
+ *
+ * @param {unknown} input
+ * @param {string} suffix
+ * @returns {string}
+ */
+export function ensureSuffix(input: unknown, suffix: string): string;
+/**
+ * Removes `prefix` if the text starts with it.
+ *
+ * @example
+ * str.removePrefix("https://example.com", "https://"); // "example.com"
+ *
+ * @param {unknown} input
+ * @param {string} prefix
+ * @returns {string}
+ */
+export function removePrefix(input: unknown, prefix: string): string;
+/**
+ * Removes `suffix` if the text ends with it.
+ *
+ * @example
+ * str.removeSuffix("report.pdf", ".pdf"); // "report"
+ *
+ * @param {unknown} input
+ * @param {string} suffix
+ * @returns {string}
+ */
+export function removeSuffix(input: unknown, suffix: string): string;
+/**
+ * Compares two strings the way people sort them: numbers in natural order
+ * and accents in the right place. Pass it straight to `sort()`.
+ *
+ * @example
+ * ["file10", "file2", "File1"].sort(str.compare); // ["File1", "file2", "file10"]
+ * str.compare("a", "A", { sensitivity: "base" }); // 0
+ *
+ * @param {unknown} a
+ * @param {unknown} b
+ * @param {CompareOptions} [options]
+ * @returns {number} Negative if `a` comes first, positive if `b` does, `0` if equal.
+ */
+export function compare(a: unknown, b: unknown, options?: CompareOptions): number;
+/**
+ * The number of single-character edits needed to turn `a` into `b`.
+ *
+ * @example
+ * str.levenshtein("kitten", "sitting"); // 3
+ *
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {number}
+ */
+export function levenshtein(a: unknown, b: unknown): number;
+/**
+ * How alike two strings are, from `0` (nothing in common) to `1` (identical).
+ *
+ * @example
+ * str.similarity("hello", "hallo"); // 0.8
+ *
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {number}
+ */
+export function similarity(a: unknown, b: unknown): number;
+/**
+ * Finds the candidate closest to `input`. Made for "Did you mean...?"
+ * suggestions.
+ *
+ * @example
+ * str.closest("instal", ["install", "uninstall", "list"]); // "install"
+ * str.closest("xyz", ["install", "list"]);                 // undefined
+ *
+ * @param {unknown} input
+ * @param {Iterable<string>} candidates
+ * @param {ClosestOptions} [options]
+ * @returns {string | undefined} `undefined` when nothing is close enough.
+ */
+export function closest(input: unknown, candidates: Iterable<string>, options?: ClosestOptions): string | undefined;
+/**
+ * A random string. It relies on `Math.random`, so don't use it for secrets:
+ * `nc.id.token()` and `nc.id.nano()` are made for that.
+ *
+ * @example
+ * str.random();                                // "aZ3kP9qL0xYb7TcW"
+ * str.random(6, { charset: "0123456789" });    // "402917"
  *
- * @param {number} [length=16] - Desired length.
- * @param {string} [charset] - Characters to pick from.
- * @returns {string} The random string.
+ * @param {number} [size=16]
+ * @param {RandomStringOptions | string} [options] Options, or the charset itself.
+ * @returns {string}
  */
-export function random(length?: number, charset?: string): string;
+export function random(size?: number, options?: RandomStringOptions | string): string;
 //# sourceMappingURL=Str.d.ts.map