@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 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-18T14:21:40.277Z
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`. A refetch after an error is one more subscription (a re-mount
179
- or a key change) or a `client.invalidate()`.
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`. A refetch after an error is one more subscription (a re-mount
59
- * or a key change) or a `client.invalidate()`.
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
  */
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
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`. A refetch after an error is one more subscription (a re-mount
59
- * or a key change) or a `client.invalidate()`.
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.2",
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.2",
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",