@molecule/app-query-react 1.1.1 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
3
  Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
4
  Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
5
  To change this document, edit the module-level JSDoc in src/index.ts.
6
- Generated: 2026-10-26T02:00:44.547Z
6
+ Generated: 2026-10-27T04:18:56.986Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-query-react
@@ -37,12 +37,29 @@ This package needs a bonded client: install `@molecule/app-query` with a bond
37
37
 
38
38
  ```tsx
39
39
  import { Link } from 'react-router'
40
+ import { getClient, isHttpError } from '@molecule/app-http'
41
+ import { t } from '@molecule/app-i18n'
40
42
  import { intentPrefetchProps, useQuery } from '@molecule/app-query-react'
41
43
 
44
+ interface PackageDocument {
45
+ name: string
46
+ description: string
47
+ }
48
+
42
49
  const packageQuery = (name: string) => ({
43
50
  key: ['package', name],
44
- fetch: (signal: AbortSignal) =>
45
- fetch(`/data/packages/${name}.json`, { signal }).then((r) => r.json()),
51
+ fetch: async (signal: AbortSignal): Promise<PackageDocument | null> => {
52
+ try {
53
+ const response = await getClient().get<PackageDocument | null>(
54
+ `/data/packages/${encodeURIComponent(name)}.json`,
55
+ { signal },
56
+ )
57
+ return response.data
58
+ } catch (error) {
59
+ if (isHttpError(error) && error.status === 404) return null
60
+ throw error
61
+ }
62
+ },
46
63
  })
47
64
 
48
65
  function PackageLink({ name }: { name: string }) {
@@ -55,8 +72,25 @@ function PackageLink({ name }: { name: string }) {
55
72
 
56
73
  function PackagePage({ name }: { name: string }) {
57
74
  const { data, status } = useQuery(packageQuery(name))
58
- if (!data) return status === 'error' ? <NotFound /> : <Skeleton />
59
- return <Article doc={data} />
75
+ if (status === 'error') {
76
+ return (
77
+ <p role="alert">
78
+ {t('packages.loadFailed', undefined, { defaultValue: 'Unable to load package.' })}
79
+ </p>
80
+ )
81
+ }
82
+ if (status === 'idle' || status === 'loading') {
83
+ return <p role="status">{t('common.loading', undefined, { defaultValue: 'Loading…' })}</p>
84
+ }
85
+ if (data == null) {
86
+ return <p>{t('packages.notFound', undefined, { defaultValue: 'Package not found.' })}</p>
87
+ }
88
+ return (
89
+ <article>
90
+ <h1>{data.name}</h1>
91
+ <p>{data.description}</p>
92
+ </article>
93
+ )
60
94
  }
61
95
  ```
62
96
 
@@ -139,6 +173,8 @@ response, `invalidate()` marks what it affects for the next mount, and an
139
173
  explicit `fetch()` retries into the mounted page.
140
174
 
