@ooneex/utils 0.0.6 → 0.1.0

package/README.md

@@ -1,335 +1,671 @@
 # @ooneex/utils
 
-A comprehensive collection of utility functions for common programming tasks including string manipulation, number formatting, time conversion, and more.
+A comprehensive TypeScript/JavaScript utility library providing essential helper functions for string manipulation, time formatting, data parsing, and more. This package offers a collection of lightweight, type-safe utilities designed to streamline common development tasks across web applications.
+
+![Browser](https://img.shields.io/badge/Browser-Compatible-green?style=flat-square&logo=googlechrome)
+![Bun](https://img.shields.io/badge/Bun-Compatible-orange?style=flat-square&logo=bun)
+![Deno](https://img.shields.io/badge/Deno-Compatible-blue?style=flat-square&logo=deno)
+![Node.js](https://img.shields.io/badge/Node.js-Compatible-green?style=flat-square&logo=node.js)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript)
+![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)
+
+## Features
+
+✅ **String Manipulation** - Case conversion utilities (camelCase, PascalCase, kebab-case)
+
+✅ **Time Formatting** - Convert seconds/milliseconds to human-readable formats
+
+✅ **Data Parsing** - Intelligent string parsing with type inference
+
+✅ **Type-Safe** - Full TypeScript support with proper type definitions
+
+✅ **Lightweight** - Minimal dependencies and optimized bundle size
+
+✅ **Cross-Platform** - Works in Browser, Node.js, Bun, and Deno
+
+✅ **Environment Variables** - Parse and transform environment variables
+
+✅ **File Utilities** - Convert data URLs to File objects
+
+✅ **Random Generation** - Generate random IDs and strings
+
+✅ **Number Formatting** - Format numbers with locale-aware compact notation
+
+✅ **Zero Dependencies** - Only one small dependency (nanoid) for random generation
 
 ## Installation
 
+### Bun
 ```bash
-npm install @ooneex/utils
-# or
 bun add @ooneex/utils
-# or
-yarn add @ooneex/utils
-# or
+```
+
+### pnpm
+```bash
 pnpm add @ooneex/utils
 ```
 
+### Yarn
+```bash
+yarn add @ooneex/utils
+```
+
+### npm
+```bash
+npm install @ooneex/utils
+```
+
 ## Usage
 
+### String Manipulation
+
 ```typescript
-import { capitalizeWord, formatRelativeNumber, random, sleep, dataURLtoFile } from '@ooneex/utils';
+import {
+  capitalizeWord,
+  toCamelCase,
+  toPascalCase,
+  toKebabCase,
+  splitToWords,
+  trim
+} from '@ooneex/utils';
+
+// Capitalize words
+console.log(capitalizeWord('hello')); // 'Hello'
+console.log(capitalizeWord('WORLD')); // 'World'
+
+// Case conversions
+console.log(toCamelCase('hello world')); // 'helloWorld'
+console.log(toPascalCase('hello world')); // 'HelloWorld'
+console.log(toKebabCase('Hello World')); // 'hello-world'
+
+// Split strings to words
+console.log(splitToWords('HelloWorldExample')); // ['Hello', 'World', 'Example']
+console.log(splitToWords('hello-world_example')); // ['hello', 'world', 'example']
+
+// Advanced trimming
+console.log(trim('...hello...', '\\.')); // 'hello'
+console.log(trim('[test]', '\\[|\\]')); // 'test'
 ```
 
-## API Reference
+### Time Formatting
 
-### File Utilities
+```typescript
+import {
+  secondsToHMS,
+  secondsToMS,
+  millisecondsToHMS,
+  sleep
+} from '@ooneex/utils';
+
+// Convert seconds to time formats
+console.log(secondsToHMS(3661)); // '1:01:01'
+console.log(secondsToHMS(125)); // '2:05'
+console.log(secondsToHMS(45)); // '45'
+
+console.log(secondsToMS(125)); // '2:05'
+console.log(secondsToMS(45)); // '0:45'
+
+// Convert milliseconds to time format
+console.log(millisecondsToHMS(3661000)); // '1:01:01'
+console.log(millisecondsToHMS(125000)); // '2:05'
+
+// Async sleep utility
+await sleep(1000); // Wait 1 second
+```
 
-#### `dataURLtoFile(dataurl: string, filename: string): File`
+### Data Parsing
 
-Converts a data URL string into a File object, useful for handling base64-encoded file data.
+```typescript
+import { parseString, parseEnvVars } from '@ooneex/utils';
+
+// Intelligent string parsing with type inference
+console.log(parseString('123')); // 123 (number)
+console.log(parseString('12.34')); // 12.34 (number)
+console.log(parseString('true')); // true (boolean)
+console.log(parseString('false')); // false (boolean)
+console.log(parseString('null')); // null
+console.log(parseString('[1,2,3]')); // [1, 2, 3] (array)
+console.log(parseString('{"name":"John"}')); // {name: "John"} (object)
+console.log(parseString('1e5')); // 100000 (scientific notation)
+console.log(parseString('hello')); // 'hello' (string fallback)
+
+// Parse environment variables
+const envs = {
+  'API_PORT': '3000',
+  'DEBUG_MODE': 'true',
+  'ALLOWED_HOSTS': '["localhost", "127.0.0.1"]'
+};
+
+const parsed = parseEnvVars(envs);
+// Result: { apiPort: 3000, debugMode: true, allowedHosts: ['localhost', '127.0.0.1'] }
+```
+
+### Number Formatting
+
+```typescript
+import { formatRelativeNumber } from '@ooneex/utils';
+
+// Format numbers with compact notation
+console.log(formatRelativeNumber(1000)); // '1K'
+console.log(formatRelativeNumber(1500)); // '1.5K'
+console.log(formatRelativeNumber(1000000)); // '1M'
+console.log(formatRelativeNumber(2500000)); // '2.5M'
+console.log(formatRelativeNumber(1000000000)); // '1B'
+
+// Custom precision
+console.log(formatRelativeNumber(1234, { precision: 2 })); // '1.23K'
+console.log(formatRelativeNumber(1234, { precision: 0 })); // '1K'
+
+// Different locales
+console.log(formatRelativeNumber(1500, { lang: 'de-DE' })); // '1500'
+console.log(formatRelativeNumber(1500000, { lang: 'de-DE' })); // '1,5 Mio.'
+console.log(formatRelativeNumber(1500, { lang: 'fr-FR' })); // '1,5 k'
+```
+
+### File Utilities
 
-**Examples:**
 ```typescript
 import { dataURLtoFile } from '@ooneex/utils';
 
-// Convert a data URL to a File object
+// Convert data URL to File object
 const dataUrl = 'data:text/plain;base64,SGVsbG8gV29ybGQ=';
 const file = dataURLtoFile(dataUrl, 'hello.txt');
 
-// Use with image data URLs
-const imageDataUrl = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...';
-const imageFile = dataURLtoFile(imageDataUrl, 'image.png');
-
-// The resulting File object can be used in FormData or uploaded
-const formData = new FormData();
-formData.append('file', file);
+console.log(file.name); // 'hello.txt'
+console.log(file.type); // 'text/plain'
+console.log(file.size); // 11
 ```
 
-### String Utilities
+### Random Generation
 
-#### `capitalizeWord(word: string): string`
+```typescript
+import { random } from '@ooneex/utils';
 
-Capitalizes the first letter of a word and makes the rest lowercase.
+// Generate random hex strings
+console.log(random.nanoid()); // 'a1b2c3d4e5' (10 chars default)
+console.log(random.nanoid(8)); // 'f6e5d4c3' (8 chars)
 
-**Examples:**
-```typescript
-import { capitalizeWord } from '@ooneex/utils';
+// Generate numeric strings
+console.log(random.stringInt()); // '1234567890' (10 digits default)
+console.log(random.stringInt(6)); // '123456' (6 digits)
 
-capitalizeWord('hello');      // 'Hello'
-capitalizeWord('WORLD');      // 'World'
-capitalizeWord('javaScript'); // 'Javascript'
-capitalizeWord('');           // ''
+// Create a factory function
+const generateId = random.nanoidFactory(12);
+console.log(generateId()); // 12-character hex string
+console.log(generateId(8)); // 8-character hex string (overrides factory size)
 ```
 
-#### `splitToWords(input: string): string[]`
+## API Reference
+
+### String Utilities
+
+#### `capitalizeWord(word: string): string`
+Capitalizes the first letter and lowercases the rest.
 
-Splits a string into an array of words, handling camelCase, PascalCase, kebab-case, snake_case, and more.
+**Parameters:**
+- `word` - The word to capitalize
 
-**Examples:**
+**Returns:** Capitalized word
+
+**Example:**
 ```typescript
-import { splitToWords } from '@ooneex/utils';
-
-splitToWords('helloWorld');           // ['hello', 'World']
-splitToWords('PascalCaseString');     // ['Pascal', 'Case', 'String']
-splitToWords('kebab-case-string');    // ['kebab', 'case', 'string']
-splitToWords('snake_case_string');    // ['snake', 'case', 'string']
-splitToWords('HTMLElement123');       // ['HTML', 'Element', '123']
-splitToWords('URLParser');            // ['URL', 'Parser']
+capitalizeWord('hello'); // 'Hello'
+capitalizeWord('WORLD'); // 'World'
+capitalizeWord(''); // ''
 ```
 
 #### `toCamelCase(input: string): string`
+Converts string to camelCase.
 
-Converts a string to camelCase.
+**Parameters:**
+- `input` - The string to convert
 
-**Examples:**
-```typescript
-import { toCamelCase } from '@ooneex/utils';
+**Returns:** camelCase string
 
-toCamelCase('hello world');           // 'helloWorld'
-toCamelCase('PascalCaseString');      // 'pascalCaseString'
-toCamelCase('kebab-case-string');     // 'kebabCaseString'
-toCamelCase('snake_case_string');     // 'snakeCaseString'
-toCamelCase('  SPACED  STRING  ');    // 'spacedString'
+**Example:**
+```typescript
+toCamelCase('hello world'); // 'helloWorld'
+toCamelCase('Hello-World_Example'); // 'helloWorldExample'
+toCamelCase('API_KEY'); // 'apiKey'
 ```
 
 #### `toPascalCase(input: string): string`
+Converts string to PascalCase.
 
-Converts a string to PascalCase.
+**Parameters:**
+- `input` - The string to convert
 
-**Examples:**
-```typescript
-import { toPascalCase } from '@ooneex/utils';
+**Returns:** PascalCase string
 
-toPascalCase('hello world');          // 'HelloWorld'
-toPascalCase('camelCaseString');      // 'CamelCaseString'
-toPascalCase('kebab-case-string');    // 'KebabCaseString'
-toPascalCase('snake_case_string');    // 'SnakeCaseString'
-toPascalCase('  spaced  string  ');   // 'SpacedString'
+**Example:**
+```typescript
+toPascalCase('hello world'); // 'HelloWorld'
+toPascalCase('api-key'); // 'ApiKey'
+toPascalCase('user_name'); // 'UserName'
 ```
 
 #### `toKebabCase(input: string): string`
+Converts string to kebab-case.
 
-Converts a string to kebab-case.
+**Parameters:**
+- `input` - The string to convert
 
-**Examples:**
+**Returns:** kebab-case string
+
+**Example:**
 ```typescript
-import { toKebabCase } from '@ooneex/utils';
+toKebabCase('Hello World'); // 'hello-world'
+toKebabCase('camelCaseString'); // 'camel-case-string'
+toKebabCase('PascalCaseString'); // 'pascal-case-string'
+```
+
+#### `splitToWords(input: string): string[]`
+Splits a string into individual words, handling various naming conventions.
+
+**Parameters:**
+- `input` - The string to split
 
-toKebabCase('Hello World');           // 'hello-world'
-toKebabCase('camelCaseString');       // 'camel-case-string'
-toKebabCase('PascalCaseString');      // 'pascal-case-string'
-toKebabCase('snake_case_string');     // 'snake-case-string'
-toKebabCase('  SPACED  STRING  ');    // 'spaced-string'
+**Returns:** Array of words
+
+**Example:**
+```typescript
+splitToWords('HelloWorld'); // ['Hello', 'World']
+splitToWords('hello-world_example'); // ['hello', 'world', 'example']
+splitToWords('XMLHttpRequest'); // ['XML', 'Http', 'Request']
+splitToWords('user123Name'); // ['user', '123', 'Name']
 ```
 
 #### `trim(text: string, char?: string): string`
+Trims specified characters from the beginning and end of a string.
 
-Trims specified characters from the beginning and end of a string. Defaults to trimming whitespace.
+**Parameters:**
+- `text` - The string to trim
+- `char` - Characters to trim (default: space). Supports regex patterns.
 
-**Examples:**
-```typescript
-import { trim } from '@ooneex/utils';
+**Returns:** Trimmed string
 
-trim('  hello world  ');              // 'hello world'
-trim('...hello world...', '.');       // 'hello world'
-trim('[hello world]', '[');           // 'hello world]'
-trim('[hello world]', '\\[|\\]');     // 'hello world'
-trim('***hello world***', '*');       // 'hello world'
+**Example:**
+```typescript
+trim('  hello  '); // 'hello'
+trim('...hello...', '\\.'); // 'hello'
+trim('[test]', '\\[|\\]'); // 'test'
+trim('!!hello!!', '!'); // 'hello'
 ```
 
-### Parsing Utilities
+### Time Utilities
 
-#### `parseString<T = unknown>(text: string): T`
+#### `secondsToHMS(seconds: number): string`
+Converts seconds to HH:MM:SS or MM:SS or SS format.
 
-Intelligently parses a string into appropriate JavaScript types (number, boolean, array, object, etc.).
+**Parameters:**
+- `seconds` - Number of seconds
 
-**Examples:**
+**Returns:** Formatted time string
+
+**Example:**
 ```typescript
-import { parseString } from '@ooneex/utils';
-
-parseString('123');                   // 123 (number)
-parseString('45.67');                 // 45.67 (number)
-parseString('true');                  // true (boolean)
-parseString('false');                 // false (boolean)
-parseString('null');                  // null
-parseString('[1, 2, 3]');             // [1, 2, 3] (array)
-parseString('{"key": "value"}');      // { key: "value" } (object)
-parseString('hello');                 // 'hello' (string)
-parseString('[apple, banana, 123]'); // ['apple', 'banana', 123]
+secondsToHMS(3661); // '1:01:01' (1 hour, 1 minute, 1 second)
+secondsToHMS(125); // '2:05' (2 minutes, 5 seconds)
+secondsToHMS(45); // '45' (45 seconds)
+secondsToHMS(0); // '0'
 ```
 
-#### `parseEnvVars<T = Record<string, unknown>>(envs: Record<string, unknown>): T`
+#### `secondsToMS(seconds: number): string`
+Converts seconds to MM:SS format.
+
+**Parameters:**
+- `seconds` - Number of seconds
 
-Parses environment variables, converting keys to camelCase and values to appropriate types.
+**Returns:** MM:SS formatted string
 
-**Examples:**
+**Example:**
 ```typescript
-import { parseEnvVars } from '@ooneex/utils';
+secondsToMS(125); // '2:05'
+secondsToMS(45); // '0:45'
+secondsToMS(3661); // '61:01'
+```
 
-const envVars = {
-  'DATABASE_URL': 'postgresql://localhost:5432/db',
-  'PORT': '3000',
-  'ENABLE_LOGGING': 'true',
-  'MAX_CONNECTIONS': '100'
-};
+#### `millisecondsToHMS(ms: number): string`
+Converts milliseconds to HH:MM:SS or MM:SS or SS format.
 
-const parsed = parseEnvVars(envVars);
-// {
-//   databaseUrl: 'postgresql://localhost:5432/db',
-//   port: 3000,
-//   enableLogging: true,
-//   maxConnections: 100
-// }
+**Parameters:**
+- `ms` - Number of milliseconds
+
+**Returns:** Formatted time string
+
+**Example:**
+```typescript
+millisecondsToHMS(3661000); // '1:01:01'
+millisecondsToHMS(125000); // '2:05'
+millisecondsToHMS(45000); // '45'
+millisecondsToHMS(500); // '0'
 ```
 
-### Number Formatting
+#### `sleep(ms: number): Promise<void>`
+Creates a promise that resolves after the specified number of milliseconds.
 
-#### `formatRelativeNumber(num: number, config?: { precision?: number; lang?: string }): string`
+**Parameters:**
+- `ms` - Number of milliseconds to wait
 
-Formats numbers using compact notation (K, M, B, etc.).
+**Returns:** Promise that resolves after the delay
 
-**Examples:**
+**Example:**
 ```typescript
-import { formatRelativeNumber } from '@ooneex/utils';
-
-formatRelativeNumber(1234);                           // '1.2K'
-formatRelativeNumber(1234567);                        // '1.2M'
-formatRelativeNumber(1234567890);                     // '1.2B'
-formatRelativeNumber(1234, { precision: 0 });         // '1K'
-formatRelativeNumber(1234, { precision: 2 });         // '1.23K'
-formatRelativeNumber(1234, { lang: 'de' });           // '1,2 Tsd.'
-formatRelativeNumber(1500000, { lang: 'fr' });        // '1,5 M'
+await sleep(1000); // Wait 1 second
+await sleep(500); // Wait 0.5 seconds
+
+// Usage in async function
+async function delayedLog() {
+  console.log('First');
+  await sleep(2000);
+  console.log('Second (2 seconds later)');
+}
 ```
 
-### Time Conversion
+### Data Parsing
 
-#### `millisecondsToHMS(ms: number): string`
+#### `parseString<T>(text: string): T`
+Intelligently parses a string and returns the appropriate type.
+
+**Parameters:**
+- `text` - The string to parse
 
-Converts milliseconds to HH:MM:SS or MM:SS format.
+**Returns:** Parsed value with inferred type
 
-**Examples:**
+**Supported Formats:**
+- Integers: `"123"` → `123`
+- Floats: `"12.34"` → `12.34`
+- Scientific notation: `"1e5"` → `100000`
+- Booleans: `"true"`, `"false"` (case insensitive)
+- Null: `"null"` (case insensitive)
+- Arrays: `"[1,2,3]"` → `[1, 2, 3]`
+- Objects: `'{"key":"value"}'` → `{key: "value"}`
+- JSON strings: `'"hello"'` → `"hello"`
+
+**Example:**
 ```typescript
-import { millisecondsToHMS } from '@ooneex/utils';
-
-millisecondsToHMS(30000);          // '30'
-millisecondsToHMS(90000);          // '1:30'
-millisecondsToHMS(3661000);        // '1:01:01'
-millisecondsToHMS(45000);          // '45'
-millisecondsToHMS(125000);         // '2:05'
-millisecondsToHMS(7323000);        // '2:02:03'
+parseString('123'); // 123 (number)
+parseString('12.34'); // 12.34 (number)
+parseString('1e3'); // 1000 (number)
+parseString('true'); // true (boolean)
+parseString('null'); // null
+parseString('[1,2,3]'); // [1, 2, 3] (array)
+parseString('{"name":"John"}'); // {name: "John"} (object)
+parseString('hello'); // 'hello' (string fallback)
+
+// With type annotation
+const num = parseString<number>('123'); // TypeScript knows it's a number
+const arr = parseString<number[]>('[1,2,3]'); // TypeScript knows it's number[]
 ```
 
-#### `secondsToHMS(seconds: number): string`
+#### `parseEnvVars<T>(envs: Record<string, string>): T`
+Parses environment variables, converting keys to camelCase and values using `parseString`.
 
-Converts seconds to HH:MM:SS or MM:SS format.
+**Parameters:**
+- `envs` - Object with environment variable key-value pairs
 
-**Examples:**
+**Returns:** Object with camelCase keys and parsed values
+
+**Example:**
 ```typescript
-import { secondsToHMS } from '@ooneex/utils';
-
-secondsToHMS(30);                  // '30'
-secondsToHMS(90);                  // '1:30'
-secondsToHMS(3661);                // '1:01:01'
-secondsToHMS(45);                  // '45'
-secondsToHMS(125);                 // '2:05'
-secondsToHMS(7323);                // '2:02:03'
+const envVars = {
+  'API_PORT': '3000',
+  'DEBUG_MODE': 'true',
+  'ALLOWED_HOSTS': '["localhost", "127.0.0.1"]',
+  'MAX_CONNECTIONS': '100',
+  'ENABLE_SSL': 'false'
+};
+
+const config = parseEnvVars(envVars);
+// Result:
+// {
+//   apiPort: 3000,
+//   debugMode: true,
+//   allowedHosts: ['localhost', '127.0.0.1'],
+//   maxConnections: 100,
+//   enableSsl: false
+// }
+
+// With type annotation
+interface Config {
+  apiPort: number;
+  debugMode: boolean;
+  allowedHosts: string[];
+}
+const typedConfig = parseEnvVars<Config>(envVars);
 ```
 
-#### `secondsToMS(seconds: number): string`
+### Number Utilities
 
-Converts seconds to MM:SS format.
+#### `formatRelativeNumber(num: number, config?: { precision?: number; lang?: string }): string`
+Formats numbers using compact notation with locale support.
+
+**Parameters:**
+- `num` - The number to format
+- `config.precision` - Maximum decimal places (default: 1)
+- `config.lang` - Locale code (default: 'en-GB')
+
+**Returns:** Formatted number string
 
-**Examples:**
+**Example:**
 ```typescript
-import { secondsToMS } from '@ooneex/utils';
+formatRelativeNumber(1000); // '1K'
+formatRelativeNumber(1500); // '1.5K'
+formatRelativeNumber(1000000); // '1M'
+formatRelativeNumber(1000000000); // '1B'
+
+// Custom precision
+formatRelativeNumber(1234, { precision: 2 }); // '1.23K'
+formatRelativeNumber(1234, { precision: 0 }); // '1K'
+
+// Different locales
+formatRelativeNumber(1500, { lang: 'de-DE' }); // '1500'
+formatRelativeNumber(1500000, { lang: 'de-DE' }); // '1,5 Mio.'
+formatRelativeNumber(1500, { lang: 'fr-FR' }); // '1,5 k'
+formatRelativeNumber(1500, { lang: 'es-ES' }); // '1,5 mil'
+```
+
+### File Utilities
+
+#### `dataURLtoFile(dataurl: string, filename: string): File`
+Converts a data URL to a File object.
+
+**Parameters:**
+- `dataurl` - The data URL string
+- `filename` - The desired filename for the File object
 
-secondsToMS(30);                   // '0:30'
-secondsToMS(90);                   // '1:30'
-secondsToMS(125);                  // '2:05'
-secondsToMS(3661);                 // '61:01'
+**Returns:** File object
+
+**Example:**
+```typescript
+// Text file
+const textDataUrl = 'data:text/plain;base64,SGVsbG8gV29ybGQ=';
+const textFile = dataURLtoFile(textDataUrl, 'hello.txt');
+console.log(textFile.name); // 'hello.txt'
+console.log(textFile.type); // 'text/plain'
+console.log(textFile.size); // 11
+
+// Image file
+const imgDataUrl = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==';
+const imgFile = dataURLtoFile(imgDataUrl, 'pixel.png');
+console.log(imgFile.type); // 'image/png'
+
+// Usage with FileReader
+const reader = new FileReader();
+reader.onload = (e) => console.log(e.target?.result);
+reader.readAsText(textFile);
 ```
 
 ### Random Generation
 
-#### `random`
+#### `random.nanoid(size?: number): string`
+Generates a random hexadecimal string.
+
+**Parameters:**
+- `size` - Length of the generated string (default: 10)
 
-Object containing various random string generation functions.
+**Returns:** Random hex string
 
-**Examples:**
+**Example:**
 ```typescript
-import { random } from '@ooneex/utils';
+random.nanoid(); // 'a1b2c3d4e5' (10 characters)
+random.nanoid(8); // 'f6e5d4c3' (8 characters)
+random.nanoid(16); // '1a2b3c4d5e6f7890' (16 characters)
+```
 
-// Generate random hexadecimal string (default 10 characters)
-random.nanoid();                   // 'a1b2c3d4e5'
-random.nanoid(5);                  // '1a2b3'
-random.nanoid(16);                 // '1234567890abcdef'
+#### `random.stringInt(size?: number): string`
+Generates a random numeric string.
 
-// Generate random numeric string
-random.stringInt();                // '1234567890'
-random.stringInt(5);               // '12345'
+**Parameters:**
+- `size` - Length of the generated string (default: 10)
 
-// Create a factory function for consistent length
-const generateId = random.nanoidFactory(8);
-generateId();                      // 'a1b2c3d4'
-generateId();                      // '5e6f7890'
+**Returns:** Random numeric string
+
+**Example:**
+```typescript
+random.stringInt(); // '1234567890' (10 digits)
+random.stringInt(6); // '123456' (6 digits)
+random.stringInt(4); // '9876' (4 digits)
 ```
 
-### Async Utilities
+#### `random.nanoidFactory(size?: number): (size?: number) => string`
+Creates a factory function for generating random hex strings.
 
-#### `sleep(ms: number): Promise<void>`
+**Parameters:**
+- `size` - Default length for the factory (default: 10)
 
-Creates a promise that resolves after the specified number of milliseconds, useful for adding delays in async functions.
+**Returns:** Factory function that accepts optional size parameter
 
-**Examples:**
+**Example:**
 ```typescript
-import { sleep } from '@ooneex/utils';
+const generateId = random.nanoidFactory(12);
+generateId(); // 12-character hex string
+generateId(8); // 8-character hex string (overrides factory default)
+generateId(16); // 16-character hex string
 
-// Wait for 1 second
-await sleep(1000);
+const generateShortId = random.nanoidFactory(6);
+generateShortId(); // 6-character hex string
+```
 
-// Use in async function
-async function delayedOperation() {
-  console.log('Starting...');
-  await sleep(2000);  // Wait 2 seconds
-  console.log('Done!');
-}
+## Advanced Usage
 
-// Use with other async operations
-async function retryWithDelay() {
-  for (let i = 0; i < 3; i++) {
-    try {
-      await someOperation();
-      break;
-    } catch (error) {
-      if (i < 2) await sleep(1000); // Wait 1 second before retry
-    }
-  }
+### Environment Configuration
+
+```typescript
+import { parseEnvVars } from '@ooneex/utils';
+
+// Define your configuration interface
+interface AppConfig {
+  port: number;
+  host: string;
+  debug: boolean;
+  features: string[];
+  dbConfig: {
+    host: string;
+    port: number;
+  };
 }
+
+// Parse environment variables
+const envConfig = parseEnvVars<Partial<AppConfig>>(process.env);
+
+// Merge with defaults
+const config: AppConfig = {
+  port: 3000,
+  host: 'localhost',
+  debug: false,
+  features: [],
+  dbConfig: { host: 'localhost', port: 5432 },
+  ...envConfig
+};
 ```
 
-## Type Safety
+### String Processing Pipeline
 
-All functions are fully typed with TypeScript, providing excellent IDE support and compile-time type checking.
+```typescript
+import { splitToWords, toCamelCase, capitalizeWord } from '@ooneex/utils';
+
+function processUserInput(input: string): {
+  words: string[];
+  camelCase: string;
+  title: string;
+  kebabCase: string;
+} {
+  const words = splitToWords(input);
+
+  return {
+    words,
+    camelCase: toCamelCase(input),
+    title: words.map(capitalizeWord).join(' '),
+    kebabCase: toKebabCase(input)
+  };
+}
+
+const result = processUserInput('user-profile_settings');
+// {
+//   words: ['user', 'profile', 'settings'],
+//   camelCase: 'userProfileSettings',
+//   title: 'User Profile Settings',
+//   kebabCase: 'user-profile-settings'
+// }
+```
+
+### Time-based Progress Tracking
 
 ```typescript
-// Generic type support
-const parsedNumber = parseString<number>('123');     // Type: number
-const parsedArray = parseString<string[]>('[a,b,c]'); // Type: string[]
+import { millisecondsToHMS, formatRelativeNumber } from '@ooneex/utils';
 
-// Environment variables with custom type
-interface AppConfig {
-  port: number;
-  databaseUrl: string;
-  enableLogging: boolean;
+class ProgressTracker {
+  private startTime: number;
+  private itemsProcessed: number = 0;
+  private totalItems: number;
+
+  constructor(totalItems: number) {
+    this.startTime = Date.now();
+    this.totalItems = totalItems;
+  }
+
+  update(processed: number): string {
+    this.itemsProcessed = processed;
+    const elapsed = Date.now() - this.startTime;
+    const rate = processed / (elapsed / 1000);
+    const remaining = (this.totalItems - processed) / rate * 1000;
+
+    return [
+      `Processed: ${formatRelativeNumber(processed)}/${formatRelativeNumber(this.totalItems)}`,
+      `Elapsed: ${millisecondsToHMS(elapsed)}`,
+      `ETA: ${millisecondsToHMS(remaining)}`
+    ].join(' | ');
+  }
 }
 
-const config = parseEnvVars<AppConfig>(process.env);
+const tracker = new ProgressTracker(100000);
+console.log(tracker.update(15000));
+// "Processed: 15K/100K | Elapsed: 2:30 | ETA: 14:10"
 ```
 
 ## License
 
-MIT
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `bun install`
+3. Run tests: `bun run test`
+4. Build the project: `bun run build`
+
+### Guidelines
+
+- Write tests for new features
+- Follow the existing code style
+- Update documentation for API changes
+- Ensure all tests pass before submitting PR
+
+---
+
+Made with ❤️ by the Ooneex team