OpenParable
Skip to content
← Back to skills

Atomico Hooks Async

Development
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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/atomicojs/atomico/blob/HEAD/.agents/skills/atomico-hooks-async/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/atomico-hooks-async, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Async Hooks

usePromise — Promise State Tracking

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

API

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

Return Type

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

Basic Usage

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

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)

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

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

Usage

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

const status = useSuspense(fps?: number);

Return Type

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

Usage

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

const controller = useAbortController(args);

Usage with Fetch

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