@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 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-11T18:03:13.387Z
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): QueryState<T>
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. `isPreviousData` is `true` while `data` is the previous key's document for the same principal.
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
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuTG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
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';
@@ -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 {};
@@ -3,7 +3,8 @@
3
3
  *
4
4
  * @module
5
5
  */
6
- import type { QueryOptions, QueryState } from '@molecule/app-query';
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. `isPreviousData` is `true` while `data` is
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): QueryState<T>;
46
+ export declare function useQuery<T>(options: QueryOptions<T> | null): UseQueryResult<T>;
44
47
  //# sourceMappingURL=useQuery.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"useQuery.d.ts","sourceRoot":"","sources":["../src/useQuery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAwBnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,CA0E1E"}
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. `isPreviousData` is `true` while `data` is
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.2.0",
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",