Getting started

Overview

What hapi is, and what it is not.

hapi is a typed pipeline over TanStack Query. You declare an endpoint once — method, path, and schemas — and get back one object carrying every way you might call it: the query hook, the suspense hook, the mutation, the infinite query, the options object for prefetching, and a plain promise for code that has no React in it.

It does not replace TanStack Query. Every option you pass to useQuery still reaches TanStack unchanged, and every key-driven API — invalidateQueries, useQueries, prefetchQuery, useMutationState — works on the keys hapi produces. hapi adds a declaration layer and a validated request pipeline underneath the parts you already use.

What it adds

• One declaration per endpoint, with every call shape derived from it.
• Request, response, and path-parameter validation, with any Zod-shaped or Standard Schema validator.
• A closed error union of eight tags, so error handling is a switch rather than a chain of instanceof checks.
• Cancellation and timeouts everywhere, including outside React.
• Cache keys that carry the resolved path, so two resources cannot share an entry.
• Eight lifecycle hooks, cascading from API to service to endpoint.

What it deliberately does not do

• Wrap QueryClient. You create and configure it yourself.
• Re-export TanStack hooks. Import those from TanStack.
• Normalise validation issues. A ZodError reaches you intact.
• Put headers in the cache key. See Cache keys for why, and what to do instead.