JavaScript Common Utility Functions Library

A comprehensive collection of JavaScript util functions I regularly use in my projects. This library is modular, allowing you to import only what you need or the entire library.

Table of Contents

• Overview
• Usage
• Utilities List
  • Array Utilities
  • Object Utilities
  • String Utilities
  • Browser Utilities
  • Calendar Utilities
  • Color Utilities
  • Cookie Utilities
  • DOM Utilities
  • Math Utilities
  • Other Utilities
• Contributing
• Testing
• License

Usage

You can set the utils up in any of the following 3 ways:

1. Import Individual File via Tag or ES Module Import

Script Tag:

<script src="path/to/array.js"></script>
<script src="path/to/object.js"></script>

JavaScript (ES Module):

import { someArrayFunction } from './path/to/array.js';
import { someObjectFunction } from './path/to/object.js';

2. Import Single Minified File via Tag

You can also include the entire set of utilities in a single minified file using the following tag. All utility functions will be available globally in your project. You can find this file in the dist/ folder of this repo.

Script Tag:

<script src="path/to/utils.min.js"></script>

3. Install via NPM You can install the utilities as an npm package for easy integration into Node.js or browser-based JavaScript projects.

npm install @jozbiz-jp/common-js-utils

Then import the necessary functions into your project:

const { someArrayFunction, someObjectFunction } = require('@jozbiz-jp/common-js-utils');

In case of ES Module:

import { someArrayFunction, someObjectFunction } from '@jozbiz-jp/common-js-utils';

For example:

import { getOrdinalSuffix } from "@jozbiz-jp/common-js-utils";
getOrdinalSuffix(21) // 21st

Utilities List

Array Utilities

• uniqueArray(arr) Description: Removes duplicate elements from an array. Usage:

  const arr = [1, 2, 2, 3];
  const unique = uniqueArray(arr); // [1, 2, 3]

• flattenArray(arr) Description: Flattens a multi-dimensional array into a single-dimensional array. Usage:

  const nested = [1, [2, 3], [[4]]];
  const flat = flattenArray(nested); // [1, 2, 3, 4]

• arrayChunk(arr, size) Description: Splits an array into chunks of a specified size. Usage:

  const arr = [1, 2, 3, 4, 5];
  const chunked = arrayChunk(arr, 2); // [[1, 2], [3, 4], [5]]

• arrayIntersection(arr1, arr2) Description: Returns the intersection of two arrays. Usage:

  const arr1 = [1, 2, 3];
  const arr2 = [2, 3, 4];
  const intersection = arrayIntersection(arr1, arr2); // [2, 3]

• groupBy(array, key) Description: Groups an array of objects by a specified key. Usage:

  const arr = [{ age: 20 }, { age: 30 }];
  const grouped = groupBy(arr, 'age');  // { 20: [{ age: 20 }], 30: [{ age: 30 }] }

• getRandomItemFromArray(arr) Description: Returns a random item from an array. Usage:

  const arr = [1, 2, 3];
  const randomItem = getRandomItemFromArray(arr); // e.g., 2

• shuffleArray(arr) Description: Shuffles an array randomly. Usage:

  const arr = [1, 2, 3];
  const shuffled = shuffleArray(arr); // e.g., [3, 1, 2]

• difference(arr1, arr2) Description: Returns the elements in the first array that are not present in the second array. Usage:

  const arr1 = [1, 2, 3];
  const arr2 = [2, 3];
  const diff = difference(arr1, arr2); // [1]

• sum(arr) Description: Returns the sum of an array of numbers. Usage:

  const arr = [1, 2, 3];
  const total = sum(arr); // 6

• average(arr) Description: Returns the average of an array of numbers. Usage:

  const arr = [1, 2, 3];
  const avg = average(arr); // 2

• arrayToCSV(arr) Description: Converts a two-dimensional array into a CSV string. Usage:

  const arr = [['a', 'b'], ['c', 'd']];
  arrayToCSV(arr) // "a","b"\n"c","d"'

• csvToArray(csvString) Description: Parses a CSV string into a two-dimensional array. Usage:

  const csvString = '"a","b"\n"c","d"';
  csvToArray(csvString) // [['a', 'b'], ['c', 'd']];

• mergeArrays(arr1, arr2) Description: Merges two arrays, removing duplicates. Usage:

  const arr1 = [1, 2, 3];
  const arr2 = [2, 3, 4];
  mergeArrays(arr1, arr2)  // [1, 2, 3, 4];

• removeNulls(arr) Description: Removes all null values from an array. Usage:

  const arr = [1, null, 2, null, 3];
  removeNulls(arr) // [1, 2, 3];

