@turndown/library 0.1.16 → 0.1.22

package/dist/helpers/string/index.js

@@ -1,161 +1,495 @@
 /**
- * Convert a string to "Normal Case":
- * - Inserts spaces between camel/pascal case boundaries
- * - Capitalizes the first letter of each word, lowercases the rest
+ * String utilities for common text manipulation tasks.
+ */
+const wordBoundaryRegex = /([a-z0-9])([A-Z])/g;
+const acronymBoundaryRegex = /([A-Z]+)([A-Z][a-z])/g;
+const getWords = (value) => {
+    return value
+        .trim()
+        .replace(acronymBoundaryRegex, "$1 $2")
+        .replace(wordBoundaryRegex, "$1 $2")
+        .replace(/[^a-zA-Z0-9]+/g, " ")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+};
+const capitalizeWord = (value) => {
+    if (!value) {
+        return "";
+    }
+    return value.charAt(0).toUpperCase() + value.slice(1).toLowerCase();
+};
+/**
+ * Adds commas to a number for thousands separators.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * normalCase("helloWorld") // "Hello World"
- * normalCase("XMLHttpRequest") // "Xml Http Request"
+ * @example formatNumber(1000) => '1,000'
+ * @example formatNumber('1234567') => '1,234,567'
+ * @example formatNumber(1234567.89) => '1,234,567.89'
  */
+export const formatNumber = (value) => {
+    const str = String(value);
+    const [integer, decimal] = str.split(".");
+    const formattedInteger = integer.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    return decimal !== undefined
+        ? `${formattedInteger}.${decimal}`
+        : formattedInteger;
+};
 export const normalCase = (str) => {
-    if (!str)
+    if (!str) {
         return "";
-    return str
-        .replace(/([a-z])([A-Z])/g, "$1 $2")
-        .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2")
-        .split(/\s+/)
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
-        .join(" ");
+    }
+    return getWords(str).map(capitalizeWord).join(" ");
+};
+export const sentenceCase = (str) => {
+    if (!str) {
+        return "";
+    }
+    const normalizedValue = str.trim().toLowerCase();
+    return normalizedValue.charAt(0).toUpperCase() + normalizedValue.slice(1);
+};
+export const upperCase = (str) => {
+    return str?.toUpperCase() ?? "";
+};
+export const lowerCase = (str) => {
+    return str?.toLowerCase() ?? "";
 };
 /**
- * Capitalize only the first character; lowercases the rest.
- * Trims leading/trailing spaces before processing.
+ * Converts a string to camelCase.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * sentenceCase("hELLO WORLD") // "Hello world"
+ * @example toCamelCase('hello-world') => 'helloWorld'
+ * @example toCamelCase('hello_world') => 'helloWorld'
  */
