@explita/utils

A lightweight and versatile collection of TypeScript utility functions and React hooks designed for everyday development needs. Streamline your Node.js, React, and Next.js projects with a powerful set of well-organized helpers for strings, arrays, dates, objects, and more.

Features

• String Manipulation: Comprehensive set of helpers for formatting, casing, and slugifying.
• Object Transformation: Deep merge, flatten, and unflatten objects with type safety.
• Date Utilities: Extensive helpers for formatting, shifting, and comparing dates.
• Array Utilities: Chunking, duplication finding, and shuffling.
• React Hooks: Premium hooks like useList, useLocalStorage (with cross-tab sync), and more.
• File Export: Save data as CSV, XML, or JSON directly from the browser.
• Type Safety: Built with TypeScript from the ground up.

Installation

# npm
npm install @explita/utils

# pnpm
pnpm add @explita/utils

# yarn
yarn add @explita/utils

📚 API Reference

🧵 String Utilities

import { ... } from "@explita/utils"

| Function | Description | Example | | :----------------- | :------------------------------------ | :------------------------------------------------- | | addOrdinal | Appends ordinal suffix to number. | addOrdinal(1) // "1st" | | buildQueryString | Builds query string from object. | buildQueryString({a:1}) // "a=1" | | capitalize | Capitalizes the first letter. | capitalize("hello") // "Hello" | | chunkSplit | Splits string with separator. | chunkSplit("123456", 3, "-") // "123-456" | | convertFileSize | Formats bytes to human-readable. | convertFileSize(1024) // "1.0 KB" | | formatCurrency | Formats number as currency. | formatCurrency(1000, "$") // "$1,000.00" | | greeting | Returns greeting based on time. | greeting("John") // "Good morning John" | | hexToRgb | Converts Hex color to RGB. | hexToRgb("#FF0000") // "rgb(255, 0, 0)" | | isEmpty | Checks if value is empty/null. | isEmpty("") // true | | isValidEmail | Validates email format. | isValidEmail("[email protected]") // true | | isValidPassword | Validates password strength. | isValidPassword("Pass123!") // true | | isValidPhone | Validates phone number. | isValidPhone("+1234567") // true | | nl2br | Replaces \n with <br>. | nl2br("hi\nthere") // "hi<br>there" | | parseQueryString | Parses URL query to object. | parseQueryString("?a=1") // {a: "1"} | | randomColor | Generates random color (hex/rgb/hsl). | randomColor("hex") | | rgbToHex | Converts RGB color to Hex. | rgbToHex(255, 0, 0) // "#FF0000" | | slugify | Creates a URL-friendly slug. | slugify("Hello World!") // "hello-world" | | toCamelCase | Converts string to camelCase. | toCamelCase("hello-world") // "helloWorld" | | toKebabCase | Converts string to kebab-case. | toKebabCase("Hello World") // "hello-world" | | toRomanNumeral | Converts number to Roman. | toRomanNumeral(4) // "IV" | | toSentenceCase | Converts string to Sentence case. | toSentenceCase("hello world") // "Hello world" | | toSnakeCase | Converts string to snake_case. | toSnakeCase("Hello World") // "hello_world" | | toTitleCase | Converts string to Title Case. | toTitleCase("hello_world") // "Hello World" | | truncateEmail | Hides parts of an email. | truncateEmail("[email protected]") // "jo***@doe.com" | | uniqueString | Generates a random string. | uniqueString(10) // "aB3dE5gH1j" |

📦 Object Utilities

import { ... } from "@explita/utils"

| Function | Description | Example | | :---------------- | :--------------------------------- | :----------------------------------------- | | deepMerge | Deeply merges two objects. | deepMerge({a:1}, {b:2}) // {a:1, b:2} | | flattenObject | Flattens a nested object. | flattenObject({a:{b:1}}) // {"a.b": 1} | | isObject | Checks if value is a plain object. | isObject({}) // true | | jsonify | Handles BigInts & Dates for JSON. | jsonify(objWithBigInt) | | omitFromObject | Removes specific keys. | omitFromObject(obj, ['password']) | | pickFromObject | Picks specific keys. | pickFromObject(obj, ['id', 'name']) | | prependKeys | Adds prefix to all object keys. | prependKeys({a:1}, "p_") // {p_a: 1} | | unflattenObject | Restores a flattened object. | unflattenObject({"a.b": 1}) // {a:{b:1}} |

📅 Date Utilities

import { ... } from "@explita/utils"