• objectToArray(obj) Description: Converts an object into an array of key-value pairs. Usage:

  const obj = { a: 1, b: 2 };
  objectToArray(obj) // [['a', 1], ['b', 2]];

• findIndexBy(arr, fn) Description: Finds the index of an element in an array based on a predicate function. Usage:

  const arr = [1, 2, 3, 4];
  findIndexBy(arr, x => x === 3) // 2;
  findIndexBy(arr, x => x === 5) // -1;

• filterByType(arr, type) Description: Filters an array by a specific data type. Usage:

  const arr = [1, 'two', 3, true];
  filterByType(arr, 'number') // [1, 3];
  filterByType(arr, 'string') // ['two'];

String Utilities

• capitalize(str) Description: Capitalizes the first letter of a string. Usage:

  const result = capitalize('hello'); // 'Hello'

• truncateString(str, num) Description: Truncates a string to a specified length, adding an ellipsis if necessary. Usage:

  const result = truncateString('Hello world', 5); // 'Hello...'

• escapeHTML(str) Description: Escapes HTML special characters in a string. Usage:

  const escaped = escapeHTML('<div>Hello</div>'); // '&lt;div&gt;Hello&lt;/div&gt;'

• unescapeHTML(str) Description: Unescapes HTML special characters in a string. Usage:

  const unescaped = unescapeHTML('&lt;div&gt;Hello&lt;/div&gt;'); // '<div>Hello</div>'

• copyToClipboard(text) Description: Copies a string to the clipboard. Usage:

  copyToClipboard('Hello world'); // Copies 'Hello world' to the clipboard

• isEmailValid(email) Description: Validates an email address format. Usage:

  const valid = isEmailValid('[email protected]'); // true

• randomString(length) Description: Generates a random alphanumeric string of a specified length. Usage:

  const randomStr = randomString(8); // e.g., 'A1b2C3d4'

• isPalindrome(str) Description: Checks if a given string is a palindrome. Usage:

  const result = isPalindrome('madam'); // true

• isValidJSON(str) Description: Checks if a string is valid JSON. Usage:

  const valid = isValidJSON('{"name": "John"}'); // true

• getOrdinalSuffix(n) Description: Returns the ordinal suffix of a given number (e.g., 1st, 2nd, 3rd). Usage:

  const suffix = getOrdinalSuffix(1); // '1st'
  const suffix2 = getOrdinalSuffix(22); // '22nd'

• generateSlug(str) Description: Converts a string into a URL-friendly slug. Usage:

  const slug = generateSlug('Hello World!'); // 'hello-world'

• currencyFormatter(amount, currency = 'USD', locale = 'en-US') Description: Formats a number as a currency string. Usage:

  const formatted = currencyFormatter(1234.56); // '$1,234.56'
  const formatted2 = currencyFormatter(1234.56, 'EUR', 'de-DE'); // '1.234,56 €'

• toBoolean(val) Description: Converts various values to a boolean (e.g., "true", "1", etc. to true). Usage:

  const bool = toBoolean('true'); // true
  const bool2 = toBoolean('0'); // false

• toKebabCase(str) Description: Converts a string to kebab-case. Usage:

  const kebab = toKebabCase('Hello World'); // 'hello-world'

• toSnakeCase(str) Description: Converts a string to snake_case. Usage:

  const snake = toSnakeCase('Hello World'); // 'hello_world'

• toCamelCase(str) Description: Converts a string to camelCase. Usage:

  const camel = toCamelCase('hello world'); // 'helloWorld'

• capitalizeWords(str) Description: Capitalizes the first letter of each word in a string. Usage:

  const capitalized = capitalizeWords('hello world'); // 'Hello World'

• stripHTML(html) Description: Removes HTML tags from a string. Usage:

  const stripped = stripHTML('<div>Hello</div>'); // 'Hello'

• truncateMiddle(str, maxLength) Description: Truncates a string in the middle, keeping the start and end intact. Usage:

  const truncated = truncateMiddle('Hello World', 5); // 'He...ld'

• isBase64(str) Description: Checks if a string is a valid Base64 encoded string. Usage:

  const isValidBase64 = isBase64('SGVsbG8gd29ybGQ='); // true

• encodeBase64(str) Description: Encodes a string into Base64 format. Usage:

  const encoded = encodeBase64('Hello world'); // 'SGVsbG8gd29ybGQ='

• decodeBase64(str) Description: Decodes a Base64 encoded string. Usage:

  const decoded = decodeBase64('SGVsbG8gd29ybGQ='); // 'Hello world'

