Utilities

A zero-dependency toolkit of pure helper functions for strings, objects, numbers, and async flow. Every method is available through Aura.utils and is designed to eliminate the need for lodash in most projects.

Quick Start

js
import aura from 'aura.js';

aura.utils.titleCase('hello world');     // "Hello World"
aura.utils.slugify('My Blog Post!');     // "my-blog-post"
aura.utils.mask('4242424242424242');   // "************4242"
aura.utils.uid();                       // "aB3kZ9mQ4xLp"
aura.utils.clamp(150, 0, 100);        // 100
aura.utils.isEmpty({});                  // true
await aura.utils.sleep(1000);           // pauses for 1 second

String Methods

titleCase()

Capitalize the first letter of every word and lowercase the rest.

titleCase(s: string): string

Param	Type	Description
s	string	The input string.

js
aura.utils.titleCase('hello world');   // "Hello World"
aura.utils.titleCase('jOHN DOE');     // "John Doe"

uppercase()

Convert the entire string to uppercase.

uppercase(s: string): string

Param	Type	Description
s	string	The input string.

js
aura.utils.uppercase('hello'); // "HELLO"

lowercase()

Convert the entire string to lowercase.

lowercase(s: string): string

Param	Type	Description
s	string	The input string.

js
aura.utils.lowercase('HELLO'); // "hello"

mask()

Mask a string, revealing only the last N characters. Useful for displaying credit card numbers, tokens, or sensitive data.

mask(s: string, visible?: number, ch?: string): string

Param	Type	Description
s	string	The string to mask.
visible	number	Number of characters to keep visible at the end. Default: `4`.
ch	string	The masking character. Default: `'*'`.

js
aura.utils.mask('4242424242424242');          // "************4242"
aura.utils.mask('secret-token', 6);            // "******-token"
aura.utils.mask('mypassword', 3, '#');        // "#######ord"

slugify()

Convert a string into a URL-friendly slug. Lowercases, trims, removes special characters, and replaces spaces with hyphens.

slugify(s: string): string

Param	Type	Description
s	string	The input string.

js
aura.utils.slugify('Hello World!');          // "hello-world"
aura.utils.slugify('My Blog Post #42');      // "my-blog-post-42"
aura.utils.slugify('  extra   spaces  ');    // "extra-spaces"

escapeHTML()

Escape HTML special characters to prevent XSS when inserting untrusted content into the DOM. Handles &, <, >, ", and '.

escapeHTML(s: string): string

Param	Type	Description
s	string	The raw string to escape.

js
aura.utils.escapeHTML('<script>alert("xss")</script>');
// "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"

Object Methods

isPlainObject()

Check if a value is a plain object (created by {} or Object.create(null)). Returns false for arrays, class instances, null, etc.

isPlainObject(v: unknown): v is Record<string, unknown>

Param	Type	Description
v	unknown	The value to check.

js
aura.utils.isPlainObject({ a: 1 });      // true
aura.utils.isPlainObject([1, 2]);         // false
aura.utils.isPlainObject(null);            // false
aura.utils.isPlainObject(new Date());     // false

deepClone()

Create a deep copy of a value. Uses structuredClone when available; falls back to JSON round-trip.

deepClone<T>(obj: T): T

Param	Type	Description
obj	T	The value to clone.

js
const original = { nested: { value: 42 } };
const copy = aura.utils.deepClone(original);
copy.nested.value = 99;
console.log(original.nested.value); // 42 (unchanged)

deepMerge()

Recursively merge multiple objects together. Plain objects are merged deeply; all other values are overwritten by the rightmost argument.

deepMerge<T extends Record<string, unknown>>(...objects: Partial<T>[]): T

Param	Type	Description
...objects	Partial<T>[]	Two or more objects to merge.

js
const defaults = { theme: 'light', api: { timeout: 5000, retries: 3 } };
const user     = { theme: 'dark',  api: { timeout: 10000 } };

const config = aura.utils.deepMerge(defaults, user);
// { theme: "dark", api: { timeout: 10000, retries: 3 } }

