@pol-studios/utils

Utility functions for POL applications

The foundation package for the POL-One monorepo. Provides common utility functions for string manipulation, array operations, object handling, date parsing, async patterns, formatting, and more. This package has no internal dependencies and serves as the base for other @pol-studios/* packages.

Installation

pnpm add @pol-studios/utils

Peer Dependencies

pnpm add moment

Quick Start

import { cn, camelize, groupBy, formatCurrency } from "@pol-studios/utils";

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

// String transformation
const camelCase = camelize("hello-world"); // "helloWorld"

// Array grouping
const grouped = groupBy(items, (item) => item.category);

// Currency formatting
const price = formatCurrency(1234.56); // "$1,234.56"

Subpath Exports

| Path | Description | |------|-------------| | @pol-studios/utils | All exports combined | | @pol-studios/utils/string | String manipulation utilities | | @pol-studios/utils/array | Array operations and transformations | | @pol-studios/utils/object | Object manipulation utilities | | @pol-studios/utils/date | Date parsing, comparison, and manipulation | | @pol-studios/utils/async | Async utilities (delay, debounce, semaphore) | | @pol-studios/utils/format | Currency and decimal formatting | | @pol-studios/utils/tailwind | Tailwind CSS class utilities | | @pol-studios/utils/cache | Function result caching | | @pol-studios/utils/types | TypeScript type utilities | | @pol-studios/utils/color | Color manipulation utilities | | @pol-studios/utils/validation | Input validation and password utilities | | @pol-studios/utils/error | Error handling utilities | | @pol-studios/utils/device | Device detection utilities | | @pol-studios/utils/uuid | UUID generation utilities | | @pol-studios/utils/state | State management utilities | | @pol-studios/utils/enum | Enum handling utilities | | @pol-studios/utils/dev | Development utilities |

API Reference

String Utilities

import { camelize, pascalize, slugify, sanitizeInput, isBlank } from "@pol-studios/utils/string";

camelize("hello-world");           // "helloWorld"
pascalize("hello-world");          // "HelloWorld"
pascalizeWithSpaces("hello_world"); // "Hello World"
slugify("Hello World");            // "hello-world"
generateSlug("My Title");          // "my-title"
sanitizeInput("<script>alert()</script>"); // Sanitized string
isBlank("");                       // true
isNullOrWhitespace("  ");          // true

Array Utilities

import { sortBy, groupBy, chunk, unique, range, tryGetSum, tryGetAverage } from "@pol-studios/utils/array";

sortBy(items, "name");                    // Sort by property
groupBy(items, (i) => i.category);        // Group by function
groupByMultipleCriteria(items, ["a", "b"]); // Multi-level grouping
chunk([1, 2, 3, 4, 5], 2);                // [[1, 2], [3, 4], [5]]
unique([1, 2, 2, 3]);                     // [1, 2, 3]
mapUnique(items, "id");                   // Unique by property
range(1, 5);                              // [1, 2, 3, 4, 5]
tryGetSum(items, "amount");               // Sum of property values
tryGetAverage(items, "score");            // Average of property values
selectByMin(items, "price");              // Item with minimum value
convertArrayToObject(items, "id");        // Convert to keyed object

Object Utilities

import { omit, pick, diff, getPath, setPath, deepEquals } from "@pol-studios/utils/object";

omit(obj, ["password", "secret"]);  // Remove properties
pick(obj, ["name", "email"]);       // Keep only specified properties
includeOnly(obj, ["a", "b"]);       // Alias for pick
diff(objA, objB);                   // Get differences between objects
getPath(obj, "user.address.city");  // Deep property access
getValueByPath(obj, "a.b.c");       // Alias for getPath
setPath(obj, "user.name", "John");  // Deep property setting
setValueByPath(obj, "a.b", value);  // Alias for setPath
deepEquals(objA, objB);             // Deep equality comparison
isDeepEqual(objA, objB);            // Alias for deepEquals

Date Utilities

import { parseDate, compareDates, addDays, toUTC } from "@pol-studios/utils/date";

// Parsing, comparison, addition, and UTC conversion utilities
// Requires moment as a peer dependency

Async Utilities

import { delay, debounce, runConcurrent, Semaphore } from "@pol-studios/utils/async";

await delay(1000);                          // Wait 1 second
const debouncedFn = debounce(fn, 300);      // Debounce function calls
await runConcurrent(tasks, 5);              // Run with concurrency limit
const semaphore = new Semaphore(3);         // Limit concurrent operations

Format Utilities

import { formatCurrency, formatDecimal } from "@pol-studios/utils/format";

formatCurrency(1234.56);     // "$1,234.56"
formatDecimal(0.1234, 2);    // "0.12"

Tailwind Utilities

import { cn } from "@pol-studios/utils/tailwind";

// Merge Tailwind classes with conflict resolution (clsx + tailwind-merge)
cn("px-4 py-2", isActive && "bg-blue-500", "px-8"); // "py-2 bg-blue-500 px-8"

Cache Utilities

import { cacheFunction, clearCache, clearAllCache } from "@pol-studios/utils/cache";

// Cache async function results
const data = await cacheFunction("key", fetchData, 60000); // Cache for 1 minute
clearCache("key");    // Clear specific cache
clearAllCache();      // Clear all cached data

Color Utilities

import { isDarkColor } from "@pol-studios/utils/color";

isDarkColor("#000000"); // true
isDarkColor("#ffffff"); // false

Validation Utilities

import { isValidEmail, isValidPhone, validatePassword } from "@pol-studios/utils/validation";

// Input validation and password strength checking

TypeScript Types

The package exports namespace modules for tree-shaking:

import { string, array, object, date } from "@pol-studios/utils";

string.camelize("hello-world");
array.groupBy(items, fn);
object.pick(obj, keys);

Related Packages

• @pol-studios/db/auth - Authentication (depends on utils)
• @pol-studios/db - Database layer (depends on utils)
• @pol-studios/hooks - React hooks (depends on utils)
• @pol-studios/ui - UI components (depends on utils)

License

UNLICENSED