-export const sentenceCase = (str) => {
-    if (!str)
+export const toCamelCase = (str) => {
+    const words = getWords(str);
+    if (words.length === 0) {
         return "";
-    const s = str.trim();
-    return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+    }
+    const [firstWord, ...remainingWords] = words;
+    return [
+        firstWord.toLowerCase(),
+        ...remainingWords.map(capitalizeWord),
+    ].join("");
 };
+export const camelCase = toCamelCase;
 /**
- * Uppercase the entire string.
+ * Converts a string to kebab-case.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * upperCase("Hello world") // "HELLO WORLD"
+ * @example toKebabCase('helloWorld') => 'hello-world'
+ * @example toKebabCase('Hello_World') => 'hello-world'
  */
-export const upperCase = (str) => {
-    return str ? str.toUpperCase() : "";
+export const toKebabCase = (str) => {
+    return getWords(str).map((word) => word.toLowerCase()).join("-");
 };
+export const kebabCase = toKebabCase;
 /**
- * Lowercase the entire string.
+ * Converts a string to snake_case.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * lowerCase("Hello WORLD") // "hello world"
+ * @example toSnakeCase('helloWorld') => 'hello_world'
+ * @example toSnakeCase('hello-world') => 'hello_world'
  */
-export const lowerCase = (str) => {
-    return str ? str.toLowerCase() : "";
+export const toSnakeCase = (str) => {
+    return getWords(str).map((word) => word.toLowerCase()).join("_");
 };
+export const snakeCase = toSnakeCase;
 /**
- * Convert to camelCase.
- * Splits on spaces, underscores, and hyphens; lowercases the first word,
- * TitleCases the rest, then joins with no separators.
+ * Converts a string to PascalCase.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * camelCase("Hello world") // "helloWorld"
- * camelCase("hello_world-again") // "helloWorldAgain"
+ * @example toPascalCase('hello-world') => 'HelloWorld'
+ * @example toPascalCase('hello_world') => 'HelloWorld'
  */
-export const camelCase = (str) => {
-    if (!str)
-        return "";
-    return str
-        .toLowerCase()
-        .split(/[\s_-]+/)
-        .map((word, i) => i === 0
-        ? word
-        : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
-        .join("");
+export const toPascalCase = (str) => {
+    return getWords(str).map(capitalizeWord).join("");
+};
+export const pascalCase = toPascalCase;
+export const snakeCaseToSpaces = (str) => {
+    return str.replace(/_+/g, " ").trim();
+};
+export const kebabToSpaces = (str) => {
+    return str.replace(/-+/g, " ").trim();
 };
 /**
- * Convert to PascalCase.
- * Splits on spaces, underscores, and hyphens; TitleCases all words and joins them.
+ * Capitalizes the first character of a string.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * pascalCase("hello world") // "HelloWorld"
- * pascalCase("hello_world-again") // "HelloWorldAgain"
+ * @example capitalize('hello world') => 'Hello world'
  */
-export const pascalCase = (str) => {
-    if (!str)
+export const capitalize = (str) => {
+    if (!str) {
         return "";
-    return str
-        .toLowerCase()
-        .split(/[\s_-]+/)
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-        .join("");
+    }
+    return str.charAt(0).toUpperCase() + str.slice(1);
 };
 /**
- * Convert to kebab-case.
- * Inserts hyphens between camelCase boundaries, then replaces spaces/underscores with hyphens.
+ * Capitalizes the first letter of each word.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * kebabCase("HelloWorld Again") // "hello-world-again"
- * kebabCase("hello_world") // "hello-world"
+ * @example titleCase('hello world') => 'Hello World'
  */
-export const kebabCase = (str) => {
-    if (!str)
+export const titleCase = (str) => {
+    return str.replace(/\b\w/g, (char) => char.toUpperCase());
+};
+/**
+ * Truncates a string to a specified length and adds ellipsis.
+ *
+ * @example truncate('hello world', 5) => 'he...'
+ */
+export const truncate = (str, length, suffix = "...") => {
+    if (length <= 0) {
         return "";
+    }
+    if (str.length <= length) {
+        return str;
+    }
+    const maxLength = Math.max(0, length - suffix.length);
+    if (maxLength === 0) {
+        return suffix.length > length ? "" : suffix;
+    }
+    return str.slice(0, maxLength) + suffix;
+};
+/**
+ * Removes all whitespace from a string.
+ *
+ * @example removeWhitespace('hello world') => 'helloworld'
+ */
+export const removeWhitespace = (str) => {
+    return str.replace(/\s+/g, "");
+};
+/**
+ * Removes all non-alphanumeric characters.
+ *
+ * @example removeSpecialChars('hello@world#123') => 'helloworld123'
+ */
+export const removeSpecialChars = (str) => {
+    return str.replace(/[^a-zA-Z0-9]/g, "");
+};
+/**
+ * Generates a URL-friendly slug from a string.
+ *
+ * @example slug('Hello World 2024!') => 'hello-world-2024'
+ */
+export const slug = (str) => {
     return str
-        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, "")
         .replace(/[\s_]+/g, "-")
-        .toLowerCase();
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
 };
 /**
- * Convert to snake_case.
- * Inserts underscores between camelCase boundaries, then replaces spaces/hyphens with underscores.
+ * Validates if a string is a valid email.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * snakeCase("HelloWorld Again") // "hello_world_again"
- * snakeCase("hello-world") // "hello_world"
+ * @example isEmail('user@example.com') => true
  */
-export const snakeCase = (str) => {
-    if (!str)
-        return "";
-    return str
-        .replace(/([a-z])([A-Z])/g, "$1_$2")
-        .replace(/[\s-]+/g, "_")
-        .toLowerCase();
+export const isEmail = (str) => {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(str.trim());
 };
 /**
- * Convert snake_case to space-delimited words.
+ * Validates if a string is a valid URL.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * snakeCaseToSpaces("hello_world_again") // "hello world again"
+ * @example isUrl('https://example.com') => true
  */
-export const snakeCaseToSpaces = (str) => {
-    if (!str)
-        return "";
-    return str.split("_").join(" ");
+export const isUrl = (str) => {
+    try {
+        const parsedUrl = new URL(str);
+        return parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
 };
 /**
- * Convert kebab-case to space-delimited words.
+ * Validates if a string contains only numbers.
  *
- * @param {TurndownObject} [str] Input value (falsy returns an empty string)
- * @returns {string}
- * @example
- * kebabToSpaces("hello-world-again") // "hello world again"
+ * @example isNumeric('12345') => true
+ * @example isNumeric('123abc') => false
  */
-export const kebabToSpaces = (str) => {
-    if (!str)
-        return "";
-    return str.split("-").join(" ");
+export const isNumeric = (str) => {
+    return /^\d+$/.test(str);
+};
+/**
+ * Checks if a string is empty or contains only whitespace.
+ *
+ * @example isEmpty('  ') => true
+ * @example isEmpty('hello') => false
+ */
+export const isEmpty = (str) => {
+    return str.trim().length === 0;
+};
+/**
+ * Reverses a string.
+ *
+ * @example reverse('hello') => 'olleh'
+ */
+export const reverse = (str) => {
+    return Array.from(str).reverse().join("");
+};
+/**
+ * Repeats a string a specified number of times.
+ *
+ * @example repeat('ab', 3) => 'ababab'
+ */
+export const repeat = (str, times) => {
+    return str.repeat(Math.max(0, Math.floor(times)));
+};
+/**
+ * Pads a string to a specified length.
+ *
+ * @example padStart('5', 3, '0') => '005'
+ * @example padEnd('5', 3, '0') => '500'
+ */
+export const padStart = (str, length, padChar = " ") => {
+    return str.padStart(length, padChar);
+};
+export const padEnd = (str, length, padChar = " ") => {
+    return str.padEnd(length, padChar);
+};
+/**
+ * Encodes a string to Base64.
+ *
+ * @example toBase64('hello') => 'aGVsbG8='
+ */
+export const toBase64 = (str) => {
+    return Buffer.from(str, "utf-8").toString("base64");
+};
+/**
+ * Decodes a Base64 string.
+ *
+ * @example fromBase64('aGVsbG8=') => 'hello'
+ */
+export const fromBase64 = (str) => {
+    return Buffer.from(str, "base64").toString("utf-8");
+};
+/**
+ * Counts the number of words in a string.
+ *
+ * @example wordCount('hello world test') => 3
+ */
+export const wordCount = (str) => {
+    const trimmedValue = str.trim();
+    if (!trimmedValue) {
+        return 0;
+    }
+    return trimmedValue.split(/\s+/).length;
+};
+/**
+ * Counts the number of characters, excluding whitespace.
+ *
+ * @example charCount('hello world') => 10
+ */
+export const charCount = (str) => {
+    return str.replace(/\s/g, "").length;
+};
+/**
+ * Repeats a character a specified number of times.
+ *
+ * @example repeatChar('*', 5) => '*****'
+ */
+export const repeatChar = (char, times) => {
+    return char.repeat(Math.max(0, Math.floor(times)));
+};
+/**
+ * Extracts numbers from a string.
+ *
+ * @example extractNumbers('abc123def456') => '123456'
+ */
+export const extractNumbers = (str) => {
+    return str.replace(/\D/g, "");
+};
+/**
+ * Removes duplicate consecutive characters.
+ *
+ * @example removeDuplicates('aabbccdd') => 'abcd'
+ */
+export const removeDuplicates = (str) => {
+    return str.replace(/(.)\1+/g, "$1");
+};
+/**
+ * Checks if a string is a palindrome.
+ *
+ * @example isPalindrome('racecar') => true
+ * @example isPalindrome('hello') => false
+ */
+export const isPalindrome = (str) => {
+    const cleaned = str.toLowerCase().replace(/[^a-z0-9]/g, "");
+    return cleaned === cleaned.split("").reverse().join("");
+};
+/**
+ * Finds the longest word in a string.
+ *
+ * @example longestWord('the quick brown fox') => 'quick'
+ */
+export const longestWord = (str) => {
+    const words = str.trim().split(/\s+/).filter(Boolean);
+    return words.reduce((longest, word) => (word.length > longest.length ? word : longest), "");
+};
+/**
+ * Pluralizes common English words using a simple ruleset.
+ *
+ * @example pluralize('cat') => 'cats'
+ * @example pluralize('box') => 'boxes'
+ */
+export const pluralize = (word) => {
+    const exceptions = {
+        child: "children",
+        person: "people",
+        man: "men",
+        woman: "women",
+        tooth: "teeth",
+        foot: "feet",
+        mouse: "mice",
+    };
+    const lowercaseWord = word.toLowerCase();
+    const exception = exceptions[lowercaseWord];
+    if (exception) {
+        return word.charAt(0) === word.charAt(0).toUpperCase()
+            ? capitalize(exception)
+            : exception;
+    }
+    if (/[^aeiou]y$/i.test(word)) {
+        return `${word.slice(0, -1)}ies`;
+    }
+    if (/(s|x|z|ch|sh)$/i.test(word)) {
+        return `${word}es`;
+    }
+    if (/fe$/i.test(word)) {
+        return `${word.slice(0, -2)}ves`;
+    }
+    if (/f$/i.test(word)) {
+        return `${word.slice(0, -1)}ves`;
+    }
+    return `${word}s`;
+};
+/**
+ * Highlights a substring within a string by wrapping it with markers.
+ *
+ * @example highlight('hello world', 'world', '**') => 'hello **world**'
+ */
+export const highlight = (str, substring, marker = "**") => {
+    if (!substring) {
+        return str;
+    }
+    return str.replace(new RegExp(`(${escapeRegex(substring)})`, "gi"), `${marker}$1${marker}`);
+};
+/**
+ * Converts a string to a regex-safe string.
+ *
+ * @example escapeRegex('a.b*c') => 'a\\.b\\*c'
+ */
+export const escapeRegex = (str) => {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+};
+/**
+ * Finds similarity between two strings using Levenshtein distance.
+ * Returns a value between 0 and 1, where 1 means identical.
+ *
+ * @example stringSimilarity('hello', 'hallo') => 0.8
+ */
+export const stringSimilarity = (str1, str2) => {
+    const s1 = str1.toLowerCase();
+    const s2 = str2.toLowerCase();
+    const longer = s1.length > s2.length ? s1 : s2;
+    const shorter = s1.length > s2.length ? s2 : s1;
+    if (longer.length === 0) {
+        return 1;
+    }
+    const editDistance = getEditDistance(longer, shorter);
+    return (longer.length - editDistance) / longer.length;
+};
+/**
+ * Helper function to calculate edit distance (Levenshtein distance).
+ */
+const getEditDistance = (s1, s2) => {
+    const costs = [];
+    for (let i = 0; i <= s1.length; i += 1) {
+        let lastValue = i;
+        for (let j = 0; j <= s2.length; j += 1) {
+            if (i === 0) {
+                costs[j] = j;
+            }
+            else if (j > 0) {
+                let newValue = costs[j - 1];
+                if (s1.charAt(i - 1) !== s2.charAt(j - 1)) {
+                    newValue = Math.min(Math.min(newValue, lastValue), costs[j]) + 1;
+                }
+                costs[j - 1] = lastValue;
+                lastValue = newValue;
+            }
+        }
+        if (i > 0) {
+            costs[s2.length] = lastValue;
+        }
+    }
+    return costs[s2.length];
+};
+/**
+ * Strips HTML tags from a string.
+ *
+ * @example stripHtml('<p>Hello <b>world</b></p>') => 'Hello world'
+ */
+export const stripHtml = (str) => {
+    return str.replace(/<[^>]*>/g, "");
+};
+/**
+ * Replaces multiple spaces with a single space.
+ *
+ * @example normalizeSpaces('hello    world') => 'hello world'
+ */
+export const normalizeSpaces = (str) => {
+    return str.replace(/\s+/g, " ").trim();
+};
+/**
+ * Converts a string to a number, returning null if not valid.
+ *
+ * @example toNumber('123') => 123
+ * @example toNumber('abc') => null
+ */
+export const toNumber = (str) => {
+    if (str.trim() === "") {
+        return null;
+    }
+    const num = Number(str);
+    return Number.isNaN(num) ? null : num;
+};
+/**
+ * Splits a string by multiple delimiters.
+ *
+ * @example splitMultiple('a,b;c:d', ',', ';', ':') => ['a', 'b', 'c', 'd']
+ */
+export const splitMultiple = (str, ...delimiters) => {
+    if (delimiters.length === 0) {
+        return [str].filter((part) => part.length > 0);
+    }
+    let result = [str];
+    delimiters.forEach((delimiter) => {
+        if (delimiter !== "") {
+            result = result.flatMap((part) => part.split(delimiter));
+        }
+    });
+    return result.filter((part) => part.length > 0);
+};
+/**
+ * Checks if a string contains any of the provided substrings.
+ *
+ * @example containsAny('hello world', 'foo', 'world') => true
+ */
+export const containsAny = (str, ...substrings) => {
+    return substrings.some((substring) => str.includes(substring));
+};
+/**
+ * Checks if a string contains all of the provided substrings.
+ *
+ * @example containsAll('hello world', 'hello', 'world') => true
+ */
+export const containsAll = (str, ...substrings) => {
+    return substrings.every((substring) => str.includes(substring));
+};
+export const formatAddress = (address) => {
+    const parts = [
+        address.addressLine1,
+        address.addressLine2,
+        address.city,
+        address.stateCode,
+        address.postalCode,
+    ].filter(Boolean);
+    return parts.join(", ");
 };

package/dist/types/api/index.d.ts

@@ -3,28 +3,39 @@
  * Standard response structure for all API endpoints
  */
 import { TurndownObject } from "../base";
-export interface ApiError {
+export declare const HTTP_METHOD: {
+    readonly Get: "GET";
+    readonly Post: "POST";
+    readonly Put: "PUT";
+    readonly Patch: "PATCH";
+    readonly Delete: "DELETE";
+};
+export type THttpMethod = (typeof HTTP_METHOD)[keyof typeof HTTP_METHOD];
+export interface IApiError<TDetails extends object = TurndownObject> {
     message: string;
     code?: string;
-    details?: TurndownObject;
+    details?: TDetails;
 }
-export interface ApiMeta {
+export interface IApiMeta {
     timestamp: string;
     version: string;
     environment: string;
     requestId?: string;
 }
-export interface ApiResponse<T = TurndownObject> {
+export interface IApiResponse<TData = TurndownObject> {
     success: boolean;
-    data?: T | null;
-    error?: ApiError | null;
-    meta?: ApiMeta;
+    data?: TData | null;
+    error?: IApiError | null;
+    meta?: IApiMeta;
 }
+export type TApiResponse<T> = {
+    data: T;
+};
 /**
  * Error Codes
  * Standardized error codes used across the platform
  */
-export declare const ErrorCodes: {
+export declare const ERROR_CODES: {
     readonly BAD_REQUEST: "BAD_REQUEST";
     readonly VALIDATION_ERROR: "VALIDATION_ERROR";
     readonly MISSING_FIELDS: "MISSING_FIELDS";
@@ -39,12 +50,12 @@ export declare const ErrorCodes: {
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
     readonly DATABASE_ERROR: "DATABASE_ERROR";
 };
-export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+export type TErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
 /**
  * HTTP Status Codes
  * Common status codes used in responses
  */
-export declare const HttpStatus: {
+export declare const HTTP_STATUS: {
     readonly OK: 200;
     readonly CREATED: 201;
     readonly NO_CONTENT: 204;
@@ -56,4 +67,4 @@ export declare const HttpStatus: {
     readonly RATE_LIMIT: 429;
     readonly INTERNAL_ERROR: 500;
 };
-export type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
+export type THttpStatusCode = (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS];