Utilities

Harpia provides a robust set of built-in utilities designed to accelerate your development process. These utilities handle common operations related to strings, arrays, objects, dates, pagination, and terminal output styling.

You can import these utilities directly from the @harpiats/common package (or your corresponding alias).

The Utils Object

The Utils object is a centralized collection of singleton utility classes for manipulating primitive data types: strings, arrays, and objects.

import { Utils } from "@harpiats/common";

// Examples
const camelCased = Utils.string.camelCase("Hello World"); // "helloWorld"
const uniqueNumbers = Utils.array.uniq([1, 1, 2, 3]); // [1, 2, 3]
const isObjEmpty = Utils.object.isEmpty({}); // true

String Utilities (Utils.string)

Powered under the hood by Lodash and Inflection, the string utilities provide a wide range of text formatting and manipulation methods.

• pluralize(word): Converts a word to its plural form.
• singularize(word): Converts a word to its singular form.
• camelCase(str): Converts a string to camelCase.
• pascalCase(str): Converts a string to PascalCase.
• snakeCase(str): Converts a string to snake_case.
• kebabCase(str): Converts a string to kebab-case.
• capitalize(str): Capitalizes the first letter of a string.
• contains(str, substring): Checks if a string contains a substring.
• trim(str): Removes whitespace from both ends of a string.
• onlyNumbers(str): Removes all non-numeric characters from a string.
• onlyLetters(str): Removes all non-letter characters (preserves spaces).
• toSlug(str): Converts string to URL-friendly slug format.
• truncate(str, maxLength): Truncates a string with ellipsis if it exceeds max length.
• alphanumeric(str): Removes special characters (keeps alphanumeric + spaces).
• stripTags(str): Removes HTML/XML tags from a string.

Array Utilities (Utils.array)

A collection of array manipulation helpers.

• sortBy(array, key): Sorts an array of objects by a specific property key.
• filter(array, predicate): Filters an array based on a predicate function.
• compact(array): Removes falsy values (false, null, 0, "", undefined, NaN) from an array.
• uniq(array): Returns unique values from an array.
• difference(array1, array2): Returns the difference between two arrays.

Object Utilities (Utils.object)

Essential helpers for manipulating and transforming objects.

• merge(...objects): Deeply merges two or more objects.
• pick(obj, keys): Picks specific properties from an object.
• omit(obj, keys): Omits specific properties from an object.
• omitFromList(list, keys): Omits specific properties from each object in an array.
• isEmpty(obj): Checks if an object is empty.

DateUtility

The DateUtility class provides a robust API for parsing, formatting, and manipulating dates, supporting a Moment.js-like formatting token syntax.

import { DateUtility } from "@harpiats/common";

const date = new DateUtility("2026-04-23");

console.log(date.format("YYYY-MM-DD")); // "2026-04-23"
console.log(date.add(1, "month").format("YYYY-MM-DD")); // "2026-05-23"

Key Features:

• Parsing: Supports Date objects, timestamps (numbers), and common string formats (e.g., YYYY-MM-DD).
• Formatting: format(formatStr) and formatUTC(formatStr) using tokens like YYYY, MM, DD, HH, mm, ss, etc.
• Manipulation: add(amount, unit) and subtract(amount, unit) for dynamic date math.
• Comparison: isBefore(), isAfter(), isSame(), and difference().
• Boundaries: startOf(unit) and endOf(unit) (e.g., to get the start of the current day).
• Localization: Built-in support for localized month (getMonthName()) and day (getDayName()) names.

Pagination (paginate)

The paginate function standardizes the structure of paginated API responses, automatically calculating metadata such as lastPage and totalPages.

import { paginate } from "@harpiats/common";

const results = [/* ... data array ... */];

const response = paginate({
  data: results,
  page: 1,
  perPage: 10,
  totalData: 100,
});

/*
Returns:
{
  data: [...],
  meta: {
    currentPage: 1,
    lastPage: 10,
    perPage: 10,
    totalPages: 10,
    totalItems: 100
  }
}
*/

Colorize Output (colorize)

For CLI tool builders or custom loggers, Harpia exposes a simple wrapper over Bun’s native ANSI color formatting.

import { colorize } from "@harpiats/common";

console.log(colorize("green", "Task completed successfully!"));

This ensures your console output can be easily styled natively.