• pluralize(word, count) Description: Returns the plural form of a word based on a given count. Usage:

  const plural = pluralize('apple', 2); // 'apples'
  const singular = pluralize('apple', 1); // 'apple'

• stripWhitespace(str) Description: Removes all whitespace from a string. Usage:

  const stripped = stripWhitespace('  Hello   World  '); // 'HelloWorld'

• capitalizeFirstLetter(str) Description: Capitalizes the first letter of a string. Usage:

  const capitalized = capitalizeFirstLetter('hello'); // 'Hello'

• isEvenLength(str) Description: Checks if the length of a string is even. Usage:

  const isEven = isEvenLength('test'); // true
  const isOdd = isEvenLength('hello'); // false

• isOddLength(str) Description: Checks if the length of a string is odd. Usage:

  const isOdd = isOddLength('test'); // false
  const isOdd2 = isOddLength('hello'); // true

• reverseString(str) Description: Reverses the characters in a string. Usage:

  const reversed = reverseString('hello'); // 'olleh'

Object Utilities

• isObject(value) Description: Checks if a value is an object. Usage:

  const result = isObject({}); // true
  const result2 = isObject(null); // false

• deepClone(obj) Description: Creates a deep copy of an object or array to prevent unintended mutations. Usage:

  const obj = { a: 1, b: { c: 2 } };
  const cloned = deepClone(obj); // { a: 1, b: { c: 2 } }

• isEmptyObject(obj) Description: Checks if an object is empty. Usage:

  const obj = {};
  const isEmpty = isEmptyObject(obj); // true

• mergeObjects(...objects) Description: Deep merges two or more objects into one. Usage:

  const obj1 = { a: 1 };
  const obj2 = { b: 2 };
  const merged = mergeObjects(obj1, obj2); // { a: 1, b: 2 }

• isEqual(value1, value2) Description: Checks if two values are deeply equal. Usage:

  const obj1 = { a: 1 };
  const obj2 = { a: 1 };
  const equal = isEqual(obj1, obj2); // true

• deepFreeze(obj) Description: Recursively freezes an object, making it immutable. Usage:

  const obj = { a: 1, b: { c: 2 } };
  deepFreeze(obj); // Object is now immutable

• objectToQueryString(obj) Description: Converts an object to a query string. Usage:

  const obj = { name: 'John Doe', age: 30 };
  objectToQueryString(obj) // name=John%20Doe&age=30

• queryStringToObject(queryString) Description: Converts a query string to an object. Usage:

  const queryString = '?name=John%20Doe&age=30';
  queryStringToObject(queryString) // { name: 'John Doe', age: '30' }

• getNestedValue(obj, path, defaultValue) Description: Retrieves the value of a nested property in an object safely. Usage:

  const obj = { a: { b: 1 } };
  const value = getNestedValue(obj, 'a.b', 0); // 1

• arrayToObject(arr) Description: Converts an array of key-value pairs into an object. Usage:

  const arr = [['a', 1], ['b', 2]];
  arrayToObject(arr) // { a: 1, b: 2 };

• invertObject(obj) Description: Inverts the keys and values of an object. Usage:

  const obj = { a: 1, b: 2 };
  const inverted = invertObject(obj); // { 1: 'a', 2: 'b' }

• groupByKey(arr, key) Description: Groups an array of objects by a specific key. Usage:

  const arr = [{ group: 'A', val: 1 }, { group: 'B', val: 2 }, { group: 'A', val: 3 }];
  groupByKey(arr, 'group')
  // {
  //    A: [{ group: 'A', val: 1 }, { group: 'A', val: 3 }], B: [{ group: 'B', val: 2 }]
  // }

• differenceBy(arr1, arr2, fn) Description: Returns the difference between two arrays based on a provided function. Usage:

  const arr1 = [2.1, 1.2];
  const arr2 = [2.3, 3.4];
  const result = differenceBy(arr1, arr2, Math.floor); // [1.2]

• flattenObject(obj) Description: Flattens a nested object into a single level with dot-separated keys. Usage:

  const obj = { a: { b: 1 } };
  const flat = flattenObject(obj); // { 'a.b': 1 }

• unflattenObject(obj) Description: Unflattens a dot-separated object back into a nested object. Usage:

  const flat = { 'a.b': 1 };
  const nested = unflattenObject(flat); // { a: { b: 1 } }

• hasKey(obj, key) Description: Checks if an object has a specific key. Usage:

  const obj = { a: 1 };
  hasKey(obj, 'a') // true

• mapObject(obj, fn) Description: Applies a function to each key-value pair in an object. Usage:

  const obj = { a: 1, b: 2 };
  mapObject(obj, val => val * 2) // { a: 2, b: 4 }

