@alsania-io/utils

Shared utilities for Alsania ecosystem

Features

• 📝 Response Parsing — Extract text from various AI response formats (OpenAI, Anthropic, etc.)
• 🔐 Hash Utilities — BLAKE3, SHA3-256, SHA256, HMAC-SHA256
• 🆔 UUID Generation — Random UUIDs and short IDs
• ⏱️ Async Utilities — Sleep, retry with exponential backoff, timeout
• 📦 Object Utilities — Deep merge, deep clone, pick, omit
• 📝 String Utilities — Truncate, capitalize, camelCase, snake_case
• 🔍 Type Guards — isNotNull, isString, isObject, isArray
• 🌐 Environment Utilities — Type-safe env variable access

Installation

npm install @alsania-io/utils

Usage

Response Parsing

import { extractText } from '@alsania-io/utils';

// OpenAI format
const openaiResponse = {
  choices: [{ message: { content: 'Hello!' } }]
};
console.log(extractText(openaiResponse)); // 'Hello!'

// Anthropic format
const anthropicResponse = {
  content: [{ text: 'Hello!' }]
};
console.log(extractText(anthropicResponse)); // 'Hello!'

// Direct text
console.log(extractText('Hello!')); // 'Hello!'

Hashing

import { blake3Hash, sha3Hash, sha256Hash } from '@alsania-io/utils';

const data = 'hello world';
console.log(sha3Hash(data)); // 0x...
console.log(sha256Hash(data)); // ...

Async Utilities

import { sleep, retry, timeout } from '@alsania-io/utils';

// Sleep
await sleep(1000); // Wait 1 second

// Retry with exponential backoff
const result = await retry(
  async () => {
    // Your async operation
    return await fetchData();
  },
  { maxAttempts: 5, initialDelay: 100 }
);

// Timeout
const result = await timeout(fetchData(), 5000);

Object Utilities

import { deepMerge, pick, omit } from '@alsania-io/utils';

const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };
console.log(deepMerge(obj1, obj2)); // { a: 1, b: { c: 2, d: 3 }, e: 4 }

const picked = pick(obj1, ['a']); // { a: 1 }
const omitted = omit(obj1, ['a']); // { b: { c: 2 } }

String Utilities

import { capitalize, toCamelCase, toSnakeCase, truncate } from '@alsania-io/utils';

console.log(capitalize('hello')); // 'Hello'
console.log(toCamelCase('hello-world')); // 'helloWorld'
console.log(toSnakeCase('helloWorld')); // 'hello_world'
console.log(truncate('hello world', 5)); // 'hello...'

Environment Utilities

import { getEnv, getEnvNumber, getEnvBoolean } from '@alsania-io/utils';

const apiKey = getEnv('API_KEY', 'default-key');
const port = getEnvNumber('PORT', 3000);
const debug = getEnvBoolean('DEBUG', false);

API Reference

Response Parsing

• extractText(data: any): string — Extract text from various AI response formats
• safeJsonParse<T>(json: string, fallback: T): T — Safe JSON parsing
• safeStringify(obj: any, indent?: number): string — Safe JSON stringify with circular ref handling

Hash Utilities

• blake3Hash(data: string | Buffer): string — BLAKE3 hash (SHA3-256 fallback)
• sha3Hash(data: string | Buffer): string — SHA3-256 hash
• sha256Hash(data: string | Buffer): string — SHA256 hash
• hmacSha256(key: string | Buffer, data: string | Buffer): string — HMAC-SHA256

UUID

• uuid(): string — Generate UUID v4
• shortId(length?: number): string — Generate short ID

Async

• sleep(ms: number): Promise<void> — Sleep
• retry<T>(fn: () => Promise<T>, options?): Promise<T> — Retry with exponential backoff
• timeout<T>(promise: Promise<T>, ms: number): Promise<T> — Timeout a promise

Object

• deepMerge<T>(target: T, source: Partial<T>): T — Deep merge objects
• deepClone<T>(obj: T): T — Deep clone
• pick<T, K>(obj: T, keys: K[]): Pick<T, K> — Pick specific keys
• omit<T, K>(obj: T, keys: K[]): Omit<T, K> — Omit specific keys

String

• truncate(str: string, maxLength: number, suffix?: string): string — Truncate string
• capitalize(str: string): string — Capitalize first letter
• toCamelCase(str: string): string — Convert to camelCase
• toSnakeCase(str: string): string — Convert to snake_case

Type Guards

• isNotNull<T>(value: T | null | undefined): value is T
• isString(value: unknown): value is string
• isObject(value: unknown): value is Record<string, any>
• isArray(value: unknown): value is any[]

Environment

• getEnv(key: string, defaultValue?: string): string
• getEnvNumber(key: string, defaultValue?: number): number
• getEnvBoolean(key: string, defaultValue?: boolean): boolean

License

MIT