@molecule/app-query-react 1.2.0 → 1.3.0
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 +25 -3
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -0
- package/dist/types.d.ts +15 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +1 -0
- package/dist/useQuery.d.ts +6 -3
- package/dist/useQuery.d.ts.map +1 -1
- package/dist/useQuery.js +19 -3
- package/package.json +1 -1
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-11-
|
|
6
|
+
Generated: 2026-11-12T06:19:59.085Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/app-query-react
|
|
@@ -373,6 +373,21 @@ interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
|
|
|
373
373
|
}
|
|
374
374
|
```
|
|
375
375
|
|
|
376
|
+
#### `UseQueryResult`
|
|
377
|
+
|
|
378
|
+
A mounted query's state and its explicit refresh action.
|
|
379
|
+
|
|
380
|
+
```typescript
|
|
381
|
+
interface UseQueryResult<T> extends QueryState<T> {
|
|
382
|
+
/**
|
|
383
|
+
* Fetch this key again, even when its cached document is fresh. Observers receive the
|
|
384
|
+
* updated state. Resolves with that state, including an error when the request fails;
|
|
385
|
+
* a disabled (`null`) query resolves idle without a request.
|
|
386
|
+
*/
|
|
387
|
+
refetch: () => Promise<QueryState<T>>
|
|
388
|
+
}
|
|
389
|
+
```
|
|
390
|
+
|
|
376
391
|
#### `IntentPrefetchProps`
|
|
377
392
|
|
|
378
393
|
The handlers {@link intentPrefetchProps} returns.
|
|
@@ -464,6 +479,8 @@ lands. It is aborted only when the key changes or the component unmounts
|
|
|
464
479
|
`useEffect` + `fetch`: an effect whose cleanup sets a `cancelled` flag, and
|
|
465
480
|
whose deps include a function rebuilt each render, cancels its own request
|
|
466
481
|
on every re-render and then skips the refetch.
|
|
482
|
+
An explicit `refetch()` is an awaited cache fetch; it can finish after the observer unmounts,
|
|
483
|
+
like an explicit `client.fetch(options)` caller.
|
|
467
484
|
|
|
468
485
|
For a LIST, put the route's page, filter and selected view in the key and
|
|
469
486
|
pass `keepPreviousData` with a `principal`: a Next/Previous or filter change
|
|
@@ -477,12 +494,12 @@ an endpoint that answers every viewer the same takes a viewer-free key with
|
|
|
477
494
|
`principal: 'public'`.
|
|
478
495
|
|
|
479
496
|
```typescript
|
|
480
|
-
function useQuery<T>(options: QueryOptions<T> | null):
|
|
497
|
+
function useQuery<T>(options: QueryOptions<T> | null): UseQueryResult<T>
|
|
481
498
|
```
|
|
482
499
|
|
|
483
500
|
- `options` — Key, fetch, freshness, and optionally `principal` with `keepPreviousData`; or `null`.
|
|
484
501
|
|
|
485
|
-
**Returns:** The document's state
|
|
502
|
+
**Returns:** The document's state and `refetch()`. `isPreviousData` is `true` while `data` is the previous key's document for the same principal.
|
|
486
503
|
|
|
487
504
|
## Injection Notes
|
|
488
505
|
|
|
@@ -548,6 +565,11 @@ Peer dependencies:
|
|
|
548
565
|
- Prefetching respects the browser's data-saver setting and skips 2G
|
|
549
566
|
connections (`shouldPrefetch()` in the core) — do not bypass that for
|
|
550
567
|
"important" links; the person can still click.
|
|
568
|
+
- **Refresh a mounted document with `query.refetch()`.** It fetches even a fresh cache
|
|
569
|
+
entry and updates every observer of that key. After a mutation whose response is not the
|
|
570
|
+
whole document, `await query.refetch()` reloads the displayed list. It resolves with the
|
|
571
|
+
resulting state (including `status: 'error'` on failure); a disabled query stays idle.
|
|
572
|
+
Prefer `client.set(key, response)` when the mutation already returned the whole document.
|
|
551
573
|
- Errors are not thrown from the hook; read `status === 'error'` and
|
|
552
574
|
`error`. `client.invalidate()` does NOT refetch a mounted page — it only
|
|
553
575
|
marks documents stale, so the page keeps its error (or its old document)
|
package/dist/index.d.ts
CHANGED
|
@@ -295,6 +295,11 @@
|
|
|
295
295
|
* - Prefetching respects the browser's data-saver setting and skips 2G
|
|
296
296
|
* connections (`shouldPrefetch()` in the core) — do not bypass that for
|
|
297
297
|
* "important" links; the person can still click.
|
|
298
|
+
* - **Refresh a mounted document with `query.refetch()`.** It fetches even a fresh cache
|
|
299
|
+
* entry and updates every observer of that key. After a mutation whose response is not the
|
|
300
|
+
* whole document, `await query.refetch()` reloads the displayed list. It resolves with the
|
|
301
|
+
* resulting state (including `status: 'error'` on failure); a disabled query stays idle.
|
|
302
|
+
* Prefer `client.set(key, response)` when the mutation already returned the whole document.
|
|
298
303
|
* - Errors are not thrown from the hook; read `status === 'error'` and
|
|
299
304
|
* `error`. `client.invalidate()` does NOT refetch a mounted page — it only
|
|
300
305
|
* marks documents stale, so the page keeps its error (or its old document)
|
|
@@ -311,6 +316,7 @@
|
|
|
311
316
|
* @module
|
|
312
317
|
*/
|
|
313
318
|
export * from './resource.js';
|
|
319
|
+
export * from './types.js';
|
|
314
320
|
export * from './usePrefetch.js';
|
|
315
321
|
export * from './useQuery.js';
|
|
316
322
|
//# sourceMappingURL=index.d.ts.map
|
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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4TG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
|
package/dist/index.js
CHANGED
|
@@ -295,6 +295,11 @@
|
|
|
295
295
|
* - Prefetching respects the browser's data-saver setting and skips 2G
|
|
296
296
|
* connections (`shouldPrefetch()` in the core) — do not bypass that for
|
|
297
297
|
* "important" links; the person can still click.
|
|
298
|
+
* - **Refresh a mounted document with `query.refetch()`.** It fetches even a fresh cache
|
|
299
|
+
* entry and updates every observer of that key. After a mutation whose response is not the
|
|
300
|
+
* whole document, `await query.refetch()` reloads the displayed list. It resolves with the
|
|
301
|
+
* resulting state (including `status: 'error'` on failure); a disabled query stays idle.
|
|
302
|
+
* Prefer `client.set(key, response)` when the mutation already returned the whole document.
|
|
298
303
|
* - Errors are not thrown from the hook; read `status === 'error'` and
|
|
299
304
|
* `error`. `client.invalidate()` does NOT refetch a mounted page — it only
|
|
300
305
|
* marks documents stale, so the page keeps its error (or its old document)
|
|
@@ -311,5 +316,6 @@
|
|
|
311
316
|
* @module
|
|
312
317
|
*/
|
|
313
318
|
export * from './resource.js';
|
|
319
|
+
export * from './types.js';
|
|
314
320
|
export * from './usePrefetch.js';
|
|
315
321
|
export * from './useQuery.js';
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* React query observer contracts.
|
|
3
|
+
* @module
|
|
4
|
+
*/
|
|
5
|
+
import type { QueryState } from '@molecule/app-query';
|
|
6
|
+
/** A mounted query's state and its explicit refresh action. */
|
|
7
|
+
export interface UseQueryResult<T> extends QueryState<T> {
|
|
8
|
+
/**
|
|
9
|
+
* Fetch this key again, even when its cached document is fresh. Observers receive the
|
|
10
|
+
* updated state. Resolves with that state, including an error when the request fails;
|
|
11
|
+
* a disabled (`null`) query resolves idle without a request.
|
|
12
|
+
*/
|
|
13
|
+
refetch: () => Promise<QueryState<T>>;
|
|
14
|
+
}
|
|
15
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,+DAA+D;AAC/D,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;CACtC"}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/useQuery.d.ts
CHANGED
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
*
|
|
4
4
|
* @module
|
|
5
5
|
*/
|
|
6
|
-
import type { QueryOptions
|
|
6
|
+
import type { QueryOptions } from '@molecule/app-query';
|
|
7
|
+
import type { UseQueryResult } from './types.js';
|
|
7
8
|
/**
|
|
8
9
|
* The document for `options.key`, kept current: cached data is returned on
|
|
9
10
|
* the very first render (so a warmed page never flashes a loading state),
|
|
@@ -20,6 +21,8 @@ import type { QueryOptions, QueryState } from '@molecule/app-query';
|
|
|
20
21
|
* `useEffect` + `fetch`: an effect whose cleanup sets a `cancelled` flag, and
|
|
21
22
|
* whose deps include a function rebuilt each render, cancels its own request
|
|
22
23
|
* on every re-render and then skips the refetch.
|
|
24
|
+
* An explicit `refetch()` is an awaited cache fetch; it can finish after the observer unmounts,
|
|
25
|
+
* like an explicit `client.fetch(options)` caller.
|
|
23
26
|
*
|
|
24
27
|
* For a LIST, put the route's page, filter and selected view in the key and
|
|
25
28
|
* pass `keepPreviousData` with a `principal`: a Next/Previous or filter change
|
|
@@ -34,11 +37,11 @@ import type { QueryOptions, QueryState } from '@molecule/app-query';
|
|
|
34
37
|
*
|
|
35
38
|
* @param options - Key, fetch, freshness, and optionally `principal` with
|
|
36
39
|
* `keepPreviousData`; or `null`.
|
|
37
|
-
* @returns The document's state
|
|
40
|
+
* @returns The document's state and `refetch()`. `isPreviousData` is `true` while `data` is
|
|
38
41
|
* the previous key's document for the same principal.
|
|
39
42
|
* @throws {Error} When `keepPreviousData` is set without `principal` — the
|
|
40
43
|
* hook cannot tell a route change from a principal switch, so it refuses
|
|
41
44
|
* rather than risk showing one principal's document to another.
|
|
42
45
|
*/
|
|
43
|
-
export declare function useQuery<T>(options: QueryOptions<T> | null):
|
|
46
|
+
export declare function useQuery<T>(options: QueryOptions<T> | null): UseQueryResult<T>;
|
|
44
47
|
//# sourceMappingURL=useQuery.d.ts.map
|
package/dist/useQuery.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"useQuery.d.ts","sourceRoot":"","sources":["../src/useQuery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,
|
|
1
|
+
{"version":3,"file":"useQuery.d.ts","sourceRoot":"","sources":["../src/useQuery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,qBAAqB,CAAA;AAGnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAuBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,CAsF9E"}
|
package/dist/useQuery.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* @module
|
|
5
5
|
*/
|
|
6
|
-
import { useEffect, useMemo, useRef, useState } from 'react';
|
|
6
|
+
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
|
|
7
7
|
import { getQueryClient, hashQueryKey } from '@molecule/app-query';
|
|
8
8
|
const IDLE = {
|
|
9
9
|
data: undefined,
|
|
@@ -28,6 +28,8 @@ const IDLE = {
|
|
|
28
28
|
* `useEffect` + `fetch`: an effect whose cleanup sets a `cancelled` flag, and
|
|
29
29
|
* whose deps include a function rebuilt each render, cancels its own request
|
|
30
30
|
* on every re-render and then skips the refetch.
|
|
31
|
+
* An explicit `refetch()` is an awaited cache fetch; it can finish after the observer unmounts,
|
|
32
|
+
* like an explicit `client.fetch(options)` caller.
|
|
31
33
|
*
|
|
32
34
|
* For a LIST, put the route's page, filter and selected view in the key and
|
|
33
35
|
* pass `keepPreviousData` with a `principal`: a Next/Previous or filter change
|
|
@@ -42,7 +44,7 @@ const IDLE = {
|
|
|
42
44
|
*
|
|
43
45
|
* @param options - Key, fetch, freshness, and optionally `principal` with
|
|
44
46
|
* `keepPreviousData`; or `null`.
|
|
45
|
-
* @returns The document's state
|
|
47
|
+
* @returns The document's state and `refetch()`. `isPreviousData` is `true` while `data` is
|
|
46
48
|
* the previous key's document for the same principal.
|
|
47
49
|
* @throws {Error} When `keepPreviousData` is set without `principal` — the
|
|
48
50
|
* hook cannot tell a route change from a principal switch, so it refuses
|
|
@@ -58,6 +60,20 @@ export function useQuery(options) {
|
|
|
58
60
|
// Options are read once per key: a fresh `fetch` closure every render must
|
|
59
61
|
// not resubscribe.
|
|
60
62
|
const stable = useMemo(() => options, [hash]);
|
|
63
|
+
const refetch = useCallback(async () => {
|
|
64
|
+
if (!stable)
|
|
65
|
+
return IDLE;
|
|
66
|
+
const client = getQueryClient();
|
|
67
|
+
client.invalidate(stable.key);
|
|
68
|
+
try {
|
|
69
|
+
await client.fetch(stable);
|
|
70
|
+
}
|
|
71
|
+
catch (_error) {
|
|
72
|
+
// The cache publishes the failure to every observer. Return that state just as the
|
|
73
|
+
// initial subscription does, so an event handler can safely use `void query.refetch()`.
|
|
74
|
+
}
|
|
75
|
+
return client.getState(stable.key);
|
|
76
|
+
}, [stable]);
|
|
61
77
|
const [state, setState] = useState(() => ({
|
|
62
78
|
hash,
|
|
63
79
|
value: stable ? getQueryClient().getState(stable.key) : IDLE,
|
|
@@ -114,5 +130,5 @@ export function useQuery(options) {
|
|
|
114
130
|
const client = getQueryClient();
|
|
115
131
|
return client.subscribe(stable, (value) => setState({ hash, value }));
|
|
116
132
|
}, [stable, hash]);
|
|
117
|
-
return value;
|
|
133
|
+
return useMemo(() => ({ ...value, refetch }), [value, refetch]);
|
|
118
134
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-query-react",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.0",
|
|
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",
|