• filterObject(obj, fn) Description: Filters an object by its keys or values using a predicate function. Usage:

  const obj = { a: 1, b: 2, c: 3 };
  filterObject(obj, val => val > 1) // { b: 2, c: 3 });

Browser Utilities

• detectLanguage() Description: Detects the user's browser language. Usage:

  const language = detectLanguage(); // 'en-US'

• isMobileDevice() Description: Detects if the user is on a mobile device. Usage:

  const isMobile = isMobileDevice(); // true or false

• isTouchDevice() Description: Checks if the device supports touch events. Usage:

  const isTouch = isTouchDevice(); // true or false

• isBrowser() Description: Checks if the code is running in a browser environment. Usage:

  const isInBrowser = isBrowser(); // true or false

• isNode() Description: Checks if the code is running in a Node.js environment. Usage:

  const isInNode = isNode(); // true or false

• getURLParams() Description: Retrieves all query parameters from the current URL as an object. Usage:

  const params = getURLParams(); // { name: 'John', age: '30' }

• getQueryParam(name) Description: Retrieves the value of a URL query parameter by its name. Usage:

  const param = getQueryParam('name'); // 'John'

Calendar Utilities

• isValidDate(dateString) Description: Checks if a date string is valid. Usage:

  const valid = isValidDate('2024-02-29'); // true
  const invalid = isValidDate('2024-02-30'); // false

• secondsToTime(seconds) Description: Converts seconds into a time string (HH:MM). Usage:

  const time = secondsToTime(3661); // '01:01:01'

• timeToSeconds(timeString) Description: Converts a time string (HH:MM) into seconds. Usage:

  const seconds = timeToSeconds('01:01:01'); // 3661

• getDaysBetweenDates(date1, date2) Description: Calculates the number of days between two dates. Usage:

  const days = getDaysBetweenDates(new Date('2023-01-01'), new Date('2023-01-10')); // 9

• isLeapYear(year) Description: Checks if a given year is a leap year. Usage:

  const result = isLeapYear(2024); // true

• getCurrentTimestamp() Description: Returns the current timestamp in milliseconds. Usage:

  const timestamp = getCurrentTimestamp(); // e.g., 1609459200000

Color Utilities

• isHexColor(hex) Description: Checks if a string is a valid hex color. Usage:

  const validHex = isHexColor('#ff5733'); // true
  const invalidHex = isHexColor('ff5733'); // false

• randomColor() Description: Generates a random hex color code. Usage:

  const color = randomColor(); // e.g., '#a1b2c3'

• hexToRGB(hex) Description: Converts a hex color code to an RGB string. Usage:

  const rgb = hexToRGB('#ff5733'); // 'rgb(255, 87, 51)'

• rgbToHex(r, g, b) Description: Converts an RGB value to a hex color code. Usage:

  const hex = rgbToHex(255, 87, 51); // '#FF5733'

• hexToHSL(hex) Description: Converts a hex color code to HSL format. Usage:

  const hsl = hexToHSL('#ff5733'); // [9, 100, 60]

• hexToHSB(hex) Description: Converts a hex color to HSB (Hue, Saturation, Brightness). Usage:

  const hsb = hexToHSB('#ff5733'); // [9, 80, 100]

• getContrastYIQ(hex) Description: Determines if a color is closer to white or black for contrast. Usage:

  const contrast = getContrastYIQ('#ff5733'); // 'black'

Cookie Utilities

• parseCookies() Description: Parses document cookies into an object. Usage:

  // Assuming document.cookie = "username=JohnDoe; sessionId=12345";
  const cookies = parseCookies(); 
  // { username: 'JohnDoe', sessionId: '12345' }

• setCookie(name, value, options = {}) Description: Sets a cookie with a specific name, value, and options (such as expires, path, etc.). Usage:

  // Set a cookie with a name, value, and options
  setCookie('username', 'JohnDoe', { expires: 'Fri, 31 Dec 9999 23:59:59 GMT', path: '/' });

• deleteCookie(name) Description: Deletes a cookie by setting its expiration date to the past. Usage:

  // Delete a cookie by its name
  deleteCookie('username');
  // Cookie 'username' is now deleted

DOM Utilities

• scrollToTop() Description: Smoothly scrolls the window to the top of the page. Usage:

  // Scrolls to the top of the page smoothly
  scrollToTop();

• scrollToElement(element) Description: Smoothly scrolls the window to a specific element. Usage:

  const element = document.querySelector('#section');
  // Scrolls to the specific element smoothly
  scrollToElement(element);