pick()

Create a new object containing only the specified keys from the source.

pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>

Param	Type	Description
obj	T	The source object.
keys	K[]	Array of keys to include.

js
const user = { id: 1, name: 'Alex', email: 'a@b.com', password: '...' };
aura.utils.pick(user, ['id', 'name']);
// { id: 1, name: "Alex" }

omit()

Create a new object with the specified keys removed.

omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>

Param	Type	Description
obj	T	The source object.
keys	K[]	Array of keys to exclude.

js
const user = { id: 1, name: 'Alex', password: 'secret' };
aura.utils.omit(user, ['password']);
// { id: 1, name: "Alex" }

isEmpty()

Check if a value is "empty". Handles null, undefined, empty strings, arrays, Maps, Sets, and plain objects.

isEmpty(v: unknown): boolean

Param	Type	Description
v	unknown	The value to check.

js
aura.utils.isEmpty(null);          // true
aura.utils.isEmpty('');            // true
aura.utils.isEmpty([]);            // true
aura.utils.isEmpty({});            // true
aura.utils.isEmpty(new Map());    // true
aura.utils.isEmpty([1]);           // false
aura.utils.isEmpty(0);             // false

Function Methods

debounce()

Create a debounced version of a function that delays invocation until after ms milliseconds have passed since the last call. The returned function also has a .cancel() method.

debounce<T extends (...args: unknown[]) => void>(fn: T, ms: number): T & { cancel(): void }

Param	Type	Description
fn	T	The function to debounce.
ms	number	Delay in milliseconds.

Returns: The debounced function with an additional cancel() method.

js
const search = aura.utils.debounce((query) => {
  aura.api.get(`/search?q=${query}`);
}, 300);

input.addEventListener('input', (e) => search(e.target.value));

// Cancel any pending invocation
search.cancel();

throttle()

Create a throttled version of a function that invokes at most once every ms milliseconds.

throttle<T extends (...args: unknown[]) => void>(fn: T, ms: number): T

Param	Type	Description
fn	T	The function to throttle.
ms	number	Minimum interval in milliseconds.

js
const onScroll = aura.utils.throttle(() => {
  console.log('scroll position:', window.scrollY);
}, 100);

window.addEventListener('scroll', onScroll);

pipe()

Pass a value through a series of transform functions, left to right. Each function receives the result of the previous one.

pipe<T>(value: T, ...fns: ((v: T) => T)[]): T

Param	Type	Description
value	T	The initial value.
...fns	((v: T) => T)[]	Transform functions to apply in order.

js
const result = aura.utils.pipe(
  '  Hello World  ',
  s => s.trim(),
  s => s.toLowerCase(),
  s => s.replace(/\s+/g, '-')
);
// "hello-world"

Miscellaneous

uid()

Generate a cryptographically random alphanumeric string. Uses crypto.getRandomValues for secure randomness.

uid(len?: number): string

Param	Type	Description
len	number	Length of the generated ID. Default: `12`.

js
aura.utils.uid();      // "aB3kZ9mQ4xLp"  (12 chars)
aura.utils.uid(6);    // "k9Qm4x"        (6 chars)
aura.utils.uid(24);   // "aB3kZ9mQ4xLpR7wN2jY5tU8v" (24 chars)

sleep()

Return a Promise that resolves after the given number of milliseconds. Useful for adding delays in async workflows.

sleep(ms: number): Promise<void>

Param	Type	Description
ms	number	Duration in milliseconds.

js
async function showNotification() {
  showToast('Saved!');
  await aura.utils.sleep(3000);
  hideToast();
}

clamp()

Restrict a number to a given range.

clamp(n: number, min: number, max: number): number

Param	Type	Description
n	number	The value to clamp.
min	number	Minimum bound.
max	number	Maximum bound.

js
aura.utils.clamp(150, 0, 100);   // 100
aura.utils.clamp(-5, 0, 100);    // 0
aura.utils.clamp(50, 0, 100);    // 50