This guide walks you through the most common use cases for Temelj packages. Each example uses real APIs from the library to solve practical problems.
Installation
First, install the packages you need:
npm install @temelj/async @temelj/result
Async operations with retry
Use the retry function to handle transient failures with exponential backoff:
import { retry } from '@temelj/async';
// Retry an API call with exponential backoff
const data = await retry(
async (attempt) => {
const response = await fetch('https://api.example.com/data');
if (!response.ok) throw new Error('Request failed');
return response.json();
},
{
times: 5,
delay: (attempt) => Math.pow(2, attempt) * 1000, // 1s, 2s, 4s, 8s, 16s
}
);
The retry function receives the current attempt number (0-indexed), allowing you to implement custom backoff strategies.
Functional error handling with Result
The Result type provides a type-safe way to handle errors without throwing exceptions:
import { ok, err, isOk, unwrapOr, type Result } from '@temelj/result';
function divide(a: number, b: number): Result<number, string> {
if (b === 0) {
return err('Division by zero');
}
return ok(a / b);
}
const result = divide(10, 2);
if (isOk(result)) {
console.log('Result:', result.value); // 5
} else {
console.log('Error:', result.error);
}
// Or use unwrapOr for a default value
const value = unwrapOr(result, 0);
Converting promises to Results
import { fromPromise } from '@temelj/result';
const result = await fromPromise(
fetch('https://api.example.com/data')
);
if (isOk(result)) {
const response = result.value;
// Handle success
} else {
const error = result.error;
// Handle error
}
Working with iterators
Use iterator utilities for lazy evaluation and efficient data processing:
import { range, filter, map, take } from '@temelj/iterator';
// Generate numbers lazily
const numbers = range(1, 100);
// Chain operations without intermediate arrays
const result = Array.from(
take(
map(
filter(numbers, n => n % 2 === 0),
n => n * n
),
5
)
);
console.log(result); // [4, 16, 36, 64, 100]
Parsing numeric ranges
import { parseNumericRange } from '@temelj/iterator';
const range = parseNumericRange('1-5,8,10-12');
console.log(range);
// [{ start: 1, end: 5 }, { start: 8, end: 8 }, { start: 10, end: 12 }]
String case conversions
Convert between different naming conventions:
import { toCamelCase, toSnakeCase, toKebabCase, toPascalCase } from '@temelj/string';
const apiField = 'user_name';
console.log(toCamelCase(apiField)); // 'userName'
console.log(toPascalCase(apiField)); // 'UserName'
console.log(toKebabCase(apiField)); // 'user-name'
Math utilities
Work with 2D vectors and rectangles:
import { Vector2, clamp } from '@temelj/math';
// Vector operations
const v1 = new Vector2(3, 4);
const v2 = new Vector2(1, 2);
const sum = v1.add(v2); // Vector2(4, 6)
const scaled = v1.scale(2); // Vector2(6, 8)
const length = v1.length(); // 5
// Clamp values to a range
const value = clamp(15, 0, 10); // 10
Combining utilities
Here’s a real-world example combining multiple packages:
import { retry } from '@temelj/async';
import { fromPromise, isOk, map } from '@temelj/result';
import { toCamelCase } from '@temelj/string';
// Fetch data with retry and convert to Result
async function fetchUserData(userId: string) {
return await retry(async () => {
const result = await fromPromise(
fetch(`https://api.example.com/users/${userId}`)
);
if (isOk(result)) {
const response = result.value;
const data = await response.json();
// Convert snake_case keys to camelCase
return map(result, () => ({
userId: data.user_id,
firstName: data.first_name,
lastName: data.last_name,
}));
}
return result;
}, {
times: 3,
delay: 1000,
});
}
Next steps
Core Packages
Explore async, result, iterator, and value packages
API Reference
Dive into detailed API documentation
Usage Patterns
Learn best practices and common patterns
TypeScript Integration
Configure TypeScript for optimal type safety