141
175
  ```tsx
176
+ import { getClient } from '@molecule/app-http'
177
+ import { t } from '@molecule/app-i18n'
142
178
  import { getQueryClient } from '@molecule/app-query'
143
179
 
144
180
  // The key names what the document actually depends on — here the signed-in
@@ -149,14 +185,16 @@ const feedKey = (principal: string, filter: string, page: number) =>
149
185
 
150
186
  const feedOptions = (principal: string, filter: string, page: number) => ({
151
187
  key: feedKey(principal, filter, page),
152
- fetch: (signal: AbortSignal) =>
153
- fetch(`/api/feeds/${filter}?page=${page}`, { signal }).then((r) => r.json()),
188
+ fetch: async (signal: AbortSignal) =>
189
+ (await getClient().get(`/api/feeds/${filter}`, { signal, params: { page } })).data,
154
190
  })
155
191
 
156
192
  async function setFollowing(principal: string, authorId: string, follow: boolean) {
157
193
  const client = getQueryClient()
158
- const res = await fetch(`/api/follows/${authorId}`, { method: follow ? 'POST' : 'DELETE' })
159
- const body = await res.json()
194
+ const http = getClient()
195
+ const { data: body } = follow
196
+ ? await http.post<{ feed: unknown }>(`/api/follows/${authorId}`)
197
+ : await http.delete<{ feed: unknown }>(`/api/follows/${authorId}`)
160
198
  // The response IS the document: paint it now, with no second round trip.
161
199
  // (If it were only a count or a flag, skip set() and invalidate() instead.)
162
200
  client.set(feedKey(principal, 'following', 1), body.feed)
@@ -172,10 +210,11 @@ function Retry({ principal }: { principal: string }) {
172
210
  // an explicit fetch retries into it. useQuery shows the outcome.
173
211
  void getQueryClient()
174
212
  .fetch(feedOptions(principal, 'following', 1))
175
- .catch(() => {})
213
+ // The mounted useQuery observer presents this failure via status/error.
214
+ .catch((_error) => {})
176
215
  }}
177
216
  >
178
- Retry
217
+ {t('common.retry', undefined, { defaultValue: 'Retry' })}
179
218
  </button>
180
219
  )
181
220
  }
@@ -217,7 +256,7 @@ Warms the cache for a document, when the connection can afford it (see
217
256
  in-flight document is skipped, and failures are swallowed.
218
257
 
219
258
  ```typescript
220
- function prefetchQuery(options: QueryOptions<T>): void
259
+ function prefetchQuery<T>(options: QueryOptions<T>): void
221
260
  ```
222
261
 
223
262
  - `options` — Key, fetch, freshness.
@@ -239,7 +278,7 @@ pointer arriving, keyboard focus, or a touch starting. Spread them onto a
239
278
  link: `<Link {...intentPrefetchProps(packageQuery(name))} />`.
240
279
 
241
280
  ```typescript
242
- function intentPrefetchProps(options: QueryOptions<T>): IntentPrefetchProps
281
+ function intentPrefetchProps<T>(options: QueryOptions<T>): IntentPrefetchProps
243
282
  ```
244
283
 
245
284
  - `options` — Key, fetch, freshness.
@@ -275,7 +314,7 @@ passes the same value as `principal` (`'anonymous'` when signed out): an
275
314
  _(description truncated — read the full text in `node_modules/@molecule/app-query-react/dist/useQuery.d.ts`.)_
276
315
 
277
316
  ```typescript
278
- function useQuery(options: QueryOptions<T> | null): QueryState<T>
317
+ function useQuery<T>(options: QueryOptions<T> | null): QueryState<T>
279
318
  ```
280
319
 
281
320
  - `options` — Key, fetch, freshness, and optionally `principal` with `keepPreviousData`; or `null`.
@@ -299,7 +338,12 @@ Peer dependencies:
299
338
  - **`useQuery` reads the cache synchronously on the first render.** A
300
339
  document prefetched from a hovered link, or seeded with `client.set()`
301
340
  from a server-rendered JSON island, renders at once — no spinner, no
302
- layout shift. Render a loading state only when `data` is `undefined`.
341
+ layout shift. Render loading from `status === 'idle' || status === 'loading'`;
342
+ `undefined` data can also accompany a completed error. A completed `null`
343
+ response is missing, not pending. The detail example treats only HTTP 404
344
+ or a successful null response as missing; other errors stay load failures.
345
+ The app's bonded HTTP client rejects non-2xx responses. Native `fetch`
346
+ resolves them, so a custom fetcher must check `response.ok` before JSON.
303
347
  - **The key is the identity.** Building `options` inline is fine; the
304
348
  hook resubscribes only when the key's value changes, not when the
305
349
  `fetch` closure does.
package/dist/index.d.ts CHANGED
@@ -23,12 +23,29 @@
23
23
  * @example
24
24
  * ```tsx
25
25
  * import { Link } from 'react-router'
