Logos DX

https://logosdx.dev/
Admin
Logos DX is a collection of focused TypeScript utilities for building JavaScript applications on any...
Tokens:665,353
Snippets:9,399
Trust Score:7.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### FetchEngine Production Setup

Source: https://logosdx.dev/packages/fetch/advanced.html

Example of initializing FetchEngine for a production environment with timeouts, headers, and deduplication.

```APIDOC
## FetchEngine Production Initialization

### Description
Configures a production-ready FetchEngine instance with global headers, request timeouts, and deduplication policies.

### Configuration Options
- **baseUrl** (string) - The base URL for API requests
- **defaultType** (string) - Default response type (e.g., 'json')
- **totalTimeout** (number) - Maximum time for the entire operation
- **attemptTimeout** (number) - Maximum time per individual attempt
- **requestIdHeader** (string) - Header name for distributed tracing
- **headers** (object) - Global headers to include in every request
- **dedupePolicy** (object) - Configuration for preventing duplicate concurrent requests
```

--------------------------------

### FetchEngine Plugin Installation

Source: https://logosdx.dev/packages/fetch/plugins.html#at-construction-time

How to configure and install plugins during FetchEngine initialization.

```APIDOC
## FetchEngine Constructor Plugins

### Description
Plugins are passed to the FetchEngine constructor to extend request lifecycle behavior. Multiple plugins can be provided in the plugins array.

### Usage
```typescript
import { FetchEngine, retryPlugin, cachePlugin, dedupePlugin, rateLimitPlugin } from '@logosdx/fetch';

const api = new FetchEngine({
    baseUrl: 'https://api.example.com',
    plugins: [
        retryPlugin({ maxAttempts: 3, baseDelay: 1000 }),
        cachePlugin({ ttl: 60000, staleIn: 30000 }),
        dedupePlugin(true),
        rateLimitPlugin({ maxCalls: 100, windowMs: 60000 }),
    ]
});
```
```

--------------------------------

### Quick Start with HookEngine

Source: https://logosdx.dev/packages/hooks.html

Basic setup for defining a lifecycle interface and executing hooks within a function.

```typescript
import { HookEngine } from '@logosdx/hooks';

interface FetchLifecycle {
    beforeFetch(url: string, options: RequestInit): Promise<Response>;
    afterFetch(response: Response, url: string): Promise<Response>;
}

const hooks = new HookEngine<FetchLifecycle>()
    .register('beforeFetch', 'afterFetch');

// Callbacks receive spread args + ctx as last param
hooks.add('beforeFetch', (url, options, ctx) => {
    ctx.args(url, {
        ...options,
        headers: { ...options.headers, Authorization: `Bearer ${token}` }
    });
});

// In your library code
async function fetchWithHooks(url: string, options: RequestInit = {}) {

    const pre = await hooks.run('beforeFetch', url, options);
    if (pre.returned) return pre.result!;

    const response = await fetch(...pre.args);

    const post = await hooks.run('afterFetch', response, url);
    return post.returned ? post.result! : response;
}
```

--------------------------------

### OPTIONS Request Example

Source: https://logosdx.dev/packages/fetch/requests.html#delete

Example of checking server capabilities by retrieving headers.

```typescript
const { headers } = await api.options('/users');
```

--------------------------------

### GET Request Examples

Source: https://logosdx.dev/packages/fetch/requests.html#delete

Examples of retrieving data with and without additional query parameters.

```typescript
const users = await api.get<User[]>('/users');
if (users.ok) console.log(users.data); // User[]

const user = await api.get<User>('/users/123', {
    params: { include: 'profile' }
});
if (user.ok) console.log(user.data); // User
```

--------------------------------

### Install @logosdx/fetch

Source: https://logosdx.dev/packages/fetch

Installation commands for various package managers.

```bash
npm install @logosdx/fetch
```

```bash
yarn add @logosdx/fetch
```

```bash
pnpm add @logosdx/fetch
```

--------------------------------

### Install @logosdx/utils

