A zero-dependency TypeScript utility library covering the common ground every project needs — dates, strings, objects, geography, files, and more. Modular by design, so you only import what you use.

Documentation · GitHub · Issues

Installation

npm install @akadenia/helpers

Usage

import { DateHelpers, TextHelpers, ObjectHelpers, MapHelpers, GenericHelpers, FileHelpers } from '@akadenia/helpers'

Table of Contents

• DateHelpers
• TextHelpers
• ObjectHelpers
• MapHelpers
• GenericHelpers
• FileHelpers
• Contributing

DateHelpers

getReadableDateTime(datetime?)

Returns the date in yyyy-mm-dd hh:mm:ss format.

Parameters:

• datetime (optional): Date — The date to convert. Defaults to current date.

Example:

import { DateHelpers } from '@akadenia/helpers'

DateHelpers.getReadableDateTime()
// "2026-02-27 15:30:25"

DateHelpers.getReadableDateTime(new Date('2024-01-15T10:30:00Z'))
// "2024-01-15 10:30:00"

getReadableDate(datetime?)

Returns the date in yyyy-mm-dd format.

Parameters:

• datetime (optional): Date — The date to convert. Defaults to current date.

Example:

DateHelpers.getReadableDate()
// "2026-02-27"

DateHelpers.getReadableDate(new Date('2024-01-15T10:30:00Z'))
// "2024-01-15"

getDateString(date)

Returns a locale-formatted date string.

Parameters:

• date: string | Date — The date to convert.

Example:

DateHelpers.getDateString('2024-01-15')
// "1/15/2024" (locale-dependent)

formatDateTime(date, options, localTimezone?)

Returns a formatted date string using Intl.DateTimeFormat options.

Parameters:

• date: string | Date — The date to format.
• options: Intl.DateTimeFormatOptions — Formatting options.
• localTimezone (optional): string | Intl.Locale — Locale. Defaults to "en-US".

Example:

DateHelpers.formatDateTime(
  new Date('2024-01-15T10:30:00Z'),
  { year: 'numeric', month: 'long', day: 'numeric', hour: '2-digit', minute: '2-digit' },
  'en-US'
)
// "January 15, 2024 at 10:30 AM"

parseDate(date)

Parses a string or Date into a Date object. Throws on invalid input.

Parameters:

• date: string | Date — The date to parse.

Example:

DateHelpers.parseDate('2024-01-15')
// Date object

DateHelpers.parseDate('invalid-date')
// throws Error: Cannot parse date: "invalid-date"

getShortOrdinalDate(date, appendTime?)

Returns a date in short ordinal format, e.g. "Feb 27th 2026".

Parameters:

• date: string | Date — The date to format.
• appendTime (optional): boolean — Whether to include time. Defaults to false.

Example:

DateHelpers.getShortOrdinalDate('2024-01-15')
// "Jan 15th 2024"

DateHelpers.getShortOrdinalDate('2024-01-15T10:30:00Z', true)
// "Jan 15th 2024 10:30:00"

TextHelpers

uuidv4()

Generates a random UUID v4 string.

Example:

TextHelpers.uuidv4()
// "f47ac10b-58cc-4372-a567-0e02b2c3d479"

formatPosition(position)

Returns a position number with the appropriate ordinal suffix.

Parameters:

• position: number — The position.

Example:

TextHelpers.formatPosition(1)  // "1st"
TextHelpers.formatPosition(2)  // "2nd"
TextHelpers.formatPosition(3)  // "3rd"
TextHelpers.formatPosition(4)  // "4th"
TextHelpers.formatPosition(21) // "21st"

truncateText(text, characterLimit)

Truncates text to the character limit, appending "...".

Parameters:

• text: string — Text to truncate.
• characterLimit: number — Maximum number of characters.

Example:

TextHelpers.truncateText("Hello World", 5)  // "He..."
TextHelpers.truncateText("Hello World", 20) // "Hello World"

fileNameFromPath(path)

Extracts the filename from a file path.

Parameters:

• path: string — The file path.

Example:

TextHelpers.fileNameFromPath('/uploads/documents/file.pdf') // "file.pdf"

replaceSpacesWithUnderscore(s?)

Replaces spaces with underscores.

Example:

TextHelpers.replaceSpacesWithUnderscore("hello world") // "hello_world"

