@molecule/app-query-react 1.1.2 → 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 +56 -12
- package/dist/index.d.ts +46 -11
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +46 -11
- package/package.json +2 -2
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-
|
|
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
|
-
|
|
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 (
|
|
59
|
-
|
|
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
|
-
|
|
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
|
|
159
|
-
const body =
|
|
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
|
-
|
|
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
|
}
|
|
@@ -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
|
|
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
|
-
*
|
|
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 (
|
|
41
|
-
*
|
|
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
|
-
*
|
|
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
|
|
143
|
-
* const body =
|
|
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
|
-
*
|
|
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
|
|
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/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA
|
|
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
|
-
*
|
|
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 (
|
|
41
|
-
*
|
|
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
|
-
*
|
|
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
|
|
143
|
-
* const body =
|
|
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
|
-
*
|
|
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
|
|
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.
|
|
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.
|
|
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",
|