Source: https://logosdx.dev/packages/utils

Installation commands for various package managers.

```bash
npm install @logosdx/utils
```

```bash
yarn add @logosdx/utils
```

```bash
pnpm add @logosdx/utils
```

--------------------------------

### Install Observer via Package Managers

Source: https://logosdx.dev/packages/observer#debug-on-boolean

Standard installation commands for common JavaScript package managers.

```bash
npm install @logosdx/observer
```

```bash
yarn add @logosdx/observer
```

```bash
pnpm add @logosdx/observer
```

--------------------------------

### FetchEngine.use()

Source: https://logosdx.dev/packages/fetch/plugins.html#at-construction-time

Dynamically install a plugin at runtime.

```APIDOC
## FetchEngine.use(plugin)

### Description
Installs a plugin at runtime and returns an uninstall function to remove the plugin's hooks.

### Usage
```typescript
const uninstall = api.use(myPlugin);

// Later, remove the plugin's hooks
uninstall();
```
```

--------------------------------

### Install State Machine Package

Source: https://logosdx.dev/packages/state-machine

Install the library using your preferred package manager.

```bash
npm install @logosdx/state-machine
```

```bash
yarn add @logosdx/state-machine
```

```bash
pnpm add @logosdx/state-machine
```

--------------------------------

### Install @logosdx/localize

Source: https://logosdx.dev/packages/localize

Installation commands for various package managers.

```bash
npm install @logosdx/localize
```

```bash
yarn add @logosdx/localize
```

```bash
pnpm add @logosdx/localize
```

--------------------------------

### HEAD Request Example

Source: https://logosdx.dev/packages/fetch/requests.html#delete

Example of retrieving headers for a specific resource.

```typescript
const { headers } = await api.head('/users/123');
```

--------------------------------

### Install @logosdx/hooks

Source: https://logosdx.dev/packages/hooks.html

Installation commands for various package managers.

```bash
npm install @logosdx/hooks
```

```bash
yarn add @logosdx/hooks
```

```bash
pnpm add @logosdx/hooks
```

--------------------------------

### Token Bucket Configuration Example

Source: https://logosdx.dev/packages/fetch/policies.html

Example configuration for a specific rate limit of 10 requests per minute.

```typescript
// Example: 10 requests per minute = 1 token every 6 seconds
{
    maxCalls: 10,
    windowMs: 60000  // 60000ms / 10 = 6000ms per token
}
```

--------------------------------

### withInflightDedup Usage Examples

Source: https://logosdx.dev/packages/utils/performance.html

Practical examples demonstrating basic usage, observability hooks, custom key generation, and conditional deduplication.

```typescript
import { withInflightDedup, attempt } from '@logosdx/utils'

// Basic usage - database query deduplication
const fetchUser = async (id: string) => db.users.findById(id)
const getUser = withInflightDedup(fetchUser)

// Three concurrent calls -> one database query
const [user1, user2, user3] = await Promise.all([
    getUser("42"),
    getUser("42"),
    getUser("42")
])

// With hooks for observability
const search = async (q: string) => api.search(q)
const dedupedSearch = withInflightDedup(search, {
    onStart: (k) => logger.debug("search started", k),
    onJoin: (k) => logger.debug("joined existing search", k),
    onResolve: (k) => logger.debug("search completed", k),
    onReject: (k, e) => logger.error("search failed", k, e),
})

// Custom key - ignore volatile parameters
const fetchData = async (id: string, opts: { timestamp?: number }) => {

    const response = await fetch(`/api/data/${id}`)
    return response.json()
}

const dedupedFetch = withInflightDedup(fetchData, {
    generateKey: (id) => id  // Only dedupe by id, ignore opts
})

// Conditional deduplication - bypass for cache-busting requests
const smartFetch = withInflightDedup(fetchData, {
    shouldDedupe: (id, opts) => !opts?.bustCache
})

// Normal calls are deduped
await Promise.all([
    smartFetch("42"),
    smartFetch("42")
])  // -> one request

// Cache-busting calls bypass deduplication
await smartFetch("42", { bustCache: true })  // -> executes independently
```