| Function | Description | Example | | :----------------- | :-------------------------------- | :------------------------------------- | | formatDate | Advanced date formatting. | formatDate(date, "YYYY-MM-DD") | | formatTime | Advanced time formatting. | formatTime(date, "hh:mm A") | | formatDateTime | Combined date & time format. | formatDateTime(date) | | timeAgo | Returns relative time string. | timeAgo(pastDate) // "2 hours ago" | | dayOfYear | Gets day number of the year. | dayOfYear(date) // 1-366 | | daysBetween | Calculates diff in days. | daysBetween(date1, date2) | | daysInMonth | Gets number of days in month. | daysInMonth(2024, 1) // 29 | | daysSince | Days elapsed since date. | daysSince(pastDate) | | daysUntil | Days remaining until date. | daysUntil(futureDate) | | endOfMonth | Returns last moment of month. | endOfMonth(date) | | extractDate | Gets YYYY-MM-DD string. | extractDate(date) | | extractDOB | Parses DOB from identifier. | extractDOB("ID_NUMBER") | | firstDayOfMonth | Returns first day of month Date. | firstDayOfMonth(date) | | getDayName | Gets full day name. | getDayName(date) // "Monday" | | getMonthName | Gets full month name. | getMonthName(date) // "January" | | isFuture | Checks if date is in future. | isFuture(date) | | isPast | Checks if date is in past. | isPast(date) | | isToday | Checks if date is today. | isToday(date) | | isValidDate | Robust valid date check. | isValidDate("2024-01-01") // true | | isWeekday | Checks if day is Mon-Fri. | isWeekday(date) | | isWeekend | Checks if day is Sat-Sun. | isWeekend(date) | | isWithinInterval | Checks if date is in range. | isWithinInterval(date, {start, end}) | | isYesterday | Checks if date was yesterday. | isYesterday(date) | | lastDayOfMonth | Returns last day of month Date. | lastDayOfMonth(date) | | normalizeDate | Sets time to 00:00:00. | normalizeDate(date) | | shiftDays | Adds/subtracts days. | shiftDays(date, 5) | | shiftMonths | Adds/subtracts months. | shiftMonths(date, 1) | | shiftYears | Adds/subtracts years. | shiftYears(date, 1) | | startOfDay | Returns first moment of day. | startOfDay(date) | | startOfMonth | Returns first moment of month. | startOfMonth(date) | | toDate | Robust conversion to Date object. | toDate("2024-01-01") | | weekOfYear | Gets week number of the year. | weekOfYear(date) |

🔢 Number Utilities

import { ... } from "@explita/utils"

| Function | Description | Example | | :----------- | :-------------------------- | :---------------------------- | | isNumeric | Robust numeric check. | isNumeric("123.45") // true | | percentage | Calculates percentage. | percentage(50, 200) // 25 | | random | Generates a random integer. | random(1, 100) |

🧪 Array Utilities

import { ... } from "@explita/utils"

| Function | Description | Example | | :--------------- | :------------------------- | :-------------------------------------- | | chunk | Splits array into sizes. | chunk([1,2,3,4], 2) // [[1,2], [3,4]] | | findDuplicates | Finds duplicates by key. | findDuplicates(data, 'email') | | flattenArray | Flattens a nested array. | flattenArray([[1], [2]]) // [1, 2] | | groupByKey | Groups objects by key. | groupByKey(users, 'role') | | shuffle | Randomizes array order. | shuffle([1, 2, 3]) | | unique | Removes duplicates. | unique([1, 2, 2, 3]) // [1, 2, 3] | | uniqueByKey | Removes duplicates by key. | uniqueByKey(data, 'id') |

⚡ Misc Utilities

import { ... } from "@explita/utils"

| Function | Description | Example | | :--------- | :------------------------------ | :---------------------------- | | debounce | Limits function execution rate. | debounce(fn, 500) | | delay | Promisified timeout. | await delay(1000) | | logger | Conditional console logging. | logger.info("data") | | retry | Retries a failing function. | await retry(fn, {times: 3}) | | throttle | Limits execution frequency. | throttle(fn, 500) | | tryCatch | Clean async error handling. | tryCatch(fetch(url)) |

📡 Axios Utilities

import { ... } from "@explita/utils/axios"

| Function | Description | Example | | :--------- | :------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | | tryAxios | Optimized tryCatch for Axios. Supports generic error schemas and includes kind, meta, and original error properties. | tryAxios<T, ErrorSchema>(api.get(url)) |

Error Properties:

• kind: Categorizes the error as "network", "logic", or "unknown".
• meta: Contains an error snapshot including name, message, and stack.
• original: The raw AxiosError for deep inspection.
• Dynamic Data: Automatically spreads the response body (e.g., message, errors) into the error object for direct access.

💾 File Utilities (Browser Only)

import { ... } from "@explita/utils/file"

| Function | Description | Example | | :--------------- | :-------------------- | :------------------------------- | | saveCSVToFile | Exports data as CSV. | saveCSVToFile(data, "users") | | saveJSONToFile | Exports data as JSON. | saveJSONToFile(data, "config") | | saveXMLToFile | Exports data as XML. | saveXMLToFile(data, "report") |

🛡️ Zod Validation

import { ... } from "@explita/utils/zod"

| Function | Description | Example | | :-------------------- | :-------------------------------------------------------------------------- | :---------------------------- | | validateForm | Validates FormData or objects using Zod schemas with clean error responses. | validateForm(data, schema) | | mapZodIssues | Converts Zod issues into a flat Record<string, string>. | mapZodIssues(error.issues) | | createDefaultValues | Generates initial values based on a Zod schema. | createDefaultValues(schema) | | isZodIssue | Type guard for Zod issues. | isZodIssue(error) |

⚛️ React Hooks

import { ... } from "@explita/utils/react"

| Hook | Description | | :---------------- | :------------------------------------------------------------------- | | stripTags | Utility to strip HTML tags from string or ReactNode. | | useDisclosure | Open/Close/Toggle management for modals and drawers. | | useList | Advanced state management for arrays (append, filter, remove, etc.). | | useLocalStorage | Persistent state with auto-serialization and cross-tab sync. | | useLocation | Geolocation manager with permission handling. | | useNetwork | Current online status and connection details (rtt, downlink). | | useWindowScroll | Reactive scroll positions and programmatic scroll helpers. | | useWindowSize | Responsive window dimensions and device type booleans. |

Example Usage:

import { useList, useLocalStorage } from "@explita/utils/react";

function App() {
  const [items, { append, remove }] = useList(["Task 1"]);
  const [theme, setTheme] = useLocalStorage("theme", "dark");

  return (
    <div className={theme}>
      <button onClick={() => append("New Task")}>Add</button>
      {items.map((it, i) => (
        <div onClick={() => remove(i)}>{it}</div>
      ))}
    </div>
  );
}

📄 License

MIT © Explita