@molecule/app-query-vue 1.1.0 → 1.2.1

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-15T13:02:10.518Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-query-vue
@@ -208,7 +208,7 @@ explicit `fetch()` retries into the mounted page.
208
208
  ```ts
209
209
  import { getQueryClient } from '@molecule/app-query'
210
210
  import { getClient } from '@molecule/app-http'
211
- import { t } from '@molecule/app-i18n'
211
+ import { useTranslation } from '@molecule/app-vue'
212
212
  import { defineComponent, h } from 'vue'
213
213
 
214
214
  // The key names what the document actually depends on — here the signed-in
@@ -239,6 +239,7 @@ async function setFollowing(principal: string, authorId: string, follow: boolean
239
239
  const Retry = defineComponent({
240
240
  props: { principal: { type: String, required: true } },
241
241
  setup(props) {
242
+ const { t } = useTranslation()
242
243
  return () =>
243
244
  h(
244
245
  'button',
@@ -520,6 +521,24 @@ interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
520
521
  }
521
522
  ```
522
523
 
524
+ #### `ListQueryState`
525
+
526
+ The list state a list query reads. `useListRoute` from `@molecule/app-vue` returns it as a
527
+ computed ref, which {@link useListQuery} takes as it is.
528
+
529
+ ```typescript
530
+ interface ListQueryState<Filter extends string = string> {
531
+ /** False while a protected view waits for auth, is signed out, or is unavailable. */
532
+ readonly canLoad: boolean
533
+ /** The current URL filter values. */
534
+ readonly filters: Readonly<Record<Filter, string | undefined>>
535
+ /** The configured items per page. */
536
+ readonly pageSize: number
537
+ /** The zero-indexed item offset for the API request. */
538
+ readonly offset: number
539
+ }
540
+ ```
541
+
523
542
  #### `QueryContentSlots`
524
543
 
525
544
  The slots {@link QueryContent} accepts alongside its props: every node-valued
@@ -605,6 +624,24 @@ interface IntentPrefetchProps {
605
624
 
606
625
  ### Types
607
626
 
627
+ #### `ListQuerySource`
628
+
629
+ A plain value, a ref or a getter: each input {@link useListQuery} reads reactively.
630
+
631
+ ```typescript
632
+ type ListQuerySource<T> = MaybeRefOrGetter<T>
633
+ ```
634
+
635
+ #### `ListQueryInputs`
636
+
637
+ Each input of {@link useListQuery} as a {@link ListQuerySource}.
638
+
639
+ ```typescript
640
+ type ListQueryInputs<Values> = {
641
+ readonly [Key in keyof Values]: ListQuerySource<Values[Key]>
642
+ }
643
+ ```
644
+
608
645
  #### `QueryOptionsInput`
609
646
 
610
647
  What {@link useQuery} observes: the same options object React's hook takes,
@@ -665,6 +702,28 @@ function createQueryResource<T, Create = Partial<T>, Update = Partial<T>>(
665
702
 
666
703
  **Returns:** List and detail query options, and create, update, remove, toggle and refresh.
667
704
 
705
+ #### `useListQuery(route, inputs, read)`
706
+
707
+ Observe the page a URL list route points at. `read` builds the query from the current value of
708
+ each input (the signed-in `viewer`, request params, a parent record's id) and the route's
709
+ filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
710
+ null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
711
+ the same observer to the new page.
712
+
713
+ ```typescript
714
+ function useListQuery<T, Values extends { viewer: string | null }, Filter extends string = string>(
715
+ route: MaybeRefOrGetter<ListQueryState<Filter>>,
716
+ inputs: ListQueryInputs<Values>,
717
+ read: (values: Values & { viewer: string }, list: ListQueryState<Filter>) => QueryOptions<T>,
718
+ ): Ref<UseQueryResult<T>>
719
+ ```
720
+
721
+ - `route` — The list state, usually `useListRoute(...)` from `@molecule/app-vue`.
722
+ - `inputs` — Plain values, refs or getters; `viewer` is the signed-in user's id, 'anonymous', or null while auth is restoring.
723
+ - `read` — Builds the page's query options, e.g. a generated `articlesPage(...)`.
724
+
725
+ **Returns:** The query state as a ref, as {@link useQuery} returns it.
726
+
668
727
  #### `usePrefetch()`
669
728
 
670
729
  A stable `prefetch(options)` function for event handlers.
package/dist/index.d.ts CHANGED
@@ -176,7 +176,7 @@
176
176
  * ```ts
177
177
  * import { getQueryClient } from '@molecule/app-query'
178
178
  * import { getClient } from '@molecule/app-http'
179
- * import { t } from '@molecule/app-i18n'
179
+ * import { useTranslation } from '@molecule/app-vue'
180
180
  * import { defineComponent, h } from 'vue'
181
181
  *
182
182
  * // The key names what the document actually depends on — here the signed-in
@@ -207,6 +207,7 @@
207
207
  * const Retry = defineComponent({
208
208
  * props: { principal: { type: String, required: true } },
209
209
  * setup(props) {
210
+ * const { t } = useTranslation()
210
211
  * return () =>
211
212
  * h(
212
213
  * 'button',
@@ -433,6 +434,7 @@
433
434
  *
434
435
  * @module
435
436
  */
437
+ export * from './list-query.js';
436
438
  export * from './query-content.js';
437
439
  export * from './resource.js';
438
440
  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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmbG;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
@@ -176,7 +176,7 @@
176
176
  * ```ts
177
177
  * import { getQueryClient } from '@molecule/app-query'
178
178
  * import { getClient } from '@molecule/app-http'
179
- * import { t } from '@molecule/app-i18n'
179
+ * import { useTranslation } from '@molecule/app-vue'
180
180
  * import { defineComponent, h } from 'vue'
181
181
  *
182
182
  * // The key names what the document actually depends on — here the signed-in
@@ -207,6 +207,7 @@
207
207
  * const Retry = defineComponent({
208
208
  * props: { principal: { type: String, required: true } },
209
209
  * setup(props) {
210
+ * const { t } = useTranslation()
210
211
  * return () =>
211
212
  * h(
212
213
  * 'button',
@@ -433,6 +434,7 @@
433
434
  *
434
435
  * @module
435
436
  */
437
+ export * from './list-query.js';
436
438
  export * from './query-content.js';
437
439
  export * from './resource.js';
438
440
  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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmbG;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.1",
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",
@@ -50,14 +50,14 @@
50
50
  },
51
51
  "devDependencies": {
52
52
  "@molecule/app-framework-conformance": "0.0.0",
53
- "@molecule/app-i18n": "1.2.1",
53
+ "@molecule/app-i18n": "1.2.2",
54
54
  "@molecule/app-icons": "1.0.4",
55
55
  "@molecule/app-query": "1.2.0",
56
56
  "@molecule/app-query-memory": "1.0.5",
57
57
  "@molecule/app-query-tanstack": "1.0.5",
58
- "@molecule/app-ui": "1.3.11",
59
- "@molecule/app-ui-vue": "1.1.2",
60
- "@molecule/app-vue": "3.6.0",
58
+ "@molecule/app-ui": "1.4.0",
59
+ "@molecule/app-ui-vue": "1.1.4",
60
+ "@molecule/app-vue": "3.7.1",
61
61
  "@types/node": "26.6.5",
62
62
  "jsdom": "30.1.3",
63
63
  "typescript": "6.0.3",