@molecule/app-query-react 1.4.0 → 1.6.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-12T14:06:05.610Z
6
+ Generated: 2026-11-14T04:22:15.656Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-query-react
@@ -302,10 +302,19 @@ const page = tickets.listPage(
302
302
  // and tickets.refresh('agent-1') refresh this page too.
303
303
  // A second list can use tickets.listPage(viewer, params, readPage, '/tickets/open').
304
304
  // Use one canonical page reader per path; list() still returns only its own rows.
305
+ // For immediate deletion from an opaque page, add a fifth argument:
306
+ // (page, id) => {
307
+ // const rows = page.tickets.filter((row) => String(row.id) !== id)
308
+ // return { ...page, tickets: rows, total: page.total - (page.tickets.length - rows.length) }
309
+ // }
305
310
  ```
306
311
 
307
312
  A resource mutation also waits out a pre-mutation list request before fetching again;
308
313
  joining that older in-flight read alone would leave the new record absent.
314
+ Successful deletion removes a row immediately, including one just created through the
315
+ resource. Stale reads cannot restore acknowledged deletions for that viewer; an explicit
316
+ successful create can recreate the identity. Opaque listPage envelopes need their own
317
+ removeFromPage adapter; no row or total property is guessed.
309
318
 
310
319
  ## Type
311
320
 
@@ -394,12 +403,15 @@ interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
394
403
  * Options for a collection's whole page (rows plus totals), or a filtered collection path.
395
404
  * Reads share this resource's mutation refresh and viewer isolation. `readPage` reads the
396
405
  * canonical page response for `path`; row-only `list` reads keep a separate cache entry.
406
+ * Supply `removeFromPage` for opaque page envelopes to remove acknowledged deletions
407
+ * immediately and keep stale list responses from restoring them.
397
408
  */
398
409
  listPage<Page>(
399
410
  viewer: string,
400
411
  params: Record<string, unknown>,
401
412
  readPage: (response: ResourceResponse) => Page,
402
413
  path?: string,
414
+ removeFromPage?: (page: Page, id: string) => Page,
403
415
  ): QueryOptions<Page>
404
416
  /**
405
417
  * `useQuery` options for one record, or null while `id` is not known yet (`useQuery(null)`
@@ -410,7 +422,7 @@ interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
410
422
  create(viewer: string, input: Create): Promise<T>
411
423
  /** Updates a record, shows the saved record in the cache and refreshes the lists on screen. */
412
424
  update(viewer: string, id: string, input: Update): Promise<T>
413
- /** Removes a record, drops it from the cache and refreshes the lists on screen. */
425
+ /** Removes a record from detail and tracked row lists, then refreshes those lists. */
414
426
  remove(viewer: string, id: string): Promise<void>
415
427
  /**
416
428
  * Switches a flag the API models as a sub-path: `POST path/id/action` turns it on and
@@ -448,6 +460,25 @@ interface UseQueryResult<T> extends QueryState<T> {
448
460
  }
449
461
  ```
450
462
 
463
+ #### `QueryContentProps`
464
+
465
+ A loaded document owns its controls; absent documents expose only status content.
466
+
467
+ ```typescript
468
+ interface QueryContentProps<T> {
469
+ /** State from useQuery, or any compatible query observer. */
470
+ query: Pick<QueryState<T>, 'data' | 'status' | 'error'>
471
+ /** Mounted only with a real document, including false, zero and an empty list. */
472
+ children: (data: NonNullable<T>) => ReactNode
473
+ /** Initial idle/loading content. Render a status node, never a fake item or action. */
474
+ pending?: ReactNode
475
+ /** Content for a loaded null record. Null is distinct from an unfinished request. */
476
+ missing?: ReactNode
477
+ /** A failed initial read. Cached data stays visible if its refresh fails. */
478
+ error?: (error: unknown) => ReactNode
479
+ }
480
+ ```
481
+
451
482
  #### `IntentPrefetchProps`
452
483
 
453
484
  The handlers {@link intentPrefetchProps} returns.
@@ -462,6 +493,28 @@ interface IntentPrefetchProps {
462
493
 
463
494
  ### Functions
464
495
 
496
+ #### `QueryContent(props)`
497
+
498
+ The loaded-data branch receives a non-null document. Pending, failed initial reads and
499
+ missing records never mount that branch, so its actions cannot swallow an early click.
500
+ Cached data remains mounted during refresh, including a failed refresh. Status fallbacks
501
+ belong outside the list or record container rendered by `children`, and so does a refresh
502
+ line; the default fallbacks render nothing.
503
+
504
+ ```typescript
505
+ function QueryContent<T>({
506
+ query,
507
+ children,
508
+ pending = null,
509
+ missing = null,
510
+ error,
511
+ }: QueryContentProps<T>): ReactNode
512
+ ```
513
+
514
+ - `props` — Query state, loaded content and optional status fallbacks.
515
+
516
+ **Returns:** Loaded content or the appropriate fallback.
517
+
465
518
  #### `createQueryResource(config)`
466
519
 
467
520
  Describe one API resource once and get its reads and writes on the shared cache.
@@ -647,3 +700,25 @@ Peer dependencies:
647
700
  `client.invalidate(prefix)` marks the affected reads stale for their next
648
701
  mount. Which key and which scope is the app's decision: the cache does not
649
702
  infer it from auth or form state.
703
+
704
+ Render resource-dependent lists and controls through {@link QueryContent}. Its child function
705
+ receives only loaded, non-null data; loading and error content never mount item actions.
706
+ It renders cached content during refresh and treats an empty list, false and zero as data.
707
+ Put the list, or the record's own container (its card, header or profile block), inside the
708
+ child and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
709
+ a reader that finds the container and reads its paragraph must read the record, not "Loading…".
710
+
711
+ ```tsx
712
+ <QueryContent
713
+ query={query}
714
+ pending={<p role="status">{loadingLabel}</p>}
715
+ missing={<p>{missingLabel}</p>}
716
+ error={() => <p role="alert">{errorLabel}</p>}
717
+ >
718
+ {(record) => <RecordActions record={record} />}
719
+ </QueryContent>
720
+ ```
721
+
722
+ Keep every resource identity in the query key. A boundary cannot correct a query that supplies
723
+ another record's cached data. For a list, map real rows inside the child; never style a status
724
+ placeholder as a row. QueryContent is headless and owns no translations or styling.
package/dist/index.d.ts CHANGED
@@ -271,9 +271,18 @@
271
271
  * // and tickets.refresh('agent-1') refresh this page too.
272
272
  * // A second list can use tickets.listPage(viewer, params, readPage, '/tickets/open').
273
273
  * // Use one canonical page reader per path; list() still returns only its own rows.
274
+ * // For immediate deletion from an opaque page, add a fifth argument:
275
+ * // (page, id) => {
276
+ * // const rows = page.tickets.filter((row) => String(row.id) !== id)
277
+ * // return { ...page, tickets: rows, total: page.total - (page.tickets.length - rows.length) }
278
+ * // }
274
279
  * ```
275
280
  * A resource mutation also waits out a pre-mutation list request before fetching again;
276
281
  * joining that older in-flight read alone would leave the new record absent.
282
+ * Successful deletion removes a row immediately, including one just created through the
283
+ * resource. Stale reads cannot restore acknowledged deletions for that viewer; an explicit
284
+ * successful create can recreate the identity. Opaque listPage envelopes need their own
285
+ * removeFromPage adapter; no row or total property is guessed.
277
286
  *
278
287
  * @remarks
279
288
  * - **`useQuery` reads the cache synchronously on the first render.** A
@@ -344,8 +353,27 @@
344
353
  * mount. Which key and which scope is the app's decision: the cache does not
345
354
  * infer it from auth or form state.
346
355
  *
356
+ * Render resource-dependent lists and controls through {@link QueryContent}. Its child function
357
+ * receives only loaded, non-null data; loading and error content never mount item actions.
358
+ * It renders cached content during refresh and treats an empty list, false and zero as data.
359
+ * Put the list, or the record's own container (its card, header or profile block), inside the
360
+ * child and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
361
+ * a reader that finds the container and reads its paragraph must read the record, not "Loading…".
362
+ *
363
+ * ```tsx
364
+ * <QueryContent query={query} pending={<p role="status">{loadingLabel}</p>}
365
+ * missing={<p>{missingLabel}</p>} error={() => <p role="alert">{errorLabel}</p>}>
366
+ * {(record) => <RecordActions record={record} />}
367
+ * </QueryContent>
368
+ * ```
369
+ *
370
+ * Keep every resource identity in the query key. A boundary cannot correct a query that supplies
371
+ * another record's cached data. For a list, map real rows inside the child; never style a status
372
+ * placeholder as a row. QueryContent is headless and owns no translations or styling.
373
+ *
347
374
  * @module
348
375
  */
376
+ export * from './query-content.js';
349
377
  export * from './resource.js';
350
378
  export * from './types.js';
351
379
  export * from './usePrefetch.js';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2VG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsXG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
package/dist/index.js CHANGED
@@ -271,9 +271,18 @@
271
271
  * // and tickets.refresh('agent-1') refresh this page too.
272
272
  * // A second list can use tickets.listPage(viewer, params, readPage, '/tickets/open').
273
273
  * // Use one canonical page reader per path; list() still returns only its own rows.
274
+ * // For immediate deletion from an opaque page, add a fifth argument:
275
+ * // (page, id) => {
276
+ * // const rows = page.tickets.filter((row) => String(row.id) !== id)
277
+ * // return { ...page, tickets: rows, total: page.total - (page.tickets.length - rows.length) }
278
+ * // }
274
279
  * ```
275
280
  * A resource mutation also waits out a pre-mutation list request before fetching again;
276
281
  * joining that older in-flight read alone would leave the new record absent.
282
+ * Successful deletion removes a row immediately, including one just created through the
283
+ * resource. Stale reads cannot restore acknowledged deletions for that viewer; an explicit
284
+ * successful create can recreate the identity. Opaque listPage envelopes need their own
285
+ * removeFromPage adapter; no row or total property is guessed.
277
286
  *
278
287
  * @remarks
279
288
  * - **`useQuery` reads the cache synchronously on the first render.** A
@@ -344,8 +353,27 @@
344
353
  * mount. Which key and which scope is the app's decision: the cache does not
345
354
  * infer it from auth or form state.
346
355
  *
356
+ * Render resource-dependent lists and controls through {@link QueryContent}. Its child function
357
+ * receives only loaded, non-null data; loading and error content never mount item actions.
358
+ * It renders cached content during refresh and treats an empty list, false and zero as data.
359
+ * Put the list, or the record's own container (its card, header or profile block), inside the
360
+ * child and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
361
+ * a reader that finds the container and reads its paragraph must read the record, not "Loading…".
362
+ *
363
+ * ```tsx
364
+ * <QueryContent query={query} pending={<p role="status">{loadingLabel}</p>}
365
+ * missing={<p>{missingLabel}</p>} error={() => <p role="alert">{errorLabel}</p>}>
366
+ * {(record) => <RecordActions record={record} />}
367
+ * </QueryContent>
368
+ * ```
369
+ *
370
+ * Keep every resource identity in the query key. A boundary cannot correct a query that supplies
371
+ * another record's cached data. For a list, map real rows inside the child; never style a status
372
+ * placeholder as a row. QueryContent is headless and owns no translations or styling.
373
+ *
347
374
  * @module
348
375
  */
376
+ export * from './query-content.js';
349
377
  export * from './resource.js';
350
378
  export * from './types.js';
351
379
  export * from './usePrefetch.js';
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Render resource-dependent content only after its document exists.
3
+ * @module
4
+ */
5
+ import type { ReactNode } from 'react';
6
+ import type { QueryContentProps } from './types.js';
7
+ /**
8
+ * The loaded-data branch receives a non-null document. Pending, failed initial reads and
9
+ * missing records never mount that branch, so its actions cannot swallow an early click.
10
+ * Cached data remains mounted during refresh, including a failed refresh. Status fallbacks
11
+ * belong outside the list or record container rendered by `children`, and so does a refresh
12
+ * line; the default fallbacks render nothing.
13
+ *
14
+ * @param props - Query state, loaded content and optional status fallbacks.
15
+ * @returns Loaded content or the appropriate fallback.
16
+ */
17
+ export declare function QueryContent<T>({ query, children, pending, missing, error, }: QueryContentProps<T>): ReactNode;
18
+ //# sourceMappingURL=query-content.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"query-content.d.ts","sourceRoot":"","sources":["../src/query-content.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAC9B,KAAK,EACL,QAAQ,EACR,OAAc,EACd,OAAc,EACd,KAAK,GACN,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,CAMlC"}
@@ -0,0 +1,18 @@
1
+ /**
2
+ * The loaded-data branch receives a non-null document. Pending, failed initial reads and
3
+ * missing records never mount that branch, so its actions cannot swallow an early click.
4
+ * Cached data remains mounted during refresh, including a failed refresh. Status fallbacks
5
+ * belong outside the list or record container rendered by `children`, and so does a refresh
6
+ * line; the default fallbacks render nothing.
7
+ *
8
+ * @param props - Query state, loaded content and optional status fallbacks.
9
+ * @returns Loaded content or the appropriate fallback.
10
+ */
11
+ export function QueryContent({ query, children, pending = null, missing = null, error, }) {
12
+ if (query.data === undefined) {
13
+ return query.status === 'error' && error ? error(query.error) : pending;
14
+ }
15
+ if (query.data === null)
16
+ return missing;
17
+ return children(query.data);
18
+ }
@@ -57,8 +57,10 @@ export interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
57
57
  * Options for a collection's whole page (rows plus totals), or a filtered collection path.
58
58
  * Reads share this resource's mutation refresh and viewer isolation. `readPage` reads the
59
59
  * canonical page response for `path`; row-only `list` reads keep a separate cache entry.
60
+ * Supply `removeFromPage` for opaque page envelopes to remove acknowledged deletions
61
+ * immediately and keep stale list responses from restoring them.
60
62
  */
61
- listPage<Page>(viewer: string, params: Record<string, unknown>, readPage: (response: ResourceResponse) => Page, path?: string): QueryOptions<Page>;
63
+ listPage<Page>(viewer: string, params: Record<string, unknown>, readPage: (response: ResourceResponse) => Page, path?: string, removeFromPage?: (page: Page, id: string) => Page): QueryOptions<Page>;
62
64
  /**
63
65
  * `useQuery` options for one record, or null while `id` is not known yet (`useQuery(null)`
64
66
  * observes nothing). A missing record resolves to null, not to an error.
@@ -68,7 +70,7 @@ export interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
68
70
  create(viewer: string, input: Create): Promise<T>;
69
71
  /** Updates a record, shows the saved record in the cache and refreshes the lists on screen. */
70
72
  update(viewer: string, id: string, input: Update): Promise<T>;
71
- /** Removes a record, drops it from the cache and refreshes the lists on screen. */
73
+ /** Removes a record from detail and tracked row lists, then refreshes those lists. */
72
74
  remove(viewer: string, id: string): Promise<void>;
73
75
  /**
74
76
  * Switches a flag the API models as a sub-path: `POST path/id/action` turns it on and
@@ -1 +1 @@
1
- {"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"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"}
package/dist/resource.js CHANGED
@@ -34,10 +34,31 @@ export function createQueryResource(config) {
34
34
  // The lists handed out most recently, newest last: the ones a write fetches again. A list
35
35
  // nobody reads any more costs one request and is then dropped by the next ones.
36
36
  const recent = new Map();
37
- const track = (viewer, options) => {
37
+ const removed = new Map();
38
+ const removals = (viewer) => removed.get(viewer) ?? new Set();
39
+ const recordId = (record) => {
40
+ const id = record != null ? record[idField] : undefined;
41
+ return typeof id === 'string' || typeof id === 'number' ? String(id) : undefined;
42
+ };
43
+ const withoutRemoved = (viewer, rows) => {
44
+ const ids = removed.get(viewer);
45
+ return ids?.size ? rows.filter((record) => !ids.has(recordId(record) ?? '')) : rows;
46
+ };
47
+ const projectPage = (viewer, page, remove) => {
48
+ if (!remove)
49
+ return page;
50
+ for (const id of removals(viewer))
51
+ page = remove(page, id);
52
+ return page;
53
+ };
54
+ const track = (viewer, options, remove) => {
38
55
  const hash = hashQueryKey(options.key);
39
56
  recent.delete(hash);
40
- recent.set(hash, { viewer, options });
57
+ recent.set(hash, {
58
+ viewer,
59
+ options,
60
+ ...(remove ? { remove: (page, id) => remove(page, id) } : {}),
61
+ });
41
62
  for (const stale of [...recent.keys()].slice(0, -REFRESHED_LISTS))
42
63
  recent.delete(stale);
43
64
  return options;
@@ -47,9 +68,9 @@ export function createQueryResource(config) {
47
68
  key: [config.name, viewer, 'list', params],
48
69
  principal: viewer,
49
70
  keepPreviousData: true,
50
- fetch: async (signal) => readList(await config.http().get(base, { signal, params })),
71
+ fetch: async (signal) => withoutRemoved(viewer, readList(await config.http().get(base, { signal, params }))),
51
72
  };
52
- return track(viewer, options);
73
+ return track(viewer, options, (rows) => withoutRemoved(viewer, rows));
53
74
  };
54
75
  const refresh = async (viewer) => {
55
76
  const client = getQueryClient();
@@ -70,32 +91,39 @@ export function createQueryResource(config) {
70
91
  }
71
92
  }));
72
93
  };
73
- const saved = async (viewer, response) => {
94
+ const saved = async (viewer, response, created = false) => {
74
95
  const record = readOne(response);
75
96
  if (record == null)
76
97
  throw new Error(`${config.name}: the response held no record`);
77
- const id = record[idField];
78
- if (typeof id === 'string' || typeof id === 'number')
79
- getQueryClient().set(detailKey(viewer, String(id)), record);
98
+ const id = recordId(record);
99
+ if (id !== undefined) {
100
+ if (created)
101
+ removed.get(viewer)?.delete(id);
102
+ if (!removals(viewer).has(id))
103
+ getQueryClient().set(detailKey(viewer, id), record);
104
+ }
80
105
  await refresh(viewer);
81
106
  return record;
82
107
  };
83
108
  return {
84
109
  list,
85
- listPage: (viewer, params, readPage, path = base) => track(viewer, {
110
+ listPage: (viewer, params, readPage, path = base, removeFromPage) => track(viewer, {
86
111
  key: [config.name, viewer, 'list', 'page', path, params],
87
112
  principal: viewer,
88
113
  keepPreviousData: true,
89
- fetch: async (signal) => readPage(await config.http().get(path, { signal, params })),
90
- }),
114
+ fetch: async (signal) => projectPage(viewer, readPage(await config.http().get(path, { signal, params })), removeFromPage),
115
+ }, removeFromPage),
91
116
  detail: (viewer, id) => id == null || id === ''
92
117
  ? null
93
118
  : {
94
119
  key: detailKey(viewer, id),
95
120
  principal: viewer,
96
121
  fetch: async (signal) => {
122
+ if (removals(viewer).has(id))
123
+ return null;
97
124
  try {
98
- return readOne(await config.http().get(one(id), { signal }));
125
+ const record = readOne(await config.http().get(one(id), { signal }));
126
+ return removals(viewer).has(id) ? null : record;
99
127
  }
100
128
  catch (error) {
101
129
  // A record that does not exist is an answer, not a failed load.
@@ -105,11 +133,22 @@ export function createQueryResource(config) {
105
133
  }
106
134
  },
107
135
  },
108
- create: async (viewer, input) => saved(viewer, await config.http().post(base, input)),
136
+ create: async (viewer, input) => saved(viewer, await config.http().post(base, input), true),
109
137
  update: async (viewer, id, input) => saved(viewer, await config.http()[config.updateMethod ?? 'put'](one(id), input)),
110
138
  remove: async (viewer, id) => {
111
139
  await config.http().delete(one(id));
112
- getQueryClient().set(detailKey(viewer, id), null);
140
+ const ids = removed.get(viewer) ?? new Set();
141
+ ids.add(id);
142
+ removed.set(viewer, ids);
143
+ const client = getQueryClient();
144
+ client.set(detailKey(viewer, id), null);
145
+ for (const entry of recent.values()) {
146
+ if (entry.viewer !== viewer || !entry.remove)
147
+ continue;
148
+ const page = client.getState(entry.options.key).data;
149
+ if (page !== undefined)
150
+ client.set(entry.options.key, entry.remove(page, id));
151
+ }
113
152
  await refresh(viewer);
114
153
  },
115
154
  toggle: async (viewer, id, action, on) => {
package/dist/types.d.ts CHANGED
@@ -2,6 +2,7 @@
2
2
  * React query observer contracts.
3
3
  * @module
4
4
  */
5
+ import type { ReactNode } from 'react';
5
6
  import type { QueryState } from '@molecule/app-query';
6
7
  /** A mounted query's state and its explicit cache and refresh actions. */
7
8
  export interface UseQueryResult<T> extends QueryState<T> {
@@ -22,4 +23,17 @@ export interface UseQueryResult<T> extends QueryState<T> {
22
23
  */
23
24
  refetch: () => Promise<QueryState<T>>;
24
25
  }
26
+ /** A loaded document owns its controls; absent documents expose only status content. */
27
+ export interface QueryContentProps<T> {
28
+ /** State from useQuery, or any compatible query observer. */
29
+ query: Pick<QueryState<T>, 'data' | 'status' | 'error'>;
30
+ /** Mounted only with a real document, including false, zero and an empty list. */
31
+ children: (data: NonNullable<T>) => ReactNode;
32
+ /** Initial idle/loading content. Render a status node, never a fake item or action. */
33
+ pending?: ReactNode;
34
+ /** Content for a loaded null record. Null is distinct from an unfinished request. */
35
+ missing?: ReactNode;
36
+ /** A failed initial read. Cached data stays visible if its refresh fails. */
37
+ error?: (error: unknown) => ReactNode;
38
+ }
25
39
  //# sourceMappingURL=types.d.ts.map
@@ -1 +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,0EAA0E;AAC1E,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD;;;;;;;;OAQG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;IAC1E;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;CACtC"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,0EAA0E;AAC1E,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD;;;;;;;;OAQG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;IAC1E;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;CACtC;AAED,wFAAwF;AACxF,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,6DAA6D;IAC7D,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,CAAA;IACvD,kFAAkF;IAClF,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,SAAS,CAAA;IAC7C,uFAAuF;IACvF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qFAAqF;IACrF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,CAAA;CACtC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-query-react",
3
- "version": "1.4.0",
3
+ "version": "1.6.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",
@@ -41,8 +41,8 @@
41
41
  },
42
42
  "devDependencies": {
43
43
  "@molecule/app-query": "1.1.3",
44
- "@molecule/app-query-memory": "1.0.4",
45
- "@molecule/app-query-tanstack": "1.0.4",
44
+ "@molecule/app-query-memory": "1.0.5",
45
+ "@molecule/app-query-tanstack": "1.0.5",
46
46
  "@types/node": "26.6.5",
47
47
  "@types/react": "19.3.0",
48
48
  "@types/react-dom": "19.3.0",