@pelatform/utils

A comprehensive library of utility functions for building modern SaaS applications. This package provides type-safe utilities for string manipulation, date/time formatting, cryptography, validation, URL handling, and more.

Installation

npm install @pelatform/utils
# or
bun add @pelatform/utils

Quick Start

import {
  cn,
  formatDate,
  validateEmail,
  nanoid,
  truncate,
} from "@pelatform/utils";

// Tailwind-aware class merging
const className = cn("px-4 py-2", isActive && "bg-blue-500");

// Date formatting
const formatted = formatDate(new Date()); // "November 26, 2025"

// Email validation
const result = validateEmail("[email protected]");
if (result.isValid) {
  console.log(result.normalized); // Normalized email
}

// Generate unique IDs
const id = nanoid(); // "a1B2c3D" (7 chars by default)

// Smart text truncation
const short = truncate("Long text here...", 20); // "Long text here..."

Key Features

• Type-Safe: Full TypeScript support with comprehensive types
• Tree-Shakeable: Import only what you need
• Zero Dependencies: Most utilities have no external dependencies
• Client & Server: Works in both browser and Node.js environments
• Well-Tested: Comprehensive test coverage
• ESM-Only: Modern ES modules format

Available Utilities

String Manipulation

import {
  cn, // Tailwind-aware class merging
  capitalize, // Capitalize strings
  camelCase, // Convert to camelCase
  slugify, // Create URL-friendly slugs
  truncate, // Truncate text
  smartTruncate, // Smart truncation (word-aware)
  pluralize, // Pluralize words
  getInitials, // Extract initials from names
} from "@pelatform/utils";

// Examples
cn("text-sm", isActive && "font-bold"); // "text-sm font-bold"
capitalize("hello world"); // "Hello world"
slugify("Hello World!"); // "hello-world"
getInitials("John Doe"); // "JD"

Date & Time

import {
  formatDate,
  formatDateTime,
  formatTime,
  timeAgo,
  getDatetimeLocal,
} from "@pelatform/utils";

// Examples
formatDate(new Date()); // "November 26, 2025"
formatDateTime(new Date()); // "Nov 26, 2025, 3:45 PM"
timeAgo(new Date(Date.now() - 3600000)); // "1 hour ago"

Email Validation

import {
  validateEmail,
  normalizeEmail,
  isDisposableEmail,
  isBusinessEmail,
  getEmailDomain,
} from "@pelatform/utils";

// Comprehensive validation
const result = validateEmail("[email protected]", {
  allowDisposable: false,
});
// result.isValid, result.normalized, result.details

// Check disposable emails
isDisposableEmail("[email protected]"); // true

// Check business emails
isBusinessEmail("[email protected]"); // true

Cryptography & IDs

import { nanoid, uid, cuid, hashString } from "@pelatform/utils";

// Generate IDs
nanoid(); // "a1B2c3D" (7 chars, customizable)
nanoid(12); // "a1B2c3De5F6g" (12 chars)
uid(); // "1732632000123" (timestamp-based)
cuid(); // "clj5...abc" (collision-resistant)

// Hash strings
hashString("secret"); // "5en6G6MezRroT3..."

URL Utilities

import {
  constructMetadata,
  getUrlFromString,
  isValidUrl,
  getDomainWithoutWWW,
} from "@pelatform/utils";

// Build metadata for SEO
const metadata = constructMetadata({
  title: "My Page",
  description: "Page description",
  image: "/og-image.png",
});

// URL validation
isValidUrl("https://example.com"); // true
getDomainWithoutWWW("www.example.com"); // "example.com"

File Utilities

import { formatFileSize } from "@pelatform/utils";

formatFileSize(1024); // "1 KB"
formatFileSize(1048576); // "1 MB"
formatFileSize(1073741824); // "1 GB"

Number Formatting

import { nformatter, currencyFormatter } from "@pelatform/utils";

nformatter(1234); // "1.2K"
nformatter(1234567); // "1.2M"
currencyFormatter(1234.56); // "$1,234.56"

Array Utilities

import { chunk, randomValue, stableSort } from "@pelatform/utils";

// Split array into chunks
chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]

// Get random element
randomValue([1, 2, 3, 4]); // Random element

// Stable sorting
stableSort(array, (a, b) => a.name.localeCompare(b.name));

Validation

import { deepEqual, keys, isIframeable } from "@pelatform/utils";

// Deep object comparison
deepEqual(obj1, obj2); // true/false

// Type-safe object keys
const myKeys = keys({ a: 1, b: 2 }); // ('a' | 'b')[]

// Check if URL can be embedded
isIframeable("https://example.com"); // true/false

Browser Utilities (Client-side only)

import { storage, cookies, getHeight, resizeImage } from "@pelatform/utils";

// localStorage wrapper
storage.set("key", { value: "data" });
const data = storage.get("key");

// Cookie management
cookies.set("name", "value", { maxAge: 3600 });
const value = cookies.get("name");

// DOM utilities
const height = getHeight(element);
const resized = await resizeImage(file, { width: 800, height: 600 });

Configuration

Client vs Server

Most utilities work in both environments. For server-only utilities:

// Server-only exports (Node.js/Bun)
import { ... } from '@pelatform/utils/server';

API Categories

• String: Text manipulation, formatting, slugification
• Date/Time: Date formatting, time ago, period calculations
• Crypto: ID generation, hashing, random strings
• Email: Validation, normalization, disposable detection
• URL: URL parsing, validation, metadata construction
• File: File size formatting, type detection
• Array: Chunking, sorting, random selection
• Validation: Email, URL, deep equality checks
• Browser: Storage, cookies, DOM utilities (client-only)
• Number: Formatting, currency, abbreviations

Runtime Compatibility

| Export | Node.js | Bun | CF Workers | Deno | Browser | | ------------------- | -------- | -------- | ---------- | -------- | --------- | | . (main) | Yes | Yes | Yes | Yes | Yes | | ./server | Yes | Yes | No | Yes | No | | Browser functions* | SSR-safe | SSR-safe | SSR-safe | SSR-safe | Yes | | Constants (env) | Filled | Filled | Undefined | Filled | Undefined |

* getHeight, resizeImage, resizeAndCropImage, loadImage, fileToBase64 — all have runtime guards, return 0 or throw descriptive errors when called outside browser.

Entry Points

• @pelatform/utils — Safe everywhere. Constants use runtime-guarded process.env access (returns undefined when process is unavailable). Browser-only functions have SSR guards.
• @pelatform/utils/server — Node.js / Bun / Deno only. Contains generateRandomString (node:crypto), JWT utilities (jsonwebtoken), password hashing (bcryptjs), and parseDatetime (chrono-node).

Links

• npm Package
• Contributing Guide
• Code of Conduct
• License

License

MIT © Pelatform Inc.