• hasClass(element, className) Description: Checks if an element has a specific CSS class. Usage:

  const element = document.querySelector('.my-element');
  const hasMyClass = hasClass(element, 'active'); // true or false

• addClass(element, className) Description: Adds a CSS class to an element. Usage:

  const element = document.querySelector('.my-element');
  // Adds the class 'active' to the element
  addClass(element, 'active');

• removeClass(element, className) Description: Removes a CSS class from an element. Usage:

  const element = document.querySelector('.my-element');
  // Removes the class 'active' from the element
  removeClass(element, 'active');

• toggleClass(element, className) Description: Toggles a class on a DOM element. Usage:

  const element = document.querySelector('.my-element');
  // Toggles the class 'active' on the element
  toggleClass(element, 'active');

• getScrollPosition() Description: Returns the current scroll position of the window. Usage:

  const scrollPos = getScrollPosition(); // { x: 0, y: 250 }

• setScrollPosition(x, y) Description: Sets the scroll position of the window to specific coordinates. Usage:

  // Scrolls the window to x: 0, y: 300
  setScrollPosition(0, 300);

• isInViewport(element) Description: Checks if an element is in the viewport. Usage:

  const element = document.querySelector('.my-element');
  const inViewport = isInViewport(element); // true or false

Math Utilities

• randomInt(min, max) Description: Generates a random integer between two values, inclusive. Usage:

  const random = randomInt(1, 10); // e.g., 7

• getRandomFloat(min, max) Description: Returns a random float between two values. Usage:

  const randomFloat = getRandomFloat(1.5, 5.5); // e.g., 3.47

• isPrime(num) Description: Checks if a number is prime. Usage:

  const result = isPrime(7); // true
  const result2 = isPrime(4); // false

• factorial(n) Description: Calculates the factorial of a number. Usage:

  const result = factorial(5); // 120

• clamp(num, min, max) Description: Clamps a number between a minimum and maximum value. Usage:

  const clamped = clamp(10, 1, 5); // 5

• roundToDecimalPlace(num, decimalPlaces) Description: Rounds a number to a specified number of decimal places. Usage:

  const rounded = roundToDecimalPlace(1.005, 2); // 1.01

• isEven(num) Description: Checks if a number is even. Usage:

  const even = isEven(4); // true

• isOdd(num) Description: Checks if a number is odd. Usage:

  const odd = isOdd(5); // true

Other Utilities

• debounce(func, wait) Description: Limits the rate at which a function is executed, particularly useful for events like scrolling or resizing. Usage:

  const debouncedFunction = debounce(() => console.log('Executed'), 300);
  window.addEventListener('scroll', debouncedFunction); // Logs only after scrolling stops for 300ms

• throttle(func, limit) Description: Ensures that a function is called at most once in a specified period, useful for rate-limiting events. Usage:

  const throttledFunction = throttle(() => console.log('Executed'), 1000);
  window.addEventListener('scroll', throttledFunction); // Executes function at most once every 1 second

• once(func) Description: Ensures a function can only be called once. Usage:

  const callOnce = once(() => console.log('This will run only once'));
  callOnce(); // Logs 'This will run only once'
  callOnce(); // No output

• memoize(func) Description: Caches the results of a function to improve performance. Usage:

  const slowFunction = (num) => {
      console.log('Calculating...');
      return num * 2;
  };
  const memoizedFunction = memoize(slowFunction);
  memoizedFunction(5); // Logs 'Calculating...' and returns 10
  memoizedFunction(5); // Returns 10 from cache without logging

• generateUUID() Description: Generates a random UUID (Universally Unique Identifier). Usage:

  const uuid = generateUUID(); // e.g., 'b7e7c8d6-933d-4f0e-9b5d-0d6abec13dbf'

• downloadFile(filename, content, mimeType = 'text/plain') Description: Creates a download link for a given file and triggers the download. Usage:

  const content = 'Hello, world!';
  downloadFile('hello.txt', content, 'text/plain'); // Triggers download of a file 'hello.txt' with the content 'Hello, world!'

• formatBytes(bytes, decimals = 2) Description: Formats a number of bytes as a human-readable string (e.g., KB, MB, GB). Usage:

  const formatted = formatBytes(1024); // '1.00 KB'
  const formattedLarge = formatBytes(1048576); // '1.00 MB'

Contributing

Contributions are welcome! Please see our Contributing Guidelines for more information.

Testing

Add tests for your changes in the tests directory using Jest, and confirm the test cases passing by:

npm test

Ensure that all tests pass before submitting your PR.

License

This project is licensed under the MIT License - see the LICENSE file for details.