replaceUnderscoreWithSpaces(s?)

Replaces underscores with spaces.

Example:

TextHelpers.replaceUnderscoreWithSpaces("hello_world") // "hello world"

pluralizeOnCondition(word, condition)

Pluralizes a word when the condition is true. Handles common English rules (-y → -ies, -s/-sh/-ch/-x → -es).

Parameters:

• word: string — The word to pluralize.
• condition: boolean — Whether to pluralize.

Example:

TextHelpers.pluralizeOnCondition("item", true)    // "items"
TextHelpers.pluralizeOnCondition("address", true) // "addresses"
TextHelpers.pluralizeOnCondition("library", true) // "libraries"
TextHelpers.pluralizeOnCondition("item", false)   // "item"

convertSnakeToCamelCase(data)

Converts snake_case to camelCase for strings, objects, or arrays of objects (deep).

Example:

TextHelpers.convertSnakeToCamelCase("hello_world")
// "helloWorld"

TextHelpers.convertSnakeToCamelCase({ first_name: "John", user_info: { phone_number: "123" } })
// { firstName: "John", userInfo: { phoneNumber: "123" } }

convertCamelToSnakeCase(data)

Converts camelCase to snake_case for strings, objects, or arrays of objects (deep).

Example:

TextHelpers.convertCamelToSnakeCase("helloWorld")
// "hello_world"

TextHelpers.convertCamelToSnakeCase({ firstName: "John", userInfo: { phoneNumber: "123" } })
// { first_name: "John", user_info: { phone_number: "123" } }

convertCamelToKebabCase(word)

Converts camelCase to kebab-case.

Example:

TextHelpers.convertCamelToKebabCase("helloWorld")     // "hello-world"
TextHelpers.convertCamelToKebabCase("XMLHttpRequest") // "xml-http-request"

convertKebabToCamelCase(word)

Converts kebab-case to CamelCase.

Example:

TextHelpers.convertKebabToCamelCase("hello-world")     // "HelloWorld"
TextHelpers.convertKebabToCamelCase("xml-http-request") // "XmlHttpRequest"

convertCamelCaseToReadableText(name)

Converts camelCase to a space-separated readable string.

Example:

TextHelpers.convertCamelCaseToReadableText("helloWorld")     // "Hello World"
TextHelpers.convertCamelCaseToReadableText("XMLHttpRequest") // "XML Http Request"

generateAcronym(term)

Generates an acronym from the first letter of each word.

Example:

TextHelpers.generateAcronym("Hyper Text Markup Language") // "HTML"
TextHelpers.generateAcronym("Application Programming Interface") // "API"

isAcronym(word)

Returns true if the word is all uppercase (i.e. an acronym).

Example:

TextHelpers.isAcronym("HTML")       // true
TextHelpers.isAcronym("JavaScript") // false

acronymToKebabCase(word)

Converts an acronym to kebab-case. Throws if input is not an acronym.

Example:

TextHelpers.acronymToKebabCase("HTML") // "h-t-m-l"
TextHelpers.acronymToKebabCase("API")  // "a-p-i"
TextHelpers.acronymToKebabCase("html") // throws Error

handleNullDisplay(value, defaultValue?)

Returns the value, or a default string if null or undefined.

Parameters:

• value: string | null | undefined
• defaultValue (optional): string — Defaults to "N/A".

Example:

TextHelpers.handleNullDisplay("Hello")       // "Hello"
TextHelpers.handleNullDisplay(null)          // "N/A"
TextHelpers.handleNullDisplay(null, "—")     // "—"

capitalizeText(text?)

Capitalizes the first letter, lowercases the rest.

Example:

TextHelpers.capitalizeText("hello world") // "Hello world"
TextHelpers.capitalizeText("HELLO")       // "Hello"
TextHelpers.capitalizeText()              // ""

enforceCharacterLimit({ text, characterLimit, onCharacterLimit })

Truncates text to the limit and calls a callback when the limit is hit.

Example:

TextHelpers.enforceCharacterLimit({
  text: "This is a long text",
  characterLimit: 10,
  onCharacterLimit: () => console.log("Limit hit!"),
})
// "This is a" (and logs "Limit hit!")

isValidEmail(email)

Validates an email address against RFC-compliant rules.

