> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ooneex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Utils

> A grab-bag of small, focused helper functions for strings, time formatting, IDs, translations, and environment parsing.

`@ooneex/utils` is a collection of tiny, single-purpose helper functions you reach for again and again: case converters, time formatters, random ID generators, a string parser, a minimal translator, and a few odds and ends. Each helper is exported from its own subpath so you only pull in what you use.

## Installation

Add the package with Bun.

```bash theme={null}
bun add @ooneex/utils
```

## Usage

Every helper is imported from a dedicated subpath (`@ooneex/utils/<name>`).

### String and case helpers

Convert strings between cases, capitalize a single word, split a string into words, or trim arbitrary characters.

```typescript theme={null}
import { capitalize } from "@ooneex/utils/capitalize";
import { toCamelCase } from "@ooneex/utils/toCamelCase";
import { toPascalCase } from "@ooneex/utils/toPascalCase";
import { toKebabCase } from "@ooneex/utils/toKebabCase";
import { toSnakeCase } from "@ooneex/utils/toSnakeCase";
import { splitToWords } from "@ooneex/utils/splitToWords";
import { trim } from "@ooneex/utils/trim";

capitalize("hELLO");              // "Hello"

toCamelCase("user_first_name");   // "userFirstName"
toPascalCase("user-first-name");  // "UserFirstName"
toKebabCase("HTMLElement");       // "html-element"
toSnakeCase("Apple123 Pie");      // "apple123_pie"

splitToWords("HTMLElement v2");   // ["HTML", "Element", "v2"]

trim("  hello  ");                // "hello" (defaults to spaces)
trim("[value]", "[");             // "value]" -> char is auto-escaped for regex
```

### Parsing helpers

`parseString` coerces a string into its natural type (number, boolean, null, array, or JSON). `parseEnvVars` runs the same coercion over an env object while camel-casing the keys.

```typescript theme={null}
import { parseString } from "@ooneex/utils/parseString";
import { parseEnvVars } from "@ooneex/utils/parseEnvVars";

parseString("42");          // 42 (number)
parseString("3.14");        // 3.14 (number)
parseString("true");        // true (boolean)
parseString("null");        // null
parseString("[1, two, 3]"); // [1, "two", 3] (recursively parsed)
parseString("plain text");  // "plain text"

const config = parseEnvVars<{ appPort: number; appDebug: boolean }>({
  APP_PORT: "3000",
  APP_DEBUG: "true",
});
// { appPort: 3000, appDebug: true }
```

### Time helpers

Format durations for display, or pause an async flow with `sleep`.

```typescript theme={null}
import { secondsToHMS } from "@ooneex/utils/secondsToHMS";
import { secondsToMS } from "@ooneex/utils/secondsToMS";
import { millisecondsToHMS } from "@ooneex/utils/millisecondsToHMS";
import { sleep } from "@ooneex/utils/sleep";

secondsToHMS(3661);        // "1:01:01"
secondsToHMS(75);          // "1:15"
secondsToMS(75);           // "1:15" (always minutes:seconds)
millisecondsToHMS(65000);  // "1:05"

await sleep(500);          // resolves after 500ms
```

### Numbers and IDs

Format large numbers compactly and generate random identifiers (backed by `nanoid`).

```typescript theme={null}
import { formatRelativeNumber } from "@ooneex/utils/formatRelativeNumber";
import { random } from "@ooneex/utils/random";

formatRelativeNumber(1500);                       // "1.5K"
formatRelativeNumber(2_400_000);                  // "2.4M"
formatRelativeNumber(1500, { lang: "fr-FR" });    // "1,5 k"

random.id();          // 20-char hex string, e.g. "9f3a...c1"
random.nanoid(12);    // 12-char hex string
random.stringInt(6);  // 6-digit numeric string, e.g. "048213"

const generate = random.nanoidFactory(8); // reusable generator
generate();           // 8-char hex string
```

### Translations

`trans` resolves a dotted key from a nested dictionary, with locale fallback, pluralization (`_zero` / `_plural`), and `{{ param }}` interpolation. It returns a tagged result so you can branch on misses.

```typescript theme={null}
import { trans, has, type TransDictType } from "@ooneex/utils/trans";

const dict: TransDictType = {
  cart: {
    items: { en: "{{ count }} item", fr: "{{ count }} article" },
    items_plural: { en: "{{ count }} items", fr: "{{ count }} articles" },
  },
};

has(dict, "cart.items"); // true

const result = trans(dict, "cart.items", { lang: "fr", count: 3 });
if (result.found) {
  result.value; // "3 articles"
}

trans(dict, "cart.missing"); // { found: false, reason: "key" }
```

### Browser helper

`dataURLtoFile` turns a base64 data URL (e.g. from a canvas or file reader) into a `File` instance.

```typescript theme={null}
import { dataURLtoFile } from "@ooneex/utils/dataURLtoFile";

const file = dataURLtoFile(canvas.toDataURL("image/png"), "avatar.png");
// File { name: "avatar.png", type: "image/png" }
```

## When to use it

* You need consistent case conversion (`toCamelCase`, `toKebabCase`, etc.) for keys, slugs, identifiers, or class names.
* You want to coerce string config or query values into real types with `parseString`, or normalize an env object with `parseEnvVars`.
* You're formatting durations or large numbers for the UI, or need a quick `await sleep(ms)` in async code.
* You need short, URL-safe random IDs without pulling in a full UUID library.
* You want a lightweight, dependency-free translation lookup with plurals and interpolation instead of a heavy i18n framework.
* You don't need it for heavy text processing or full internationalization — reach for a dedicated i18n/NLP library when requirements grow beyond these helpers.