--------------------------------

### Install plugins at construction

Source: https://logosdx.dev/packages/fetch/plugins.html

Register built-in plugins during FetchEngine initialization.

```typescript
import { FetchEngine, retryPlugin, cachePlugin, dedupePlugin, rateLimitPlugin } from '@logosdx/fetch';

const api = new FetchEngine({
    baseUrl: 'https://api.example.com',
    plugins: [
        retryPlugin({ maxAttempts: 3, baseDelay: 1000 }),
        cachePlugin({ ttl: 60000, staleIn: 30000 }),
        dedupePlugin(true),
        rateLimitPlugin({ maxCalls: 100, windowMs: 60000 }),
    ]
});
```

--------------------------------

### Quick Start with StorageAdapter

Source: https://logosdx.dev/packages/storage#driver-pattern

Initialize the storage adapter with a driver and perform basic CRUD operations.

```typescript
import { StorageAdapter, LocalStorageDriver } from '@logosdx/storage'

interface AppStorage {
    user: { id: string; name: string; email: string }
    settings: { theme: 'light' | 'dark'; notifications: boolean }
    cart: { id: string; quantity: number }[]
}

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

// All operations are async
await storage.set('user', { id: '123', name: 'Jane', email: 'jane@example.com' })
const user = await storage.get('user')

// Subscribe to updates (returns cleanup function)
const cleanup = storage.on('after-set', (event) => {
    console.log('Set:', event.key, event.value)
})

// Merge object properties
await storage.assign('settings', { notifications: false })

// Remove and clear
await storage.rm(['user', 'settings'])
await storage.clear()

// Cleanup listener when done
cleanup()
```

--------------------------------

### Initialize via CDN

Source: https://logosdx.dev/packages/state-machine

Include the library in a browser environment using a script tag.

```html
<script src="https://cdn.jsdelivr.net/npm/@logosdx/state-machine@latest/dist/browser/bundle.min.js"></script>
<script>
    const { StateMachine, StateHub } = LogosDx.StateMachine;
</script>
```

--------------------------------

### Install @logosdx/dom

Source: https://logosdx.dev/packages/dom

Installation commands for various package managers.

```bash
npm install @logosdx/dom
```

```bash
yarn add @logosdx/dom
```

```bash
pnpm add @logosdx/dom
```

--------------------------------

### Initialize StateMachine

Source: https://logosdx.dev/llms-full.txt

Demonstrates creating a machine instance with initial state, context, and transition logic.

```ts
import { StateMachine } from '@logosdx/state-machine'

const machine = new StateMachine<CheckoutContext, CheckoutEvents>({
    initial: 'idle',
    context: { items: [], error: null },
    transitions: {
        idle: {
            on: {
                FETCH: 'loading',
                ADD_ITEM: {
                    target: 'idle',
                    action: (ctx, data) => ({ ...ctx, items: [...ctx.items, data] }),
                },
            },
        },
        loading: {
            on: {
                SUCCESS: {
                    target: 'idle',
                    action: (ctx, data) => ({ ...ctx, items: data.items }),
                },
                FAILURE: {
                    target: 'error',
                    action: (ctx, data) => ({ ...ctx, error: data.message }),
                },
            },
        },
        error: {
            on: {
                RETRY: 'loading',
                RESET: {
                    target: 'idle',
                    action: () => ({ items: [], error: null }),
                },
            },
        },
    },
})

// Properties
machine.state    // 'idle' — current state name
machine.context  // { items: [], error: null } — cloned, safe to read
```

--------------------------------

### FetchEngine Configuration

Source: https://logosdx.dev/packages/fetch/advanced.html#VPContent

Example of initializing a FetchEngine instance with production-ready settings such as timeouts, global headers, and request deduplication policies.