Example:

TextHelpers.isValidEmail("[email protected]")    // true
TextHelpers.isValidEmail("[email protected]")   // true
TextHelpers.isValidEmail("invalid-email")        // false
TextHelpers.isValidEmail("")                     // false

generateIDFromWord(text)

Converts a phrase to a lowercase hyphenated ID.

Example:

TextHelpers.generateIDFromWord("My Awesome Feature") // "my-awesome-feature"

generateWordFromId(id, customList?)

Converts a hyphenated ID back to a readable title. Supports a custom lookup map.

Example:

TextHelpers.generateWordFromId("hello-world-test")
// "Hello World Test"

TextHelpers.generateWordFromId("api", { api: "Application Programming Interface" })
// "Application Programming Interface"

generateSlugFromWordsWithID(id, ...words)

Generates a URL-safe slug combining words and an ID.

Example:

TextHelpers.generateSlugFromWordsWithID("123", "Blog Post", "Tech")
// "blog-post-tech-123"

extractIDfromSlug(slug)

Extracts the last segment of a hyphenated slug (the ID).

Example:

TextHelpers.extractIDfromSlug("my-blog-post-42") // "42"
TextHelpers.extractIDfromSlug("")               // throws Error

abbreviateNumber(number)

Abbreviates large numbers with K / M / B suffixes.

Example:

TextHelpers.abbreviateNumber(500)         // "500"
TextHelpers.abbreviateNumber(1500)        // "1.5K"
TextHelpers.abbreviateNumber(1500000)     // "1.5M"
TextHelpers.abbreviateNumber(1500000000)  // "1.5B"
TextHelpers.abbreviateNumber(null)        // null

ObjectHelpers

isPureObject(object)

Returns true if the value is a plain object (not an array, Date, or function).

Example:

ObjectHelpers.isPureObject({})          // true
ObjectHelpers.isPureObject([])          // false
ObjectHelpers.isPureObject(new Date())  // false
ObjectHelpers.isPureObject(() => {})    // false

parseCookie(str)

Parses a Cookie header string into a key-value object.

Example:

ObjectHelpers.parseCookie("name=John; age=30; city=New York")
// { name: "John", age: "30", city: "New York" }

filterObjectsByProperty(array, propertyName, propertyValue)

Filters an array of objects by a specific property value.

Example:

const users = [
  { id: 1, name: "John", role: "admin" },
  { id: 2, name: "Jane", role: "user" },
  { id: 3, name: "Bob",  role: "admin" },
]

ObjectHelpers.filterObjectsByProperty(users, "role", "admin")
// [{ id: 1, ... }, { id: 3, ... }]

containsSubObject(mainObject, subObject)

Returns true if the main object contains all the key-value pairs of the sub-object.

Example:

const user = { id: 1, name: "John", age: 30, city: "New York" }

ObjectHelpers.containsSubObject(user, { name: "John", age: 30 }) // true
ObjectHelpers.containsSubObject(user, { name: "Jane" })          // false

findObjectBySubObject(array, subObject)

Finds the first object in an array containing the specified sub-object. Returns null if not found.

Example:

const users = [
  { id: 1, name: "John", city: "New York" },
  { id: 2, name: "Jane", city: "Boston" },
]

ObjectHelpers.findObjectBySubObject(users, { city: "Boston" })
// { id: 2, name: "Jane", city: "Boston" }

ObjectHelpers.findObjectBySubObject(users, { name: "Alice" })
// null

filterObjectsBySubObject(array, subObject)

Filters an array of objects to those containing the specified sub-object.

Example:

const users = [
  { id: 1, name: "John", age: 30 },
  { id: 2, name: "Jane", age: 25 },
  { id: 3, name: "Bob",  age: 30 },
]

ObjectHelpers.filterObjectsBySubObject(users, { age: 30 })
// [{ id: 1, ... }, { id: 3, ... }]

objectPropHasValue({ object, propName, value })

Checks if a specific property on an object equals a given value.

Example:

const user = { id: 1, name: "John", age: 30 }

ObjectHelpers.objectPropHasValue({ object: user, propName: "name", value: "John" }) // true
ObjectHelpers.objectPropHasValue({ object: user, propName: "age",  value: 25 })     // false

findEntry(array, predicate)

