Utilities

Shared TypeScript utility functions for string manipulation, ID generation, object/array operations, type guards, and async helpers.

The @unflow-ui/utils package provides small, well-typed utility functions used across the design system and consuming applications.

Installation

npm install @unflow-ui/utils

Import

import { capitalize, groupBy, isDefined } from '@unflow-ui/utils';

String utilities

`capitalize(str)`

Capitalises the first character of a string.

capitalize('hello world') // → 'Hello world'

`toKebabCase(str)`

Converts camelCase or PascalCase to kebab-case.

toKebabCase('MyComponent')  // → 'my-component'
toKebabCase('camelCase')    // → 'camel-case'

`truncate(str, maxLength, suffix?)`

Truncates a string to maxLength characters, appending a suffix (defaults to '…').

truncate('Hello, world!', 7)        // → 'Hello, …'
truncate('Hello, world!', 7, '...') // → 'Hello, ...'

ID utilities

`generateId(prefix?)`

Generates a lightweight unique ID string. Not cryptographically secure — intended for DOM IDs, list keys, and similar non-security use cases.

generateId()          // → 'k7d3m'
generateId('button')  // → 'button-k7d3m'

Object utilities

`omit(obj, keys)`

Returns a shallow copy of obj with the specified keys removed.

omit({ a: 1, b: 2, c: 3 }, ['b', 'c']) // → { a: 1 }

`pick(obj, keys)`

Returns a shallow copy of obj with only the specified keys.

pick({ a: 1, b: 2, c: 3 }, ['a', 'c']) // → { a: 1, c: 3 }

Array utilities

`groupBy(arr, key)`

Groups an array of items by a key function.

groupBy(
  [{ role: 'admin', name: 'Alice' }, { role: 'user', name: 'Bob' }, { role: 'admin', name: 'Carol' }],
  item => item.role
)
// → { admin: [{ role: 'admin', name: 'Alice' }, { role: 'admin', name: 'Carol' }], user: [{ role: 'user', name: 'Bob' }] }

`uniqueBy(arr, key)`

Removes duplicate items from an array, comparing by a key function.

uniqueBy([{ id: 1 }, { id: 2 }, { id: 1 }], item => item.id)
// → [{ id: 1 }, { id: 2 }]

Number utilities

`clamp(value, min, max)`

Constrains a number to be between min and max.

clamp(150, 0, 100) // → 100
clamp(-5, 0, 100)  // → 0
clamp(50, 0, 100)  // → 50

`formatCurrency(amount, currency?, locale?)`

Formats a number as a currency string using the Internationalization API.

formatCurrency(1234.56)              // → '$1,234.56'  (USD, en-US)
formatCurrency(1234.56, 'EUR', 'de') // → '1.234,56 €'

Type guards

`isDefined(value)`

Returns true if value is neither null nor undefined. Narrows the type to T.

const items = [1, null, 2, undefined, 3];
items.filter(isDefined) // → [1, 2, 3] — typed as number[]

`isString(value)`

Returns true if value is a string.

isString('hello') // → true
isString(42)      // → false

`isObject(value)`

Returns true if value is a non-null object (excludes arrays).

isObject({ a: 1 })  // → true
isObject([1, 2])    // → false
isObject(null)      // → false

Async utilities

`sleep(ms)`

Returns a Promise that resolves after ms milliseconds.

await sleep(500); // pause for 500ms

`withRetry(fn, maxAttempts?, baseDelayMs?)`

Retries an async function with exponential backoff on failure.

const data = await withRetry(
  () => fetch('/api/data').then(r => r.json()),
  3,    // max 3 attempts (default: 3)
  200   // starting delay 200ms, then 400ms, 800ms… (default: 100ms)
);

On this page