```APIDOC
## FetchEngine Initialization

### Description
Initializes a new FetchEngine instance with specific production configurations including timeouts, headers, and deduplication rules.

### Request Example
```typescript
const api = new FetchEngine({
    baseUrl: process.env.API_BASE_URL!,
    defaultType: 'json',
    totalTimeout: 30000,
    attemptTimeout: 10000,
    requestIdHeader: 'X-Request-Id',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    },
    dedupePolicy: {
        enabled: true,
        methods: ['GET'],
        rules: [
            { includes: '/realtime', enabled: false },
            { includes: '/stream', enabled: false }
        ]
    }
});
```
```

--------------------------------

### PUT Request Example

Source: https://logosdx.dev/packages/fetch/requests.html#delete

Example of replacing an existing resource.

```typescript
const replaced = await api.put<User, UpdateUserData>('/users/123', {
    name: 'Jane Doe',
    email: 'jane@example.com'
});
if (replaced.ok) console.log(replaced.data); // User
```

--------------------------------

### Initialize and Use HookEngine

Source: https://logosdx.dev/llms-full.txt

Demonstrates registering hooks, subscribing to events, running hooks, and wrapping functions with pre/post hooks.

```typescript
import { HookEngine, HookScope, HookError, isHookError } from '@logosdx/hooks';

interface Lifecycle {
    beforeFetch(url: string, options: RequestInit): Promise<Response>;
    afterFetch(result: Response, url: string): Promise<Response>;
}

const hooks = new HookEngine<Lifecycle>()
    .register('beforeFetch', 'afterFetch');

// Subscribe — callbacks receive spread args + ctx as last param
const cleanup = hooks.add('beforeFetch', (url, options, ctx) => {
    ctx.args(url, { ...options, cache: 'no-store' });
});

// Run
const result = await hooks.run('beforeFetch', url, options);
// result.args, result.result, result.returned, result.scope

// Wrap function with pre/post hooks
const wrapped = hooks.wrap(fn, { pre: 'beforeFetch', post: 'afterFetch' });

// Clear all
hooks.clear();

// Remove subscription
cleanup();
```

--------------------------------

### Queue Usage Example

Source: https://logosdx.dev/packages/observer/queues.html#add

Demonstrates initializing a queue, monitoring events, adding items with priority, and controlling processing flow.

```typescript
const queue = observer.queue('data:process', async (data) => {
    await processData(data)
}, {
    name: 'data-processor',
    concurrency: 5,
    rateLimitCapacity: 100,
    rateLimitIntervalMs: 1000,
    taskTimeoutMs: 30000
})

// Monitor queue
queue.on('error', (item) => {
    console.error('Processing failed:', item.error)
})

queue.on('idle', () => {
    console.log('Queue is idle')
})

// Add items with priority
queue.add(urgentData, 10)  // High priority
queue.add(normalData, 1)   // Low priority

// Control processing
await queue.flush(10)      // Process 10 items
queue.pause()              // Pause processing
queue.resume()             // Resume processing
await queue.shutdown()     // Graceful shutdown
```

--------------------------------

### POST Request Example

Source: https://logosdx.dev/packages/fetch/requests.html#delete

Example of creating a resource by sending a payload.

```typescript
const created = await api.post<User, CreateUserData>('/users', {
    name: 'John Doe',
    email: 'john@example.com'
});
if (created.ok) console.log(created.data); // User
```

--------------------------------

### Setup React context and providers

Source: https://logosdx.dev/packages/react.html#api-hooks-vs-fetch-context

Initialize engine instances and create context/hook pairs for use in the application.

