@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 +77 -2
- package/dist/index.d.ts +28 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +28 -0
- package/dist/query-content.d.ts +18 -0
- package/dist/query-content.d.ts.map +1 -0
- package/dist/query-content.js +18 -0
- package/dist/resource.d.ts +4 -2
- package/dist/resource.d.ts.map +1 -1
- package/dist/resource.js +53 -14
- package/dist/types.d.ts +14 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +3 -3
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-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
|
|
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';
|
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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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
|
+
}
|
package/dist/resource.d.ts
CHANGED
|
@@ -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
|
|
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
|
package/dist/resource.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGjE,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAA;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GACnE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC5B,yBAAyB;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC7D,0BAA0B;IAC1B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC5D,4CAA4C;IAC5C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC9D,yBAAyB;IACzB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAChD;AAED,yEAAyE;AACzE,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,0FAA0F;IAC1F,IAAI,EAAE,MAAM,YAAY,CAAA;IACxB,uEAAuE;IACvE,EAAE,CAAC,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACrB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,CAAC,EAAE,CAAA;IAC9C,uFAAuF;IACvF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,CAAC,GAAG,IAAI,CAAA;CACnD;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IACxE;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC,CAAA;IACzE
|
|
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
|
|
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, {
|
|
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
|
|
78
|
-
if (
|
|
79
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
package/dist/types.d.ts.map
CHANGED
|
@@ -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.
|
|
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.
|
|
45
|
-
"@molecule/app-query-tanstack": "1.0.
|
|
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",
|