26
+ * import { getClient, isHttpError } from '@molecule/app-http'
27
+ * import { t } from '@molecule/app-i18n'
26
28
  * import { intentPrefetchProps, useQuery } from '@molecule/app-query-react'
27
29
  *
30
+ * interface PackageDocument {
31
+ * name: string
32
+ * description: string
33
+ * }
34
+ *
28
35
  * const packageQuery = (name: string) => ({
29
36
  * key: ['package', name],
30
- * fetch: (signal: AbortSignal) =>
31
- * fetch(`/data/packages/${name}.json`, { signal }).then((r) => r.json()),
37
+ * fetch: async (signal: AbortSignal): Promise<PackageDocument | null> => {
38
+ * try {
39
+ * const response = await getClient().get<PackageDocument | null>(
40
+ * `/data/packages/${encodeURIComponent(name)}.json`,
41
+ * { signal },
42
+ * )
43
+ * return response.data
44
+ * } catch (error) {
45
+ * if (isHttpError(error) && error.status === 404) return null
46
+ * throw error
47
+ * }
48
+ * },
32
49
  * })
33
50
  *
34
51
  * function PackageLink({ name }: { name: string }) {
@@ -37,8 +54,16 @@
37
54
  *
38
55
  * function PackagePage({ name }: { name: string }) {
39
56
  * const { data, status } = useQuery(packageQuery(name))
40
- * if (!data) return status === 'error' ? <NotFound /> : <Skeleton />
41
- * return <Article doc={data} />
57
+ * if (status === 'error') {
58
+ * return <p role="alert">{t('packages.loadFailed', undefined, { defaultValue: 'Unable to load package.' })}</p>
59
+ * }
60
+ * if (status === 'idle' || status === 'loading') {
61
+ * return <p role="status">{t('common.loading', undefined, { defaultValue: 'Loading…' })}</p>
62
+ * }
63
+ * if (data == null) {
64
+ * return <p>{t('packages.notFound', undefined, { defaultValue: 'Package not found.' })}</p>
65
+ * }
66
+ * return <article><h1>{data.name}</h1><p>{data.description}</p></article>
42
67
  * }
43
68
  * ```
44
69
  *
@@ -123,6 +148,8 @@
123
148
  * explicit `fetch()` retries into the mounted page.
124
149
  *
125
150
  * ```tsx
151
+ * import { getClient } from '@molecule/app-http'
152
+ * import { t } from '@molecule/app-i18n'
126
153
  * import { getQueryClient } from '@molecule/app-query'
127
154
  *
128
155
  * // The key names what the document actually depends on — here the signed-in
@@ -133,14 +160,16 @@
133
160
  *
134
161
  * const feedOptions = (principal: string, filter: string, page: number) => ({
135
162
  * key: feedKey(principal, filter, page),
136
- * fetch: (signal: AbortSignal) =>
137
- * fetch(`/api/feeds/${filter}?page=${page}`, { signal }).then((r) => r.json()),
163
+ * fetch: async (signal: AbortSignal) =>
164
+ * (await getClient().get(`/api/feeds/${filter}`, { signal, params: { page } })).data,
138
165
  * })
139
166
  *
140
167
  * async function setFollowing(principal: string, authorId: string, follow: boolean) {
141
168
  * const client = getQueryClient()
142
- * const res = await fetch(`/api/follows/${authorId}`, { method: follow ? 'POST' : 'DELETE' })
143
- * const body = await res.json()
169
+ * const http = getClient()
170
+ * const { data: body } = follow
171
+ * ? await http.post<{ feed: unknown }>(`/api/follows/${authorId}`)
172
+ * : await http.delete<{ feed: unknown }>(`/api/follows/${authorId}`)
144
173
  * // The response IS the document: paint it now, with no second round trip.
145
174
  * // (If it were only a count or a flag, skip set() and invalidate() instead.)
146
175
  * client.set(feedKey(principal, 'following', 1), body.feed)
@@ -156,10 +185,11 @@
156
185
  * // an explicit fetch retries into it. useQuery shows the outcome.
157
186
  * void getQueryClient()
158
187
  * .fetch(feedOptions(principal, 'following', 1))
159
- * .catch(() => {})
188
+ * // The mounted useQuery observer presents this failure via status/error.
189
+ * .catch((_error) => {})
160
190
  * }}