```typescript
// setup.ts — run once, types inferred from instances
import { ObserverEngine } from '@logosdx/observer';
import { FetchEngine } from '@logosdx/fetch';
import { StorageAdapter, WebStorageDriver } from '@logosdx/storage';
import { LocaleManager } from '@logosdx/localize';
import { StateMachine } from '@logosdx/state-machine';
import {
    createObserverContext,
    createFetchContext,
    createStorageContext,
    createLocalizeContext,
    createStateMachineContext,
    composeProviders,
} from '@logosdx/react';

// Create your engine instances
const observer = new ObserverEngine<AppEvents>();
const api = new FetchEngine({ baseUrl: 'https://api.example.com' });
const storage = new StorageAdapter<AppStore>({
    driver: new WebStorageDriver(localStorage),
    prefix: 'myapp',
});
const i18n = new LocaleManager({ current: 'en', fallback: 'en', locales });
const game = new StateMachine<GameContext, GameEvents, GameStates>({ ... });

// Create context + hook pairs — rename freely
export const [AppObserver, useAppObserver] = createObserverContext(observer);
export const [ApiFetch, useApiFetch] = createFetchContext(api);
export const [AppStorage, useAppStorage] = createStorageContext(storage);
export const [AppLocale, useAppLocale] = createLocalizeContext(i18n);
export const [GameProvider, useGame] = createStateMachineContext(game);

// Compose into a single wrapper — no nesting required
export const Providers = composeProviders(
    AppObserver,
    ApiFetch,
    AppStorage,
    AppLocale,
    GameProvider,
);
```

--------------------------------

### Install @logosdx/storage

Source: https://logosdx.dev/packages/storage#driver-pattern

Commands to install the package using common package managers.

```bash
npm install @logosdx/storage
```

```bash
yarn add @logosdx/storage
```

```bash
pnpm add @logosdx/storage
```

--------------------------------

### Basic Configuration Usage

Source: https://logosdx.dev/llms-full.txt

Example of initializing a nested configuration from process.env and performing path-based lookups and overrides.

```ts
// Given process.env: APP_DB_HOST='localhost', APP_DB_PORT='5432', APP_DEBUG='true'
type AppConfig = {
  db: { host: string; port: number };
  debug: boolean;
}

const config = makeNestedConfig<AppConfig>(process.env, {
  filter: (key) => key.startsWith('APP_'),
  stripPrefix: 'APP_',
  forceAllCapToLower: true
})

config.allConfigs()                   // { db: { host: 'localhost', port: 5432 }, debug: true }
config.getConfig('db.host')           // 'localhost'
config.getConfig('db.port')           // 5432
config.getConfig('api.timeout', 5000) // 5000 (default for missing path)

config.updateParsedConfig({ db: { host: 'db.internal' } })
config.allConfigs().db.host           // 'db.internal' (override wins, survives re-parse)
```

--------------------------------

### Install engine dependencies

Source: https://logosdx.dev/packages/react.html#api-hooks-vs-fetch-context

Install the specific engine packages required for your application.

```bash
pnpm add @logosdx/observer @logosdx/fetch @logosdx/storage @logosdx/localize @logosdx/state-machine
```

--------------------------------

### DELETE Request Examples

Source: https://logosdx.dev/packages/fetch/requests.html#delete

Examples of deleting a resource with and without a request body.

```typescript
await api.delete('/users/123');

// With request body
await api.delete('/users/batch', { ids: ['1', '2', '3'] });
```

--------------------------------

### Initialize Production FetchEngine

Source: https://logosdx.dev/packages/fetch/advanced.html#VPContent

Example configuration for production environments, including timeouts, tracing headers, and request deduplication policies.

```typescript
const api = new FetchEngine({
    baseUrl: process.env.API_BASE_URL!,
    defaultType: 'json',
    totalTimeout: 30000,      // 30s max for entire operation
    attemptTimeout: 10000,    // 10s per attempt

    // Distributed tracing - sends requestId as header to server
    requestIdHeader: 'X-Request-Id',

    // Global headers
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    },

    // Request deduplication - prevent duplicate concurrent requests
    dedupePolicy: {
        enabled: true,
        methods: ['GET'],
        rules: [
            { includes: '/realtime', enabled: false },
            { includes: '/stream', enabled: false }
        ]
    },
})
```

--------------------------------

### GET Request Method

Source: https://logosdx.dev/packages/fetch/requests.html

Retrieve data from the server using the GET method.

```typescript
api.get<Res, ResHdr>(path: string, options?: CallConfig): FetchPromise<Res>
```

