— @zhaoworks/query-state

Declarative React components for managing async query states.

Installation

λ bun add @zhaoworks/query-state

Usage

import QueryState, { useQueryState } from '@zhaoworks/query-state';

// → Basic usage with QueryState (default export)
function UserProfile({ userId }) {
  const [data, setData] = useState(null);
  const [error, setError] = useState(null);
  const [status, setStatus] = useState('loading');

  useEffect(() => {
    fetchUser(userId).then(
      user => (setData(user), setStatus('success')),
      err => (setError(err), setStatus('error'))
    )
  }, [userId]);

  return (
    <QueryState.Root data={data} error={error} status={status}>
      <QueryState.Pending>
        <div>Loading user...</div>
      </QueryState.Pending>
      <QueryState.Success>{(user: { name: string }) => <h1>Hello, {user.name}!</h1>}</QueryState.Success>
      <QueryState.Error>{(error: Error) => <div>Failed to load: {error.message}</div>}</QueryState.Error>
      <QueryState.Empty><div>No user found</div></QueryState.Empty>
    </QueryState.Root>
  );
}

// → Use `useQueryState` for a type-safe alternative to QueryState
function UserProfileTyped({ userId }) {
  const query = useAsyncQuery(() => fetchUser(userId), [userId]);
  const Query = useQueryState<User, Error>(query);

  return (
    <Query.Root>
      <Query.Pending>
        <div>Loading user...</div>
      </Query.Pending>
      <Query.Success>{(user) => <h1>Hello, {user.name}!</h1>}</Query.Success>{/* ← user is typed as User */}
      <Query.Error>{(error) => <div>Failed: {error.message}</div>}</Query.Error>{/* ← error is typed as Error */}
    </Query.Root>
  );
}

API

Components

• Root — Provides query context with optional loading delay
• Pending — Shows content while loading
• Success — Shows content when query succeeds
• Error — Shows content when query fails
• Result — Handles both success and error states
• Empty — Shows content when data is empty

Hooks

• useQueryState(query) — Creates type-safe components (recommended)
• useQueryInfo() — Access query context data

Types

• QueryStatus — 'loading' | 'success' | 'error'
• QueryInfo<T, E> — Contains data, error, and status

License

MIT