# Atomico Hooks Async

> Atomico Hooks Async is an Agent Skill for development published in the atomicojs/atomico repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use usePromise, useAsync, useSuspense, and useAbortController hooks for asynchronous data fetching and loading state management. Triggers when the user needs to fetch data, handle loading/error/fulfilled states, implement suspense boundaries, or abort in-flight requests in Atomico components.

- Skill name: `atomico-hooks-async`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/atomicojs/atomico/blob/HEAD/.agents/skills/atomico-hooks-async/SKILL.md
- Repository: atomicojs/atomico (1,276 GitHub stars when collected)

## SKILL.md

# Async Hooks

## `usePromise` — Promise State Tracking

Executes an async callback and tracks its lifecycle state (pending, fulfilled,
rejected, aborted). Integrates with `useSuspense` automatically.

### API

```ts
const state = usePromise(callback, args?, autorun?);
```

### Return Type

```ts
interface PromiseState<T> {
    result?: T;
    pending?: boolean;
    fulfilled?: boolean;
    rejected?: boolean;
    aborted?: boolean;
}
```

### Basic Usage

```tsx
import { c, usePromise } from "atomico";

interface Photo {
    albumId: number;
    id: number;
    title: string;
    url: string;
    thumbnailUrl: string;
}

const PhotoList = c(() => {
    const promise = usePromise(
        async (): Promise<Photo[]> =>
            await fetch("https://jsonplaceholder.typicode.com/photos")
                .then((res) => res.json()),
        []  // Dependencies — empty = run once
    );

    return (
        <host>
            <ul>
                {promise.fulfilled ? (
                    promise.result.map((item) => <li>{item.title}</li>)
                ) : (
                    <li>Loading...</li>
                )}
            </ul>
        </host>
    );
});
```

### With Dependencies

```tsx
const UserProfile = c(
    ({ userId }) => {
        const promise = usePromise(
            async (id: number) =>
                fetch(`/api/users/${id}`).then((r) => r.json()),
            [userId]  // Re-fetches when userId changes
        );

        return (
            <host>
                {promise.pending && <p>Loading...</p>}
                {promise.fulfilled && <h1>{promise.result.name}</h1>}
                {promise.rejected && <p>Error loading user</p>}
            </host>
        );
    },
    { props: { userId: Number } }
);
```

### Conditional Execution (autorun)

```tsx
const [shouldFetch, setShouldFetch] = useState(false);

const promise = usePromise(
    async () => fetch("/api/data").then((r) => r.json()),
    [],
    shouldFetch  // Only executes when true
);
```

---

## `useAsync` — Suspense-Based Async

Wraps `usePromise` but throws a `SUSPENSE` signal while pending. The component
won't render until the promise resolves. **Must be used within a `useSuspense`
boundary**.

### API

```ts
const result = useAsync<T>(callback, args);
```

### Usage

```tsx
import { c, useAsync } from "atomico";

const PhotoList = c(() => {
    // Component suspends until data is available
    const result = useAsync(
        async (): Promise<Photo[]> =>
            await fetch("https://jsonplaceholder.typicode.com/photos")
                .then((res) => res.json()),
        []
    );

    // `result` is always the resolved value — no pending/rejected checks needed
    return (
        <host>
            <ul>
                {result.map((item) => <li>{item.title}</li>)}
            </ul>
        </host>
    );
});
```

> **Note**: If `useAsync` is used without a `useSuspense` parent, the SUSPENSE
> error will propagate and the component won't render at all.

---

## `useSuspense` — Loading Boundary

Creates a suspense boundary that tracks all `usePromise`/`useAsync` states in
its subtree via context. Returns an aggregated status.

### API

```ts
const status = useSuspense(fps?: number);
```

### Return Type

```ts
interface SuspenseStatus {
    pending?: boolean;
    fulfilled?: boolean;
    rejected?: boolean;
    aborted?: boolean;
}
```

### Usage

```tsx
import { c, css, useSuspense, usePromise } from "atomico";

const DataLoader = c(
    ({ delay }) => {
        const promise = usePromise(
            async (ms: number): Promise<string> =>
                new Promise((resolve) => setTimeout(() => resolve("done"), ms)),
            [delay]
        );

        return (
            <host>
                {promise.pending
                    ? `Loading... (${delay}ms)`
                    : promise.fulfilled
                    ? promise.result
                    : ""}
            </host>
        );
    },
    { props: { delay: Number } }
);

const App = c(
    () => {
        const status = useSuspense();

        return (
            <host shadowDom>
                <h1>{status.pending ? "Loading..." : "All done!"}</h1>
                <DataLoader delay={3000} />
                <DataLoader delay={5000} />
            </host>
        );
    },
    {
        styles: css`
            :host { display: grid; gap: 1rem; }
        `
    }
);
```

### Context Integration

`useSuspense` uses Atomico's context system internally. The `SuspenseContext`
propagates through the DOM tree, so any `usePromise` call in a descendant
automatically communicates its status to the nearest `useSuspense` ancestor.

---

## `useAbortController` — Cancellable Requests

Creates an `AbortController` that is automatically aborted when dependencies
change or the component unmounts.

### API

```ts
const controller = useAbortController(args);
```

### Usage with Fetch

```tsx
import { c, useAbortController, usePromise } from "atomico";

const MyComponent = c(
    ({ query }) => {
        const controller = useAbortController([query]);

        const promise = usePromise(
            async (q: string) =>
                fetch(`/api/search?q=${q}`, {
                    signal: controller.signal
                }).then((r) => r.json()),
            [query]
        );

        return (
            <host>
                {promise.pending && <p>Searching...</p>}
                {promise.aborted && <p>Request cancelled</p>}
                {promise.fulfilled && <p>Found: {promise.result.length}</p>}
            </host>
        );
    },
    { props: { query: String } }
);
```

### Lifecycle

1. A new `AbortController` is created via `useMemo` when `args` change
2. The previous controller is aborted via `useEffect` cleanup
3. On component unmount, the current controller is aborted

---

Source: https://www.openparable.com/skill/development/atomico-hooks-async (OpenParable). Cite the canonical URL above.