Returns the first array entry satisfying the predicate, or null.

Example:

ObjectHelpers.findEntry([1, 2, 3, 4], (n) => n % 2 === 0) // 2
ObjectHelpers.findEntry([1, 2, 3],    (n) => n > 10)       // null

convertArrayToMap(arrayData, keyProp)

Converts an array of objects into a keyed map using a specified property.

Example:

const users = [
  { id: 1, name: "John" },
  { id: 2, name: "Jane" },
]

ObjectHelpers.convertArrayToMap(users, "id")
// { "1": { id: 1, name: "John" }, "2": { id: 2, name: "Jane" } }

convertObjectKeysToKebabCase(obj)

Converts all camelCase keys of an object to kebab-case. Returns undefined for undefined input.

Example:

ObjectHelpers.convertObjectKeysToKebabCase({ firstName: "John", lastName: "Doe" })
// { "first-name": "John", "last-name": "Doe" }

ObjectHelpers.convertObjectKeysToKebabCase(undefined)
// undefined

MapHelpers

getDistanceBetweenPoints(point1, point2)

Calculates the distance between two [lat, lng] points using the Haversine formula. Returns metres, or null for undefined input.

Example:

// New York → Los Angeles
MapHelpers.getDistanceBetweenPoints([40.7128, -74.006], [34.0522, -118.2437])
// ~3,944,419 metres (~3,944 km)

MapHelpers.getDistanceBetweenPoints([40.7128, -74.006], undefined)
// null

compareLocations(location1, location2, precision?)

Compares two [lat, lng] coordinates within a decimal precision. Throws if either is undefined.

Parameters:

• precision (optional): number — Decimal places. Defaults to 6.

Example:

MapHelpers.compareLocations([51.5074, -0.1278], [51.5074, -0.1278])       // true
MapHelpers.compareLocations([51.5074, -0.1278], [51.5074001, -0.127801])  // true  (within 6 decimals)
MapHelpers.compareLocations([51.5074, -0.1278], [51.51,      -0.13], 2)   // false

getBearingToCoordinate({ startCoordinate, endCoordinate })

Returns the compass bearing (0–360°) from start to end coordinate. Throws if either is undefined.

Example:

// New York → Los Angeles
MapHelpers.getBearingToCoordinate({
  startCoordinate: [40.7128, -74.006],
  endCoordinate:   [34.0522, -118.2437],
})
// ~277.5 (roughly west)

GenericHelpers

delay(ms)

Async sleep for the specified number of milliseconds.

Example:

await GenericHelpers.delay(1000) // wait 1 second

getPreferredUriScheme(host)

Returns "http" for local/private hosts, "https" for everything else.

Example:

GenericHelpers.getPreferredUriScheme("api.example.com") // "https"
GenericHelpers.getPreferredUriScheme("localhost")        // "http"
GenericHelpers.getPreferredUriScheme("192.168.1.1")      // "http"
GenericHelpers.getPreferredUriScheme("10.0.0.1")         // "http"

FileHelpers

checkFileExtension(filePath, validExtensions)

Returns true if the file has one of the allowed extensions.

Example:

FileHelpers.checkFileExtension("report.pdf",  ["pdf", "docx"]) // true
FileHelpers.checkFileExtension("data.geojson", ["geojson"])    // true
FileHelpers.checkFileExtension("photo.txt",   ["jpg", "png"])  // false

formatFileSize(bytes)

Formats a byte count into a human-readable size string.

Example:

FileHelpers.formatFileSize(512)              // "512 B"
FileHelpers.formatFileSize(1024)             // "1.0 KB"
FileHelpers.formatFileSize(1024 * 1024 * 2) // "2.0 MB"
FileHelpers.formatFileSize(0)               // "0 B"
FileHelpers.formatFileSize(null)            // "0 B"

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

Development Setup

git clone https://github.com/akadenia/AkadeniaHelpers.git
cd AkadeniaHelpers
pnpm install
pnpm run build
pnpm test

Commit Message Guidelines

We follow Conventional Commits. Scope is required.

type(scope): description

Common scopes: date · text · object · map · generic · file · docs · deps · test · build · ci

Types: feat · fix · docs · style · refactor · test · chore

Requirements

• Node.js >= 20
• Zero runtime dependencies

License

MIT