What is LogosDX?

Logos /lōgōs/ n.
    ¹ From the ancient Greek meaning "divine reason" and "rational principle."
    ² Represents the fundamental order that governs the universe.
    ³ The stoics believed it was the rational law underlying all things.

DX /di-eks/ n.
    ¹ Stands for "developer experience."

LogosDX /lōgōs di-eks/ n.
    ¹ A rational developer experience.

---

In the ancient Greek conception of Logos - the divine reason that brings order to chaos - we found inspiration for these utilities. After years of rebuilding the same retry logic across projects, copying storage wrappers between codebases, and watching our own teams rediscover patterns we'd already solved, LogosDX emerged from the recognition that certain principles appear in every reliable system.

These aren't just utility packages. They're the distilled patterns we kept reaching for: explicit error handling that makes failure paths visible, storage abstractions that work everywhere, events that understand patterns, HTTP clients that handle failure gracefully. The utilities we wished existed when we were building cross-platform applications that needed to work reliably in production.

The rational principles that create order from development complexity.

Why is this different?

1. Explicit error handling control flow: Utilities like attempt/attemptSync return [value, error] tuples, which eliminates the need for try/catch— no more invisible error paths due to nested logic. This makes tests, retries, and fallbacks straightforward and more legible.

2. Resilience is a primary concern: retry, withTimeout, circuitBreaker, and rateLimit are available as primitives. FetchEngine adds timeouts, retries, backoff, and gives you abstractions to handle common patterns (e.g., honor Retry-After) on top of the standard Fetch API.

3. It offers observability, but more advanced: ObserverEngine provides typed topics, regex subscriptions, async iteration, and priority queues so you can coordinate workloads. TypeScript and debugging aren't an afterthought.

4. Runtime-agnostic by construction: No Node-only globals or browser-only assumptions. Everything runs the same in React apps, CLIs, workers, and scripts.

5. Tight dependency policy: Only @logosdx/* dependencies. This reduces supply-chain churn and makes upgrades predictable.

Our goals

• TypeScript-first.
• Resilience built in.
• Tree-shakable.
• Runtime agnostic.
• Small and fast.
• Debuggable, testable, and well-documented.
• Zero external dependencies.

Use Cases

• Shared logic across runtimes: Validation, transformation, and I/O utilities that work in browsers and servers without forking code.
• Processing and ETL: Controlled concurrency, backoff, and explicit error handling for bulk jobs and data pipelines.
• Third-party integrations: Handle timeouts, rate limits, and partial failures without littering code with custom retry logic.
• Event-driven systems: Typed channels with queueing and async iteration for workflows and background work.

Quick examples

Error tuples are the cleanest way to handle errors. This avoids nested try-catch blocks, which can often lead to invisible error paths and unexpected behavior. It keeps your code legible and explicit.

import { attempt } from '@logosdx/utils'

const [user, err] = await attempt(() => fetchUser(userId));

if (err) {

    return respond(404, 'User not found');
}

Fetch API is great and available everywhere, but it lacks quite a bit of the features we'd expect from a modern HTTP client. Fetch engine gives us timeouts, retries, lifecycle hooks, and more. Use it together with attempt to handle errors gracefully.

import Fetch, { FetchEngine, isFetchError } from '@logosdx/fetch'
import { attempt } from '@logosdx/utils'

const api = new FetchEngine({
    baseUrl: 'https://api.example.com',
    retry: { maxAttempts: 3, baseDelay: 250 },
    totalTimeout: 5_000,
    defaultType: 'json',
    headers: {
        'Content-Type': 'application/json',
    },
});

api.state.set({ userId: '123' });

const [orders, ordersErr] = await attempt(() => api.get('/orders'))

if (isFetchError(ordersErr)) {
    // Handle error appropriately
}

// Or use the global instance
const [page, pageErr] = await attempt(() => Fetch.get('https://logosdx.dev/cheat-sheet.html'));

The ObserverEngine is a mature event system with typed topics, regex subscriptions, async iteration, and priority queues. It's a great way to coordinate work across your application. Use it to build event-driven systems, background work, and more.

import { ObserverEngine } from '@logosdx/observer'

interface Events {
    'order:created': { id: string; total: number }
}

const bus = new ObserverEngine<Events>()

bus.on('order:created', ({ id }) => queueFulfillment(id));
bus.queue('order:created', processOrder, { concurrency: 4 });

Combine all these utilities together to build robust, resilient, and maintainable applications.

import { attempt, assert, isDefined } from '@logosdx/utils';
import { $, attrs } from '@logosdx/dom';
import { ObserverEngine } from '@logosdx/observer';
import { FetchEngine } from '@logosdx/fetch';
import { StorageAdapter, LocalStorageDriver } from '@logosdx/storage';

type Events = {
    'app:ready': void;
}

const bus = new ObserverEngine<Events>();

type AppStorage = {
    apiState: AppState;
}

const storage = new StorageAdapter<AppStorage>({
    driver: new LocalStorageDriver(localStorage),
    prefix: 'logosdx',
});


const generateHmac = async (secret: string, _message: unknown) => {

    assert(isDefined(_message), 'Message must be a string');
    assert(typeof secret === 'string', 'Secret must be a string');

    // Encode the secret key and message as Uint8Array
    // const encoder = new TextEncoder();
    // ...
    // const cryptoKey = await window.crypto.subtle.importKey(...)

    return hashHex;
}

interface AppHeaders {
    'X-Client-Version': string;
    'X-HMAC-Token': string;
    'X-Timestamp': string;
}

interface AppState {
    userId: string;
    jwt: string;
}

const api = new FetchEngine<
    AppHeaders,
    {},
    AppState,
>({
    baseUrl: window.location.origin
});

api.on('state-set', (state) => storage.set('apiState', state));

const app = async () => {

    const [apiState, apiErr] = await attempt(() => storage.get('apiState'));

    if (apiErr) throw apiErr;

    api.state.set(apiState); // Restore the state after a refresh

    bus.emit('app:ready');
}

app();

Principles and guarantees

• Observability: Hooks are added, events are emitted, and metrics are collected so work can be measured and traced.
• Compatibility: Works with native fetch and standard browser/Node APIs; no custom runtimes required.
• Versioning discipline: Semantic versioning; no breaking changes in minor releases.
• Type safety: Types are always prioritized for an optimal developer experience.
• Minimal dependencies: Only @logosdx/* packages—no dependency hell, no abandoned addons.