<!--
AUTO-GENERATED — DO NOT EDIT THIS FILE.
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
To change this document, edit the module-level JSDoc in src/index.ts.
Generated: 2026-10-16T23:37:21.992Z
-->

# @molecule/app-query-tanstack

TanStack Query bond for `@molecule/app-query`.

The molecule query contract over `@tanstack/query-core`: the same
`fetch` / `prefetch` / `get` / `subscribe` calls, backed by TanStack's
cache, deduplication, staleness and garbage collection. Wrap an app's
existing TanStack client so molecule packages and the app's own hooks
share one cache.

> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
> It is written to be read by coding agents as much as by people, and is generated from this
> package's source — edit `src/index.ts` JSDoc, not this file.

## Quick Start

```typescript
import { QueryClient } from '@tanstack/query-core'
import { setProvider } from '@molecule/app-query'
import { createProvider, provider } from '@molecule/app-query-tanstack'

setProvider(provider) // its own client
// or share the app's:
setProvider(createProvider({ client: new QueryClient() }))
```

## Type

`provider`

## Installation

```bash
npm install @molecule/app-query-tanstack @molecule/app-query @tanstack/query-core
```

## API

### Interfaces

#### `TanstackQueryConfig`

Provider-specific configuration options.

```typescript
interface TanstackQueryConfig {
  /**
   * An existing TanStack `QueryClient` to wrap, so an app that already uses
   * TanStack Query (its devtools, its hooks) shares one cache with molecule
   * packages. When omitted, each `createClient()` makes its own.
   */
  client?: TanstackQueryClient
}
```

### Functions

#### `createProvider(config)`

Creates a TanStack Query provider.

```typescript
function createProvider(config?: TanstackQueryConfig): QueryProvider
```

- `config` — Provider configuration.

**Returns:** A query provider.

### Constants

#### `provider`

Default TanStack Query provider instance.

```typescript
const provider: QueryProvider
```

## Core Interface

Implements `@molecule/app-query` interface.

## Bond Wiring

Setup function to register this provider with the core interface:

```typescript
import { setProvider } from '@molecule/app-query'
import { provider } from '@molecule/app-query-tanstack'

export function setupQueryTanstack(): void {
  setProvider(provider)
}
```

## Injection Notes

### Requirements

Peer dependencies:

- `@molecule/app-query` ^1.0.0

### Runtime Dependencies

- `@molecule/app-query`
- `@tanstack/query-core`

- **Retries are off.** The contract says a failed fetch rejects and is not
  cached; TanStack's default of three retries would hide that. Wrap
  `fetch` yourself if a query should retry.
- `invalidate(key)` marks matching queries stale without refetching them;
  observers refetch on their next subscription and `fetch()` refetches on
  its next call, exactly as with the memory bond.
- A query nobody observes is garbage-collected `gcMs` after its last use
  (TanStack's `gcTime`), so `get()` can return `undefined` for something
  fetched long ago; treat it as a cache.
- Framework hooks live in `@molecule/app-query-react`, not here; this bond
  depends only on `@tanstack/query-core`.

## E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt
each item to this app's actual screens/flows, and check every box off one
by one. A box you can't check is an integration bug to fix — not a skip:

- [ ] Opening a detail page after hovering its link shows no loading
      state (the document was warmed) and the page is the right one.
- [ ] Opening the same page twice fetches it once (check the network panel).
- [ ] Going back to a page painted earlier paints at once, from memory.
- [ ] After the app invalidates a key (an edit, a refresh action), the
      next view shows the new data.
- [ ] With the browser's data-saver on, hovering links fetches nothing.
