@molecule/app-query-react 1.0.2 → 1.0.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 +57 -3
- package/dist/index.d.ts +57 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +57 -2
- package/package.json +3 -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-21T17:39:17.642Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/app-query-react
|
|
@@ -59,6 +59,54 @@ function PackagePage({ name }: { name: string }) {
|
|
|
59
59
|
}
|
|
60
60
|
```
|
|
61
61
|
|
|
62
|
+
A mutation or a failed load has to change a page that is ALREADY mounted, and
|
|
63
|
+
the cache never starts that request by itself: `set()` paints a mutation's own
|
|
64
|
+
response, `invalidate()` marks what it affects for the next mount, and an
|
|
65
|
+
explicit `fetch()` retries into the mounted page.
|
|
66
|
+
|
|
67
|
+
```tsx
|
|
68
|
+
import { getQueryClient } from '@molecule/app-query'
|
|
69
|
+
|
|
70
|
+
// The key names what the document actually depends on — here the signed-in
|
|
71
|
+
// principal, the filter and the page. Another principal's feed is a
|
|
72
|
+
// different document, so an invalidation scoped to this one leaves it alone.
|
|
73
|
+
const feedKey = (principal: string, filter: string, page: number) =>
|
|
74
|
+
['feed', principal, filter, page] as const
|
|
75
|
+
|
|
76
|
+
const feedOptions = (principal: string, filter: string, page: number) => ({
|
|
77
|
+
key: feedKey(principal, filter, page),
|
|
78
|
+
fetch: (signal: AbortSignal) =>
|
|
79
|
+
fetch(`/api/feeds/${filter}?page=${page}`, { signal }).then((r) => r.json()),
|
|
80
|
+
})
|
|
81
|
+
|
|
82
|
+
async function setFollowing(principal: string, authorId: string, follow: boolean) {
|
|
83
|
+
const client = getQueryClient()
|
|
84
|
+
const res = await fetch(`/api/follows/${authorId}`, { method: follow ? 'POST' : 'DELETE' })
|
|
85
|
+
const body = await res.json()
|
|
86
|
+
// The response IS the document: paint it now, with no second round trip.
|
|
87
|
+
// (If it were only a count or a flag, skip set() and invalidate() instead.)
|
|
88
|
+
client.set(feedKey(principal, 'following', 1), body.feed)
|
|
89
|
+
// Future reads of every feed this principal owns are stale.
|
|
90
|
+
client.invalidate(['feed', principal])
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function Retry({ principal }: { principal: string }) {
|
|
94
|
+
return (
|
|
95
|
+
<button
|
|
96
|
+
onClick={() => {
|
|
97
|
+
// invalidate() alone would leave the mounted page on its error;
|
|
98
|
+
// an explicit fetch retries into it. useQuery shows the outcome.
|
|
99
|
+
void getQueryClient()
|
|
100
|
+
.fetch(feedOptions(principal, 'following', 1))
|
|
101
|
+
.catch(() => {})
|
|
102
|
+
}}
|
|
103
|
+
>
|
|
104
|
+
Retry
|
|
105
|
+
</button>
|
|
106
|
+
)
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
62
110
|
## Type
|
|
63
111
|
|
|
64
112
|
`feature`
|
|
@@ -175,5 +223,11 @@ Peer dependencies:
|
|
|
175
223
|
connections (`shouldPrefetch()` in the core) — do not bypass that for
|
|
176
224
|
"important" links; the person can still click.
|
|
177
225
|
- Errors are not thrown from the hook; read `status === 'error'` and
|
|
178
|
-
`error`.
|
|
179
|
-
|
|
226
|
+
`error`. `client.invalidate()` does NOT refetch a mounted page — it only
|
|
227
|
+
marks documents stale, so the page keeps its error (or its old document)
|
|
228
|
+
until the app retries with `client.fetch(options)` or the page subscribes
|
|
229
|
+
again (a key change or a re-mount).
|
|
230
|
+
- After a mutation, `client.set(key, response)` paints the server's own
|
|
231
|
+
answer at once, and `client.invalidate(prefix)` marks the affected reads
|
|
232
|
+
stale for their next mount. Which key and which scope is the app's
|
|
233
|
+
decision: the cache does not infer it from auth or form state.
|
package/dist/index.d.ts
CHANGED
|
@@ -41,6 +41,55 @@
|
|
|
41
41
|
* }
|
|
42
42
|
* ```
|
|
43
43
|
*
|
|
44
|
+
* @example
|
|
45
|
+
* A mutation or a failed load has to change a page that is ALREADY mounted, and
|
|
46
|
+
* the cache never starts that request by itself: `set()` paints a mutation's own
|
|
47
|
+
* response, `invalidate()` marks what it affects for the next mount, and an
|
|
48
|
+
* explicit `fetch()` retries into the mounted page.
|
|
49
|
+
*
|
|
50
|
+
* ```tsx
|
|
51
|
+
* import { getQueryClient } from '@molecule/app-query'
|
|
52
|
+
*
|
|
53
|
+
* // The key names what the document actually depends on — here the signed-in
|
|
54
|
+
* // principal, the filter and the page. Another principal's feed is a
|
|
55
|
+
* // different document, so an invalidation scoped to this one leaves it alone.
|
|
56
|
+
* const feedKey = (principal: string, filter: string, page: number) =>
|
|
57
|
+
* ['feed', principal, filter, page] as const
|
|
58
|
+
*
|
|
59
|
+
* const feedOptions = (principal: string, filter: string, page: number) => ({
|
|
60
|
+
* key: feedKey(principal, filter, page),
|
|
61
|
+
* fetch: (signal: AbortSignal) =>
|
|
62
|
+
* fetch(`/api/feeds/${filter}?page=${page}`, { signal }).then((r) => r.json()),
|
|
63
|
+
* })
|
|
64
|
+
*
|
|
65
|
+
* async function setFollowing(principal: string, authorId: string, follow: boolean) {
|
|
66
|
+
* const client = getQueryClient()
|
|
67
|
+
* const res = await fetch(`/api/follows/${authorId}`, { method: follow ? 'POST' : 'DELETE' })
|
|
68
|
+
* const body = await res.json()
|
|
69
|
+
* // The response IS the document: paint it now, with no second round trip.
|
|
70
|
+
* // (If it were only a count or a flag, skip set() and invalidate() instead.)
|
|
71
|
+
* client.set(feedKey(principal, 'following', 1), body.feed)
|
|
72
|
+
* // Future reads of every feed this principal owns are stale.
|
|
73
|
+
* client.invalidate(['feed', principal])
|
|
74
|
+
* }
|
|
75
|
+
*
|
|
76
|
+
* function Retry({ principal }: { principal: string }) {
|
|
77
|
+
* return (
|
|
78
|
+
* <button
|
|
79
|
+
* onClick={() => {
|
|
80
|
+
* // invalidate() alone would leave the mounted page on its error;
|
|
81
|
+
* // an explicit fetch retries into it. useQuery shows the outcome.
|
|
82
|
+
* void getQueryClient()
|
|
83
|
+
* .fetch(feedOptions(principal, 'following', 1))
|
|
84
|
+
* .catch(() => {})
|
|
85
|
+
* }}
|
|
86
|
+
* >
|
|
87
|
+
* Retry
|
|
88
|
+
* </button>
|
|
89
|
+
* )
|
|
90
|
+
* }
|
|
91
|
+
* ```
|
|
92
|
+
*
|
|
44
93
|
* @remarks
|
|
45
94
|
* - **`useQuery` reads the cache synchronously on the first render.** A
|
|
46
95
|
* document prefetched from a hovered link, or seeded with `client.set()`
|
|
@@ -55,8 +104,14 @@
|
|
|
55
104
|
* connections (`shouldPrefetch()` in the core) — do not bypass that for
|
|
56
105
|
* "important" links; the person can still click.
|
|
57
106
|
* - Errors are not thrown from the hook; read `status === 'error'` and
|
|
58
|
-
* `error`.
|
|
59
|
-
*
|
|
107
|
+
* `error`. `client.invalidate()` does NOT refetch a mounted page — it only
|
|
108
|
+
* marks documents stale, so the page keeps its error (or its old document)
|
|
109
|
+
* until the app retries with `client.fetch(options)` or the page subscribes
|
|
110
|
+
* again (a key change or a re-mount).
|
|
111
|
+
* - After a mutation, `client.set(key, response)` paints the server's own
|
|
112
|
+
* answer at once, and `client.invalidate(prefix)` marks the affected reads
|
|
113
|
+
* stale for their next mount. Which key and which scope is the app's
|
|
114
|
+
* decision: the cache does not infer it from auth or form state.
|
|
60
115
|
*
|
|
61
116
|
* @module
|
|
62
117
|
*/
|
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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoHG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
|
package/dist/index.js
CHANGED
|
@@ -41,6 +41,55 @@
|
|
|
41
41
|
* }
|
|
42
42
|
* ```
|
|
43
43
|
*
|
|
44
|
+
* @example
|
|
45
|
+
* A mutation or a failed load has to change a page that is ALREADY mounted, and
|
|
46
|
+
* the cache never starts that request by itself: `set()` paints a mutation's own
|
|
47
|
+
* response, `invalidate()` marks what it affects for the next mount, and an
|
|
48
|
+
* explicit `fetch()` retries into the mounted page.
|
|
49
|
+
*
|
|
50
|
+
* ```tsx
|
|
51
|
+
* import { getQueryClient } from '@molecule/app-query'
|
|
52
|
+
*
|
|
53
|
+
* // The key names what the document actually depends on — here the signed-in
|
|
54
|
+
* // principal, the filter and the page. Another principal's feed is a
|
|
55
|
+
* // different document, so an invalidation scoped to this one leaves it alone.
|
|
56
|
+
* const feedKey = (principal: string, filter: string, page: number) =>
|
|
57
|
+
* ['feed', principal, filter, page] as const
|
|
58
|
+
*
|
|
59
|
+
* const feedOptions = (principal: string, filter: string, page: number) => ({
|
|
60
|
+
* key: feedKey(principal, filter, page),
|
|
61
|
+
* fetch: (signal: AbortSignal) =>
|
|
62
|
+
* fetch(`/api/feeds/${filter}?page=${page}`, { signal }).then((r) => r.json()),
|
|
63
|
+
* })
|
|
64
|
+
*
|
|
65
|
+
* async function setFollowing(principal: string, authorId: string, follow: boolean) {
|
|
66
|
+
* const client = getQueryClient()
|
|
67
|
+
* const res = await fetch(`/api/follows/${authorId}`, { method: follow ? 'POST' : 'DELETE' })
|
|
68
|
+
* const body = await res.json()
|
|
69
|
+
* // The response IS the document: paint it now, with no second round trip.
|
|
70
|
+
* // (If it were only a count or a flag, skip set() and invalidate() instead.)
|
|
71
|
+
* client.set(feedKey(principal, 'following', 1), body.feed)
|
|
72
|
+
* // Future reads of every feed this principal owns are stale.
|
|
73
|
+
* client.invalidate(['feed', principal])
|
|
74
|
+
* }
|
|
75
|
+
*
|
|
76
|
+
* function Retry({ principal }: { principal: string }) {
|
|
77
|
+
* return (
|
|
78
|
+
* <button
|
|
79
|
+
* onClick={() => {
|
|
80
|
+
* // invalidate() alone would leave the mounted page on its error;
|
|
81
|
+
* // an explicit fetch retries into it. useQuery shows the outcome.
|
|
82
|
+
* void getQueryClient()
|
|
83
|
+
* .fetch(feedOptions(principal, 'following', 1))
|
|
84
|
+
* .catch(() => {})
|
|
85
|
+
* }}
|
|
86
|
+
* >
|
|
87
|
+
* Retry
|
|
88
|
+
* </button>
|
|
89
|
+
* )
|
|
90
|
+
* }
|
|
91
|
+
* ```
|
|
92
|
+
*
|
|
44
93
|
* @remarks
|
|
45
94
|
* - **`useQuery` reads the cache synchronously on the first render.** A
|
|
46
95
|
* document prefetched from a hovered link, or seeded with `client.set()`
|
|
@@ -55,8 +104,14 @@
|
|
|
55
104
|
* connections (`shouldPrefetch()` in the core) — do not bypass that for
|
|
56
105
|
* "important" links; the person can still click.
|
|
57
106
|
* - Errors are not thrown from the hook; read `status === 'error'` and
|
|
58
|
-
* `error`.
|
|
59
|
-
*
|
|
107
|
+
* `error`. `client.invalidate()` does NOT refetch a mounted page — it only
|
|
108
|
+
* marks documents stale, so the page keeps its error (or its old document)
|
|
109
|
+
* until the app retries with `client.fetch(options)` or the page subscribes
|
|
110
|
+
* again (a key change or a re-mount).
|
|
111
|
+
* - After a mutation, `client.set(key, response)` paints the server's own
|
|
112
|
+
* answer at once, and `client.invalidate(prefix)` marks the affected reads
|
|
113
|
+
* stale for their next mount. Which key and which scope is the app's
|
|
114
|
+
* decision: the cache does not infer it from auth or form state.
|
|
60
115
|
*
|
|
61
116
|
* @module
|
|
62
117
|
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-query-react",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.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,8 +40,9 @@
|
|
|
40
40
|
"react": "^18.0.0 || ^19.0.0"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
|
-
"@molecule/app-query": "1.0.
|
|
43
|
+
"@molecule/app-query": "1.0.3",
|
|
44
44
|
"@molecule/app-query-memory": "1.0.2",
|
|
45
|
+
"@molecule/app-query-tanstack": "1.0.1",
|
|
45
46
|
"@types/node": "26.1.2",
|
|
46
47
|
"@types/react": "19.2.17",
|
|
47
48
|
"@types/react-dom": "19.2.3",
|