161
191
  * >
162
- * Retry
192
+ * {t('common.retry', undefined, { defaultValue: 'Retry' })}
163
193
  * </button>
164
194
  * )
165
195
  * }
@@ -169,7 +199,12 @@
169
199
  * - **`useQuery` reads the cache synchronously on the first render.** A
170
200
  * document prefetched from a hovered link, or seeded with `client.set()`
171
201
  * from a server-rendered JSON island, renders at once — no spinner, no
172
- * layout shift. Render a loading state only when `data` is `undefined`.
202
+ * layout shift. Render loading from `status === 'idle' || status === 'loading'`;
203
+ * `undefined` data can also accompany a completed error. A completed `null`
204
+ * response is missing, not pending. The detail example treats only HTTP 404
205
+ * or a successful null response as missing; other errors stay load failures.
206
+ * The app's bonded HTTP client rejects non-2xx responses. Native `fetch`
207
+ * resolves them, so a custom fetcher must check `response.ok` before JSON.
173
208
  * - **The key is the identity.** Building `options` inline is fine; the
174
209
  * hook resubscribes only when the key's value changes, not when the
175
210
  * `fetch` closure does.
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyNG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4PG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
package/dist/index.js CHANGED
@@ -23,12 +23,29 @@
23
23
  * @example
24
24
  * ```tsx
25
25
  * import { Link } from 'react-router'
26
+ * import { getClient, isHttpError } from '@molecule/app-http'
27
+ * import { t } from '@molecule/app-i18n'
26
28
  * import { intentPrefetchProps, useQuery } from '@molecule/app-query-react'
27
29
  *
30
+ * interface PackageDocument {
31
+ * name: string
32
+ * description: string
33
+ * }
34
+ *
28
35
  * const packageQuery = (name: string) => ({
29
36
  * key: ['package', name],
30
- * fetch: (signal: AbortSignal) =>
31
- * fetch(`/data/packages/${name}.json`, { signal }).then((r) => r.json()),
37
+ * fetch: async (signal: AbortSignal): Promise<PackageDocument | null> => {
38
+ * try {
39
+ * const response = await getClient().get<PackageDocument | null>(
40
+ * `/data/packages/${encodeURIComponent(name)}.json`,
41
+ * { signal },
42
+ * )
43
+ * return response.data
44
+ * } catch (error) {
45
+ * if (isHttpError(error) && error.status === 404) return null
46
+ * throw error
47
+ * }
48
+ * },
32
49
  * })
33
50
  *
34
51
  * function PackageLink({ name }: { name: string }) {
@@ -37,8 +54,16 @@
37
54
  *
38
55
  * function PackagePage({ name }: { name: string }) {
39
56
  * const { data, status } = useQuery(packageQuery(name))
40
- * if (!data) return status === 'error' ? <NotFound /> : <Skeleton />
41
- * return <Article doc={data} />
57
+ * if (status === 'error') {
58
+ * return <p role="alert">{t('packages.loadFailed', undefined, { defaultValue: 'Unable to load package.' })}</p>
59
+ * }
60
+ * if (status === 'idle' || status === 'loading') {
61
+ * return <p role="status">{t('common.loading', undefined, { defaultValue: 'Loading…' })}</p>
62
+ * }
63
+ * if (data == null) {
64
+ * return <p>{t('packages.notFound', undefined, { defaultValue: 'Package not found.' })}</p>
65
+ * }
66
+ * return <article><h1>{data.name}</h1><p>{data.description}</p></article>
42
67
  * }
43
68
  * ```
44
69
  *
@@ -123,6 +148,8 @@
123
148
  * explicit `fetch()` retries into the mounted page.
124
149
  *
