@hichchi/utils 0.0.1-beta.2 → 0.0.2

package/index.esm.js

@@ -0,0 +1,3575 @@
+// noinspection JSUnusedGlobalSymbols
+/**
+ * Validates if a redirect URL is allowed based on a whitelist of permitted domains.
+ *
+ * This security utility function checks whether a given URL's domain is included in a list
+ * of allowed domains, helping prevent open redirect vulnerabilities. It supports both exact
+ * domain matching and subdomain matching, where a URL's hostname must either exactly match
+ * an allowed domain or be a subdomain of an allowed domain.
+ *
+ * This is essential for secure redirect functionality in web applications, preventing
+ * attackers from redirecting users to malicious external sites. It's commonly used in
+ * authentication flows, logout redirects, and any feature that accepts user-provided
+ * redirect URLs.
+ *
+ * @param {string} url - The URL to validate. Must be a valid URL string that can be parsed
+ *                       by the URL constructor. Can include protocol, path, query parameters, etc.
+ * @param {string[]} allowedDomains - Array of domain names that are permitted for redirects.
+ *                                    Domains should be specified without protocol (e.g., "example.com").
+ *                                    Subdomains of these domains will also be allowed.
+ * @returns {boolean} True if the URL's hostname matches or is a subdomain of any allowed domain,
+ *                    false if the domain is not allowed or if the URL is invalid
+ *
+ * @example
+ * ```typescript
+ * // Basic domain validation
+ * const allowedDomains = ["example.com", "myapp.com"];
+ *
+ * const isValid1 = isValidRedirectUrl("https://example.com/dashboard", allowedDomains);
+ * // Returns: true (exact domain match)
+ *
+ * const isValid2 = isValidRedirectUrl("https://api.example.com/callback", allowedDomains);
+ * // Returns: true (subdomain of allowed domain)
+ *
+ * const isValid3 = isValidRedirectUrl("https://malicious.com/phishing", allowedDomains);
+ * // Returns: false (domain not in allowed list)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Authentication redirect validation
+ * function handleAuthRedirect(redirectUrl: string): void {
+ *   const trustedDomains = [
+ *     "myapp.com",
+ *     "admin.myapp.com",
+ *     "localhost" // for development
+ *   ];
+ *
+ *   if (isValidRedirectUrl(redirectUrl, trustedDomains)) {
+ *     window.location.href = redirectUrl;
+ *   } else {
+ *     // Redirect to safe default instead
+ *     window.location.href = "/dashboard";
+ *     console.warn("Attempted redirect to untrusted domain:", redirectUrl);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // API endpoint validation
+ * app.post('/auth/login', (req, res) => {
+ *   const { username, password, redirectUrl } = req.body;
+ *
+ *   if (authenticateUser(username, password)) {
+ *     const allowedDomains = ["myapp.com", "partner.com"];
+ *
+ *     if (redirectUrl && isValidRedirectUrl(redirectUrl, allowedDomains)) {
+ *       res.json({ success: true, redirectUrl });
+ *     } else {
+ *       res.json({ success: true, redirectUrl: "/dashboard" });
+ *     }
+ *   } else {
+ *     res.status(401).json({ error: "Invalid credentials" });
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Complex subdomain scenarios
+ * const domains = ["company.com"];
+ *
+ * isValidRedirectUrl("https://app.company.com", domains);        // true
+ * isValidRedirectUrl("https://api.app.company.com", domains);    // true
+ * isValidRedirectUrl("https://company.com.evil.com", domains);   // false
+ * isValidRedirectUrl("https://fakecompany.com", domains);        // false
+ * ```
+ *
+ * @remarks
+ * - Uses the native URL constructor for reliable URL parsing
+ * - Supports both exact domain matches and subdomain matches
+ * - Returns false for invalid URLs that cannot be parsed
+ * - Domain matching is case-insensitive (handled by URL constructor)
+ * - Does not validate the protocol - focuses only on hostname validation
+ * - Subdomain matching uses endsWith() to ensure proper domain boundaries
+ * - Empty or null URL strings will cause the function to return false
+ *
+ * @throws {never} This function catches all URL parsing errors and returns false instead of throwing
+ */
+function isValidRedirectUrl(url, allowedDomains) {
+  try {
+    const parsedUrl = new URL(url);
+    return allowedDomains.some(domain => parsedUrl.hostname === domain || parsedUrl.hostname.endsWith(`.${domain}`));
+  } catch {
+    return false;
+  }
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// noinspection JSUnusedGlobalSymbols
+/**
+ * Deep copy an object.
+ * @template T Type of the object.
+ * @param {T} obj Object to copy.
+ * @returns {T} Copied object.
+ *
+ * @example
+ * ```TypeScript
+ * // Example usage
+ * const object = {
+ *    name: "John Doe"
+ * }
+ *
+ * const copiedObject = deepCopy(object);
+ * ```
+ */
+function deepCopy(obj) {
+  if (Array.isArray(obj)) {
+    return obj.map(deepCopy);
+  } else if (typeof obj === "object" && obj !== null) {
+    return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, deepCopy(value)]));
+  }
+  return obj;
+}
+/**
+ * Get the key of a map by value.
+ * @param {Map<string, unknown>} map Map to get key from.
+ * @param {unknown} value Value to get key for.
+ * @returns {string | undefined} Key of the map.
+ *
+ * @example
+ * ```TypeScript
+ * // Example usage
+ * const user = new Map<string, string>([
+ *     ["firstName", "John"],
+ *     ["lastName", "Doe"],
+ *     ["preferredName", "John"],
+ *     ["age", 30],
+ * ]);
+ *
+ * const key = getMapKey(user, "value2");
+ *
+ * // Example output: "firstName"
+ * ```
+ */
+function getMapKey(map, value) {
+  return [...Array.from(map.entries())].find(([, v]) => v === value)?.[0];
+}
+/**
+ * Retrieves all keys from a Map where the corresponding values contain a specified substring.
+ *
+ * This utility function searches through a Map's values and returns an array of keys
+ * whose associated values include the provided partial string. The search is case-sensitive
+ * and uses JavaScript's native string.includes() method for matching.
+ *
+ * This is particularly useful for implementing search functionality, filtering operations,
+ * or finding related entries in configuration maps, user preference stores, or any
+ * key-value data structure where you need to locate entries by partial value matching.
+ *
+ * @param {Map<string, string>} map - The Map to search through for matching values
+ * @param {string} partialValue - The substring to search for within the Map's values
+ * @returns {string[]} An array of keys whose corresponding values contain the partial value
+ *
+ * @example
+ * ```typescript
+ * // Search user preferences for entries containing "John"
+ * const userPreferences = new Map<string, string>([
+ *     ["displayName", "John Doe"],
+ *     ["firstName", "John"],
+ *     ["lastName", "Doe"],
+ *     ["preferredName", "Johnny"],
+ *     ["email", "john.doe@example.com"]
+ * ]);
+ *
+ * const johnKeys = getMapKeys(userPreferences, "John");
+ * // Returns: ["displayName", "firstName", "email"]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Find configuration keys related to database settings
+ * const config = new Map<string, string>([
+ *     ["db_host", "localhost"],
+ *     ["db_port", "5432"],
+ *     ["cache_host", "redis-server"],
+ *     ["db_name", "myapp_database"],
+ *     ["log_level", "debug"]
+ * ]);
+ *
+ * const dbKeys = getMapKeys(config, "db");
+ * // Returns: ["db_name"] (only values containing "db", not keys)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Search in a translations map
+ * const translations = new Map<string, string>([
+ *     ["welcome_message", "Welcome to our application"],
+ *     ["error_message", "An error occurred"],
+ *     ["success_message", "Operation completed successfully"],
+ *     ["info_message", "Please check your information"]
+ * ]);
+ *
+ * const messageKeys = getMapKeys(translations, "message");
+ * // Returns: ["welcome_message", "error_message", "success_message", "info_message"]
+ * ```
+ *
+ * @remarks
+ * - The search is case-sensitive; "John" will not match "john"
+ * - Returns an empty array if no matches are found
+ * - The function iterates through all Map entries, so performance scales with Map size
+ * - Only works with Maps that have string values; other value types will cause runtime errors
+ */
+const getMapKeys = (map, partialValue) => {
+  const keys = [];
+  for (const [key, value] of Array.from(map.entries())) {
+    if (value.includes(partialValue)) {
+      keys.push(key);
+    }
+  }
+  return keys;
+};
+/**
+ * Groups an array of objects into a Map based on a key extraction function.
+ *
+ * This utility function takes an array of objects and organizes them into groups
+ * based on a common key or property. The grouping is performed using a key extraction
+ * function that you provide, which determines how each object should be categorized.
+ * The result is a Map where each key represents a group and the value is an array
+ * of objects belonging to that group.
+ *
+ * This is particularly useful for data analysis, reporting, organizing collections
+ * for display purposes, or preparing data for further processing where items need
+ * to be categorized by shared characteristics.
+ *
+ * @template K - The type of the grouping key (can be string, number, boolean, etc.)
+ * @template V - The type of the objects being grouped
+ * @param {Array<V>} list - The array of objects to group
+ * @param {(input: V) => K} keyGetter - A function that extracts the grouping key from each object.
+ *                                      This function receives an object and should return the value
+ *                                      to group by. If the function returns null or undefined,
+ *                                      the object will be grouped under a null key.
+ * @returns {Map<K | null, Array<V>>} A Map where keys are the grouping values and values are arrays
+ *                                    of objects that share that grouping key
+ *
+ * @example
+ * ```typescript
+ * // Group users by age
+ * interface User {
+ *   name: string;
+ *   age: number;
+ *   department: string;
+ * }
+ *
+ * const users: User[] = [
+ *     { name: "John", age: 30, department: "Engineering" },
+ *     { name: "Jane", age: 25, department: "Marketing" },
+ *     { name: "Bob", age: 30, department: "Engineering" },
+ *     { name: "Alice", age: 25, department: "Sales" },
+ *     { name: "Charlie", age: 35, department: "Engineering" }
+ * ];
+ *
+ * const usersByAge = groupBy(users, user => user.age);
+ * // Returns:
+ * // Map {
+ * //   30 => [
+ * //     { name: "John", age: 30, department: "Engineering" },
+ * //     { name: "Bob", age: 30, department: "Engineering" }
+ * //   ],
+ * //   25 => [
+ * //     { name: "Jane", age: 25, department: "Marketing" },
+ * //     { name: "Alice", age: 25, department: "Sales" }
+ * //   ],
+ * //   35 => [
+ * //     { name: "Charlie", age: 35, department: "Engineering" }
+ * //   ]
+ * // }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Group products by category
+ * interface Product {
+ *   id: number;
+ *   name: string;
+ *   category: string;
+ *   price: number;
+ * }
+ *
+ * const products: Product[] = [
+ *     { id: 1, name: "Laptop", category: "Electronics", price: 999 },
+ *     { id: 2, name: "Book", category: "Education", price: 29 },
+ *     { id: 3, name: "Phone", category: "Electronics", price: 699 },
+ *     { id: 4, name: "Pen", category: "Office", price: 5 }
+ * ];
+ *
+ * const productsByCategory = groupBy(products, product => product.category);
+ * // Useful for creating category-based product listings
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Group tasks by completion status with boolean keys
+ * interface Task {
+ *   id: number;
+ *   title: string;
+ *   completed: boolean;
+ * }
+ *
+ * const tasks: Task[] = [
+ *     { id: 1, title: "Review code", completed: true },
+ *     { id: 2, title: "Write tests", completed: false },
+ *     { id: 3, title: "Deploy app", completed: true },
+ *     { id: 4, title: "Update docs", completed: false }
+ * ];
+ *
+ * const tasksByStatus = groupBy(tasks, task => task.completed);
+ * // Returns Map with boolean keys: true and false
+ * ```
+ *
+ * @remarks
+ * - The function preserves the original order of objects within each group
+ * - If the keyGetter function returns null or undefined, those objects will be grouped under a null key
+ * - The Map structure allows for efficient lookups and iteration over groups
+ * - Works with any type of grouping key (string, number, boolean, objects, etc.)
+ * - Empty arrays will return an empty Map
+ */
+const groupBy = (list, keyGetter) => {
+  const map = new Map();
+  list.forEach(item => {
+    const key = keyGetter(item);
+    const collection = map.get(key);
+    if (!collection) {
+      map.set(key, [item]);
+    } else {
+      collection.push(item);
+    }
+  });
+  return map;
+};
+/**
+ * Retrieves all values from a Map that contain a specified substring.
+ *
+ * This utility function searches through a Map's values and returns an array of all values
+ * that include the provided partial string. The search is case-sensitive and uses JavaScript's
+ * native string.includes() method for matching. This is the counterpart to getMapKeys(),
+ * but instead of returning the keys, it returns the actual values that match.
+ *
+ * This is particularly useful for implementing search functionality where you need to find
+ * and display matching content, filtering data for autocomplete features, or extracting
+ * related values from configuration maps, user data, or any key-value store where you
+ * need to locate entries by partial content matching.
+ *
+ * @param {Map<string, string>} map - The Map to search through for matching values
+ * @param {string} partialValue - The substring to search for within the Map's values
+ * @returns {string[]} An array of values that contain the specified partial value
+ *
+ * @example
+ * ```typescript
+ * // Search user information for values containing "John"
+ * const userInfo = new Map<string, string>([
+ *     ["fullName", "John Doe"],
+ *     ["firstName", "John"],
+ *     ["lastName", "Doe"],
+ *     ["nickname", "Johnny"],
+ *     ["email", "john.doe@example.com"],
+ *     ["phone", "555-0123"]
+ * ]);
+ *
+ * const johnValues = searchMapValues(userInfo, "John");
+ * // Returns: ["John Doe", "John", "Johnny", "john.doe@example.com"]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Find error messages containing specific keywords
+ * const errorMessages = new Map<string, string>([
+ *     ["auth_failed", "Authentication failed. Please check your credentials."],
+ *     ["network_error", "Network connection failed. Please try again."],
+ *     ["validation_error", "Validation failed for the provided data."],
+ *     ["timeout_error", "Request timeout. The server took too long to respond."],
+ *     ["permission_denied", "Access denied. You don't have permission."]
+ * ]);
+ *
+ * const failedMessages = searchMapValues(errorMessages, "failed");
+ * // Returns: ["Authentication failed. Please check your credentials.",
+ * //          "Network connection failed. Please try again.",
+ * //          "Validation failed for the provided data."]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Search configuration values for environment-specific settings
+ * const config = new Map<string, string>([
+ *     ["api_url", "https://api.production.example.com"],
+ *     ["db_host", "production-db.example.com"],
+ *     ["cache_url", "redis://production-cache.example.com"],
+ *     ["log_level", "error"],
+ *     ["debug_mode", "false"]
+ * ]);
+ *
+ * const productionValues = searchMapValues(config, "production");
+ * // Returns: ["https://api.production.example.com",
+ * //          "production-db.example.com",
+ * //          "redis://production-cache.example.com"]
+ * ```
+ *
+ * @remarks
+ * - The search is case-sensitive; "John" will not match "john"
+ * - Returns an empty array if no matches are found
+ * - The function iterates through all Map entries, so performance scales with Map size
+ * - Only works with Maps that have string values; other value types will cause runtime errors
+ * - Values are returned in the order they appear in the Map iteration
+ *
+ * @see {@link getMapKeys} Function to get keys whose values contain a substring
+ */
+const searchMapValues = (map, partialValue) => {
+  const values = [];
+  for (const [, value] of Array.from(map.entries())) {
+    if (value.includes(partialValue)) {
+      values.push(value);
+    }
+  }
+  return values;
+};
+/**
+ * Gets a value from a nested object using a dot-notation path string.
+ *
+ * This function safely traverses a deeply nested object structure using a string path
+ * with dot notation. It handles both object properties and array indices within the path.
+ *
+ * @template T - Type of the value to be returned.
+ * @param {InfiniteObject} obj - The object to retrieve the value from.
+ * @param {string} path - The dot-notation path to the desired value.
+ *   - Use dots to navigate through nested objects: 'user.profile.address'
+ *   - Use array notation for accessing array elements: 'items[0]' or 'users[2].name'
+ * @returns {T | undefined} - The value at the specified path, or undefined if:
+ *   - Any part of the path doesn't exist
+ *   - An array index is out of bounds
+ *   - The path format is invalid
+ *
+ * @example
+ * ```typescript
+ * // Simple nested object property
+ * const user = {
+ *   profile: {
+ *     name: "John Doe",
+ *     contact: { email: "john@example.com" }
+ *   }
+ * };
+ * const email = getValueByPath<string>(user, "profile.contact.email");
+ * // Returns: "john@example.com"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Accessing array elements
+ * const data = {
+ *   users: [
+ *     { id: 1, name: "Alice" },
+ *     { id: 2, name: "Bob" }
+ *   ]
+ * };
+ * const name = getValueByPath<string>(data, "users[1].name");
+ * // Returns: "Bob"
+ * ```
+ */
+const getValueByPath = (obj, path) => {
+  const keys = path.split("."); // Split the path into an array of keys
+  let value = obj;
+  for (const key of keys) {
+    // noinspection RegExpRedundantEscape
+    const regExp = /^(\w+)\[(\d+)\]$/;
+    const isArrayIndex = regExp.exec(key); // Check if the key is an array index
+    if (isArrayIndex) {
+      const arrayKey = isArrayIndex[1];
+      // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+      const index = Number(isArrayIndex[2]);
+      if (arrayKey && Array.isArray(value[arrayKey]) && index >= 0 && index < value[arrayKey].length) {
+        value = value[arrayKey][index]; // Update the value to the array element
+      } else {
+        return undefined; // Return undefined if the array index is invalid
+      }
+    } else if (value && typeof value === "object" && key in value) {
+      value = value[key]; // Update the value to the nested property
+    } else {
+      return undefined; // Return undefined if any key is not found
+    }
+  }
+  return value;
+};
+/**
+ * Converts a nested object into a flattened DottedPathValueObject representation.
+ *
+ * This function transforms a hierarchical object structure into a flat key-value map
+ * where keys represent paths to values in the original object using dot notation.
+ *
+ * The function recursively traverses the object and flattens nested properties,
+ * converting object hierarchies like `{ user: { name: 'John' } }` into
+ * path-based entries like `{ 'user.name': 'John' }`.
+ *
+ * @param {LiteralObject} obj - The nested object to flatten
+ * @returns {DottedPathValueObject} - A flattened representation where:
+ *   - Keys are dot-notation paths to values in the original object
+ *   - Values are primitive values (strings, numbers, booleans) from the original object
+ *
+ * @remarks
+ * - Array values will be preserved as-is (not flattened into separate paths)
+ * - Only primitive values (string, number, boolean) are supported as leaf values
+ * - Circular references are not handled and will cause a stack overflow
+ *
+ * @see {@link dottedPathObjectToNested} The inverse operation to convert a DottedPathValueObject back to a nested object
+ * @see {@link DottedPathValueObject} The interface for the returned flattened object
+ *
+ * @example
+ * ```typescript
+ * // Flatten a nested user object
+ * const user = {
+ *   id: 123,
+ *   name: "John Doe",
+ *   isActive: true,
+ *   profile: {
+ *     age: 30,
+ *     address: {
+ *       city: "New York",
+ *       zip: "10001"
+ *     }
+ *   }
+ * };
+ *
+ * const flattened = objectToDottedPathValueObject(user);
+ *
+ * // Result:
+ * // {
+ * //   "id": 123,
+ * //   "name": "John Doe",
+ * //   "isActive": true,
+ * //   "profile.age": 30,
+ * //   "profile.address.city": "New York",
+ * //   "profile.address.zip": "10001"
+ * // }
+ * ```
+ */
+function objectToDottedPathValueObject(obj) {
+  const result = {};
+  function traverse(obj, path = []) {
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        const value = obj[key];
+        if (typeof value === "object" && !Array.isArray(value)) {
+          traverse(value, [...path, key]);
+        } else {
+          result[[...path, key].join(".")] = value;
+        }
+      }
+    }
+  }
+  traverse(obj);
+  return result;
+}
+/**
+ * Converts a flattened DottedPathValueObject back into a nested object structure.
+ *
+ * This function is the inverse of `objectToDottedPathValueObject`. It takes a flat map of
+ * dot-notation paths to values and reconstructs a hierarchical object structure.
+ *
+ * Each key in the input DottedPathValueObject represents a path through the object hierarchy,
+ * with dots separating each level. The function builds a nested object structure by
+ * parsing these paths and placing values at the appropriate locations.
+ *
+ * @template R - The type of the returned object (defaults to object)
+ * @param {DottedPathValueObject} pathValueSet - A flattened object with dot-notation path keys
+ * @returns {R} - A reconstructed nested object with the original hierarchy
+ *
+ * @remarks
+ * - Paths are validated for safety to prevent injection attacks
+ * - Invalid paths are silently skipped (not included in the result)
+ * - Path components should contain only alphanumeric characters, underscores, hyphens, and dots
+ *
+ * @see {@link objectToDottedPathValueObject} The inverse operation to convert an object to DottedPathValueObject
+ * @see {@link DottedPathValueObject} The interface for the input flattened object
+ *
+ * @example
+ * ```typescript
+ * // Convert a flat DottedPathValueObject to a nested object
+ * const flatData = {
+ *   "id": 123,
+ *   "name": "John Doe",
+ *   "profile.age": 30,
+ *   "profile.address.city": "New York",
+ *   "profile.address.zip": "10001"
+ * };
+ *
+ * const nestedObject = dottedPathObjectToNested(flatData);
+ *
+ * Result:
+ * // {
+ * //   id: 123,
+ * //   name: "John Doe",
+ * //   profile: {
+ * //     age: 30,
+ * //     address: {
+ * //       city: "New York",
+ * //       zip: "10001"
+ * //     }
+ * //   }
+ * // }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Typed return value
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   profile: {
+ *     age: number;
+ *     address: {
+ *       city: string;
+ *       zip: string;
+ *     };
+ *   };
+ * }
+ *
+ * const userData = dottedPathObjectToNested<User>(flatData);
+ * // Returns object with User type
+ * ```
+ */
+function dottedPathObjectToNested(pathValueSet) {
+  const object = {};
+  // Helper function to validate paths
+  const isValidPath = path => {
+    const regex = /^[a-zA-Z0-9_.-]+$/;
+    return path.split(".").every(part => regex.test(part));
+  };
+  // Helper function to set nested properties
+  const setObjectValue = (obj, keys, value) => {
+    const [firstKey, ...remainingKeys] = keys;
+    if (remainingKeys.length === 0) {
+      obj[firstKey] = value; // Set value at the final key
+      return;
+    }
+    // Initialize the key if it doesn't exist
+    obj[firstKey] = obj[firstKey] || {};
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+    setObjectValue(obj[firstKey], remainingKeys, value); // Recurse for the rest of the keys
+    // TODO: v2.0 Fix type for above
+  };
+  for (const path in pathValueSet) {
+    if (Object.prototype.hasOwnProperty.call(pathValueSet, path)) {
+      if (!isValidPath(path)) {
+        continue; // Skip invalid paths
+      }
+      const value = pathValueSet[path];
+      const keys = path.split("."); // Split path into keys
+      setObjectValue(object, keys, value); // Use helper to populate the object
+    }
+  }
+  return object;
+}
+/**
+ * Creates a new object by omitting specified properties and undefined values from the original object.
+ *
+ * This utility function performs a selective copy of an object, excluding both explicitly
+ * specified properties and any properties with undefined values. The function modifies
+ * the original object in-place by deleting the unwanted properties, making it useful for
+ * cleaning up objects before serialization, API calls, or data processing.
+ *
+ * This is particularly useful for preparing data for API requests where you need to remove
+ * sensitive fields, clean up form data, or exclude certain properties from being sent to
+ * external services. It's also helpful for removing undefined values that might cause
+ * issues in JSON serialization or database operations.
+ *
+ * @template T - The type of the object being processed
+ * @param {Partial<T>} obj - The object to process and remove properties from.
+ *                           This object will be modified in-place.
+ * @param {(keyof T)[]} [keys] - Optional array of property keys to omit from the object.
+ *                               If not provided, only undefined properties will be removed.
+ * @returns {Partial<T>} The same object reference with specified properties and undefined values removed
+ *
+ * @example
+ * ```typescript
+ * // Remove specific properties and undefined values
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ *   role: string;
+ *   address?: string;
+ *   phone?: string;
+ * }
+ *
+ * const user: Partial<User> = {
+ *     id: 123,
+ *     name: "John Doe",
+ *     email: "john@example.com",
+ *     role: "admin",
+ *     address: undefined,
+ *     phone: "555-0123"
+ * };
+ *
+ * const cleanUser = omit(user, ["role"]);
+ * // Returns: { id: 123, name: "John Doe", email: "john@example.com", phone: "555-0123" }
+ * // Note: 'role' and 'address' (undefined) are removed
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Remove only undefined values (no specific keys)
+ * const formData = {
+ *     firstName: "John",
+ *     lastName: "Doe",
+ *     middleName: undefined,
+ *     email: "john@example.com",
+ *     phone: undefined
+ * };
+ *
+ * const cleanFormData = omit(formData);
+ * // Returns: { firstName: "John", lastName: "Doe", email: "john@example.com" }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Prepare data for API request by removing sensitive fields
+ * interface UserProfile {
+ *   id: number;
+ *   username: string;
+ *   email: string;
+ *   password: string;
+ *   internalNotes: string;
+ *   createdAt: Date;
+ * }
+ *
+ * const userProfile: Partial<UserProfile> = {
+ *     id: 1,
+ *     username: "johndoe",
+ *     email: "john@example.com",
+ *     password: "secret123",
+ *     internalNotes: "VIP customer",
+ *     createdAt: new Date()
+ * };
+ *
+ * const publicProfile = omit(userProfile, ["password", "internalNotes"]);
+ * // Safe to send to client: { id: 1, username: "johndoe", email: "john@example.com", createdAt: Date }
+ * ```
+ *
+ * @remarks
+ * - This function modifies the original object in-place rather than creating a copy
+ * - Both explicitly specified keys and undefined properties are removed
+ * - If the input object is falsy (null, undefined), it's returned as-is
+ * - The function uses delete operator, which may affect object performance in some JavaScript engines
+ * - Properties with null values are preserved (only undefined values are automatically removed)
+ *
+ * @see {@link prune} Function for more comprehensive object cleaning including null and empty values
+ */
+const omit = (obj, keys) => {
+  if (obj) {
+    Object.keys(obj).forEach(key => {
+      return (obj[key] === undefined || keys?.includes(key)) && delete obj[key];
+    });
+  }
+  return obj;
+};
+/**
+ * Creates a deep copy of an object with all empty, null, undefined, and optionally prototype properties removed.
+ *
+ * This utility function recursively traverses an object and creates a clean copy by excluding
+ * properties that are null, undefined, or empty strings. It performs a deep cleaning operation,
+ * processing nested objects recursively to ensure that the entire object hierarchy is pruned
+ * of unwanted values.
+ *
+ * This is particularly useful for preparing data for serialization, cleaning up API responses,
+ * removing empty form fields, or ensuring that only meaningful data is processed or stored.
+ * The function is especially valuable when working with deeply nested objects that may contain
+ * sparse data or when you need to eliminate all traces of empty values from complex data structures.
+ *
+ * @template T - The type of the object being pruned
+ * @param {PartialWithNull<T>} obj - The object to prune. Can contain null, undefined, or empty values.
+ * @param {boolean} [omitPrototype=false] - Whether to exclude inherited properties from the prototype chain.
+ *                                          If true, only own properties will be included in the result.
+ *                                          If false (default), inherited enumerable properties will be processed.
+ * @returns {T} A new object with all empty, null, and undefined properties recursively removed
+ *
+ * @example
+ * ```typescript
+ * // Clean up a user profile with nested empty values
+ * interface UserProfile {
+ *   id: number;
+ *   name: string;
+ *   contact: {
+ *     email: string;
+ *     phone?: string;
+ *     address?: {
+ *       street: string;
+ *       city: string;
+ *       zip?: string;
+ *     };
+ *   };
+ *   preferences: {
+ *     theme: string;
+ *     notifications?: boolean;
+ *   };
+ * }
+ *
+ * const userProfile = {
+ *     id: 123,
+ *     name: "John Doe",
+ *     contact: {
+ *         email: "john@example.com",
+ *         phone: "",
+ *         address: {
+ *             street: "123 Main St",
+ *             city: "New York",
+ *             zip: null
+ *         }
+ *     },
+ *     preferences: {
+ *         theme: "dark",
+ *         notifications: undefined
+ *     }
+ * };
+ *
+ * const cleanProfile = prune(userProfile);
+ * // Returns:
+ * // {
+ * //   id: 123,
+ * //   name: "John Doe",
+ * //   contact: {
+ * //     email: "john@example.com",
+ * //     address: {
+ * //       street: "123 Main St",
+ * //       city: "New York"
+ * //     }
+ * //   },
+ * //   preferences: {
+ * //     theme: "dark"
+ * //   }
+ * // }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Clean up form data before submission
+ * const formData = {
+ *     firstName: "John",
+ *     lastName: "Doe",
+ *     middleName: "",
+ *     email: "john@example.com",
+ *     phone: null,
+ *     address: {
+ *         street: "123 Main St",
+ *         apartment: "",
+ *         city: "New York",
+ *         state: undefined,
+ *         zip: "10001"
+ *     },
+ *     emergencyContact: {
+ *         name: "",
+ *         phone: null
+ *     }
+ * };
+ *
+ * const cleanFormData = prune(formData);
+ * // Returns only fields with meaningful values:
+ * // {
+ * //   firstName: "John",
+ * //   lastName: "Doe",
+ * //   email: "john@example.com",
+ * //   address: {
+ * //     street: "123 Main St",
+ * //     city: "New York",
+ * //     zip: "10001"
+ * //   }
+ * // }
+ * // Note: emergencyContact object is completely removed as all its properties were empty
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Control prototype property inclusion
+ * class BaseUser {
+ *   role = "user";
+ * }
+ *
+ * class ExtendedUser extends BaseUser {
+ *   name = "John";
+ *   email = "";
+ * }
+ *
+ * const user = new ExtendedUser();
+ *
+ * const prunedWithPrototype = prune(user, false);
+ * // Includes inherited 'role' property: { role: "user", name: "John" }
+ *
+ * const prunedOwnOnly = prune(user, true);
+ * // Only own properties: { name: "John" }
+ * ```
+ *
+ * @remarks
+ * - Creates a new object rather than modifying the original (unlike the omit function)
+ * - Recursively processes nested objects to ensure deep cleaning
+ * - Removes properties with values: null, undefined, or empty string ("")
+ * - Preserves properties with falsy but meaningful values like 0, false
+ * - If a nested object becomes empty after pruning, it will be excluded from the result
+ * - Non-object types are returned as an empty object of the target type
+ * - The function preserves the type structure while removing empty values
+ *
+ * @see {@link omit} Function for selective property removal without deep cleaning
+ */
+const prune = (obj, omitPrototype) => {
+  const objClone = {};
+  if (typeof obj !== "object") {
+    return objClone;
+  }
+  for (const key in obj) {
+    if (!omitPrototype || Object.prototype.hasOwnProperty.call(obj, key)) {
+      if (obj[key] !== null && typeof obj[key] === "object") {
+        objClone[key] = prune(obj[key], omitPrototype);
+      } else if (obj[key] !== null && obj[key] !== undefined && obj[key] !== "") {
+        objClone[key] = obj[key];
+      }
+    }
+  }
+  return objClone;
+};
+/**
+ * Checks if an object has all specified properties as its own properties (not inherited).
+ *
+ * This utility function verifies that an object contains all the properties listed in the
+ * provided array as direct (own) properties, not inherited from the prototype chain.
+ * It uses the modern Object.hasOwn() method for reliable property existence checking,
+ * making it safer than using hasOwnProperty() directly.
+ *
+ * This is particularly useful for validating object structures, ensuring required properties
+ * exist before processing, implementing type guards, or verifying that objects conform to
+ * expected interfaces. It's commonly used in data validation, API request validation,
+ * and ensuring objects have all necessary properties before performing operations.
+ *
+ * @param {Record<PropertyKey, unknown>} obj - The object to check for property existence
+ * @param {PropertyKey[]} props - Array of property keys to verify exist on the object.
+ *                                PropertyKey includes string, number, and symbol types.
+ * @returns {boolean} True if the object has all specified properties as own properties, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Validate that a user object has required properties
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const user = {
+ *   id: 123,
+ *   name: "John Doe",
+ *   email: "john@example.com",
+ *   role: "admin"
+ * };
+ *
+ * const hasRequiredProps = hasOwnAll(user, ["id", "name", "email"]);
+ * // Returns: true
+ *
+ * const hasAllProps = hasOwnAll(user, ["id", "name", "email", "phone"]);
+ * // Returns: false (missing 'phone' property)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Validate API request payload
+ * function processUserUpdate(payload: unknown): User | null {
+ *   if (typeof payload === 'object' && payload !== null) {
+ *     const requiredFields = ['id', 'name', 'email'];
+ *
+ *     if (hasOwnAll(payload as Record<string, unknown>, requiredFields)) {
+ *       // Safe to process as we know all required fields exist
+ *       return updateUser(payload as User);
+ *     }
+ *   }
+ *
+ *   throw new Error('Invalid payload: missing required fields');
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check configuration object completeness
+ * interface DatabaseConfig {
+ *   host: string;
+ *   port: number;
+ *   database: string;
+ *   username: string;
+ *   password: string;
+ * }
+ *
+ * const config = {
+ *   host: "localhost",
+ *   port: 5432,
+ *   database: "myapp",
+ *   username: "admin"
+ *   // password is missing
+ * };
+ *
+ * const requiredConfigKeys = ['host', 'port', 'database', 'username', 'password'];
+ * const isConfigComplete = hasOwnAll(config, requiredConfigKeys);
+ * // Returns: false
+ *
+ * if (!isConfigComplete) {
+ *   throw new Error('Database configuration is incomplete');
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Work with symbol properties
+ * const symbolKey = Symbol('secret');
+ * const obj = {
+ *   name: "test",
+ *   [symbolKey]: "hidden value"
+ * };
+ *
+ * const hasSymbolProp = hasOwnAll(obj, ['name', symbolKey]);
+ * // Returns: true
+ * ```
+ *
+ * @remarks
+ * - Uses Object.hasOwn() which is more reliable than hasOwnProperty()
+ * - Only checks for own properties, not inherited properties from the prototype chain
+ * - Returns false immediately if any property is missing (short-circuit evaluation)
+ * - Works with string, number, and symbol property keys
+ * - Returns true for an empty properties array (vacuous truth)
+ * - Does not check property values, only existence
+ *
+ * @see {@link Object.hasOwn} The underlying method used for property checking
+ */
+function hasOwnAll(obj, props) {
+  return props.every(prop => Object.hasOwn(obj, prop));
+}
+/**
+ * Extracts all values from a TypeScript enum, handling both string and numeric enum types correctly.
+ *
+ * This utility function safely retrieves the actual values from TypeScript enums, accounting for
+ * the different internal representations of string and numeric enums. For numeric enums, TypeScript
+ * creates reverse mappings (value → key), so this function filters out the reverse mapping entries
+ * to return only the actual enum values. For string enums, it returns all values directly.
+ *
+ * This is particularly useful when you need to iterate over enum values, validate input against
+ * enum values, create dropdown options from enums, or perform any operation that requires access
+ * to the actual enum values rather than the keys.
+ *
+ * @template T - The enum type extending object
+ * @param {T} e - The enum object to extract values from
+ * @returns {T[keyof T][]} An array containing all the actual values of the enum
+ *
+ * @example
+ * ```typescript
+ * // String enum example
+ * enum Color {
+ *   RED = "red",
+ *   GREEN = "green",
+ *   BLUE = "blue"
+ * }
+ *
+ * const colorValues = getEnumValues(Color);
+ * // Returns: ["red", "green", "blue"]
+ *
+ * // Use for validation
+ * function isValidColor(value: string): value is Color {
+ *   return getEnumValues(Color).includes(value as Color);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Numeric enum example
+ * enum Status {
+ *   PENDING,    // 0
+ *   APPROVED,   // 1
+ *   REJECTED    // 2
+ * }
+ *
+ * const statusValues = getEnumValues(Status);
+ * // Returns: [0, 1, 2] (not ["PENDING", "APPROVED", "REJECTED", 0, 1, 2])
+ *
+ * // Use for creating select options
+ * const statusOptions = getEnumValues(Status).map(value => ({
+ *   value,
+ *   label: Status[value] // Get the key name for display
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Mixed numeric enum example
+ * enum HttpStatus {
+ *   OK = 200,
+ *   NOT_FOUND = 404,
+ *   SERVER_ERROR = 500
+ * }
+ *
+ * const httpStatusValues = getEnumValues(HttpStatus);
+ * // Returns: [200, 404, 500]
+ *
+ * // Use for status code validation
+ * function isValidHttpStatus(code: number): code is HttpStatus {
+ *   return getEnumValues(HttpStatus).includes(code as HttpStatus);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Creating dropdown options from enum
+ * enum UserRole {
+ *   ADMIN = "admin",
+ *   USER = "user",
+ *   MODERATOR = "moderator"
+ * }
+ *
+ * const roleOptions = getEnumValues(UserRole).map(role => ({
+ *   value: role,
+ *   label: role.charAt(0).toUpperCase() + role.slice(1)
+ * }));
+ * // Returns: [
+ * //   { value: "admin", label: "Admin" },
+ * //   { value: "user", label: "User" },
+ * //   { value: "moderator", label: "Moderator" }
+ * // ]
+ * ```
+ *
+ * @remarks
+ * - Automatically detects numeric vs string enums and handles them appropriately
+ * - For numeric enums, filters out reverse mapping entries that TypeScript automatically creates
+ * - For string enums, returns all values as-is since there are no reverse mappings
+ * - Works with mixed numeric enums (enums with explicit numeric values)
+ * - The returned array maintains the order of enum declaration
+ * - Type-safe: the return type is correctly inferred as an array of the enum's value types
+ *
+ * @see {@link Object.values} The underlying method used to extract enum entries
+ */
+function getEnumValues(e) {
+  const values = Object.values(e);
+  // In numeric enums, values can appear as keys (reverse mapping)
+  const isNumericEnum = values.some(v => typeof v === "number");
+  return isNumericEnum ? values.filter(v => typeof v !== "string") : values;
+}
+/**
+ * Filters items by recursively matching nested property values.
+ */
+function filterByObject(items, filters) {
+  function matchesObject(item, filter) {
+    if (typeof filter !== "object" || filter === null) {
+      return item === filter;
+    }
+    if (typeof item !== "object" || item === null) {
+      return false;
+    }
+    const itemObj = item;
+    const filterObj = filter;
+    for (const key in filterObj) {
+      if (!matchesObject(itemObj[key], filterObj[key])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  return items.filter(item => matchesObject(item, filters));
+}
+
+// noinspection JSUnusedGlobalSymbols
+/**
+ * Comprehensive mapping of file extensions to their corresponding MIME types.
+ *
+ * This map provides a bidirectional mapping between file extensions and MIME types,
+ * enabling applications to determine the appropriate content type for files or
+ * to identify the likely file extension for a given MIME type.
+ *
+ * The map includes entries for common file formats across various categories:
+ * - Documents (PDF, DOC, DOCX, XLS, XLSX, etc.)
+ * - Images (JPG, PNG, GIF, SVG, WebP, etc.)
+ * - Audio (MP3, WAV, OGG, etc.)
+ * - Video (MP4, WebM, AVI, etc.)
+ * - Archives (ZIP, RAR, 7Z, etc.)
+ * - Web resources (HTML, CSS, JS, etc.)
+ * - And many more specialized formats
+ *
+ * @remarks
+ * The map is indexed by file extension (without the dot prefix) and contains
+ * the corresponding MIME type as the value. Use utility functions like
+ * getMimeTypeFromExtension and getExtensionFromMimeType to perform lookups
+ * rather than accessing this map directly.
+ *
+ * Extensions are stored in lowercase to ensure case-insensitive matching.
+ *
+ * @example
+ * ```typescript
+ * // Get MIME type for a file extension
+ * const mimeType = getMimeTypeFromExtension('pdf'); // 'application/pdf'
+ *
+ * // Get file extension for a MIME type
+ * const extension = getExtensionFromMimeType('image/jpeg'); // 'jpg'
+ * ```
+ */
+const mimeTypes = new Map([["123", "application/vnd.lotus-1-2-3"], ["1km", "application/vnd.1000minds.decision-model+xml"], ["3dml", "text/vnd.in3d.3dml"], ["3ds", "image/x-3ds"], ["3g2", "video/3gpp2"], ["3gp", "video/3gpp"], ["3gpp", "video/3gpp"], ["3mf", "model/3mf"], ["7z", "application/x-7z-compressed"], ["aab", "application/x-authorware-bin"], ["aac", "audio/x-aac"], ["aam", "application/x-authorware-map"], ["aas", "application/x-authorware-seg"], ["abw", "application/x-abiword"], ["ac", "application/vnd.nokia.n-gage.ac+xml"], ["acc", "application/vnd.americandynamics.acc"], ["ace", "application/x-ace-compressed"], ["acu", "application/vnd.acucobol"], ["acutc", "application/vnd.acucorp"], ["adp", "audio/adpcm"], ["adts", "audio/aac"], ["aep", "application/vnd.audiograph"], ["afm", "application/x-font-type1"], ["afp", "application/vnd.ibm.modcap"], ["age", "application/vnd.age"], ["ahead", "application/vnd.ahead.space"], ["ai", "application/postscript"], ["aif", "audio/x-aiff"], ["aifc", "audio/x-aiff"], ["aiff", "audio/x-aiff"], ["air", "application/vnd.adobe.air-application-installer-package+zip"], ["ait", "application/vnd.dvb.ait"], ["ami", "application/vnd.amiga.ami"], ["aml", "application/automationml-aml+xml"], ["amlx", "application/automationml-amlx+zip"], ["amr", "audio/amr"], ["apk", "application/vnd.android.package-archive"], ["apng", "image/apng"], ["appcache", "text/cache-manifest"], ["appinstaller", "application/appinstaller"], ["application", "application/x-ms-application"], ["appx", "application/appx"], ["appxbundle", "application/appxbundle"], ["apr", "application/vnd.lotus-approach"], ["arc", "application/x-freearc"], ["arj", "application/x-arj"], ["asc", "application/pgp-signature"], ["asf", "video/x-ms-asf"], ["asm", "text/x-asm"], ["aso", "application/vnd.accpac.simply.aso"], ["asx", "video/x-ms-asf"], ["atc", "application/vnd.acucorp"], ["atom", "application/atom+xml"], ["atomcat", "application/atomcat+xml"], ["atomdeleted", "application/atomdeleted+xml"], ["atomsvc", "application/atomsvc+xml"], ["atx", "application/vnd.antix.game-component"], ["au", "audio/basic"], ["avci", "image/avci"], ["avcs", "image/avcs"], ["avi", "video/x-msvideo"], ["avif", "image/avif"], ["aw", "application/applixware"], ["azf", "application/vnd.airzip.filesecure.azf"], ["azs", "application/vnd.airzip.filesecure.azs"], ["azv", "image/vnd.airzip.accelerator.azv"], ["azw", "application/vnd.amazon.ebook"], ["b16", "image/vnd.pco.b16"], ["bat", "application/x-msdownload"], ["bcpio", "application/x-bcpio"], ["bdf", "application/x-font-bdf"], ["bdm", "application/vnd.syncml.dm+wbxml"], ["bdoc", "application/x-bdoc"], ["bed", "application/vnd.realvnc.bed"], ["bh2", "application/vnd.fujitsu.oasysprs"], ["bin", "application/octet-stream"], ["blb", "application/x-blorb"], ["blorb", "application/x-blorb"], ["bmi", "application/vnd.bmi"], ["bmml", "application/vnd.balsamiq.bmml+xml"], ["bmp", "image/x-ms-bmp"], ["book", "application/vnd.framemaker"], ["box", "application/vnd.previewsystems.box"], ["boz", "application/x-bzip2"], ["bpk", "application/octet-stream"], ["bsp", "model/vnd.valve.source.compiled-map"], ["btf", "image/prs.btif"], ["btif", "image/prs.btif"], ["buffer", "application/octet-stream"], ["bz", "application/x-bzip"], ["bz2", "application/x-bzip2"], ["c", "text/x-c"], ["c11amc", "application/vnd.cluetrust.cartomobile-config"], ["c11amz", "application/vnd.cluetrust.cartomobile-config-pkg"], ["c4d", "application/vnd.clonk.c4group"], ["c4f", "application/vnd.clonk.c4group"], ["c4g", "application/vnd.clonk.c4group"], ["c4p", "application/vnd.clonk.c4group"], ["c4u", "application/vnd.clonk.c4group"], ["cab", "application/vnd.ms-cab-compressed"], ["caf", "audio/x-caf"], ["cap", "application/vnd.tcpdump.pcap"], ["car", "application/vnd.curl.car"], ["cat", "application/vnd.ms-pki.seccat"], ["cb7", "application/x-cbr"], ["cba", "application/x-cbr"], ["cbr", "application/x-cbr"], ["cbt", "application/x-cbr"], ["cbz", "application/x-cbr"], ["cc", "text/x-c"], ["cco", "application/x-cocoa"], ["cct", "application/x-director"], ["ccxml", "application/ccxml+xml"], ["cdbcmsg", "application/vnd.contact.cmsg"], ["cdf", "application/x-netcdf"], ["cdfx", "application/cdfx+xml"], ["cdkey", "application/vnd.mediastation.cdkey"], ["cdmia", "application/cdmi-capability"], ["cdmic", "application/cdmi-container"], ["cdmid", "application/cdmi-domain"], ["cdmio", "application/cdmi-object"], ["cdmiq", "application/cdmi-queue"], ["cdx", "chemical/x-cdx"], ["cdxml", "application/vnd.chemdraw+xml"], ["cdy", "application/vnd.cinderella"], ["cer", "application/pkix-cert"], ["cfs", "application/x-cfs-compressed"], ["cgm", "image/cgm"], ["chat", "application/x-chat"], ["chm", "application/vnd.ms-htmlhelp"], ["chrt", "application/vnd.kde.kchart"], ["cif", "chemical/x-cif"], ["cii", "application/vnd.anser-web-certificate-issue-initiation"], ["cil", "application/vnd.ms-artgalry"], ["cjs", "application/node"], ["cla", "application/vnd.claymore"], ["class", "application/java-vm"], ["cld", "model/vnd.cld"], ["clkk", "application/vnd.crick.clicker.keyboard"], ["clkp", "application/vnd.crick.clicker.palette"], ["clkt", "application/vnd.crick.clicker.template"], ["clkw", "application/vnd.crick.clicker.wordbank"], ["clkx", "application/vnd.crick.clicker"], ["clp", "application/x-msclip"], ["cmc", "application/vnd.cosmocaller"], ["cmdf", "chemical/x-cmdf"], ["cml", "chemical/x-cml"], ["cmp", "application/vnd.yellowriver-custom-menu"], ["cmx", "image/x-cmx"], ["cod", "application/vnd.rim.cod"], ["coffee", "text/coffeescript"], ["com", "application/x-msdownload"], ["conf", "text/plain"], ["cpio", "application/x-cpio"], ["cpl", "application/cpl+xml"], ["cpp", "text/x-c"], ["cpt", "application/mac-compactpro"], ["crd", "application/x-mscardfile"], ["crl", "application/pkix-crl"], ["crt", "application/x-x509-ca-cert"], ["crx", "application/x-chrome-extension"], ["cryptonote", "application/vnd.rig.cryptonote"], ["csh", "application/x-csh"], ["csl", "application/vnd.citationstyles.style+xml"], ["csml", "chemical/x-csml"], ["csp", "application/vnd.commonspace"], ["css", "text/css"], ["cst", "application/x-director"], ["csv", "text/csv"], ["cu", "application/cu-seeme"], ["curl", "text/vnd.curl"], ["cwl", "application/cwl"], ["cww", "application/prs.cww"], ["cxt", "application/x-director"], ["cxx", "text/x-c"], ["dae", "model/vnd.collada+xml"], ["daf", "application/vnd.mobius.daf"], ["dart", "application/vnd.dart"], ["dataless", "application/vnd.fdsn.seed"], ["davmount", "application/davmount+xml"], ["dbf", "application/vnd.dbf"], ["dbk", "application/docbook+xml"], ["dcr", "application/x-director"], ["dcurl", "text/vnd.curl.dcurl"], ["dd2", "application/vnd.oma.dd2+xml"], ["ddd", "application/vnd.fujixerox.ddd"], ["ddf", "application/vnd.syncml.dmddf+xml"], ["dds", "image/vnd.ms-dds"], ["deb", "application/x-debian-package"], ["def", "text/plain"], ["deploy", "application/octet-stream"], ["der", "application/x-x509-ca-cert"], ["dfac", "application/vnd.dreamfactory"], ["dgc", "application/x-dgc-compressed"], ["dib", "image/bmp"], ["dic", "text/x-c"], ["dir", "application/x-director"], ["dis", "application/vnd.mobius.dis"], ["disposition-notification", "message/disposition-notification"], ["dist", "application/octet-stream"], ["distz", "application/octet-stream"], ["djv", "image/vnd.djvu"], ["djvu", "image/vnd.djvu"], ["dll", "application/x-msdownload"], ["dmg", "application/x-apple-diskimage"], ["dmp", "application/vnd.tcpdump.pcap"], ["dms", "application/octet-stream"], ["dna", "application/vnd.dna"], ["doc", "application/msword"], ["docm", "application/vnd.ms-word.document.macroenabled.12"], ["docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"], ["dot", "application/msword"], ["dotm", "application/vnd.ms-word.template.macroenabled.12"], ["dotx", "application/vnd.openxmlformats-officedocument.wordprocessingml.template"], ["dp", "application/vnd.osgi.dp"], ["dpg", "application/vnd.dpgraph"], ["dpx", "image/dpx"], ["dra", "audio/vnd.dra"], ["drle", "image/dicom-rle"], ["dsc", "text/prs.lines.tag"], ["dssc", "application/dssc+der"], ["dtb", "application/x-dtbook+xml"], ["dtd", "application/xml-dtd"], ["dts", "audio/vnd.dts"], ["dtshd", "audio/vnd.dts.hd"], ["dump", "application/octet-stream"], ["dvb", "video/vnd.dvb.file"], ["dvi", "application/x-dvi"], ["dwd", "application/atsc-dwd+xml"], ["dwf", "model/vnd.dwf"], ["dwg", "image/vnd.dwg"], ["dxf", "image/vnd.dxf"], ["dxp", "application/vnd.spotfire.dxp"], ["dxr", "application/x-director"], ["ear", "application/java-archive"], ["ecelp4800", "audio/vnd.nuera.ecelp4800"], ["ecelp7470", "audio/vnd.nuera.ecelp7470"], ["ecelp9600", "audio/vnd.nuera.ecelp9600"], ["ecma", "application/ecmascript"], ["edm", "application/vnd.novadigm.edm"], ["edx", "application/vnd.novadigm.edx"], ["efif", "application/vnd.picsel"], ["ei6", "application/vnd.pg.osasli"], ["elc", "application/octet-stream"], ["emf", "image/emf"], ["eml", "message/rfc822"], ["emma", "application/emma+xml"], ["emotionml", "application/emotionml+xml"], ["emz", "application/x-msmetafile"], ["eol", "audio/vnd.digital-winds"], ["eot", "application/vnd.ms-fontobject"], ["eps", "application/postscript"], ["epub", "application/epub+zip"], ["es3", "application/vnd.eszigno3+xml"], ["esa", "application/vnd.osgi.subsystem"], ["esf", "application/vnd.epson.esf"], ["et3", "application/vnd.eszigno3+xml"], ["etx", "text/x-setext"], ["eva", "application/x-eva"], ["evy", "application/x-envoy"], ["exe", "application/x-msdownload"], ["exi", "application/exi"], ["exp", "application/express"], ["exr", "image/aces"], ["ext", "application/vnd.novadigm.ext"], ["ez", "application/andrew-inset"], ["ez2", "application/vnd.ezpix-album"], ["ez3", "application/vnd.ezpix-package"], ["f", "text/x-fortran"], ["f4v", "video/x-f4v"], ["f77", "text/x-fortran"], ["f90", "text/x-fortran"], ["fbs", "image/vnd.fastbidsheet"], ["fcdt", "application/vnd.adobe.formscentral.fcdt"], ["fcs", "application/vnd.isac.fcs"], ["fdf", "application/vnd.fdf"], ["fdt", "application/fdt+xml"], ["fe_launch", "application/vnd.denovo.fcselayout-link"], ["fg5", "application/vnd.fujitsu.oasysgp"], ["fgd", "application/x-director"], ["fh", "image/x-freehand"], ["fh4", "image/x-freehand"], ["fh5", "image/x-freehand"], ["fh7", "image/x-freehand"], ["fhc", "image/x-freehand"], ["fig", "application/x-xfig"], ["fits", "image/fits"], ["flac", "audio/x-flac"], ["fli", "video/x-fli"], ["flo", "application/vnd.micrografx.flo"], ["flv", "video/x-flv"], ["flw", "application/vnd.kde.kivio"], ["flx", "text/vnd.fmi.flexstor"], ["fly", "text/vnd.fly"], ["fm", "application/vnd.framemaker"], ["fnc", "application/vnd.frogans.fnc"], ["fo", "application/vnd.software602.filler.form+xml"], ["for", "text/x-fortran"], ["fpx", "image/vnd.fpx"], ["frame", "application/vnd.framemaker"], ["fsc", "application/vnd.fsc.weblaunch"], ["fst", "image/vnd.fst"], ["ftc", "application/vnd.fluxtime.clip"], ["fti", "application/vnd.anser-web-funds-transfer-initiation"], ["fvt", "video/vnd.fvt"], ["fxp", "application/vnd.adobe.fxp"], ["fxpl", "application/vnd.adobe.fxp"], ["fzs", "application/vnd.fuzzysheet"], ["g2w", "application/vnd.geoplan"], ["g3", "image/g3fax"], ["g3w", "application/vnd.geospace"], ["gac", "application/vnd.groove-account"], ["gam", "application/x-tads"], ["gbr", "application/rpki-ghostbusters"], ["gca", "application/x-gca-compressed"], ["gdl", "model/vnd.gdl"], ["gdoc", "application/vnd.google-apps.document"], ["ged", "text/vnd.familysearch.gedcom"], ["geo", "application/vnd.dynageo"], ["geojson", "application/geo+json"], ["gex", "application/vnd.geometry-explorer"], ["ggb", "application/vnd.geogebra.file"], ["ggt", "application/vnd.geogebra.tool"], ["ghf", "application/vnd.groove-help"], ["gif", "image/gif"], ["gim", "application/vnd.groove-identity-message"], ["glb", "model/gltf-binary"], ["gltf", "model/gltf+json"], ["gml", "application/gml+xml"], ["gmx", "application/vnd.gmx"], ["gnumeric", "application/x-gnumeric"], ["gph", "application/vnd.flographit"], ["gpx", "application/gpx+xml"], ["gqf", "application/vnd.grafeq"], ["gqs", "application/vnd.grafeq"], ["gram", "application/srgs"], ["gramps", "application/x-gramps-xml"], ["gre", "application/vnd.geometry-explorer"], ["grv", "application/vnd.groove-injector"], ["grxml", "application/srgs+xml"], ["gsf", "application/x-font-ghostscript"], ["gsheet", "application/vnd.google-apps.spreadsheet"], ["gslides", "application/vnd.google-apps.presentation"], ["gtar", "application/x-gtar"], ["gtm", "application/vnd.groove-tool-message"], ["gtw", "model/vnd.gtw"], ["gv", "text/vnd.graphviz"], ["gxf", "application/gxf"], ["gxt", "application/vnd.geonext"], ["gz", "application/gzip"], ["h", "text/x-c"], ["h261", "video/h261"], ["h263", "video/h263"], ["h264", "video/h264"], ["hal", "application/vnd.hal+xml"], ["hbci", "application/vnd.hbci"], ["hbs", "text/x-handlebars-template"], ["hdd", "application/x-virtualbox-hdd"], ["hdf", "application/x-hdf"], ["heic", "image/heic"], ["heics", "image/heic-sequence"], ["heif", "image/heif"], ["heifs", "image/heif-sequence"], ["hej2", "image/hej2k"], ["held", "application/atsc-held+xml"], ["hh", "text/x-c"], ["hjson", "application/hjson"], ["hlp", "application/winhlp"], ["hpgl", "application/vnd.hp-hpgl"], ["hpid", "application/vnd.hp-hpid"], ["hps", "application/vnd.hp-hps"], ["hqx", "application/mac-binhex40"], ["hsj2", "image/hsj2"], ["htc", "text/x-component"], ["htke", "application/vnd.kenameaapp"], ["htm", "text/html"], ["html", "text/html"], ["hvd", "application/vnd.yamaha.hv-dic"], ["hvp", "application/vnd.yamaha.hv-voice"], ["hvs", "application/vnd.yamaha.hv-script"], ["i2g", "application/vnd.intergeo"], ["icc", "application/vnd.iccprofile"], ["ice", "x-conference/x-cooltalk"], ["icm", "application/vnd.iccprofile"], ["ico", "image/x-icon"], ["ics", "text/calendar"], ["ief", "image/ief"], ["ifb", "text/calendar"], ["ifm", "application/vnd.shana.informed.formdata"], ["iges", "model/iges"], ["igl", "application/vnd.igloader"], ["igm", "application/vnd.insors.igm"], ["igs", "model/iges"], ["igx", "application/vnd.micrografx.igx"], ["iif", "application/vnd.shana.informed.interchange"], ["img", "application/octet-stream"], ["imp", "application/vnd.accpac.simply.imp"], ["ims", "application/vnd.ms-ims"], ["in", "text/plain"], ["ini", "text/plain"], ["ink", "application/inkml+xml"], ["inkml", "application/inkml+xml"], ["install", "application/x-install-instructions"], ["iota", "application/vnd.astraea-software.iota"], ["ipfix", "application/ipfix"], ["ipk", "application/vnd.shana.informed.package"], ["irm", "application/vnd.ibm.rights-management"], ["irp", "application/vnd.irepository.package+xml"], ["iso", "application/x-iso9660-image"], ["itp", "application/vnd.shana.informed.formtemplate"], ["its", "application/its+xml"], ["ivp", "application/vnd.immervision-ivp"], ["ivu", "application/vnd.immervision-ivu"], ["jad", "text/vnd.sun.j2me.app-descriptor"], ["jade", "text/jade"], ["jam", "application/vnd.jam"], ["jar", "application/java-archive"], ["jardiff", "application/x-java-archive-diff"], ["java", "text/x-java-source"], ["jhc", "image/jphc"], ["jisp", "application/vnd.jisp"], ["jls", "image/jls"], ["jlt", "application/vnd.hp-jlyt"], ["jng", "image/x-jng"], ["jnlp", "application/x-java-jnlp-file"], ["joda", "application/vnd.joost.joda-archive"], ["jp2", "image/jp2"], ["jpe", "image/jpeg"], ["jpeg", "image/jpeg"], ["jpf", "image/jpx"], ["jpg", "image/jpeg"], ["jpg2", "image/jp2"], ["jpgm", "video/jpm"], ["jpgv", "video/jpeg"], ["jph", "image/jph"], ["jpm", "video/jpm"], ["jpx", "image/jpx"], ["js", "text/javascript"], ["json", "application/json"], ["json5", "application/json5"], ["jsonld", "application/ld+json"], ["jsonml", "application/jsonml+json"], ["jsx", "text/jsx"], ["jt", "model/jt"], ["jxr", "image/jxr"], ["jxra", "image/jxra"], ["jxrs", "image/jxrs"], ["jxs", "image/jxs"], ["jxsc", "image/jxsc"], ["jxsi", "image/jxsi"], ["jxss", "image/jxss"], ["kar", "audio/midi"], ["karbon", "application/vnd.kde.karbon"], ["kdbx", "application/x-keepass2"], ["key", "application/x-iwork-keynote-sffkey"], ["kfo", "application/vnd.kde.kformula"], ["kia", "application/vnd.kidspiration"], ["kml", "application/vnd.google-earth.kml+xml"], ["kmz", "application/vnd.google-earth.kmz"], ["kne", "application/vnd.kinar"], ["knp", "application/vnd.kinar"], ["kon", "application/vnd.kde.kontour"], ["kpr", "application/vnd.kde.kpresenter"], ["kpt", "application/vnd.kde.kpresenter"], ["kpxx", "application/vnd.ds-keypoint"], ["ksp", "application/vnd.kde.kspread"], ["ktr", "application/vnd.kahootz"], ["ktx", "image/ktx"], ["ktx2", "image/ktx2"], ["ktz", "application/vnd.kahootz"], ["kwd", "application/vnd.kde.kword"], ["kwt", "application/vnd.kde.kword"], ["lasxml", "application/vnd.las.las+xml"], ["latex", "application/x-latex"], ["lbd", "application/vnd.llamagraphics.life-balance.desktop"], ["lbe", "application/vnd.llamagraphics.life-balance.exchange+xml"], ["les", "application/vnd.hhe.lesson-player"], ["less", "text/less"], ["lgr", "application/lgr+xml"], ["lha", "application/x-lzh-compressed"], ["link66", "application/vnd.route66.link66+xml"], ["list", "text/plain"], ["list3820", "application/vnd.ibm.modcap"], ["listafp", "application/vnd.ibm.modcap"], ["litcoffee", "text/coffeescript"], ["lnk", "application/x-ms-shortcut"], ["log", "text/plain"], ["lostxml", "application/lost+xml"], ["lrf", "application/octet-stream"], ["lrm", "application/vnd.ms-lrm"], ["ltf", "application/vnd.frogans.ltf"], ["lua", "text/x-lua"], ["luac", "application/x-lua-bytecode"], ["lvp", "audio/vnd.lucent.voice"], ["lwp", "application/vnd.lotus-wordpro"], ["lzh", "application/x-lzh-compressed"], ["m13", "application/x-msmediaview"], ["m14", "application/x-msmediaview"], ["m1v", "video/mpeg"], ["m21", "application/mp21"], ["m2a", "audio/mpeg"], ["m2v", "video/mpeg"], ["m3a", "audio/mpeg"], ["m3u", "audio/x-mpegurl"], ["m3u8", "application/vnd.apple.mpegurl"], ["m4a", "audio/x-m4a"], ["m4p", "application/mp4"], ["m4s", "video/iso.segment"], ["m4u", "video/vnd.mpegurl"], ["m4v", "video/x-m4v"], ["ma", "application/mathematica"], ["mads", "application/mads+xml"], ["maei", "application/mmt-aei+xml"], ["mag", "application/vnd.ecowin.chart"], ["maker", "application/vnd.framemaker"], ["man", "text/troff"], ["manifest", "text/cache-manifest"], ["map", "application/json"], ["mar", "application/octet-stream"], ["markdown", "text/markdown"], ["mathml", "application/mathml+xml"], ["mb", "application/mathematica"], ["mbk", "application/vnd.mobius.mbk"], ["mbox", "application/mbox"], ["mc1", "application/vnd.medcalcdata"], ["mcd", "application/vnd.mcd"], ["mcurl", "text/vnd.curl.mcurl"], ["md", "text/markdown"], ["mdb", "application/x-msaccess"], ["mdi", "image/vnd.ms-modi"], ["mdx", "text/mdx"], ["me", "text/troff"], ["mesh", "model/mesh"], ["meta4", "application/metalink4+xml"], ["metalink", "application/metalink+xml"], ["mets", "application/mets+xml"], ["mfm", "application/vnd.mfmp"], ["mft", "application/rpki-manifest"], ["mgp", "application/vnd.osgeo.mapguide.package"], ["mgz", "application/vnd.proteus.magazine"], ["mid", "audio/midi"], ["midi", "audio/midi"], ["mie", "application/x-mie"], ["mif", "application/vnd.mif"], ["mime", "message/rfc822"], ["mj2", "video/mj2"], ["mjp2", "video/mj2"], ["mjs", "text/javascript"], ["mk3d", "video/x-matroska"], ["mka", "audio/x-matroska"], ["mkd", "text/x-markdown"], ["mks", "video/x-matroska"], ["mkv", "video/x-matroska"], ["mlp", "application/vnd.dolby.mlp"], ["mmd", "application/vnd.chipnuts.karaoke-mmd"], ["mmf", "application/vnd.smaf"], ["mml", "text/mathml"], ["mmr", "image/vnd.fujixerox.edmics-mmr"], ["mng", "video/x-mng"], ["mny", "application/x-msmoney"], ["mobi", "application/x-mobipocket-ebook"], ["mods", "application/mods+xml"], ["mov", "video/quicktime"], ["movie", "video/x-sgi-movie"], ["mp2", "audio/mpeg"], ["mp21", "application/mp21"], ["mp2a", "audio/mpeg"], ["mp3", "audio/mpeg"], ["mp4", "video/mp4"], ["mp4a", "audio/mp4"], ["mp4s", "application/mp4"], ["mp4v", "video/mp4"], ["mpc", "application/vnd.mophun.certificate"], ["mpd", "application/dash+xml"], ["mpe", "video/mpeg"], ["mpeg", "video/mpeg"], ["mpf", "application/media-policy-dataset+xml"], ["mpg", "video/mpeg"], ["mpg4", "video/mp4"], ["mpga", "audio/mpeg"], ["mpkg", "application/vnd.apple.installer+xml"], ["mpm", "application/vnd.blueice.multipass"], ["mpn", "application/vnd.mophun.application"], ["mpp", "application/vnd.ms-project"], ["mpt", "application/vnd.ms-project"], ["mpy", "application/vnd.ibm.minipay"], ["mqy", "application/vnd.mobius.mqy"], ["mrc", "application/marc"], ["mrcx", "application/marcxml+xml"], ["ms", "text/troff"], ["mscml", "application/mediaservercontrol+xml"], ["mseed", "application/vnd.fdsn.mseed"], ["mseq", "application/vnd.mseq"], ["msf", "application/vnd.epson.msf"], ["msg", "application/vnd.ms-outlook"], ["msh", "model/mesh"], ["msi", "application/x-msdownload"], ["msix", "application/msix"], ["msixbundle", "application/msixbundle"], ["msl", "application/vnd.mobius.msl"], ["msm", "application/octet-stream"], ["msp", "application/octet-stream"], ["msty", "application/vnd.muvee.style"], ["mtl", "model/mtl"], ["mts", "model/vnd.mts"], ["mus", "application/vnd.musician"], ["musd", "application/mmt-usd+xml"], ["musicxml", "application/vnd.recordare.musicxml+xml"], ["mvb", "application/x-msmediaview"], ["mvt", "application/vnd.mapbox-vector-tile"], ["mwf", "application/vnd.mfer"], ["mxf", "application/mxf"], ["mxl", "application/vnd.recordare.musicxml"], ["mxmf", "audio/mobile-xmf"], ["mxml", "application/xv+xml"], ["mxs", "application/vnd.triscape.mxs"], ["mxu", "video/vnd.mpegurl"], ["n-gage", "application/vnd.nokia.n-gage.symbian.install"], ["n3", "text/n3"], ["nb", "application/mathematica"], ["nbp", "application/vnd.wolfram.player"], ["nc", "application/x-netcdf"], ["ncx", "application/x-dtbncx+xml"], ["nfo", "text/x-nfo"], ["ngdat", "application/vnd.nokia.n-gage.data"], ["nitf", "application/vnd.nitf"], ["nlu", "application/vnd.neurolanguage.nlu"], ["nml", "application/vnd.enliven"], ["nnd", "application/vnd.noblenet-directory"], ["nns", "application/vnd.noblenet-sealer"], ["nnw", "application/vnd.noblenet-web"], ["npx", "image/vnd.net-fpx"], ["nq", "application/n-quads"], ["nsc", "application/x-conference"], ["nsf", "application/vnd.lotus-notes"], ["nt", "application/n-triples"], ["ntf", "application/vnd.nitf"], ["numbers", "application/x-iwork-numbers-sffnumbers"], ["nzb", "application/x-nzb"], ["oa2", "application/vnd.fujitsu.oasys2"], ["oa3", "application/vnd.fujitsu.oasys3"], ["oas", "application/vnd.fujitsu.oasys"], ["obd", "application/x-msbinder"], ["obgx", "application/vnd.openblox.game+xml"], ["obj", "model/obj"], ["oda", "application/oda"], ["odb", "application/vnd.oasis.opendocument.database"], ["odc", "application/vnd.oasis.opendocument.chart"], ["odf", "application/vnd.oasis.opendocument.formula"], ["odft", "application/vnd.oasis.opendocument.formula-template"], ["odg", "application/vnd.oasis.opendocument.graphics"], ["odi", "application/vnd.oasis.opendocument.image"], ["odm", "application/vnd.oasis.opendocument.text-master"], ["odp", "application/vnd.oasis.opendocument.presentation"], ["ods", "application/vnd.oasis.opendocument.spreadsheet"], ["odt", "application/vnd.oasis.opendocument.text"], ["oga", "audio/ogg"], ["ogex", "model/vnd.opengex"], ["ogg", "audio/ogg"], ["ogv", "video/ogg"], ["ogx", "application/ogg"], ["omdoc", "application/omdoc+xml"], ["onepkg", "application/onenote"], ["onetmp", "application/onenote"], ["onetoc", "application/onenote"], ["onetoc2", "application/onenote"], ["opf", "application/oebps-package+xml"], ["opml", "text/x-opml"], ["oprc", "application/vnd.palm"], ["opus", "audio/ogg"], ["org", "text/x-org"], ["osf", "application/vnd.yamaha.openscoreformat"], ["osfpvg", "application/vnd.yamaha.openscoreformat.osfpvg+xml"], ["osm", "application/vnd.openstreetmap.data+xml"], ["otc", "application/vnd.oasis.opendocument.chart-template"], ["otf", "font/otf"], ["otg", "application/vnd.oasis.opendocument.graphics-template"], ["oth", "application/vnd.oasis.opendocument.text-web"], ["oti", "application/vnd.oasis.opendocument.image-template"], ["otp", "application/vnd.oasis.opendocument.presentation-template"], ["ots", "application/vnd.oasis.opendocument.spreadsheet-template"], ["ott", "application/vnd.oasis.opendocument.text-template"], ["ova", "application/x-virtualbox-ova"], ["ovf", "application/x-virtualbox-ovf"], ["owl", "application/rdf+xml"], ["oxps", "application/oxps"], ["oxt", "application/vnd.openofficeorg.extension"], ["p", "text/x-pascal"], ["p10", "application/pkcs10"], ["p12", "application/x-pkcs12"], ["p7b", "application/x-pkcs7-certificates"], ["p7c", "application/pkcs7-mime"], ["p7m", "application/pkcs7-mime"], ["p7r", "application/x-pkcs7-certreqresp"], ["p7s", "application/pkcs7-signature"], ["p8", "application/pkcs8"], ["pac", "application/x-ns-proxy-autoconfig"], ["pages", "application/x-iwork-pages-sffpages"], ["pas", "text/x-pascal"], ["paw", "application/vnd.pawaafile"], ["pbd", "application/vnd.powerbuilder6"], ["pbm", "image/x-portable-bitmap"], ["pcap", "application/vnd.tcpdump.pcap"], ["pcf", "application/x-font-pcf"], ["pcl", "application/vnd.hp-pcl"], ["pclxl", "application/vnd.hp-pclxl"], ["pct", "image/x-pict"], ["pcurl", "application/vnd.curl.pcurl"], ["pcx", "image/x-pcx"], ["pdb", "application/x-pilot"], ["pde", "text/x-processing"], ["pem", "application/x-x509-ca-cert"], ["pfa", "application/x-font-type1"], ["pfb", "application/x-font-type1"], ["pfm", "application/x-font-type1"], ["pfr", "application/font-tdpfr"], ["pfx", "application/x-pkcs12"], ["pgm", "image/x-portable-graymap"], ["pgn", "application/x-chess-pgn"], ["pgp", "application/pgp-encrypted"], ["php", "application/x-httpd-php"], ["pic", "image/x-pict"], ["pkg", "application/octet-stream"], ["pki", "application/pkixcmp"], ["pkipath", "application/pkix-pkipath"], ["pkpass", "application/vnd.apple.pkpass"], ["pl", "application/x-perl"], ["plb", "application/vnd.3gpp.pic-bw-large"], ["plc", "application/vnd.mobius.plc"], ["plf", "application/vnd.pocketlearn"], ["pls", "application/pls+xml"], ["pm", "application/x-perl"], ["pml", "application/vnd.ctc-posml"], ["png", "image/png"], ["pnm", "image/x-portable-anymap"], ["portpkg", "application/vnd.macports.portpkg"], ["pot", "application/vnd.ms-powerpoint"], ["potm", "application/vnd.ms-powerpoint.template.macroenabled.12"], ["potx", "application/vnd.openxmlformats-officedocument.presentationml.template"], ["ppam", "application/vnd.ms-powerpoint.addin.macroenabled.12"], ["ppd", "application/vnd.cups-ppd"], ["ppm", "image/x-portable-pixmap"], ["pps", "application/vnd.ms-powerpoint"], ["ppsm", "application/vnd.ms-powerpoint.slideshow.macroenabled.12"], ["ppsx", "application/vnd.openxmlformats-officedocument.presentationml.slideshow"], ["ppt", "application/vnd.ms-powerpoint"], ["pptm", "application/vnd.ms-powerpoint.presentation.macroenabled.12"], ["pptx", "application/vnd.openxmlformats-officedocument.presentationml.presentation"], ["pqa", "application/vnd.palm"], ["prc", "model/prc"], ["pre", "application/vnd.lotus-freelance"], ["prf", "application/pics-rules"], ["provx", "application/provenance+xml"], ["ps", "application/postscript"], ["psb", "application/vnd.3gpp.pic-bw-small"], ["psd", "image/vnd.adobe.photoshop"], ["psf", "application/x-font-linux-psf"], ["pskcxml", "application/pskc+xml"], ["pti", "image/prs.pti"], ["ptid", "application/vnd.pvi.ptid1"], ["pub", "application/x-mspublisher"], ["pvb", "application/vnd.3gpp.pic-bw-var"], ["pwn", "application/vnd.3m.post-it-notes"], ["pya", "audio/vnd.ms-playready.media.pya"], ["pyo", "model/vnd.pytha.pyox"], ["pyox", "model/vnd.pytha.pyox"], ["pyv", "video/vnd.ms-playready.media.pyv"], ["qam", "application/vnd.epson.quickanime"], ["qbo", "application/vnd.intu.qbo"], ["qfx", "application/vnd.intu.qfx"], ["qps", "application/vnd.publishare-delta-tree"], ["qt", "video/quicktime"], ["qwd", "application/vnd.quark.quarkxpress"], ["qwt", "application/vnd.quark.quarkxpress"], ["qxb", "application/vnd.quark.quarkxpress"], ["qxd", "application/vnd.quark.quarkxpress"], ["qxl", "application/vnd.quark.quarkxpress"], ["qxt", "application/vnd.quark.quarkxpress"], ["ra", "audio/x-realaudio"], ["ram", "audio/x-pn-realaudio"], ["raml", "application/raml+yaml"], ["rapd", "application/route-apd+xml"], ["rar", "application/x-rar-compressed"], ["ras", "image/x-cmu-raster"], ["rcprofile", "application/vnd.ipunplugged.rcprofile"], ["rdf", "application/rdf+xml"], ["rdz", "application/vnd.data-vision.rdz"], ["relo", "application/p2p-overlay+xml"], ["rep", "application/vnd.businessobjects"], ["res", "application/x-dtbresource+xml"], ["rgb", "image/x-rgb"], ["rif", "application/reginfo+xml"], ["rip", "audio/vnd.rip"], ["ris", "application/x-research-info-systems"], ["rl", "application/resource-lists+xml"], ["rlc", "image/vnd.fujixerox.edmics-rlc"], ["rld", "application/resource-lists-diff+xml"], ["rm", "application/vnd.rn-realmedia"], ["rmi", "audio/midi"], ["rmp", "audio/x-pn-realaudio-plugin"], ["rms", "application/vnd.jcp.javame.midlet-rms"], ["rmvb", "application/vnd.rn-realmedia-vbr"], ["rnc", "application/relax-ng-compact-syntax"], ["rng", "application/xml"], ["roa", "application/rpki-roa"], ["roff", "text/troff"], ["rp9", "application/vnd.cloanto.rp9"], ["rpm", "application/x-redhat-package-manager"], ["rpss", "application/vnd.nokia.radio-presets"], ["rpst", "application/vnd.nokia.radio-preset"], ["rq", "application/sparql-query"], ["rs", "application/rls-services+xml"], ["rsat", "application/atsc-rsat+xml"], ["rsd", "application/rsd+xml"], ["rsheet", "application/urc-ressheet+xml"], ["rss", "application/rss+xml"], ["rtf", "text/rtf"], ["rtx", "text/richtext"], ["run", "application/x-makeself"], ["rusd", "application/route-usd+xml"], ["s", "text/x-asm"], ["s3m", "audio/s3m"], ["saf", "application/vnd.yamaha.smaf-audio"], ["sass", "text/x-sass"], ["sbml", "application/sbml+xml"], ["sc", "application/vnd.ibm.secure-container"], ["scd", "application/x-msschedule"], ["scm", "application/vnd.lotus-screencam"], ["scq", "application/scvp-cv-request"], ["scs", "application/scvp-cv-response"], ["scss", "text/x-scss"], ["scurl", "text/vnd.curl.scurl"], ["sda", "application/vnd.stardivision.draw"], ["sdc", "application/vnd.stardivision.calc"], ["sdd", "application/vnd.stardivision.impress"], ["sdkd", "application/vnd.solent.sdkm+xml"], ["sdkm", "application/vnd.solent.sdkm+xml"], ["sdp", "application/sdp"], ["sdw", "application/vnd.stardivision.writer"], ["sea", "application/x-sea"], ["see", "application/vnd.seemail"], ["seed", "application/vnd.fdsn.seed"], ["sema", "application/vnd.sema"], ["semd", "application/vnd.semd"], ["semf", "application/vnd.semf"], ["senmlx", "application/senml+xml"], ["sensmlx", "application/sensml+xml"], ["ser", "application/java-serialized-object"], ["setpay", "application/set-payment-initiation"], ["setreg", "application/set-registration-initiation"], ["sfd-hdstx", "application/vnd.hydrostatix.sof-data"], ["sfs", "application/vnd.spotfire.sfs"], ["sfv", "text/x-sfv"], ["sgi", "image/sgi"], ["sgl", "application/vnd.stardivision.writer-global"], ["sgm", "text/sgml"], ["sgml", "text/sgml"], ["sh", "application/x-sh"], ["shar", "application/x-shar"], ["shex", "text/shex"], ["shf", "application/shf+xml"], ["shtml", "text/html"], ["sid", "image/x-mrsid-image"], ["sieve", "application/sieve"], ["sig", "application/pgp-signature"], ["sil", "audio/silk"], ["silo", "model/mesh"], ["sis", "application/vnd.symbian.install"], ["sisx", "application/vnd.symbian.install"], ["sit", "application/x-stuffit"], ["sitx", "application/x-stuffitx"], ["siv", "application/sieve"], ["skd", "application/vnd.koan"], ["skm", "application/vnd.koan"], ["skp", "application/vnd.koan"], ["skt", "application/vnd.koan"], ["sldm", "application/vnd.ms-powerpoint.slide.macroenabled.12"], ["sldx", "application/vnd.openxmlformats-officedocument.presentationml.slide"], ["slim", "text/slim"], ["slm", "text/slim"], ["sls", "application/route-s-tsid+xml"], ["slt", "application/vnd.epson.salt"], ["sm", "application/vnd.stepmania.stepchart"], ["smf", "application/vnd.stardivision.math"], ["smi", "application/smil+xml"], ["smil", "application/smil+xml"], ["smv", "video/x-smv"], ["smzip", "application/vnd.stepmania.package"], ["snd", "audio/basic"], ["snf", "application/x-font-snf"], ["so", "application/octet-stream"], ["spc", "application/x-pkcs7-certificates"], ["spdx", "text/spdx"], ["spf", "application/vnd.yamaha.smaf-phrase"], ["spl", "application/x-futuresplash"], ["spot", "text/vnd.in3d.spot"], ["spp", "application/scvp-vp-response"], ["spq", "application/scvp-vp-request"], ["spx", "audio/ogg"], ["sql", "application/x-sql"], ["src", "application/x-wais-source"], ["srt", "application/x-subrip"], ["sru", "application/sru+xml"], ["srx", "application/sparql-results+xml"], ["ssdl", "application/ssdl+xml"], ["sse", "application/vnd.kodak-descriptor"], ["ssf", "application/vnd.epson.ssf"], ["ssml", "application/ssml+xml"], ["st", "application/vnd.sailingtracker.track"], ["stc", "application/vnd.sun.xml.calc.template"], ["std", "application/vnd.sun.xml.draw.template"], ["stf", "application/vnd.wt.stf"], ["sti", "application/vnd.sun.xml.impress.template"], ["stk", "application/hyperstudio"], ["stl", "model/stl"], ["stpx", "model/step+xml"], ["stpxz", "model/step-xml+zip"], ["stpz", "model/step+zip"], ["str", "application/vnd.pg.format"], ["stw", "application/vnd.sun.xml.writer.template"], ["styl", "text/stylus"], ["stylus", "text/stylus"], ["sub", "text/vnd.dvb.subtitle"], ["sus", "application/vnd.sus-calendar"], ["susp", "application/vnd.sus-calendar"], ["sv4cpio", "application/x-sv4cpio"], ["sv4crc", "application/x-sv4crc"], ["svc", "application/vnd.dvb.service"], ["svd", "application/vnd.svd"], ["svg", "image/svg+xml"], ["svgz", "image/svg+xml"], ["swa", "application/x-director"], ["swf", "application/x-shockwave-flash"], ["swi", "application/vnd.aristanetworks.swi"], ["swidtag", "application/swid+xml"], ["sxc", "application/vnd.sun.xml.calc"], ["sxd", "application/vnd.sun.xml.draw"], ["sxg", "application/vnd.sun.xml.writer.global"], ["sxi", "application/vnd.sun.xml.impress"], ["sxm", "application/vnd.sun.xml.math"], ["sxw", "application/vnd.sun.xml.writer"], ["t", "text/troff"], ["t3", "application/x-t3vm-image"], ["t38", "image/t38"], ["taglet", "application/vnd.mynfc"], ["tao", "application/vnd.tao.intent-module-archive"], ["tap", "image/vnd.tencent.tap"], ["tar", "application/x-tar"], ["tcap", "application/vnd.3gpp2.tcap"], ["tcl", "application/x-tcl"], ["td", "application/urc-targetdesc+xml"], ["teacher", "application/vnd.smart.teacher"], ["tei", "application/tei+xml"], ["teicorpus", "application/tei+xml"], ["tex", "application/x-tex"], ["texi", "application/x-texinfo"], ["texinfo", "application/x-texinfo"], ["text", "text/plain"], ["tfi", "application/thraud+xml"], ["tfm", "application/x-tex-tfm"], ["tfx", "image/tiff-fx"], ["tga", "image/x-tga"], ["thmx", "application/vnd.ms-officetheme"], ["tif", "image/tiff"], ["tiff", "image/tiff"], ["tk", "application/x-tcl"], ["tmo", "application/vnd.tmobile-livetv"], ["toml", "application/toml"], ["torrent", "application/x-bittorrent"], ["tpl", "application/vnd.groove-tool-template"], ["tpt", "application/vnd.trid.tpt"], ["tr", "text/troff"], ["tra", "application/vnd.trueapp"], ["trig", "application/trig"], ["trm", "application/x-msterminal"], ["ts", "video/mp2t"], ["tsd", "application/timestamped-data"], ["tsv", "text/tab-separated-values"], ["ttc", "font/collection"], ["ttf", "font/ttf"], ["ttl", "text/turtle"], ["ttml", "application/ttml+xml"], ["twd", "application/vnd.simtech-mindmapper"], ["twds", "application/vnd.simtech-mindmapper"], ["txd", "application/vnd.genomatix.tuxedo"], ["txf", "application/vnd.mobius.txf"], ["txt", "text/plain"], ["u32", "application/x-authorware-bin"], ["u3d", "model/u3d"], ["u8dsn", "message/global-delivery-status"], ["u8hdr", "message/global-headers"], ["u8mdn", "message/global-disposition-notification"], ["u8msg", "message/global"], ["ubj", "application/ubjson"], ["udeb", "application/x-debian-package"], ["ufd", "application/vnd.ufdl"], ["ufdl", "application/vnd.ufdl"], ["ulx", "application/x-glulx"], ["umj", "application/vnd.umajin"], ["unityweb", "application/vnd.unity"], ["uo", "application/vnd.uoml+xml"], ["uoml", "application/vnd.uoml+xml"], ["uri", "text/uri-list"], ["uris", "text/uri-list"], ["urls", "text/uri-list"], ["usda", "model/vnd.usda"], ["usdz", "model/vnd.usdz+zip"], ["ustar", "application/x-ustar"], ["utz", "application/vnd.uiq.theme"], ["uu", "text/x-uuencode"], ["uva", "audio/vnd.dece.audio"], ["uvd", "application/vnd.dece.data"], ["uvf", "application/vnd.dece.data"], ["uvg", "image/vnd.dece.graphic"], ["uvh", "video/vnd.dece.hd"], ["uvi", "image/vnd.dece.graphic"], ["uvm", "video/vnd.dece.mobile"], ["uvp", "video/vnd.dece.pd"], ["uvs", "video/vnd.dece.sd"], ["uvt", "application/vnd.dece.ttml+xml"], ["uvu", "video/vnd.uvvu.mp4"], ["uvv", "video/vnd.dece.video"], ["uvva", "audio/vnd.dece.audio"], ["uvvd", "application/vnd.dece.data"], ["uvvf", "application/vnd.dece.data"], ["uvvg", "image/vnd.dece.graphic"], ["uvvh", "video/vnd.dece.hd"], ["uvvi", "image/vnd.dece.graphic"], ["uvvm", "video/vnd.dece.mobile"], ["uvvp", "video/vnd.dece.pd"], ["uvvs", "video/vnd.dece.sd"], ["uvvt", "application/vnd.dece.ttml+xml"], ["uvvu", "video/vnd.uvvu.mp4"], ["uvvv", "video/vnd.dece.video"], ["uvvx", "application/vnd.dece.unspecified"], ["uvvz", "application/vnd.dece.zip"], ["uvx", "application/vnd.dece.unspecified"], ["uvz", "application/vnd.dece.zip"], ["vbox", "application/x-virtualbox-vbox"], ["vbox-extpack", "application/x-virtualbox-vbox-extpack"], ["vcard", "text/vcard"], ["vcd", "application/x-cdlink"], ["vcf", "text/x-vcard"], ["vcg", "application/vnd.groove-vcard"], ["vcs", "text/x-vcalendar"], ["vcx", "application/vnd.vcx"], ["vdi", "application/x-virtualbox-vdi"], ["vds", "model/vnd.sap.vds"], ["vhd", "application/x-virtualbox-vhd"], ["vis", "application/vnd.visionary"], ["viv", "video/vnd.vivo"], ["vmdk", "application/x-virtualbox-vmdk"], ["vob", "video/x-ms-vob"], ["vor", "application/vnd.stardivision.writer"], ["vox", "application/x-authorware-bin"], ["vrml", "model/vrml"], ["vsd", "application/vnd.visio"], ["vsf", "application/vnd.vsf"], ["vss", "application/vnd.visio"], ["vst", "application/vnd.visio"], ["vsw", "application/vnd.visio"], ["vtf", "image/vnd.valve.source.texture"], ["vtt", "text/vtt"], ["vtu", "model/vnd.vtu"], ["vxml", "application/voicexml+xml"], ["w3d", "application/x-director"], ["wad", "application/x-doom"], ["wadl", "application/vnd.sun.wadl+xml"], ["war", "application/java-archive"], ["wasm", "application/wasm"], ["wav", "audio/x-wav"], ["wax", "audio/x-ms-wax"], ["wbmp", "image/vnd.wap.wbmp"], ["wbs", "application/vnd.criticaltools.wbs+xml"], ["wbxml", "application/vnd.wap.wbxml"], ["wcm", "application/vnd.ms-works"], ["wdb", "application/vnd.ms-works"], ["wdp", "image/vnd.ms-photo"], ["weba", "audio/webm"], ["webapp", "application/x-web-app-manifest+json"], ["webm", "video/webm"], ["webmanifest", "application/manifest+json"], ["webp", "image/webp"], ["wg", "application/vnd.pmi.widget"], ["wgsl", "text/wgsl"], ["wgt", "application/widget"], ["wif", "application/watcherinfo+xml"], ["wks", "application/vnd.ms-works"], ["wm", "video/x-ms-wm"], ["wma", "audio/x-ms-wma"], ["wmd", "application/x-ms-wmd"], ["wmf", "image/wmf"], ["wml", "text/vnd.wap.wml"], ["wmlc", "application/vnd.wap.wmlc"], ["wmls", "text/vnd.wap.wmlscript"], ["wmlsc", "application/vnd.wap.wmlscriptc"], ["wmv", "video/x-ms-wmv"], ["wmx", "video/x-ms-wmx"], ["wmz", "application/x-msmetafile"], ["woff", "font/woff"], ["woff2", "font/woff2"], ["wpd", "application/vnd.wordperfect"], ["wpl", "application/vnd.ms-wpl"], ["wps", "application/vnd.ms-works"], ["wqd", "application/vnd.wqd"], ["wri", "application/x-mswrite"], ["wrl", "model/vrml"], ["wsc", "message/vnd.wfa.wsc"], ["wsdl", "application/wsdl+xml"], ["wspolicy", "application/wspolicy+xml"], ["wtb", "application/vnd.webturbo"], ["wvx", "video/x-ms-wvx"], ["x32", "application/x-authorware-bin"], ["x3d", "model/x3d+xml"], ["x3db", "model/x3d+fastinfoset"], ["x3dbz", "model/x3d+binary"], ["x3dv", "model/x3d-vrml"], ["x3dvz", "model/x3d+vrml"], ["x3dz", "model/x3d+xml"], ["x_b", "model/vnd.parasolid.transmit.binary"], ["x_t", "model/vnd.parasolid.transmit.text"], ["xaml", "application/xaml+xml"], ["xap", "application/x-silverlight-app"], ["xar", "application/vnd.xara"], ["xav", "application/xcap-att+xml"], ["xbap", "application/x-ms-xbap"], ["xbd", "application/vnd.fujixerox.docuworks.binder"], ["xbm", "image/x-xbitmap"], ["xca", "application/xcap-caps+xml"], ["xcs", "application/calendar+xml"], ["xdf", "application/xcap-diff+xml"], ["xdm", "application/vnd.syncml.dm+xml"], ["xdp", "application/vnd.adobe.xdp+xml"], ["xdssc", "application/dssc+xml"], ["xdw", "application/vnd.fujixerox.docuworks"], ["xel", "application/xcap-el+xml"], ["xenc", "application/xenc+xml"], ["xer", "application/patch-ops-error+xml"], ["xfdf", "application/xfdf"], ["xfdl", "application/vnd.xfdl"], ["xht", "application/xhtml+xml"], ["xhtm", "application/vnd.pwg-xhtml-print+xml"], ["xhtml", "application/xhtml+xml"], ["xhvml", "application/xv+xml"], ["xif", "image/vnd.xiff"], ["xla", "application/vnd.ms-excel"], ["xlam", "application/vnd.ms-excel.addin.macroenabled.12"], ["xlc", "application/vnd.ms-excel"], ["xlf", "application/xliff+xml"], ["xlm", "application/vnd.ms-excel"], ["xls", "application/vnd.ms-excel"], ["xlsb", "application/vnd.ms-excel.sheet.binary.macroenabled.12"], ["xlsm", "application/vnd.ms-excel.sheet.macroenabled.12"], ["xlsx", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"], ["xlt", "application/vnd.ms-excel"], ["xltm", "application/vnd.ms-excel.template.macroenabled.12"], ["xltx", "application/vnd.openxmlformats-officedocument.spreadsheetml.template"], ["xlw", "application/vnd.ms-excel"], ["xm", "audio/xm"], ["xml", "text/xml"], ["xns", "application/xcap-ns+xml"], ["xo", "application/vnd.olpc-sugar"], ["xop", "application/xop+xml"], ["xpi", "application/x-xpinstall"], ["xpl", "application/xproc+xml"], ["xpm", "image/x-xpixmap"], ["xpr", "application/vnd.is-xpr"], ["xps", "application/vnd.ms-xpsdocument"], ["xpw", "application/vnd.intercon.formnet"], ["xpx", "application/vnd.intercon.formnet"], ["xsd", "application/xml"], ["xsf", "application/prs.xsf+xml"], ["xsl", "application/xslt+xml"], ["xslt", "application/xslt+xml"], ["xsm", "application/vnd.syncml+xml"], ["xspf", "application/xspf+xml"], ["xul", "application/vnd.mozilla.xul+xml"], ["xvm", "application/xv+xml"], ["xvml", "application/xv+xml"], ["xwd", "image/x-xwindowdump"], ["xyz", "chemical/x-xyz"], ["xz", "application/x-xz"], ["yaml", "text/yaml"], ["yang", "application/yang"], ["yin", "application/yin+xml"], ["yml", "text/yaml"], ["ymp", "text/x-suse-ymp"], ["z1", "application/x-zmachine"], ["z2", "application/x-zmachine"], ["z3", "application/x-zmachine"], ["z4", "application/x-zmachine"], ["z5", "application/x-zmachine"], ["z6", "application/x-zmachine"], ["z7", "application/x-zmachine"], ["z8", "application/x-zmachine"], ["zaz", "application/vnd.zzazz.deck+xml"], ["zip", "application/zip"], ["zir", "application/vnd.zul"], ["zirz", "application/vnd.zul"], ["zmm", "application/vnd.handheld-entertainment+xml"]]);
+/**
+ * Get the file extension of the given mime type.
+ * @param {string} mimeType - Mime type.
+ * @param {Map<string, string>} [allowedMimeTypes] - Allowed mime types. If not provided, the default mime types map will be used.
+ * @returns {string | undefined} File extension or undefined if the mime type is not found.
+ *
+ * @example
+ * ```TypeScript
+ * // Using the default mime types map
+ * const extension = getFileExt('application/pdf');
+ * // Output: 'pdf'
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * // Using a custom mime types map
+ * const customMimeTypes = new Map([
+ *   ['jpg', 'image/jpeg'],
+ *   ['png', 'image/png']
+ * ]);
+ * const extension = getFileExt('image/jpeg', customMimeTypes);
+ * // Output: 'jpg'
+ * ```
+ */
+const getFileExt = (mimeType, allowedMimeTypes) => {
+  return getMapKey(allowedMimeTypes ?? mimeTypes, mimeType);
+};
+/**
+ * Get file size in human-readable format.
+ * @param {number} size - File size in bytes.
+ * @param {boolean} [round] - Whether to round the size to whole numbers. If true, decimals will be removed.
+ * @returns {string} File size in human-readable format (B, KB, MB, or GB).
+ *
+ * @example
+ * ```TypeScript
+ * // Get file size with decimals
+ * const readableSize = getFileSize(1536);
+ * // Output: '1.50 KB'
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * // Get rounded file size
+ * const roundedSize = getFileSize(1536, true);
+ * // Output: '2 KB'
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * // Get size for larger files
+ * const largeFileSize = getFileSize(1073741824);
+ * // Output: '1.00 GB'
+ * ```
+ */
+const getFileSize = (size, round) => {
+  // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+  if (size < 1024) {
+    return `${Math.round(size)} B`;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+  if (size < 1024 * 1024) {
+    // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+    return `${(size / 1024).toFixed(round ? 0 : 2)} KB`;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+  if (size < 1024 * 1024 * 1024) {
+    // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+    return `${(size / 1024 / 1024).toFixed(round ? 0 : 2)} MB`;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+  return `${(size / 1024 / 1024 / 1024).toFixed(round ? 0 : 2)} GB`;
+};
+
+/**
+ * Base for hexadecimal number conversion
+ *
+ * This constant defines the radix (base) used for hexadecimal number conversion.
+ * The value 16 represents the standard hexadecimal numbering system (0-9, A-F).
+ * It's used in toString() and parseInt() operations involving hex values.
+ *
+ * @example
+ * ```typescript
+ * // Converting a number to hexadecimal string
+ * const hexString = number.toString(HEX_RADIX);
+ *
+ * // Converting a hexadecimal string to a number
+ * const number = parseInt(hexString, HEX_RADIX);
+ * ```
+ *
+ * @see {@link HEX_PADDING_LENGTH} Related constant for hex string formatting
+ * @see {@link HEX_PADDING_CHAR} Related constant for hex string padding
+ */
+const HEX_RADIX = 16;
+/**
+ * Minimum length for padded hexadecimal strings
+ *
+ * This constant defines the minimum length for hexadecimal strings after padding.
+ * It ensures that hex values have a consistent length (e.g., "0A" instead of "A").
+ * The value 2 ensures that single-digit hex values are padded with a leading zero.
+ *
+ * @example
+ * ```typescript
+ * // Padding a hex string to ensure consistent length
+ * const paddedHex = hexString.padStart(HEX_PADDING_LENGTH, HEX_PADDING_CHAR);
+ *
+ * // Full example with conversion and padding
+ * const byteValue = 10;
+ * const hexByte = byteValue.toString(HEX_RADIX).padStart(HEX_PADDING_LENGTH, HEX_PADDING_CHAR);
+ * // hexByte = "0A"
+ * ```
+ *
+ * @see {@link HEX_RADIX} Related constant for hex conversion
+ * @see {@link HEX_PADDING_CHAR} Related constant for the padding character
+ */
+const HEX_PADDING_LENGTH = 2;
+/**
+ * Character used for padding hexadecimal strings
+ *
+ * This constant defines the character used to pad hexadecimal strings to reach
+ * the minimum length defined by HEX_PADDING_LENGTH. The value "0" is the standard
+ * padding character for hexadecimal values.
+ *
+ * @example
+ * ```typescript
+ * // Padding a hex string with zeros
+ * const paddedHex = hexString.padStart(HEX_PADDING_LENGTH, HEX_PADDING_CHAR);
+ *
+ * // Example with a single-digit hex value
+ * const hexValue = "F";
+ * const paddedHex = hexValue.padStart(HEX_PADDING_LENGTH, HEX_PADDING_CHAR);
+ * // paddedHex = "0F"
+ * ```
+ *
+ * @see {@link HEX_RADIX} Related constant for hex conversion
+ * @see {@link HEX_PADDING_LENGTH} Related constant for the minimum length
+ */
+const HEX_PADDING_CHAR = "0";
+/**
+ * Number of characters to remove in string truncation operations
+ *
+ * This constant defines the default number of characters to remove when
+ * truncating strings in various utility functions. The value 2 is commonly
+ * used when removing the last two characters of a string (e.g., removing
+ * a trailing comma and space).
+ *
+ * @example
+ * ```typescript
+ * // Removing trailing characters from a string
+ * const items = ["apple", "banana", "cherry"];
+ * let result = "";
+ *
+ * for (const item of items) {
+ *   result += item + ", ";
+ * }
+ *
+ * // Remove trailing comma and space
+ * if (result.length > 0) {
+ *   result = result.slice(0, -CHARACTERS_TO_REMOVE);
+ * }
+ * // result = "apple, banana, cherry"
+ * ```
+ */
+const CHARACTERS_TO_REMOVE = 2;
+/**
+ * Default maximum line length for word wrapping
+ *
+ * This constant defines the default maximum length of a line when performing
+ * word wrapping operations. The value 80 is a common standard for line length
+ * in many text formats and terminal displays.
+ *
+ * @example
+ * ```typescript
+ * // Wrapping a long text to the default line length
+ * function wrapText(text: string, maxLength = DEFAULT_LINE_LENGTH, breakChar = DEFAULT_BREAK_CHAR): string {
+ *   // Word wrapping implementation
+ *   const result = [];
+ *   let line = "";
+ *
+ *   for (const word of text.split(" ")) {
+ *     if ((line + word).length > maxLength) {
+ *       result.push(line);
+ *       line = word;
+ *     } else {
+ *       line += (line ? " " : "") + word;
+ *     }
+ *   }
+ *
+ *   if (line) {
+ *     result.push(line);
+ *   }
+ *
+ *   return result.join(breakChar);
+ * }
+ * ```
+ *
+ * @see {@link DEFAULT_BREAK_CHAR} Related constant for line break character
+ */
+const DEFAULT_LINE_LENGTH = 80;
+/**
+ * Default line break character for word wrapping
+ *
+ * This constant defines the default character or string used to separate lines
+ * when performing word wrapping operations. The value "\n" represents a standard
+ * line feed character used for line breaks in most text formats.
+ *
+ * @example
+ * ```typescript
+ * // Using the default break character in word wrapping
+ * const wrappedText = longText.match(new RegExp(`.{1,${DEFAULT_LINE_LENGTH}}(\\s|$)`, 'g'))
+ *   ?.join(DEFAULT_BREAK_CHAR) || longText;
+ * ```
+ *
+ * @see {@link DEFAULT_LINE_LENGTH} Related constant for maximum line length
+ */
+const DEFAULT_BREAK_CHAR = "\n";
+/**
+ * Default context length for text excerpts
+ *
+ * This constant defines the default number of characters to include before and after
+ * a search term when generating text excerpts or snippets. The value 40 provides
+ * enough context to understand the meaning while keeping the excerpt concise.
+ *
+ * @example
+ * ```typescript
+ * // Generating an excerpt around a search term
+ * function generateExcerpt(text: string, searchTerm: string): string {
+ *   const index = text.toLowerCase().indexOf(searchTerm.toLowerCase());
+ *   if (index === -1) return text.substring(0, DEFAULT_CONTEXT_LENGTH * 2) + DEFAULT_ELLIPSIS;
+ *
+ *   const start = Math.max(0, index - DEFAULT_CONTEXT_LENGTH);
+ *   const end = Math.min(text.length, index + searchTerm.length + DEFAULT_CONTEXT_LENGTH);
+ *
+ *   let excerpt = text.substring(start, end);
+ *   if (start > 0) excerpt = DEFAULT_ELLIPSIS + excerpt;
+ *   if (end < text.length) excerpt = excerpt + DEFAULT_ELLIPSIS;
+ *
+ *   return excerpt;
+ * }
+ * ```
+ *
+ * @see {@link DEFAULT_ELLIPSIS} Related constant for indicating truncated text
+ * @see {@link CONTEXT_MULTIPLIER} Related constant for adjusting context length
+ */
+const DEFAULT_CONTEXT_LENGTH = 40;
+/**
+ * Default ellipsis string for indicating truncated text
+ *
+ * This constant defines the default string used to indicate that text has been
+ * truncated or omitted in excerpts and summaries. The value "..." is the standard
+ * ellipsis used to represent omitted content.
+ *
+ * @example
+ * ```typescript
+ * // Truncating a long string with ellipsis
+ * function truncate(text: string, maxLength: number): string {
+ *   if (text.length <= maxLength) return text;
+ *   return text.substring(0, maxLength - DEFAULT_ELLIPSIS.length) + DEFAULT_ELLIPSIS;
+ * }
+ *
+ * const longText = "This is a very long text that needs to be truncated";
+ * const truncated = truncate(longText, 20);
+ * // truncated = "This is a very lo..."
+ * ```
+ *
+ * @see {@link DEFAULT_CONTEXT_LENGTH} Related constant for excerpt generation
+ */
+const DEFAULT_ELLIPSIS = "...";
+/**
+ * Multiplier for adjusting context length in excerpts
+ *
+ * This constant defines a multiplier used to adjust the context length when
+ * generating excerpts under different conditions. The value 2 is typically
+ * used to double the context length for certain scenarios, such as when no
+ * search term is found.
+ *
+ * @example
+ * ```typescript
+ * // Using the multiplier to adjust context length
+ * function getContextLength(hasSearchTerm: boolean): number {
+ *   return hasSearchTerm
+ *     ? DEFAULT_CONTEXT_LENGTH
+ *     : DEFAULT_CONTEXT_LENGTH * CONTEXT_MULTIPLIER;
+ * }
+ *
+ * // Getting the first part of a text when no search term is found
+ * function getFirstPart(text: string): string {
+ *   const length = DEFAULT_CONTEXT_LENGTH * CONTEXT_MULTIPLIER;
+ *   return text.length > length
+ *     ? text.substring(0, length) + DEFAULT_ELLIPSIS
+ *     : text;
+ * }
+ * ```
+ *
+ * @see {@link DEFAULT_CONTEXT_LENGTH} Related constant for base context length
+ */
+const CONTEXT_MULTIPLIER = 2;
+
+/**
+ * Comprehensive rules for English word inflection (singular/plural transformations)
+ *
+ * This module provides a structured collection of rules for transforming English words
+ * between singular and plural forms. The rules are organized into categories based on
+ * linguistic patterns and exceptions, ensuring accurate transformations for various
+ * word types.
+ *
+ * Key features:
+ * - Invariant words that are identical in singular and plural forms
+ * - Irregular plural forms that don't follow standard patterns
+ * - Latin and Greek origin words with their specific plural formations
+ * - Pattern-based rules for common English word endings
+ * - Default fallback rules for standard English pluralization
+ *
+ * The rules are applied in a specific priority order, from most specific to most general,
+ * to ensure correct handling of special cases. Each rule consists of a regular expression
+ * pattern and a replacement string or function.
+ *
+ * @example
+ * ```typescript
+ * // Using the rules with the plural() function
+ * import { EnglishInflectionRules } from '@hichchi/utils/constants';
+ * import { InflectionRule } from '@hichchi/utils/interfaces';
+ *
+ * function plural(word: string): string {
+ *   // Combine all rules in priority order
+ *   const rules: InflectionRule[] = [
+ *     ...EnglishInflectionRules.INVARIANT,
+ *     ...EnglishInflectionRules.IRREGULAR.toPlural,
+ *     ...EnglishInflectionRules.LATIN_GREEK.toPlural,
+ *     ...EnglishInflectionRules.PATTERN_RULES.toPlural,
+ *     ...EnglishInflectionRules.DEFAULT.toPlural,
+ *   ];
+ *
+ *   // Apply the first matching rule
+ *   for (const rule of rules) {
+ *     if (rule.regex.test(word)) {
+ *       return word.replace(rule.regex, rule.replacement as string);
+ *     }
+ *   }
+ *
+ *   return word;
+ * }
+ * ```
+ *
+ * @see {@link plural} Function that uses these rules to convert words to plural form
+ * @see {@link singular} Function that uses these rules to convert words to singular form
+ * @see {@link InflectionRuleCategories} Interface defining the structure of the rules
+ * @see {@link InflectionRule} Interface for individual transformation rules
+ */
+const EnglishInflectionRules = {
+  /**
+   * Words that are the same in singular and plural form
+   *
+   * This category contains rules for words that don't change between singular and plural forms.
+   * These invariant words (also called "zero plurals") have identical singular and plural forms
+   * in English. The rule simply returns the word unchanged.
+   *
+   * Common examples include:
+   * - Animal names: "fish", "deer", "sheep"
+   * - Scientific terms: "species", "series"
+   * - Uncountable nouns: "equipment"
+   *
+   * @example
+   * ```typescript
+   * // These words remain unchanged in plural form
+   * plural("fish");     // "fish"
+   * plural("deer");     // "deer"
+   * plural("sheep");    // "sheep"
+   * plural("species");  // "species"
+   * plural("equipment"); // "equipment"
+   * ```
+   *
+   * @see {@link plural} Function that applies these rules
+   * @see {@link singular} Function that applies these rules
+   */
+  INVARIANT: [{
+    regex: /^(fish|deer|sheep|species|series|equipment)$/i,
+    replacement: "$1"
+  }],
+  /**
+   * Irregular plural forms
+   *
+   * This category contains rules for words with irregular plural forms that don't
+   * follow standard English pluralization patterns. These words have unique
+   * transformations between singular and plural forms that must be handled as
+   * special cases.
+   *
+   * The category is divided into two rule sets:
+   * - toPlural: Rules for converting singular forms to their irregular plural forms
+   * - toSingular: Rules for converting irregular plural forms back to singular
+   *
+   * These rules handle common irregular English plurals like "child/children",
+   * "man/men", "tooth/teeth", etc. Many of these irregular forms have historical
+   * origins in Old English and other Germanic languages.
+   *
+   * @example
+   * ```typescript
+   * // Singular to plural transformations
+   * plural("child");   // "children"
+   * plural("man");     // "men"
+   * plural("tooth");   // "teeth"
+   * plural("person");  // "people"
+   *
+   * // Plural to singular transformations
+   * singular("children"); // "child"
+   * singular("men");      // "man"
+   * singular("teeth");    // "tooth"
+   * singular("people");   // "person"
+   * ```
+   *
+   * @see {@link plural} Function that applies these rules for pluralization
+   * @see {@link singular} Function that applies these rules for singularization
+   */
+  IRREGULAR: {
+    // Singular to plural transformations
+    toPlural: [{
+      regex: /^child$/i,
+      replacement: "children"
+    }, {
+      regex: /^man$/i,
+      replacement: "men"
+    }, {
+      regex: /^woman$/i,
+      replacement: "women"
+    }, {
+      regex: /^tooth$/i,
+      replacement: "teeth"
+    }, {
+      regex: /^foot$/i,
+      replacement: "feet"
+    }, {
+      regex: /^goose$/i,
+      replacement: "geese"
+    }, {
+      regex: /^mouse$/i,
+      replacement: "mice"
+    }, {
+      regex: /^person$/i,
+      replacement: "people"
+    }, {
+      regex: /^ox$/i,
+      replacement: "oxen"
+    }],
+    // Plural to singular transformations
+    toSingular: [{
+      regex: /children$/i,
+      replacement: "child"
+    }, {
+      regex: /men$/i,
+      replacement: "man"
+    }, {
+      regex: /women$/i,
+      replacement: "woman"
+    }, {
+      regex: /teeth$/i,
+      replacement: "tooth"
+    }, {
+      regex: /feet$/i,
+      replacement: "foot"
+    }, {
+      regex: /geese$/i,
+      replacement: "goose"
+    }, {
+      regex: /mice$/i,
+      replacement: "mouse"
+    }, {
+      regex: /people$/i,
+      replacement: "person"
+    }, {
+      regex: /oxen$/i,
+      replacement: "ox"
+    }]
+  },
+  /**
+   * Latin/Greek origin words
+   *
+   * This category contains rules for words borrowed from Latin and Greek that
+   * retain their original pluralization patterns. These words follow different
+   * rules than native English words and often have distinctive ending changes.
+   *
+   * The category is divided into two rule sets:
+   * - toPlural: Rules for converting Latin/Greek singular forms to their plural forms
+   * - toSingular: Rules for converting Latin/Greek plural forms back to singular
+   *
+   * Common patterns include:
+   * - "-us" → "-i" (cactus/cacti, fungus/fungi)
+   * - "-is" → "-es" (analysis/analyses, thesis/theses)
+   * - "-on"/"-um" → "-a" (criterion/criteria, datum/data)
+   * - "-ex"/"-ix" → "-ices" (index/indices, matrix/matrices)
+   *
+   * These words are often found in academic, scientific, and technical contexts.
+   * Note that some of these words have alternative anglicized plural forms that
+   * are also acceptable in modern English (e.g., "cactuses" alongside "cacti").
+   *
+   * @example
+   * ```typescript
+   * // Singular to plural transformations
+   * plural("cactus");    // "cacti"
+   * plural("analysis");  // "analyses"
+   * plural("criterion"); // "criteria"
+   * plural("index");     // "indices"
+   * plural("matrix");    // "matrices"
+   *
+   * // Plural to singular transformations
+   * singular("cacti");     // "cactus"
+   * singular("analyses");  // "analysis"
+   * singular("criteria");  // "criterion"
+   * singular("indices");   // "index"
+   * singular("matrices");  // "matrix"
+   * ```
+   *
+   * @see {@link plural} Function that applies these rules for pluralization
+   * @see {@link singular} Function that applies these rules for singularization
+   */
+  LATIN_GREEK: {
+    // Singular to plural transformations
+    toPlural: [{
+      regex: /^cactus$/i,
+      replacement: "cacti"
+    }, {
+      regex: /^focus$/i,
+      replacement: "foci"
+    }, {
+      regex: /^fungus$/i,
+      replacement: "fungi"
+    }, {
+      regex: /^nucleus$/i,
+      replacement: "nuclei"
+    }, {
+      regex: /^syllabus$/i,
+      replacement: "syllabi"
+    }, {
+      regex: /^analysis$/i,
+      replacement: "analyses"
+    }, {
+      regex: /^diagnosis$/i,
+      replacement: "diagnoses"
+    }, {
+      regex: /^thesis$/i,
+      replacement: "theses"
+    }, {
+      regex: /^criterion$/i,
+      replacement: "criteria"
+    }, {
+      regex: /^datum$/i,
+      replacement: "data"
+    }, {
+      regex: /^phenomenon$/i,
+      replacement: "phenomena"
+    }, {
+      regex: /^index$/i,
+      replacement: "indices"
+    }, {
+      regex: /^matrix$/i,
+      replacement: "matrices"
+    }, {
+      regex: /^vertex$/i,
+      replacement: "vertices"
+    }, {
+      regex: /^appendix$/i,
+      replacement: "appendices"
+    }],
+    // Plural to singular transformations
+    toSingular: [{
+      regex: /matrices$/i,
+      replacement: "matrix"
+    }, {
+      regex: /indices$/i,
+      replacement: "index"
+    }, {
+      regex: /vertices$/i,
+      replacement: "vertex"
+    }, {
+      regex: /appendices$/i,
+      replacement: "appendix"
+    }, {
+      regex: /cacti$/i,
+      replacement: "cactus"
+    }, {
+      regex: /foci$/i,
+      replacement: "focus"
+    }, {
+      regex: /fungi$/i,
+      replacement: "fungus"
+    }, {
+      regex: /nuclei$/i,
+      replacement: "nucleus"
+    }, {
+      regex: /syllabi$/i,
+      replacement: "syllabus"
+    }, {
+      regex: /analyses$/i,
+      replacement: "analysis"
+    }, {
+      regex: /diagnoses$/i,
+      replacement: "diagnosis"
+    }, {
+      regex: /theses$/i,
+      replacement: "thesis"
+    }, {
+      regex: /criteria$/i,
+      replacement: "criterion"
+    }, {
+      regex: /data$/i,
+      replacement: "datum"
+    }, {
+      regex: /phenomena$/i,
+      replacement: "phenomenon"
+    }]
+  },
+  /**
+   * Words with specific ending patterns
+   *
+   * This category contains rules for words that follow regular patterns based on
+   * their endings. These patterns represent the most common rules for English
+   * pluralization and singularization, covering a wide range of everyday words.
+   *
+   * The category is divided into two rule sets:
+   * - toPlural: Rules for converting singular forms to plural based on word endings
+   * - toSingular: Rules for converting plural forms back to singular
+   *
+   * Key pattern groups include:
+   *
+   * 1. Words ending in -f or -fe:
+   *    - "knife" → "knives", "life" → "lives", "wolf" → "wolves"
+   *
+   * 2. Words ending in -y:
+   *    - After consonant: "city" → "cities", "baby" → "babies"
+   *    - After vowel: "boy" → "boys", "key" → "keys"
+   *
+   * 3. Words ending in -o:
+   *    - Some specific words: "hero" → "heroes", "potato" → "potatoes"
+   *    - After consonant: "echo" → "echoes", "tomato" → "tomatoes"
+   *
+   * 4. Words ending in -s, -ss, -sh, -ch, -x, -z:
+   *    - "bus" → "buses", "box" → "boxes", "dish" → "dishes"
+   *
+   * These patterns cover the majority of regular English pluralization rules
+   * and are applied after checking for invariant words, irregular forms, and
+   * Latin/Greek words.
+   *
+   * @example
+   * ```typescript
+   * // Words ending in -f or -fe
+   * plural("knife");   // "knives"
+   * plural("life");    // "lives"
+   * plural("wolf");    // "wolves"
+   *
+   * // Words ending in -y
+   * plural("city");    // "cities"
+   * plural("boy");     // "boys"
+   *
+   * // Words ending in -o
+   * plural("hero");    // "heroes"
+   * plural("photo");   // "photos"
+   *
+   * // Words ending in -s, -ss, -sh, -ch, -x, -z
+   * plural("bus");     // "buses"
+   * plural("box");     // "boxes"
+   * plural("dish");    // "dishes"
+   *
+   * // Plural to singular
+   * singular("knives");  // "knife"
+   * singular("cities");  // "city"
+   * singular("boxes");   // "box"
+   * ```
+   *
+   * @see {@link plural} Function that applies these rules for pluralization
+   * @see {@link singular} Function that applies these rules for singularization
+   * @see {@link CHARACTERS_TO_REMOVE} Constant used in some replacement functions
+   */
+  PATTERN_RULES: {
+    // Singular to plural transformations
+    toPlural: [
+    // Words ending in -f or -fe
+    {
+      regex: /^((?:wi|li)fe)$/i,
+      replacement: "$1ves"
+    }, {
+      regex: /(fe)$/i,
+      replacement: "ves"
+    }, {
+      regex: /([^f])f$/i,
+      replacement: "$1ves"
+    },
+    // Words ending in -y
+    {
+      regex: /([^aeiou])y$/i,
+      replacement: "$1ies"
+    }, {
+      regex: /([aeiou]y)$/i,
+      replacement: "$1s"
+    },
+    // Words ending in -o
+    {
+      regex: /(hero|potato|tomato|torpedo|veto)$/i,
+      replacement: "$1es"
+    }, {
+      regex: /([^aeiou])o$/i,
+      replacement: "$1oes"
+    },
+    // Words ending in -is
+    {
+      regex: /(is)$/i,
+      replacement: "es"
+    },
+    // Words ending in -us
+    {
+      regex: /(us)$/i,
+      replacement: "uses"
+    },
+    // Words ending in -s, -ss, -sh, -ch, -x, -z
+    {
+      regex: /(s|ss|sh|ch|x|z)$/i,
+      replacement: "$1es"
+    }],
+    // Plural to singular transformations
+    toSingular: [
+    // Special spelling changes
+    {
+      regex: /knives$/i,
+      replacement: "knife"
+    }, {
+      regex: /lives$/i,
+      replacement: "life"
+    }, {
+      regex: /shelves$/i,
+      replacement: "shelf"
+    },
+    // Common word patterns
+    {
+      regex: /(buses|dishes|matches)$/i,
+      replacement: match => match.slice(0, -CHARACTERS_TO_REMOVE)
+    }, {
+      regex: /([^aeiouy]|qu)ies$/i,
+      replacement: "$1y"
+    }, {
+      regex: /(x|ch|ss|sh)es$/i,
+      replacement: "$1"
+    }, {
+      regex: /oes$/i,
+      replacement: "o"
+    }, {
+      regex: /ves$/i,
+      replacement: "f"
+    }]
+  },
+  /**
+   * Default rules for standard transformations
+   *
+   * This category contains fallback rules that are applied when no other rules match.
+   * These represent the most basic and common English pluralization pattern: adding
+   * an "s" to form plurals and removing an "s" to form singulars.
+   *
+   * The category is divided into two rule sets:
+   * - toPlural: Adds "s" to the end of any word to form its plural
+   * - toSingular: Removes a trailing "s" from any word to form its singular
+   *
+   * These rules are applied as a last resort after all other more specific rules
+   * have been checked. They handle the majority of regular English words that don't
+   * fall into any of the special categories or patterns.
+   *
+   * While simple, these rules can sometimes produce incorrect results for words that
+   * should follow more specific patterns but weren't included in the other rule sets.
+   * They're designed as a reasonable fallback rather than a comprehensive solution.
+   *
+   * @example
+   * ```typescript
+   * // Singular to plural with default rule
+   * plural("book");    // "books"
+   * plural("car");     // "cars"
+   * plural("apple");   // "apples"
+   *
+   * // Plural to singular with default rule
+   * singular("books");  // "book"
+   * singular("cars");   // "car"
+   * singular("apples"); // "apple"
+   * ```
+   *
+   * @see {@link plural} Function that applies these rules for pluralization
+   * @see {@link singular} Function that applies these rules for singularization
+   */
+  DEFAULT: {
+    toPlural: [{
+      regex: /(.*)$/i,
+      replacement: "$1s"
+    }],
+    toSingular: [{
+      regex: /s$/i,
+      replacement: ""
+    }]
+  }
+};
+
+// noinspection JSUnusedGlobalSymbols
+function breakToWords(str, format) {
+  if (!str) {
+    return format ? "" : [];
+  }
+  try {
+    const words = str.match(/[A-Z]{2,}(?=[A-Z][a-z]+\d*|\b)|[A-Z]?[a-z]+\d*|[A-Z]+|\d+/g)?.map(s => s.toLowerCase()) ?? [];
+    return format ? words.map(format).join(" ") : words;
+  } catch {
+    return format ? "" : [];
+  }
+}
+/**
+ * Converts a string to lowercase with safe handling of undefined or null values.
+ *
+ * This utility function provides a safe way to convert strings to lowercase, automatically
+ * handling edge cases where the input might be undefined, null, or empty. Unlike the native
+ * String.prototype.toLowerCase() method, this function won't throw an error when called
+ * with undefined or null values, instead returning an empty string.
+ *
+ * This is particularly useful when working with user input, API responses, or any scenario
+ * where string values might be optional or potentially undefined. It's commonly used for
+ * case-insensitive comparisons, search functionality, or normalizing text data.
+ *
+ * @param {string} [str] - The string to convert to lowercase. Can be undefined or null.
+ * @returns {string} The lowercase version of the input string, or an empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // Basic string conversion
+ * const result1 = toLowerCase("Hello World");
+ * // Returns: "hello world"
+ *
+ * const result2 = toLowerCase("JAVASCRIPT");
+ * // Returns: "javascript"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe handling of undefined/null values
+ * const result1 = toLowerCase(undefined);
+ * // Returns: ""
+ *
+ * const result2 = toLowerCase(null);
+ * // Returns: ""
+ *
+ * const result3 = toLowerCase("");
+ * // Returns: ""
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in case-insensitive search
+ * function searchUsers(users: User[], searchTerm: string): User[] {
+ *   const normalizedSearch = toLowerCase(searchTerm);
+ *   return users.filter(user =>
+ *     toLowerCase(user.name).includes(normalizedSearch) ||
+ *     toLowerCase(user.email).includes(normalizedSearch)
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in form validation
+ * function validateEmail(email?: string): boolean {
+ *   const normalizedEmail = toLowerCase(email);
+ *   const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+ *   return emailRegex.test(normalizedEmail);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns an empty string for any falsy input (undefined, null, empty string)
+ * - Uses the native String.prototype.toLowerCase() method for actual conversion
+ * - Does not modify the original string (strings are immutable in JavaScript)
+ * - Handles all Unicode characters correctly, following locale-independent rules
+ * - More robust than direct .toLowerCase() calls when input might be undefined
+ *
+ * @see {@link toUpperCase} Function for converting strings to uppercase
+ * @see {@link toLowerCaseBreak} Function for converting to lowercase and breaking into words
+ */
+function toLowerCase(str) {
+  if (!str) {
+    return "";
+  }
+  return str.toLowerCase();
+}
+/**
+ * Converts a string to lowercase and breaks it into words, joining them with a specified separator.
+ *
+ * This utility function combines word breaking and case conversion in a single operation.
+ * It first breaks the input string into individual words using intelligent pattern recognition
+ * (handling camelCase, snake_case, kebab-case, etc.), converts each word to lowercase,
+ * and then joins them with the specified separator or a space by default.
+ *
+ * This is particularly useful for converting various naming conventions to a consistent
+ * lowercase format, creating readable labels from variable names, generating search-friendly
+ * text, or preparing strings for further processing where consistent word separation is needed.
+ *
+ * @param {string} [str] - The string to convert and break into words. Can be undefined or null.
+ * @param {string} [join=" "] - The separator to use when joining the words. Defaults to a single space.
+ * @returns {string} A lowercase string with words separated by the specified join character,
+ *                   or an empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // Basic camelCase conversion
+ * const result1 = toLowerCaseBreak("HelloWorld");
+ * // Returns: "hello world"
+ *
+ * const result2 = toLowerCaseBreak("getUserProfile");
+ * // Returns: "get user profile"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom separators
+ * const result1 = toLowerCaseBreak("HelloWorld", "-");
+ * // Returns: "hello-world"
+ *
+ * const result2 = toLowerCaseBreak("APIResponseHandler", "_");
+ * // Returns: "api_response_handler"
+ *
+ * const result3 = toLowerCaseBreak("userAccountSettings", " | ");
+ * // Returns: "user | account | settings"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Various input formats
+ * const result1 = toLowerCaseBreak("snake_case_example");
+ * // Returns: "snake case example"
+ *
+ * const result2 = toLowerCaseBreak("kebab-case-example");
+ * // Returns: "kebab case example"
+ *
+ * const result3 = toLowerCaseBreak("CONSTANT_VALUE");
+ * // Returns: "constant value"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Creating user-friendly labels
+ * function createLabel(fieldName: string): string {
+ *   return toLowerCaseBreak(fieldName)
+ *     .split(' ')
+ *     .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+ *     .join(' ');
+ * }
+ *
+ * createLabel("firstName"); // "First Name"
+ * createLabel("emailAddress"); // "Email Address"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe handling of edge cases
+ * const result1 = toLowerCaseBreak(undefined);
+ * // Returns: ""
+ *
+ * const result2 = toLowerCaseBreak("", "-");
+ * // Returns: ""
+ *
+ * const result3 = toLowerCaseBreak("singleword");
+ * // Returns: "singleword"
+ * ```
+ *
+ * @remarks
+ * - Returns an empty string for any falsy input (undefined, null, empty string)
+ * - Uses the same intelligent word-breaking algorithm as the breakToWords function
+ * - Handles camelCase, PascalCase, snake_case, kebab-case, and mixed formats
+ * - Preserves numbers as separate words when they appear in the string
+ * - The join parameter can be any string, including empty string for concatenation
+ * - More efficient than calling breakToWords and toLowerCase separately
+ *
+ * @see {@link breakToWords} Function for breaking strings into word arrays
+ * @see {@link toLowerCase} Function for simple lowercase conversion
+ * @see {@link toUpperCaseBreak} Function for uppercase word breaking
+ */
+function toLowerCaseBreak(str, join) {
+  if (!str) {
+    return "";
+  }
+  return breakToWords(str).map(s => s.toLowerCase()).join(join ?? " ");
+}
+/**
+ * Converts a string to uppercase with safe handling of undefined or null values.
+ *
+ * This utility function provides a safe way to convert strings to uppercase, automatically
+ * handling edge cases where the input might be undefined, null, or empty. Unlike the native
+ * String.prototype.toUpperCase() method, this function won't throw an error when called
+ * with undefined or null values, instead returning an empty string.
+ *
+ * This is particularly useful when working with user input, API responses, or any scenario
+ * where string values might be optional or potentially undefined. It's commonly used for
+ * creating constants, formatting display text, generating identifiers, or normalizing text
+ * data that needs to be in uppercase format.
+ *
+ * @param {string} [str] - The string to convert to uppercase. Can be undefined or null.
+ * @returns {string} The uppercase version of the input string, or an empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // Basic string conversion
+ * const result1 = toUpperCase("hello world");
+ * // Returns: "HELLO WORLD"
+ *
+ * const result2 = toUpperCase("javascript");
+ * // Returns: "JAVASCRIPT"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe handling of undefined/null values
+ * const result1 = toUpperCase(undefined);
+ * // Returns: ""
+ *
+ * const result2 = toUpperCase(null);
+ * // Returns: ""
+ *
+ * const result3 = toUpperCase("");
+ * // Returns: ""
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Creating constants or identifiers
+ * function generateConstantName(variableName: string): string {
+ *   return toUpperCase(variableName.replace(/[^a-zA-Z0-9]/g, '_'));
+ * }
+ *
+ * generateConstantName("user-profile"); // "USER_PROFILE"
+ * generateConstantName("api.endpoint"); // "API_ENDPOINT"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in text formatting
+ * function formatTitle(title?: string): string {
+ *   if (!title) return "UNTITLED";
+ *   return toUpperCase(title.trim());
+ * }
+ *
+ * formatTitle("my document"); // "MY DOCUMENT"
+ * formatTitle(undefined);     // "UNTITLED"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in case-insensitive comparisons
+ * function compareIgnoreCase(str1?: string, str2?: string): boolean {
+ *   return toUpperCase(str1) === toUpperCase(str2);
+ * }
+ *
+ * compareIgnoreCase("Hello", "HELLO"); // true
+ * compareIgnoreCase("Test", "test");   // true
+ * ```
+ *
+ * @remarks
+ * - Returns an empty string for any falsy input (undefined, null, empty string)
+ * - Uses the native String.prototype.toUpperCase() method for actual conversion
+ * - Does not modify the original string (strings are immutable in JavaScript)
+ * - Handles all Unicode characters correctly, following locale-independent rules
+ * - More robust than direct .toUpperCase() calls when input might be undefined
+ * - Particularly useful for creating constants, headers, or display text
+ *
+ * @see {@link toLowerCase} Function for converting strings to lowercase
+ * @see {@link toUpperCaseBreak} Function for converting to uppercase and breaking into words
+ */
+function toUpperCase(str) {
+  if (!str) {
+    return "";
+  }
+  return str.toUpperCase();
+}
+/**
+ * Compares two strings for similarity using Levenshtein distance algorithm.
+ *
+ * The Levenshtein distance is a measure of the difference between two strings
+ * by counting the minimum number of single-character edits (insertions, deletions,
+ * or substitutions) required to change one string into another.
+ *
+ * @param {string} str1 - First string to compare
+ * @param {string} str2 - Second string to compare
+ * @returns {number} - A value between 0 and 1, where 1 means identical strings
+ *
+ * @example
+ * ```typescript
+ * stringSimilarity("hello", "hallo");       // 0.8 (4/5 characters match)
+ * stringSimilarity("kitten", "sitting");    // ~0.57 (higher distance)
+ * stringSimilarity("same", "same");         // 1.0 (identical)
+ * ```
+ */
+function stringSimilarity(str1, str2) {
+  if (str1 === str2) return 1.0;
+  if (!str1 || !str2) return 0.0;
+  const len1 = str1.length;
+  const len2 = str2.length;
+  // Initialize the distance matrix
+  const matrix = Array(len1 + 1).fill(null).map(() => Array(len2 + 1).fill(0));
+  // Fill the first row and column
+  for (let i = 0; i <= len1; i++) matrix[i][0] = i;
+  for (let j = 0; j <= len2; j++) matrix[0][j] = j;
+  // Fill the rest of the matrix
+  for (let i = 1; i <= len1; i++) {
+    for (let j = 1; j <= len2; j++) {
+      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(matrix[i - 1][j] + 1,
+      // deletion
+      matrix[i][j - 1] + 1,
+      // insertion
+      matrix[i - 1][j - 1] + cost);
+    }
+  }
+  // Calculate similarity from Levenshtein distance
+  const maxLen = Math.max(len1, len2);
+  if (maxLen === 0) return 1.0;
+  return 1.0 - matrix[len1][len2] / maxLen;
+}
+/**
+ * Generates a slug from a string, suitable for URLs or file names.
+ *
+ * @param {string} str - The string to convert to a slug
+ * @param {string} [separator="-"] - The character to use as separator
+ * @returns {string} - The slug string
+ *
+ * @example
+ * ```typescript
+ * slugify("Hello World");                // "hello-world"
+ * slugify("10 Tips & Tricks!");          // "10-tips-tricks"
+ * slugify("My Product (2023 Edition)");   // "my-product-2023-edition"
+ * slugify("Über résumé");                // "uber-resume"
+ * slugify("Blog Post", "_");             // "blog_post"
+ * ```
+ */
+function slugify(str, separator = "-") {
+  if (!str) return "";
+  return str.normalize("NFD") // Normalize to decomposed form for handling accents
+  .replace(/[\u0300-\u036f]/g, "") // Remove accents/diacritics
+  .toLowerCase() // Convert to lowercase
+  .trim() // Trim whitespace
+  .replace(/[^\w\s-]/g, "") // Remove non-word chars (except spaces and hyphens)
+  .replace(/[\s_]+/g, separator) // Replace spaces and underscores with separator
+  .replace(new RegExp(`${separator}+`, "g"), separator) // Replace multiple separators with single
+  .replace(new RegExp(`^${separator}|${separator}$`, "g"), ""); // Remove leading/trailing separators
+}
+/**
+ * Extracts all email addresses from a string.
+ *
+ * @param {string} str - The string to extract emails from
+ * @returns {string[]} - Array of found email addresses
+ *
+ * @example
+ * ```typescript
+ * extractEmails("Contact us at support@example.com or sales@example.com");
+ * // ["support@example.com", "sales@example.com"]
+ * ```
+ */
+function extractEmails(str) {
+  if (!str) return [];
+  const emailRegex = /([a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9._-]+)/gi;
+  return str.match(emailRegex) || [];
+}
+/**
+ * Extracts all URLs from a string.
+ *
+ * @param {string} str - The string to extract URLs from
+ * @returns {string[]} - Array of found URLs
+ *
+ * @example
+ * ```typescript
+ * extractUrls("Visit https://example.com or http://test.org/page?id=5");
+ * // ["https://example.com", "http://test.org/page?id=5"]
+ * ```
+ */
+function extractUrls(str) {
+  if (!str) return [];
+  // noinspection RegExpSimplifiable
+  const urlRegex = /(https?:\/\/[^\s]+)/g;
+  return str.match(urlRegex) || [];
+}
+/**
+ * Converts a string to a secure hash using SHA-256.
+ *
+ * Note: This is a browser-compatible implementation using the Web Crypto API.
+ * For Node.js environments, you might want to use the crypto module instead.
+ *
+ * @param {string} str - The string to hash
+ * @returns {Promise<string>} - Promise resolving to the hex hash string
+ *
+ * @example
+ * ```typescript
+ * // Browser usage
+ * await hashString("password123");
+ * // "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f"
+ * ```
+ */
+async function hashString(str) {
+  if (!str) return "";
+  // Convert string to Uint8Array
+  const encoder = new TextEncoder();
+  const data = encoder.encode(str);
+  // Hash the data
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  // Convert ArrayBuffer to hex string
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map(b => b.toString(HEX_RADIX).padStart(HEX_PADDING_LENGTH, HEX_PADDING_CHAR)).join("");
+}
+/**
+ * Generates a random string with specified length and character set.
+ *
+ * @param {number} length - The length of the random string
+ * @param {string} [charset] - The characters to use (defaults to alphanumeric)
+ * @returns {string} - The generated random string
+ *
+ * @example
+ * ```typescript
+ * // Default alphanumeric string
+ * randomString(8);
+ * // e.g. "A7bC9Df3"
+ *
+ * // Hex string
+ * randomString(6, "0123456789abcdef");
+ * // e.g. "a3f9d2"
+ *
+ * // PIN code
+ * randomString(4, "0123456789");
+ * // e.g. "8302"
+ * ```
+ */
+function randomString(length, charset) {
+  if (length <= 0) return "";
+  const chars = charset || "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  // Generate cryptographically secure random values if available
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    const values = new Uint32Array(length);
+    crypto.getRandomValues(values);
+    for (let i = 0; i < length; i++) {
+      result += chars[values[i] % chars.length];
+    }
+  } else {
+    // Fallback to Math.random (less secure)
+    for (let i = 0; i < length; i++) {
+      result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+  }
+  return result;
+}
+/**
+ * Masks a portion of a string, useful for displaying sensitive information.
+ *
+ * @param {string} str - The string to mask
+ * @param {number} [visibleStart=0] - Number of characters to show at the beginning
+ * @param {number} [visibleEnd=0] - Number of characters to show at the end
+ * @param {string} [maskChar="*"] - Character to use for masking
+ * @returns {string} - The masked string
+ *
+ * @example
+ * ```typescript
+ * // Mask credit card
+ * maskString("4111111111111111", 4, 4);
+ * // "4111********1111"
+ *
+ * // Mask email
+ * maskString("user@example.com", 2, 4, "x");
+ * // "usxxxxxx.com"
+ *
+ * // Mask phone number
+ * maskString("+1-555-123-4567", 0, 4);
+ * // "*********4567"
+ * ```
+ */
+function maskString(str, visibleStart = 0, visibleEnd = 0, maskChar = "*") {
+  if (!str) return "";
+  const length = str.length;
+  if (visibleStart + visibleEnd >= length) return str;
+  const start = str.substring(0, visibleStart);
+  const middle = maskChar.repeat(length - visibleStart - visibleEnd);
+  const end = str.substring(length - visibleEnd);
+  return start + middle + end;
+}
+/**
+ * Convert a string to first case (Capitalize first letter of the string).
+ * @param {string} [str] Optional string to join the words with.
+ * @returns {string} String in first case.
+ *
+ * @example
+ * ```TypeScript
+ * toFirstCase("hello world"); // "Hello world"
+ * ```
+ */
+function toFirstCase(str) {
+  if (!str) {
+    return "";
+  }
+  return (str[0]?.toUpperCase() || "") + str.slice(1).toLowerCase();
+}
+/**
+ * Converts a string to a camelCase or PascalCase variable name.
+ *
+ * @param {string} str - The string to convert
+ * @param {boolean} [pascalCase=false] - Whether to use PascalCase (true) or camelCase (false)
+ * @returns {string} - The variable name
+ *
+ * @example
+ * ```typescript
+ * toVariableName("Hello World");      // "helloWorld"
+ * toVariableName("API Response");     // "apiResponse"
+ * toVariableName("first-name");       // "firstName"
+ * toVariableName("user_id", true);    // "UserId"
+ * ```
+ */
+function toVariableName(str, pascalCase = false) {
+  if (!str) return "";
+  // Remove special characters and replace with spaces
+  const cleaned = str.replace(/[^\w\s]/g, " ");
+  // Break into words and process
+  return breakToWords(cleaned).map((word, index) => {
+    // Skip first word for camelCase unless it's PascalCase
+    if (index === 0 && !pascalCase) {
+      return word.toLowerCase();
+    }
+    // Capitalize first letter
+    return toFirstCase(word);
+  }).join("");
+}
+/**
+ * Wraps words in a string to ensure each line is no longer than a specified length.
+ *
+ * @param {string} str - The string to wrap
+ * @param {number} [lineLength=80] - Maximum length of each line
+ * @param {string} [breakChar="\n"] - Character(s) to insert at line breaks
+ * @returns {string} - The wrapped string
+ *
+ * @example
+ * ```typescript
+ * const text = "This is a long sentence that needs to be wrapped to fit within a certain width.";
+ *
+ * wordWrap(text, 20);
+ * // "This is a long\nsentence that needs\nto be wrapped to\nfit within a\ncertain width."
+ *
+ * wordWrap(text, 30, "<br>");
+ * // "This is a long sentence that<br>needs to be wrapped to fit<br>within a certain width."
+ * ```
+ */
+function wordWrap(str, lineLength = DEFAULT_LINE_LENGTH, breakChar = DEFAULT_BREAK_CHAR) {
+  if (!str) return "";
+  if (str.length <= lineLength) return str;
+  const words = str.split(" ");
+  let result = "";
+  let currentLine = "";
+  for (const word of words) {
+    // If adding this word exceeds line length, start a new line
+    if (currentLine.length + word.length + 1 > lineLength) {
+      result += currentLine.trim() + breakChar;
+      currentLine = `${word} `;
+    } else {
+      currentLine += `${word} `;
+    }
+  }
+  // Add the last line
+  result += currentLine.trim();
+  return result;
+}
+/**
+ * Creates an excerpt from a longer text by extracting a portion around a search term.
+ * Useful for search result highlighting or previews.
+ *
+ * @param {string} text - The full text to create an excerpt from
+ * @param {string} searchTerm - The search term to find in the text
+ * @param {number} [contextLength=40] - Number of characters to include before and after the search term
+ * @param {string} [ellipsis="..."] - Characters to use for indicating truncated text
+ * @returns {string} - The excerpt with the search term in context
+ *
+ * @example
+ * ```typescript
+ * const article = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam in dui mauris.";
+ *
+ * createExcerpt(article, "dolor", 10);
+ * // "...ipsum dolor sit amet..."
+ *
+ * createExcerpt(article, "consectetur", 15, "[...]");
+ * // "[...]sit amet, consectetur adipiscing[...]"
+ * ```
+ */
+function createExcerpt(text, searchTerm, contextLength = DEFAULT_CONTEXT_LENGTH, ellipsis = DEFAULT_ELLIPSIS) {
+  if (!text || !searchTerm) return text || "";
+  // Case-insensitive search
+  const lowerText = text.toLowerCase();
+  const lowerSearchTerm = searchTerm.toLowerCase();
+  const index = lowerText.indexOf(lowerSearchTerm);
+  if (index === -1) {
+    // If search term not found, return beginning of text
+    return text.length > contextLength * CONTEXT_MULTIPLIER ? text.substring(0, contextLength * CONTEXT_MULTIPLIER) + ellipsis : text;
+  }
+  // Calculate the start and end positions for the excerpt
+  const startPos = Math.max(0, index - contextLength);
+  const endPos = Math.min(text.length, index + searchTerm.length + contextLength);
+  // Add ellipsis if we're not at the beginning or end
+  const prefix = startPos > 0 ? ellipsis : "";
+  const suffix = endPos < text.length ? ellipsis : "";
+  // Extract the excerpt
+  return prefix + text.substring(startPos, endPos) + suffix;
+}
+/**
+ * Normalizes a string by removing accents, diacritics, and converting to lowercase.
+ *
+ * @param {string} str - The string to normalize
+ * @returns {string} - The normalized string
+ *
+ * @example
+ * ```typescript
+ * normalizeString("Café");          // "cafe"
+ * normalizeString("Über");          // "uber"
+ * normalizeString("résumé");        // "resume"
+ * normalizeString("ESPAÑA");        // "espana"
+ * ```
+ */
+function normalizeString(str) {
+  if (!str) return "";
+  return str.normalize("NFD") // Decompose accented characters
+  .replace(/[\u0300-\u036f]/g, "") // Remove accent marks
+  .toLowerCase(); // Convert to lowercase
+}
+/**
+ * Convert a string to upper cases and break into words with optional join or space.
+ * @param {string} [str] String to convert to upper cases and break into words.
+ * @param {string} [join] Optional string to join the words with.
+ * @returns {string} String in upper cases and broken into words.
+ *
+ * @example
+ * ```TypeScript
+ * toUpperCaseBreak("HelloWorld"); // "HELLO WORLD"
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * toUpperCaseBreak("HelloWorld", "! "); // "HELLO! WORLD"
+ */
+function toUpperCaseBreak(str, join) {
+  if (!str) {
+    return "";
+  }
+  return breakToWords(str).map(s => s.toUpperCase()).join(join ?? " ");
+}
+/**
+ * Converts a string to Sentence case (first word capitalized, rest lowercase) with customizable word separators.
+ *
+ * This function breaks a string into words, capitalizes the first word, converts remaining
+ * words to lowercase, and then joins them using a custom separator (or space by default).
+ *
+ * Unlike `toFirstCase()` which works on a single word, this function processes multi-word
+ * strings from various formats (camelCase, snake_case, etc.) and gives control over how
+ * the words are joined back together.
+ *
+ * @param {string} [str] - The input string to convert
+ * @param {string} [join] - Optional separator to join words (defaults to space)
+ * @returns {string} - The formatted string with first word capitalized and custom separators,
+ *                    or empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // With default space separator
+ * toFirstCaseBreak("helloWorld");       // "Hello world"
+ * toFirstCaseBreak("SYSTEM_ERROR");     // "System error"
+ * toFirstCaseBreak("api-request-log");  // "Api request log"
+ *
+ * // With custom separators
+ * toFirstCaseBreak("hello_world", "-");    // "Hello-world"
+ * toFirstCaseBreak("userAuthConfig", "."); // "User.auth.config"
+ * toFirstCaseBreak("GET_USER_DATA", "/");  // "Get/user/data"
+ * ```
+ *
+ * @see {@link toFirstCase} For capitalizing a single word
+ * @see {@link toTitleCase} For capitalizing the first letter of every word
+ * @see {@link breakToWords} The underlying function used to split input into words
+ */
+function toFirstCaseBreak(str, join) {
+  if (!str) {
+    return "";
+  }
+  return breakToWords(str).map((s, i) => i === 0 ? toFirstCase(s) : s.toLowerCase()).join(join ?? " ");
+}
+/**
+ * Convert a string to title case (Capitalize first letter of each word).
+ * @param {string} [str] String to convert to title case.
+ * @returns {string} String in title case.
+ *
+ * @example
+ * ```TypeScript
+ * toTitleCase("hello world"); // "Hello World"
+ * ```
+ */
+function toTitleCase(str) {
+  if (!str) {
+    return "";
+  }
+  return breakToWords(str).map(s => toFirstCase(s)).join(" ");
+}
+/**
+ * Convert a string to camel case.
+ * @param {string} [str] String to convert to camel case.
+ * @returns {string} String in camel case.
+ *
+ * @example
+ * ```TypeScript
+ * toCamelCase("hello world"); // "helloWorld"
+ * ```
+ */
+function toCamelCase(str) {
+  if (!str) {
+    return "";
+  }
+  return breakToWords(str).map((s, i) => i === 0 ? s.toLowerCase() : toFirstCase(s)).join("");
+}
+/**
+ * Convert a string to pascal case.
+ * @param {string} [str] String to convert to pascal case.
+ * @returns {string} String in pascal case.
+ *
+ * @example
+ * ```TypeScript
+ * toPascalCase("hello world"); // "HelloWorld"
+ * ```
+ */
+function toPascalCase(str) {
+  if (!str) {
+    return "";
+  }
+  return breakToWords(str).map(s => toFirstCase(s)).join("");
+}
+/**
+ * Convert a string to sentence case. (Capitalize first letter of every sentence).
+ * @param {string} [str] String to convert to sentence case.
+ * @returns {string} String in sentence case.
+ *
+ * @example
+ * ```TypeScript
+ * toSentenceCase("hello world. how are you?"); // "Hello world. How are you?"
+ * ```
+ */
+function toSentenceCase(str) {
+  return str.split(".").map(s => toFirstCase(s.trim())).join(". ");
+}
+/**
+ * Converts a string to snake_case format.
+ *
+ * This function transforms a string from any common case format (camel, pascal, kebab, etc.)
+ * into snake_case, where words are lowercase and separated by underscores.
+ *
+ * When the optional `caps` parameter is set to true, the result will be UPPER_SNAKE_CASE
+ * (also known as SCREAMING_SNAKE_CASE or CONSTANT_CASE).
+ *
+ * @param {string} [str] - The input string to convert
+ * @param {boolean} [caps=false] - When true, converts to UPPER_SNAKE_CASE
+ * @returns {string} - The converted snake_case string, or empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // From various formats to snake_case
+ * toSnakeCase("hello world");    // "hello_world"
+ * toSnakeCase("HelloWorld");     // "hello_world"
+ * toSnakeCase("hello-world");    // "hello_world"
+ * toSnakeCase("HELLO WORLD");    // "hello_world"
+ *
+ * // To UPPER_SNAKE_CASE (CONSTANT_CASE)
+ * toSnakeCase("hello world", true);  // "HELLO_WORLD"
+ * toSnakeCase("helloWorld", true);   // "HELLO_WORLD"
+ * ```
+ *
+ * @remarks
+ * This function first splits the string into words using `breakToWords()`,
+ * then joins them with underscores, applying the requested case transformation.
+ */
+function toSnakeCase(str, caps) {
+  if (!str) {
+    return "";
+  }
+  const snake = breakToWords(str).join("_");
+  return caps ? snake.toUpperCase() : snake.toLowerCase();
+}
+/**
+ * Convert a string to kebab case.
+ * @param {string} [str] String to convert to kebab case.
+ * @param {boolean} [caps] Whether to convert to upper case.
+ * @returns {string} String in kebab case.
+ *
+ * @example
+ * ```TypeScript
+ * toKebabCase("hello world"); // "hello-world"
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * toKebabCase("hello world", true); // "HELLO-WORLD"
+ * ```
+ */
+function toKebabCase(str, caps) {
+  if (!str) {
+    return "";
+  }
+  const kebab = breakToWords(str).join("-");
+  return caps ? kebab.toUpperCase() : kebab.toLowerCase();
+}
+/**
+ * Converts a string to a number.
+ * @param {number|string} str String to convert to a number.
+ * @returns {number|undefined} Number or undefined.
+ *
+ * @example
+ * ```TypeScript
+ * toNumber("123"); // 123
+ * ```
+ */
+function toNumber(str) {
+  return !isNaN(Number(str)) ? Number(str) : undefined;
+}
+/**
+ * Remove HTML tags from a string and return plain text.
+ * @param {string} str String to remove HTML tags from.
+ * @returns {string} Plain text.
+ *
+ * @example
+ * ```TypeScript
+ * htmlToText("<h1>Hello World</h1>"); // "Hello World"
+ * ```
+ */
+function htmlToText(str) {
+  return str.replace(/<[^>]*>?/gm, "");
+}
+/**
+ * Converts a singular English word to its plural form.
+ *
+ * This function applies common English pluralization rules to transform
+ * singular words into their plural equivalents. It handles regular patterns
+ * as well as many irregular cases and special rules for different word endings.
+ *
+ * @param {string} str - The singular word to convert to plural form
+ * @returns {string} - The plural form of the word, or the original string if:
+ *   - Input is empty/falsy
+ *   - The word is already plural
+ *
+ * @example
+ * ```typescript
+ * // Regular plurals
+ * plural("cat");      // "cats"
+ * plural("dog");      // "dogs"
+ *
+ * // Words ending in -y
+ * plural("party");    // "parties"
+ * plural("day");      // "days"
+ *
+ * // Words ending in -f or -fe
+ * plural("wolf");     // "wolves"
+ * plural("knife");    // "knives"
+ *
+ * // Words ending in -o
+ * plural("potato");   // "potatoes"
+ * plural("photo");    // "photos"
+ *
+ * // Irregular plurals
+ * plural("child");    // "children"
+ * plural("man");      // "men"
+ * plural("foot");     // "feet"
+ *
+ * // Latin/Greek words
+ * plural("cactus");   // "cacti"
+ * plural("analysis"); // "analyses"
+ * ```
+ *
+ * @remarks
+ * - This function is designed for English language words only
+ * - It pairs well with the `singular()` function for round-trip conversion
+ */
+function plural(str) {
+  if (!str) return str;
+  // Combine all rules in priority order
+  const rules = [...EnglishInflectionRules.INVARIANT, ...EnglishInflectionRules.IRREGULAR.toPlural, ...EnglishInflectionRules.LATIN_GREEK.toPlural, ...EnglishInflectionRules.PATTERN_RULES.toPlural, ...EnglishInflectionRules.DEFAULT.toPlural];
+  // Apply the first matching rule
+  for (const rule of rules) {
+    if (rule.regex.test(str)) {
+      return str.replace(rule.regex, typeof rule.replacement === "string" ? rule.replacement : rule.replacement(str));
+    }
+  }
+  return str;
+}
+/**
+ * Truncates a string to a specified length and adds an ellipsis if needed.
+ *
+ * @param {string} str - The string to truncate
+ * @param {number} length - Maximum length of the truncated string (excluding ellipsis)
+ * @param {string} [ellipsis="..."] - The ellipsis to add to truncated strings
+ * @returns {string} - The truncated string with ellipsis if needed
+ *
+ * @example
+ * ```typescript
+ * truncate("This is a long sentence", 10);  // "This is a..."
+ * truncate("Short", 10);                   // "Short"
+ * truncate("Custom ellipsis", 6, " [more]"); // "Custom [more]"
+ * ```
+ */
+function truncate(str, length, ellipsis = "...") {
+  if (!str) return "";
+  if (str.length <= length) return str;
+  return str.substring(0, length) + ellipsis;
+}
+/**
+ * Pads a string to a specified length with a specified character.
+ *
+ * @param {string} str - The string to pad
+ * @param {number} length - The target length of the resulting string
+ * @param {string} [char=" "] - The character to pad with (defaults to space)
+ * @param {boolean} [padEnd=true] - Whether to pad at the end (true) or beginning (false)
+ * @returns {string} - The padded string
+ *
+ * @example
+ * ```typescript
+ * padString("Hello", 10);           // "Hello     "
+ * padString("Hello", 10, "*");      // "Hello*****"
+ * padString("Hello", 10, "0", false); // "00000Hello"
+ * ```
+ */
+function padString(str, length, char = " ", padEnd = true) {
+  if (!str) return "";
+  if (str.length >= length) return str;
+  const padding = char.repeat(length - str.length);
+  return padEnd ? str + padding : padding + str;
+}
+/**
+ * Escapes special characters in a string for use in regular expressions.
+ *
+ * @param {string} str - The string to escape
+ * @returns {string} - The escaped string safe for use in RegExp
+ *
+ * @example
+ * ```typescript
+ * escapeRegExp("hello.world*");  // "hello\.world\*"
+ *
+ * // Usage in RegExp:
+ * const userInput = "hello.world*";
+ * const regex = new RegExp(escapeRegExp(userInput));
+ * ```
+ */
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Capitalizes each word in a string according to title case rules.
+ *
+ * This function implements proper title case rules, where:
+ * - The first and last words are always capitalized
+ * - All other major words are capitalized
+ * - Minor words (articles, conjunctions, short prepositions) are not capitalized
+ *   unless they are the first or last word
+ *
+ * @param {string} str - The string to convert to title case
+ * @returns {string} - The string in proper title case format
+ *
+ * @example
+ * ```typescript
+ * toProperTitleCase("the quick brown fox jumps over the lazy dog");
+ * // "The Quick Brown Fox Jumps over the Lazy Dog"
+ *
+ * toProperTitleCase("a tale of two cities");
+ * // "A Tale of Two Cities"
+ * ```
+ */
+function toProperTitleCase(str) {
+  if (!str) return "";
+  const minorWords = ["a", "an", "and", "as", "at", "but", "by", "for", "in", "nor", "of", "on", "or", "per", "the", "to", "via", "vs"];
+  const words = str.toLowerCase().split(/\s+/);
+  const result = words.map((word, index) => {
+    // Always capitalize first and last word
+    if (index === 0 || index === words.length - 1) {
+      return toFirstCase(word);
+    }
+    // Don't capitalize minor words
+    if (minorWords.includes(word.toLowerCase())) {
+      return word.toLowerCase();
+    }
+    // Capitalize major words
+    return toFirstCase(word);
+  });
+  return result.join(" ");
+}
+/**
+ * Implementation of the format function that handles both overloads.
+ */
+function format(template, ...values) {
+  if (!template) return "";
+  // If the first value is an object (for named placeholders), use it directly
+  if (values.length === 1 && typeof values[0] === "object" && values[0] !== null && !Array.isArray(values[0])) {
+    const replacements = values[0];
+    return template.replace(/{([^{}]+)}/g, (match, key) => {
+      const value = replacements[key];
+      return value !== undefined ? String(value) : match;
+    });
+  }
+  // Otherwise use indexed placeholders
+  return template.replace(/{(\d+)}/g, (match, index) => {
+    const value = values[Number(index)];
+    return value !== undefined ? String(value) : match;
+  });
+}
+/**
+ * Counts the occurrences of a substring within a string.
+ *
+ * @param {string} str - The string to search within
+ * @param {string} searchValue - The substring to search for
+ * @param {boolean} [caseSensitive=true] - Whether the search should be case-sensitive
+ * @returns {number} - The number of occurrences
+ *
+ * @example
+ * ```typescript
+ * countOccurrences("hello hello world", "hello");  // 2
+ * countOccurrences("Hello hello", "hello", false); // 2
+ * countOccurrences("Hello hello", "hello", true);  // 1
+ * ```
+ */
+function countOccurrences(str, searchValue, caseSensitive = true) {
+  if (!str || !searchValue) return 0;
+  const regex = new RegExp(escapeRegExp(searchValue), caseSensitive ? "g" : "gi");
+  const matches = str.match(regex);
+  return matches ? matches.length : 0;
+}
+/**
+ * Reverses a string.
+ *
+ * @param {string} str - The string to reverse
+ * @returns {string} - The reversed string
+ *
+ * @example
+ * ```typescript
+ * reverse("hello");  // "olleh"
+ * reverse("12345");  // "54321"
+ * ```
+ */
+function reverse(str) {
+  if (!str) return "";
+  return str.split("").reverse().join("");
+}
+/**
+ * Checks if a string contains only alphanumeric characters.
+ *
+ * @param {string} str - The string to check
+ * @returns {boolean} - True if the string contains only alphanumeric characters
+ *
+ * @example
+ * ```typescript
+ * isAlphanumeric("abc123");  // true
+ * isAlphanumeric("abc-123"); // false
+ * ```
+ */
+function isAlphanumeric(str) {
+  if (!str) return false;
+  return /^[a-zA-Z0-9]+$/.test(str);
+}
+/**
+ * Removes all whitespace from a string.
+ *
+ * @param {string} str - The string to process
+ * @returns {string} - The string with all whitespace removed
+ *
+ * @example
+ * ```typescript
+ * removeWhitespace("hello world");       // "helloworld"
+ * removeWhitespace("  spaces   tabs  "); // "spacestabs"
+ * ```
+ */
+function removeWhitespace(str) {
+  if (!str) return "";
+  return str.replace(/\s+/g, "");
+}
+/**
+ * Converts plural English words to their singular form.
+ *
+ * This function applies a series of linguistic rules and exceptions to transform
+ * plural English words into their singular equivalents. It handles irregular plurals
+ * (e.g., "children" → "child"), common suffix patterns (e.g., "parties" → "party"),
+ * and Latin-derived words (e.g., "cacti" → "cactus").
+ *
+ * The function applies rules in priority order, from most specific to most general,
+ * to ensure correct handling of special cases.
+ *
+ * @param {string} str - The plural word to convert to singular form
+ * @returns {string} - The singular form of the word, or the original string if:
+ *   - Input is empty/falsy
+ *   - No singular form is recognized
+ *   - The word is already singular
+ *
+ * @example
+ * ```typescript
+ * // Irregular plurals
+ * singular("children"); // "child"
+ * singular("men");     // "man"
+ * singular("feet");    // "foot"
+ *
+ * // Common patterns
+ * singular("cats");    // "cat"
+ * singular("boxes");   // "box"
+ * singular("parties"); // "party"
+ * singular("wolves"); // "wolf"
+ *
+ * // Latin-derived words
+ * singular("cacti");      // "cactus"
+ * singular("phenomena");  // "phenomenon"
+ * ```
+ *
+ * @remarks
+ * - This function is designed for English language words only
+ * - It handles many common cases but isn't exhaustive for all English plurals
+ * - Words that are identical in singular and plural form (e.g., "sheep") are returned unchanged
+ */
+function singular(str) {
+  if (!str) return str;
+  // Combine all rules in priority order
+  const rules = [...EnglishInflectionRules.INVARIANT, ...EnglishInflectionRules.IRREGULAR.toSingular, ...EnglishInflectionRules.LATIN_GREEK.toSingular, ...EnglishInflectionRules.PATTERN_RULES.toSingular, ...EnglishInflectionRules.DEFAULT.toSingular];
+  // Iterate over rules and apply the first matching one
+  for (const rule of rules) {
+    if (rule.regex.test(str)) {
+      return str.replace(rule.regex, typeof rule.replacement === "string" ? rule.replacement : rule.replacement(str));
+    }
+  }
+  // Return the original string if no rules match
+  return str;
+}
+
+// noinspection JSUnusedGlobalSymbols
+/**
+ * Type-safe utility to check if a value is an array of a specific type.
+ *
+ * This function acts as a type guard that not only checks if the provided value
+ * is an array (using the native Array.isArray method), but also narrows the TypeScript
+ * type to an array of the generic type T. This enables safer handling of potentially
+ * array-typed values with full type inference in the conditional branches.
+ *
+ * @template T The expected element type of the array
+ * @param {T | T[] | undefined} value The value to check, which could be a single item,
+ *                                     an array of items, or undefined
+ * @returns {value is T[]} Type predicate that narrows the type to T[] when true
+ *
+ * @remarks
+ * While this function essentially wraps Array.isArray, its value comes from the
+ * TypeScript type narrowing it provides, making it especially useful in code that
+ * needs to handle both single items and collections of items with type safety.
+ *
+ * The function properly handles undefined values by returning false, making it safe
+ * to use with optional parameters or potentially undefined values.
+ *
+ * @example
+ * ```typescript
+ * // Function that can accept either a single user or multiple users
+ * async function createUser(userOrUsers: UserDto | UserDto[] | undefined): Promise<User | User[]> {
+ *     // TypeScript knows userOrUsers is UserDto[] in this branch
+ *     if (isArray<UserDto>(userOrUsers)) {
+ *         return Promise.all(userOrUsers.map(user => userService.createUser(user)));
+ *     }
+ *     // TypeScript knows userOrUsers is UserDto or undefined in this branch
+ *     else if (userOrUsers) {
+ *         return userService.createUser(userOrUsers);
+ *     }
+ *     else {
+ *         throw new BadRequestException('User data is required');
+ *     }
+ * }
+ * ```
+ */
+function isArray(value) {
+  return Array.isArray(value);
+}
+/**
+ * Type-safe utility to check if a value is a non-array object of a specific type.
+ *
+ * This function serves as a type guard that checks if the provided value is an object
+ * (but not an array) and narrows the TypeScript type to the generic type T. It properly
+ * excludes null, arrays, and primitive values, focusing only on object instances.
+ *
+ * @template T The expected object type to narrow to when the check passes
+ * @param {T | T[] | undefined} [value] The value to check, which could be a single object,
+ *                                       an array of objects, or undefined
+ * @returns {value is T} Type predicate that narrows the type to T when true
+ *
+ * @remarks
+ * This function performs three checks to ensure the value is a proper object:
+ * 1. It's not an array (using Array.isArray)
+ * 2. It's of type "object" according to JavaScript's typeof operator
+ * 3. It's not null (which would pass the typeof check but isn't a valid object)
+ *
+ * This is particularly useful when handling parameters that could be either an object
+ * or a simpler identifier (like an ID), allowing for type-safe conditional logic.
+ *
+ * @example
+ * ```typescript
+ * // Function that can accept either a user ID or a user object
+ * async function getUserInfo(userIdOrUser: number | User | undefined): Promise<UserInfo> {
+ *     // TypeScript knows userIdOrUser is User in this branch
+ *     if (isObject<User>(userIdOrUser)) {
+ *         // Can safely access object properties
+ *         return await userService.getUserInfo(userIdOrUser.id);
+ *     }
+ *     // TypeScript knows userIdOrUser is number or undefined in this branch
+ *     else {
+ *         return await userService.getUserInfo(userIdOrUser);
+ *     }
+ * }
+ *
+ * // Works with optional parameters too
+ * function formatUserName(user?: User | string): string {
+ *     if (isObject<User>(user)) {
+ *         return `${user.firstName} ${user.lastName}`;
+ *     }
+ *     return user || 'Guest';
+ * }
+ * ```
+ */
+function isObject(value) {
+  return !Array.isArray(value) && typeof value === "object" && value !== null;
+}
+/**
+ * Type-safe utility to check if a value is an object with a specific property.
+ *
+ * This function acts as a type guard that determines if an unknown value is an object
+ * that contains a specified property, and narrows the TypeScript type to the generic
+ * type T when true. This provides a robust way to implement duck typing in TypeScript,
+ * allowing for safe property access in the conditional branches.
+ *
+ * @template T The expected object type that should contain the property
+ * @param {unknown} value Any value to check, with no type constraints
+ * @param {keyof T} propertyName The name of the property that should exist on the object
+ * @returns {value is T} Type predicate that narrows the type to T when true
+ *
+ * @remarks
+ * This function uses Object.prototype.hasOwnProperty.call to safely check for property
+ * existence, even if the object has a custom implementation of hasOwnProperty or if the
+ * property is named 'hasOwnProperty'.
+ *
+ * Unlike the simpler isObject utility, this function can distinguish between different
+ * object types based on their properties, making it ideal for discriminating between
+ * different interface implementations or handling union types.
+ *
+ * @example
+ * ```typescript
+ * // Check if an object has the properties of a User interface
+ * interface User {
+ *   id: number;
+ *   name: string;
+ * }
+ *
+ * interface Order {
+ *   orderNumber: string;
+ *   items: string[];
+ * }
+ *
+ * // Function that can handle different object types
+ * function processEntity(entity: unknown): void {
+ *   // Check if entity has 'id' property, indicating it's a User
+ *   if (isObjectWith<User>(entity, 'id')) {
+ *     // TypeScript knows entity is User in this branch
+ *     console.log(`Processing user: ${entity.name}`);
+ *   }
+ *   // Check if entity has 'orderNumber' property, indicating it's an Order
+ *   else if (isObjectWith<Order>(entity, 'orderNumber')) {
+ *     // TypeScript knows entity is Order in this branch
+ *     console.log(`Processing order: ${entity.orderNumber} with ${entity.items.length} items`);
+ *   }
+ *   else {
+ *     console.log('Unknown entity type');
+ *   }
+ * }
+ *
+ * // Useful for API responses where types may vary
+ * async function handleResponse(response: unknown): Promise<void> {
+ *   if (isObjectWith<ErrorResponse>(response, 'errorCode')) {
+ *     throw new ApiException(response.errorCode, response.message);
+ *   }
+ *   else if (isObjectWith<SuccessResponse>(response, 'data')) {
+ *     await processData(response.data);
+ *   }
+ * }
+ * ```
+ */
+function isObjectWith(value, propertyName) {
+  return Object.prototype.hasOwnProperty.call(value, propertyName);
+}
+
+/**
+ * Template tags for string transformations
+ *
+ * This enum defines all available template tags that can be used with the `applyTemplate`
+ * and `applyTemplates` functions. Each tag corresponds to a specific string transformation
+ * function from the string.utils module.
+ *
+ * Template tags are represented as strings in the format `#{transformationName}`. When these
+ * tags appear in template strings, they are replaced with the result of applying the
+ * corresponding transformation to the provided value.
+ *
+ * @see {@link applyTemplate} For applying a single value to a template
+ * @see {@link applyTemplates} For applying multiple values to a template
+ */
+var TemplateTag;
+(function (TemplateTag) {
+  TemplateTag["UPPER_CASE"] = "#{upperCase}";
+  TemplateTag["SNAKE_CASE"] = "#{snakeCase}";
+  TemplateTag["UPPER_SNAKE_CASE"] = "#{upperSnakeCase}";
+  TemplateTag["LOWER_CASE"] = "#{lowerCase}";
+  TemplateTag["SENTENCE_CASE"] = "#{sentenceCase}";
+  TemplateTag["FIRST_CASE"] = "#{firstCase}";
+  TemplateTag["CAMEL_CASE"] = "#{camelCase}";
+  TemplateTag["PASCAL_CASE"] = "#{pascalCase}";
+  TemplateTag["KEBAB_CASE"] = "#{kebabCase}";
+  TemplateTag["UPPER_KEBAB_CASE"] = "#{upperKebabCase}";
+  TemplateTag["TITLE_CASE"] = "#{titleCase}";
+  TemplateTag["LOWER_CASE_BREAK"] = "#{lowerCaseBreak}";
+  TemplateTag["UPPER_CASE_BREAK"] = "#{upperCaseBreak}";
+  TemplateTag["FIRST_CASE_BREAK"] = "#{firstCaseBreak}";
+  TemplateTag["SINGULAR"] = "#{singular}";
+  TemplateTag["NUMBER"] = "#{number}";
+  TemplateTag["HTML_TO_TEXT"] = "#{htmlToText}";
+  // FORMAT = "#{format}",
+})(TemplateTag || (TemplateTag = {}));
+
+// noinspection JSUnusedGlobalSymbols
+/**
+ * Applies a value to a template string containing transformation tags.
+ *
+ * This function replaces template tags in a string with transformed versions of a provided value.
+ * It's particularly useful for creating dynamic messages, error notifications, or any text
+ * that needs to include the same value in different formats.
+ *
+ * Each template tag is replaced with the result of applying the corresponding transformation
+ * function to the provided value. If a tag isn't present in the template string, that
+ * transformation is skipped.
+ *
+ * Available template tags:
+ * - `#{upperCase}` - Converts to UPPERCASE ("USER")
+ * - `#{snakeCase}` - Converts to snake_case ("user_profile")
+ * - `#{upperSnakeCase}` - Converts to UPPER_SNAKE_CASE ("USER_PROFILE")
+ * - `#{lowerCase}` - Converts to lowercase ("user")
+ * - `#{sentenceCase}` - Converts to Sentence case ("User profile")
+ * - `#{firstCase}` - Converts to First case ("User")
+ * - `#{camelCase}` - Converts to camelCase ("userProfile")
+ * - `#{pascalCase}` - Converts to PascalCase ("UserProfile")
+ * - `#{kebabCase}` - Converts to kebab-case ("user-profile")
+ * - `#{upperKebabCase}` - Converts to KEBAB-CASE ("USER-PROFILE")
+ * - `#{titleCase}` - Converts to Title Case ("User Profile")
+ * - `#{lowerCaseBreak}` - Breaks words and converts to lowercase ("user profile")
+ * - `#{upperCaseBreak}` - Breaks words and converts to UPPERCASE ("USER PROFILE")
+ * - `#{firstCaseBreak}` - Breaks words and applies First case ("User profile")
+ * - `#{singular}` - Converts plural to singular form ("users" → "user")
+ * - `#{number}` - Converts to a number if possible ("123" → 123)
+ * - `#{htmlToText}` - Removes HTML tags ("<b>User</b>" → "User")
+ * - `#{format}` - Formats a string with placeholders (used with additional parameters)
+ *
+ * @example
+ * ```typescript
+ * // Error message with different versions of the same term
+ * applyTemplate(
+ *     'Cannot create a #{lowerCase} with this email. #{sentenceCase} already exists.',
+ *     'User'
+ * );
+ * // Output: "Cannot create a user with this email. User already exists."
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using multiple transformations of the same value
+ * applyTemplate(
+ *     'Model: #{pascalCase}\nTable: #{snakeCase}\nAPI Path: #{kebabCase}',
+ *     'blogPost'
+ * );
+ * // Output:
+ * //     Model: BlogPost
+ * //     Table: blog_post
+ * //     API Path: blog-post
+ * ```
+ *
+ * @param {string} str - Template string containing transformation tags
+ * @param {string} prefix - The prefix to update with
+ * @returns {string} - The template with all tags replaced by transformed values
+ *
+ * @see {@link TemplateTag} For the full list of available template tags
+ * @see {@link applyTemplates} For applying multiple different values to a template
+ */
+function applyTemplate(str, prefix) {
+  // Apply all available template tags
+  return str.replace(TemplateTag.UPPER_CASE, toUpperCase(prefix)).replace(TemplateTag.SNAKE_CASE, toSnakeCase(prefix)).replace(TemplateTag.UPPER_SNAKE_CASE, toSnakeCase(prefix, true)).replace(TemplateTag.LOWER_CASE, toLowerCase(prefix)).replace(TemplateTag.SENTENCE_CASE, toSentenceCase(prefix)).replace(TemplateTag.FIRST_CASE, toFirstCase(prefix)).replace(TemplateTag.CAMEL_CASE, toCamelCase(prefix)).replace(TemplateTag.PASCAL_CASE, toPascalCase(prefix)).replace(TemplateTag.KEBAB_CASE, toKebabCase(prefix)).replace(TemplateTag.UPPER_KEBAB_CASE, toKebabCase(prefix, true)).replace(TemplateTag.TITLE_CASE, toTitleCase(prefix)).replace(TemplateTag.LOWER_CASE_BREAK, toLowerCaseBreak(prefix)).replace(TemplateTag.UPPER_CASE_BREAK, toUpperCaseBreak(prefix)).replace(TemplateTag.FIRST_CASE_BREAK, toFirstCaseBreak(prefix)).replace(TemplateTag.SINGULAR, singular(prefix)).replace(TemplateTag.NUMBER, String(toNumber(prefix) ?? prefix)).replace(TemplateTag.HTML_TO_TEXT, htmlToText(prefix));
+}
+/**
+ * Applies multiple named template transformations to a string with different values for each prefix.
+ *
+ * This advanced templating function allows you to use multiple different values within a single
+ * template string, each with their own set of transformation tags. Unlike `applyTemplate` which
+ * applies one value to all tags, this function lets you specify different values for different
+ * prefixes, enabling complex template scenarios with multiple entities.
+ *
+ * Each prefix in the template is identified by a namespace (e.g., `user`, `post`) followed by
+ * a dot and the transformation tag (e.g., `#{user.lowerCase}`, `#{post.titleCase}`). This allows
+ * for sophisticated template generation where different parts of the text need different source
+ * values with various transformations applied.
+ *
+ * This is particularly useful for generating complex messages, code templates, documentation,
+ * or any text that involves multiple entities that need to be formatted differently within
+ * the same template.
+ *
+ * @param {string} str - Template string containing namespaced transformation tags in the format
+ *                       `#{prefix.transformationType}` where prefix matches keys in the prefixes object
+ * @param {Record<string, string>} prefixes - Object mapping prefix names to their corresponding values.
+ *                                            Each key becomes a namespace in the template, and the value
+ *                                            is the string that will be transformed according to the tags.
+ * @returns {string} The template string with all namespaced tags replaced by their transformed values
+ *
+ * @example
+ * ```typescript
+ * // Multi-entity message generation
+ * const message = applyTemplates(
+ *     'User #{user.lowerCase} created a new #{entity.sentenceCase} titled "#{title.titleCase}"',
+ *     {
+ *         user: 'JohnDoe',
+ *         entity: 'blogPost',
+ *         title: 'my first programming tutorial'
+ *     }
+ * );
+ * // Returns: "User johndoe created a new Blog post titled "My First Programming Tutorial""
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Code generation with multiple entities
+ * const codeTemplate = applyTemplates(
+ *     `class #{model.pascalCase} {
+ *   constructor(private #{service.camelCase}: #{service.pascalCase}Service) {}
+ *
+ *   async create#{model.pascalCase}(data: #{model.pascalCase}Data): Promise<#{model.pascalCase}> {
+ *     return this.#{service.camelCase}.create(data);
+ *   }
+ * }`,
+ *     {
+ *         model: 'user-profile',
+ *         service: 'database'
+ *     }
+ * );
+ * // Generates a complete class with proper naming conventions
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // API documentation generation
+ * const apiDoc = applyTemplates(
+ *     `## #{endpoint.titleCase}
+ *
+ * **URL:** \`/api/#{endpoint.kebabCase}\`
+ * **Method:** #{method.upperCase}
+ * **Model:** #{model.pascalCase}
+ *
+ * Creates a new #{model.lowerCaseBreak} in the system.`,
+ *     {
+ *         endpoint: 'userProfiles',
+ *         method: 'post',
+ *         model: 'UserProfile'
+ *     }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Database migration script generation
+ * const migration = applyTemplates(
+ *     `CREATE TABLE #{table.snakeCase} (
+ *   id SERIAL PRIMARY KEY,
+ *   #{field.snakeCase} VARCHAR(255) NOT NULL,
+ *   created_at TIMESTAMP DEFAULT NOW()
+ * );
+ *
+ * CREATE INDEX idx_#{table.snakeCase}_#{field.snakeCase} ON #{table.snakeCase}(#{field.snakeCase});`,
+ *     {
+ *         table: 'UserProfiles',
+ *         field: 'emailAddress'
+ *     }
+ * );
+ * ```
+ *
+ * @remarks
+ * - Each prefix in the prefixes object becomes a namespace in the template
+ * - Template tags must follow the format `#{prefix.transformationType}`
+ * - All transformation types available in `applyTemplate` are supported
+ * - If a prefixed tag is not found in the template, it's simply ignored
+ * - The function processes all prefixes and their transformations in the order they appear
+ * - Supports the same transformation types as the TemplateTag enum
+ * - More flexible than `applyTemplate` but with slightly more complex syntax
+ *
+ * @see {@link applyTemplate} For applying a single value to multiple transformation tags
+ * @see {@link TemplateTag} For the complete list of available transformation types
+ */
+function applyTemplates(str, prefixes) {
+  let result = str;
+  // Process each prefix
+  for (const [key, prefix] of Object.entries(prefixes)) {
+    // Replace all possible template tags for this prefix
+    // eslint-disable-next-line no-loop-func
+    Object.values(TemplateTag).forEach(tag => {
+      // Convert #{tag} to #{prefix.tag}
+      const prefixedTag = tag.replace("#{", `#{${key}.`);
+      if (result.includes(prefixedTag)) {
+        // Get the transformation function name
+        const templateFunction = tag.replace(/#{(.+)}/, "$1");
+        // Apply the appropriate transformation based on the tag
+        let replacement = prefix;
+        switch (templateFunction) {
+          case TemplateTag.UPPER_CASE:
+            replacement = toUpperCase(prefix);
+            break;
+          case TemplateTag.SNAKE_CASE:
+            replacement = toSnakeCase(prefix);
+            break;
+          case TemplateTag.UPPER_SNAKE_CASE:
+            replacement = toSnakeCase(prefix, true);
+            break;
+          case TemplateTag.LOWER_CASE:
+            replacement = toLowerCase(prefix);
+            break;
+          case TemplateTag.SENTENCE_CASE:
+            replacement = toSentenceCase(prefix);
+            break;
+          case TemplateTag.FIRST_CASE:
+            replacement = toFirstCase(prefix);
+            break;
+          case TemplateTag.CAMEL_CASE:
+            replacement = toCamelCase(prefix);
+            break;
+          case TemplateTag.PASCAL_CASE:
+            replacement = toPascalCase(prefix);
+            break;
+          case TemplateTag.KEBAB_CASE:
+            replacement = toKebabCase(prefix);
+            break;
+          case TemplateTag.UPPER_KEBAB_CASE:
+            replacement = toKebabCase(prefix, true);
+            break;
+          case TemplateTag.TITLE_CASE:
+            replacement = toTitleCase(prefix);
+            break;
+          case TemplateTag.LOWER_CASE_BREAK:
+            replacement = toLowerCaseBreak(prefix);
+            break;
+          case TemplateTag.UPPER_CASE_BREAK:
+            replacement = toUpperCaseBreak(prefix);
+            break;
+          case TemplateTag.FIRST_CASE_BREAK:
+            replacement = toFirstCaseBreak(prefix);
+            break;
+          case TemplateTag.SINGULAR:
+            replacement = singular(prefix);
+            break;
+          case TemplateTag.NUMBER:
+            replacement = String(toNumber(prefix) ?? prefix);
+            break;
+          case TemplateTag.HTML_TO_TEXT:
+            replacement = htmlToText(prefix);
+            break;
+        }
+        result = result.replace(prefixedTag, replacement);
+      }
+    });
+  }
+  return result;
+}
+
+export { CHARACTERS_TO_REMOVE, CONTEXT_MULTIPLIER, DEFAULT_BREAK_CHAR, DEFAULT_CONTEXT_LENGTH, DEFAULT_ELLIPSIS, DEFAULT_LINE_LENGTH, EnglishInflectionRules, HEX_PADDING_CHAR, HEX_PADDING_LENGTH, HEX_RADIX, TemplateTag, applyTemplate, applyTemplates, breakToWords, countOccurrences, createExcerpt, deepCopy, dottedPathObjectToNested, escapeRegExp, extractEmails, extractUrls, filterByObject, format, getEnumValues, getFileExt, getFileSize, getMapKey, getMapKeys, getValueByPath, groupBy, hasOwnAll, hashString, htmlToText, isAlphanumeric, isArray, isObject, isObjectWith, isValidRedirectUrl, maskString, mimeTypes, normalizeString, objectToDottedPathValueObject, omit, padString, plural, prune, randomString, removeWhitespace, reverse, searchMapValues, singular, slugify, stringSimilarity, toCamelCase, toFirstCase, toFirstCaseBreak, toKebabCase, toLowerCase, toLowerCaseBreak, toNumber, toPascalCase, toProperTitleCase, toSentenceCase, toSnakeCase, toTitleCase, toUpperCase, toUpperCaseBreak, toVariableName, truncate, wordWrap };