```typescript
const users = await api.get<User[]>('/users');
if (users.ok) console.log(users.data); // User[]

const user = await api.get<User>('/users/123', {
    params: { include: 'profile' }
});
if (user.ok) console.log(user.data); // User
```

--------------------------------

### new StateMachine<Context, Events>(config, options)

Source: https://logosdx.dev/packages/state-machine/api.html#cancellation

Initializes a new state machine instance with the provided configuration and optional settings.

```APIDOC
## Constructor

### Description
Creates a new instance of the StateMachine.

### Signature
`new StateMachine<Context, Events>(config: StateMachine.Config<Context, Events>, options?: StateMachine.Options)`

### Parameters
- **config** (StateMachine.Config) - Required - The configuration object defining initial state, context, and transitions.
- **options** (StateMachine.Options) - Optional - Configuration for persistence or other machine behaviors.
```

--------------------------------

### afterRequest Hook Examples

Source: https://logosdx.dev/packages/fetch/hooks.html#adding-hooks

Examples for caching successful responses and transforming response data.

```typescript
// Cache successful responses
api.hooks.add('afterRequest', (response, url, opts, ctx) => {

    if (opts.method === 'GET' && response.status === 200) {
        myCache.set(url.toString(), response);
    }
});

// Replace the response
api.hooks.add('afterRequest', (response, url, opts, ctx) => {

    return ctx.returns({
        ...response,
        data: transformData(response.data)
    });
});
```

--------------------------------

### new StateMachine<Context, Events>(config, options)

Source: https://logosdx.dev/packages/state-machine/api.html

Initializes a new state machine instance with the provided configuration and optional persistence settings.

```APIDOC
## Constructor

### Description
Creates a new instance of the StateMachine.

### Signature
`new StateMachine<Context, Events>(config: StateMachine.Config<Context, Events>, options?: StateMachine.Options)`

### Parameters
- **config** (StateMachine.Config) - Required - The configuration object defining initial state, context, and transitions.
- **options** (StateMachine.Options) - Optional - Configuration for persistence across sessions.
```

--------------------------------

### Generic Request Example

Source: https://logosdx.dev/packages/fetch/requests.html#delete

Example of using the generic request method with a custom payload and headers.

```typescript
const res = await api.request<User>('PATCH', '/users/123', {
    payload: { name: 'Updated' },
    headers: { 'X-Custom': 'value' }
});
if (res.ok) console.log(res.data); // User
```

--------------------------------

### execute Hook Examples

Source: https://logosdx.dev/packages/fetch/hooks.html#adding-hooks

Examples of onion-style middleware for timing requests and implementing circuit breakers.

```typescript
// Timing middleware
api.hooks.add('execute', async (next, opts) => {

    const start = Date.now();
    const response = await next();
    console.log(`${opts.method} ${opts.path} took ${Date.now() - start}ms`);

    return response;
});

// Circuit breaker
api.hooks.add('execute', async (next, opts, ctx) => {

    if (circuitOpen) {
        throw new Error('Circuit breaker open');
    }

    return next();
});
```

--------------------------------

### StorageAdapter Initialization

Source: https://logosdx.dev/llms-full.txt

Examples of initializing StorageAdapter with various drivers including LocalStorage, SessionStorage, FileSystem, and IndexedDB.

```APIDOC
## StorageAdapter Initialization

### Description
Initialize a storage adapter with a specific driver to persist data in different environments.

### Drivers
- **LocalStorageDriver**: Browser-based storage using localStorage.
- **SessionStorageDriver**: Browser-based storage using sessionStorage.
- **FileSystemDriver**: Node.js-based storage using a JSON file.
- **IndexedDBDriver**: Browser-based storage using IndexedDB for structured data.

### Example
```typescript
const local = new StorageAdapter<AppStorage>({
    driver: new LocalStorageDriver(),
    prefix: 'app'
});

const file = new StorageAdapter<AppSettings>({
    driver: new FileSystemDriver('./data/settings.json'),
    prefix: 'config'
});
```
```