125
150
  * ```tsx
151
+ * import { getClient } from '@molecule/app-http'
152
+ * import { t } from '@molecule/app-i18n'
126
153
  * import { getQueryClient } from '@molecule/app-query'
127
154
  *
128
155
  * // The key names what the document actually depends on — here the signed-in
@@ -133,14 +160,16 @@
133
160
  *
134
161
  * const feedOptions = (principal: string, filter: string, page: number) => ({
135
162
  * key: feedKey(principal, filter, page),
136
- * fetch: (signal: AbortSignal) =>
137
- * fetch(`/api/feeds/${filter}?page=${page}`, { signal }).then((r) => r.json()),
163
+ * fetch: async (signal: AbortSignal) =>
164
+ * (await getClient().get(`/api/feeds/${filter}`, { signal, params: { page } })).data,
138
165
  * })
139
166
  *
140
167
  * async function setFollowing(principal: string, authorId: string, follow: boolean) {
141
168
  * const client = getQueryClient()
142
- * const res = await fetch(`/api/follows/${authorId}`, { method: follow ? 'POST' : 'DELETE' })
143
- * const body = await res.json()
169
+ * const http = getClient()
170
+ * const { data: body } = follow
171
+ * ? await http.post<{ feed: unknown }>(`/api/follows/${authorId}`)
172
+ * : await http.delete<{ feed: unknown }>(`/api/follows/${authorId}`)
144
173
  * // The response IS the document: paint it now, with no second round trip.
145
174
  * // (If it were only a count or a flag, skip set() and invalidate() instead.)
146
175
  * client.set(feedKey(principal, 'following', 1), body.feed)
@@ -156,10 +185,11 @@
156
185
  * // an explicit fetch retries into it. useQuery shows the outcome.
157
186
  * void getQueryClient()
158
187
  * .fetch(feedOptions(principal, 'following', 1))
159
- * .catch(() => {})
188
+ * // The mounted useQuery observer presents this failure via status/error.
189
+ * .catch((_error) => {})
160
190
  * }}
161
191
  * >
162
- * Retry
192
+ * {t('common.retry', undefined, { defaultValue: 'Retry' })}
163
193
  * </button>
164
194
  * )
165
195
  * }
@@ -169,7 +199,12 @@
169
199
  * - **`useQuery` reads the cache synchronously on the first render.** A
170
200
  * document prefetched from a hovered link, or seeded with `client.set()`
171
201
  * from a server-rendered JSON island, renders at once — no spinner, no
172
- * layout shift. Render a loading state only when `data` is `undefined`.
202
+ * layout shift. Render loading from `status === 'idle' || status === 'loading'`;
203
+ * `undefined` data can also accompany a completed error. A completed `null`
204
+ * response is missing, not pending. The detail example treats only HTTP 404
205
+ * or a successful null response as missing; other errors stay load failures.
206
+ * The app's bonded HTTP client rejects non-2xx responses. Native `fetch`
207
+ * resolves them, so a custom fetcher must check `response.ok` before JSON.
173
208
  * - **The key is the identity.** Building `options` inline is fine; the
174
209
  * hook resubscribes only when the key's value changes, not when the
175
210
  * `fetch` closure does.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-query-react",
3
- "version": "1.1.1",
3
+ "version": "1.1.3",
4
4
  "description": "React hooks for @molecule/app-query — read a cached document synchronously, observe it, and prefetch on intent",
5
5
  "homepage": "https://www.molecule.dev/packages/app-query-react",
6
6
  "type": "module",
@@ -40,7 +40,7 @@
40
40
  "react": "^18.0.0 || ^19.0.0"
41
41
  },
42
42
  "devDependencies": {
43
- "@molecule/app-query": "1.1.0",
43
+ "@molecule/app-query": "1.1.1",
44
44
  "@molecule/app-query-memory": "1.0.3",
45
45
  "@molecule/app-query-tanstack": "1.0.2",
46
46
  "@types/node": "26.6.5",