@molecule/app-query-vue 1.1.0 → 1.2.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-14T15:07:24.568Z
6
+ Generated: 2026-11-14T22:00:55.351Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-query-vue
@@ -520,6 +520,24 @@ interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
520
520
  }
521
521
  ```
522
522
 
523
+ #### `ListQueryState`
524
+
525
+ The list state a list query reads. `useListRoute` from `@molecule/app-vue` returns it as a
526
+ computed ref, which {@link useListQuery} takes as it is.
527
+
528
+ ```typescript
529
+ interface ListQueryState<Filter extends string = string> {
530
+ /** False while a protected view waits for auth, is signed out, or is unavailable. */
531
+ readonly canLoad: boolean
532
+ /** The current URL filter values. */
533
+ readonly filters: Readonly<Record<Filter, string | undefined>>
534
+ /** The configured items per page. */
535
+ readonly pageSize: number
536
+ /** The zero-indexed item offset for the API request. */
537
+ readonly offset: number
538
+ }
539
+ ```
540
+
523
541
  #### `QueryContentSlots`
524
542
 
525
543
  The slots {@link QueryContent} accepts alongside its props: every node-valued
@@ -605,6 +623,24 @@ interface IntentPrefetchProps {
605
623
 
606
624
  ### Types
607
625
 
626
+ #### `ListQuerySource`
627
+
628
+ A plain value, a ref or a getter: each input {@link useListQuery} reads reactively.
629
+
630
+ ```typescript
631
+ type ListQuerySource<T> = MaybeRefOrGetter<T>
632
+ ```
633
+
634
+ #### `ListQueryInputs`
635
+
636
+ Each input of {@link useListQuery} as a {@link ListQuerySource}.
637
+
638
+ ```typescript
639
+ type ListQueryInputs<Values> = {
640
+ readonly [Key in keyof Values]: ListQuerySource<Values[Key]>
641
+ }
642
+ ```
643
+
608
644
  #### `QueryOptionsInput`
609
645
 
610
646
  What {@link useQuery} observes: the same options object React's hook takes,
@@ -665,6 +701,28 @@ function createQueryResource<T, Create = Partial<T>, Update = Partial<T>>(
665
701
 
666
702
  **Returns:** List and detail query options, and create, update, remove, toggle and refresh.
667
703
 
704
+ #### `useListQuery(route, inputs, read)`
705
+
706
+ Observe the page a URL list route points at. `read` builds the query from the current value of
707
+ each input (the signed-in `viewer`, request params, a parent record's id) and the route's
708
+ filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
709
+ null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
710
+ the same observer to the new page.
711
+
712
+ ```typescript
713
+ function useListQuery<T, Values extends { viewer: string | null }, Filter extends string = string>(
714
+ route: MaybeRefOrGetter<ListQueryState<Filter>>,
715
+ inputs: ListQueryInputs<Values>,
716
+ read: (values: Values & { viewer: string }, list: ListQueryState<Filter>) => QueryOptions<T>,
717
+ ): Ref<UseQueryResult<T>>
718
+ ```
719
+
720
+ - `route` — The list state, usually `useListRoute(...)` from `@molecule/app-vue`.
721
+ - `inputs` — Plain values, refs or getters; `viewer` is the signed-in user's id, 'anonymous', or null while auth is restoring.
722
+ - `read` — Builds the page's query options, e.g. a generated `articlesPage(...)`.
723
+
724
+ **Returns:** The query state as a ref, as {@link useQuery} returns it.
725
+
668
726
  #### `usePrefetch()`
669
727
 
670
728
  A stable `prefetch(options)` function for event handlers.
package/dist/index.d.ts CHANGED
@@ -433,6 +433,7 @@
433
433
  *
434
434
  * @module
435
435
  */
436
+ export * from './list-query.js';
436
437
  export * from './query-content.js';
437
438
  export * from './resource.js';
438
439
  export * from './types.js';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkbG;AAEH,cAAc,oBAAoB,CAAA;AAClC,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkbG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
package/dist/index.js CHANGED
@@ -433,6 +433,7 @@
433
433
  *
434
434
  * @module
435
435
  */
436
+ export * from './list-query.js';
436
437
  export * from './query-content.js';
437
438
  export * from './resource.js';
438
439
  export * from './types.js';
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkbG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkbG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
@@ -0,0 +1,47 @@
1
+ /**
2
+ * `useListQuery`: one cached read driven by a URL list route.
3
+ *
4
+ * @module
5
+ */
6
+ import { type MaybeRefOrGetter, type Ref } from 'vue';
7
+ import type { QueryOptions } from '@molecule/app-query';
8
+ import type { UseQueryResult } from './types.js';
9
+ /** A plain value, a ref or a getter: each input {@link useListQuery} reads reactively. */
10
+ export type ListQuerySource<T> = MaybeRefOrGetter<T>;
11
+ /** Each input of {@link useListQuery} as a {@link ListQuerySource}. */
12
+ export type ListQueryInputs<Values> = {
13
+ readonly [Key in keyof Values]: ListQuerySource<Values[Key]>;
14
+ };
15
+ /**
16
+ * The list state a list query reads. `useListRoute` from `@molecule/app-vue` returns it as a
17
+ * computed ref, which {@link useListQuery} takes as it is.
18
+ */
19
+ export interface ListQueryState<Filter extends string = string> {
20
+ /** False while a protected view waits for auth, is signed out, or is unavailable. */
21
+ readonly canLoad: boolean;
22
+ /** The current URL filter values. */
23
+ readonly filters: Readonly<Record<Filter, string | undefined>>;
24
+ /** The configured items per page. */
25
+ readonly pageSize: number;
26
+ /** The zero-indexed item offset for the API request. */
27
+ readonly offset: number;
28
+ }
29
+ /**
30
+ * Observe the page a URL list route points at. `read` builds the query from the current value of
31
+ * each input (the signed-in `viewer`, request params, a parent record's id) and the route's
32
+ * filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
33
+ * null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
34
+ * the same observer to the new page.
35
+ *
36
+ * @param route - The list state, usually `useListRoute(...)` from `@molecule/app-vue`.
37
+ * @param inputs - Plain values, refs or getters; `viewer` is the signed-in user's id,
38
+ * 'anonymous', or null while auth is restoring.
39
+ * @param read - Builds the page's query options, e.g. a generated `articlesPage(...)`.
40
+ * @returns The query state as a ref, as {@link useQuery} returns it.
41
+ */
42
+ export declare function useListQuery<T, Values extends {
43
+ viewer: string | null;
44
+ }, Filter extends string = string>(route: MaybeRefOrGetter<ListQueryState<Filter>>, inputs: ListQueryInputs<Values>, read: (values: Values & {
45
+ viewer: string;
46
+ }, list: ListQueryState<Filter>) => QueryOptions<T>): Ref<UseQueryResult<T>>;
47
+ //# sourceMappingURL=list-query.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"list-query.d.ts","sourceRoot":"","sources":["../src/list-query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,GAAG,EAAW,MAAM,KAAK,CAAA;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhD,0FAA0F;AAC1F,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAA;AAEpD,uEAAuE;AACvE,MAAM,MAAM,eAAe,CAAC,MAAM,IAAI;IACpC,QAAQ,EAAE,GAAG,IAAI,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;CAC7D,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IAC5D,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC9D,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EACD,MAAM,SAAS;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACxC,MAAM,SAAS,MAAM,GAAG,MAAM,EAE9B,KAAK,EAAE,gBAAgB,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EAC/C,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,EAC/B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,GAC3F,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CASxB"}
@@ -0,0 +1,31 @@
1
+ /**
2
+ * `useListQuery`: one cached read driven by a URL list route.
3
+ *
4
+ * @module
5
+ */
6
+ import { toValue } from 'vue';
7
+ import { useQuery } from './useQuery.js';
8
+ /**
9
+ * Observe the page a URL list route points at. `read` builds the query from the current value of
10
+ * each input (the signed-in `viewer`, request params, a parent record's id) and the route's
11
+ * filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
12
+ * null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
13
+ * the same observer to the new page.
14
+ *
15
+ * @param route - The list state, usually `useListRoute(...)` from `@molecule/app-vue`.
16
+ * @param inputs - Plain values, refs or getters; `viewer` is the signed-in user's id,
17
+ * 'anonymous', or null while auth is restoring.
18
+ * @param read - Builds the page's query options, e.g. a generated `articlesPage(...)`.
19
+ * @returns The query state as a ref, as {@link useQuery} returns it.
20
+ */
21
+ export function useListQuery(route, inputs, read) {
22
+ return useQuery(() => {
23
+ const list = toValue(route);
24
+ const values = {};
25
+ for (const key of Object.keys(inputs))
26
+ values[key] = toValue(inputs[key]);
27
+ const { viewer } = values;
28
+ return viewer !== null && list.canLoad ? read({ ...values, viewer }, list) : null;
29
+ });
30
+ }
31
+ //# sourceMappingURL=list-query.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"list-query.js","sourceRoot":"","sources":["../src/list-query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAmC,OAAO,EAAE,MAAM,KAAK,CAAA;AAK9D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAyBxC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAK1B,KAA+C,EAC/C,MAA+B,EAC/B,IAA4F;IAE5F,OAAO,QAAQ,CAAI,GAAG,EAAE;QACtB,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;QAC3B,MAAM,MAAM,GAAoB,EAAE,CAAA;QAClC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAqB;YACvD,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,CAAuB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAC1D,MAAM,EAAE,MAAM,EAAE,GAAG,MAAgB,CAAA;QACnC,OAAO,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,GAAI,MAAiB,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC/F,CAAC,CAAC,CAAA;AACJ,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-query-vue",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Vue 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-vue",
6
6
  "type": "module",