--------------------------------

### Install LogosDX React and Engines

Source: https://logosdx.dev/packages/react.html

Commands to install the core React package and specific engine dependencies.

```bash
npm install @logosdx/react
```

```bash
yarn add @logosdx/react
```

```bash
pnpm add @logosdx/react
```

```bash
pnpm add @logosdx/observer @logosdx/fetch @logosdx/storage @logosdx/localize @logosdx/state-machine
```

--------------------------------

### Initialize FetchEngine with Plugins

Source: https://logosdx.dev/llms-full.txt

Configures the engine with standard resilience plugins and demonstrates direct access to plugin-specific methods.

```typescript
import { cachePlugin, dedupePlugin, retryPlugin, rateLimitPlugin, cookiePlugin } from '@logosdx/fetch';

// Create plugins
const cache = cachePlugin({ ttl: 300000, staleIn: 60000 });
const dedupe = dedupePlugin(true);
const retry = retryPlugin({ maxAttempts: 3 });
const rateLimit = rateLimitPlugin({ maxCalls: 100, windowMs: 60000 });
const cookies = cookiePlugin();

// Use with FetchEngine
const api = new FetchEngine({
    baseUrl: 'https://api.example.com',
    plugins: [cache, dedupe, retry, rateLimit, cookies]
});

// Access plugin methods directly
cache.clearCache();
cache.stats();   // { cacheSize, inflightCount }
dedupe.inflightCount();
```

--------------------------------

### Implement and Use Persistence

Source: https://logosdx.dev/packages/state-machine/api.html

Example of implementing a localStorage adapter and initializing a machine with persistence enabled.

```typescript
const adapter: StorageAdapter = {
    load: async (key) => {
        const raw = localStorage.getItem(key)
        return raw ? JSON.parse(raw) : null
    },
    save: async (key, snapshot) => {
        localStorage.setItem(key, JSON.stringify(snapshot))
    },
}

const machine = new StateMachine(config, {
    persistence: { key: 'checkout', adapter },
})

// Wait for hydration before using
await machine.ready()
```

--------------------------------

### Install LogosDX React package

Source: https://logosdx.dev/packages/react.html#api-hooks-vs-fetch-context

Commands to install the core React package using different package managers.

```bash
npm install @logosdx/react
```

```bash
yarn add @logosdx/react
```

```bash
pnpm add @logosdx/react
```

--------------------------------

### Type Coercion Usage Examples

Source: https://logosdx.dev/packages/utils/data.html#array-utilities

Examples of coercing strings to booleans/numbers, parsing units, and skipping specific keys.

```typescript
import { castValuesToTypes } from '@logosdx/utils'

const config = {
    debug: 'true',        // -> true
    verbose: 'yes',       // -> true
    silent: 'false',      // -> false
    disabled: 'no',       // -> false
    port: '3000',         // -> 3000
    timeout: '5000',      // -> 5000
    name: 'myapp',        // -> 'myapp' (unchanged)
    nested: {
        enabled: 'true',  // -> true (recursive)
        retries: '5'      // -> 5 (recursive)
    }
}

castValuesToTypes(config)  // Mutates in place

console.log(config.debug)  // true (boolean)
console.log(config.port)   // 3000 (number)

// Parse unit values
const configWithUnits = {
    timeout: '5m',
    maxSize: '10mb',
    debug: 'true'
}

castValuesToTypes(configWithUnits, { parseUnits: true })
console.log(configWithUnits.timeout)  // 300000 (5 minutes in ms)
console.log(configWithUnits.maxSize)  // 10485760 (10 MB in bytes)

// Skip conversion for specific keys
const configWithSkip = {
    apiKey: '12345',
    port: '3000'
}

castValuesToTypes(configWithSkip, {
    skipConversion: (key) => key.toLowerCase().includes('key')
})
console.log(configWithSkip.apiKey)  // '12345' (kept as string)
console.log(configWithSkip.port)    // 3000 (converted to number)
```
Tokens:
Raw