@molecule/app-query-solid 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-14T17:17:22.084Z
6
+ Generated: 2026-11-14T22:00:52.564Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-query-solid
@@ -475,6 +475,39 @@ interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
475
475
  }
476
476
  ```
477
477
 
478
+ #### `ListQueryRoute`
479
+
480
+ The list route a list query reads: `useListRoute` from `@molecule/app-solid` returns these
481
+ accessors (and more), so its result is passed as it is.
482
+
483
+ ```typescript
484
+ interface ListQueryRoute<Filter extends string = string> {
485
+ /** False while a protected view waits for auth, is signed out, or is unavailable. */
486
+ readonly canLoad: Accessor<boolean>
487
+ /** The current URL filter values. */
488
+ readonly filters: Accessor<Readonly<Record<Filter, string | undefined>>>
489
+ /** The configured items per page. */
490
+ readonly pageSize: Accessor<number>
491
+ /** The zero-indexed item offset for the API request. */
492
+ readonly offset: Accessor<number>
493
+ }
494
+ ```
495
+
496
+ #### `ListQueryState`
497
+
498
+ The route's current values, as `read` receives them.
499
+
500
+ ```typescript
501
+ interface ListQueryState<Filter extends string = string> {
502
+ /** The current URL filter values. */
503
+ readonly filters: Readonly<Record<Filter, string | undefined>>
504
+ /** The configured items per page. */
505
+ readonly pageSize: number
506
+ /** The zero-indexed item offset for the API request. */
507
+ readonly offset: number
508
+ }
509
+ ```
510
+
478
511
  #### `UseQueryResult`
479
512
 
480
513
  A mounted query's state and its explicit cache and refresh actions. The state
@@ -540,6 +573,26 @@ interface IntentPrefetchProps {
540
573
  }
541
574
  ```
542
575
 
576
+ ### Types
577
+
578
+ #### `ListQuerySource`
579
+
580
+ A plain value or an accessor: each input {@link useListQuery} reads reactively.
581
+
582
+ ```typescript
583
+ type ListQuerySource<T> = T | Accessor<T>
584
+ ```
585
+
586
+ #### `ListQueryInputs`
587
+
588
+ Each input of {@link useListQuery} as a {@link ListQuerySource}.
589
+
590
+ ```typescript
591
+ type ListQueryInputs<Values> = {
592
+ readonly [Key in keyof Values]: ListQuerySource<Values[Key]>
593
+ }
594
+ ```
595
+
543
596
  ### Functions
544
597
 
545
598
  #### `prefetchQuery(options)`
@@ -589,6 +642,28 @@ function createQueryResource<T, Create = Partial<T>, Update = Partial<T>>(
589
642
 
590
643
  **Returns:** List and detail query options, and create, update, remove, toggle and refresh.
591
644
 
645
+ #### `useListQuery(route, inputs, read)`
646
+
647
+ Observe the page a URL list route points at. `read` builds the query from the current value of
648
+ each input (the signed-in `viewer`, request params, a parent record's id) and the route's
649
+ filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
650
+ null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
651
+ the same observer to the new page.
652
+
653
+ ```typescript
654
+ function useListQuery<T, Values extends { viewer: string | null }, Filter extends string = string>(
655
+ route: ListQueryRoute<Filter>,
656
+ inputs: ListQueryInputs<Values>,
657
+ read: (values: Values & { viewer: string }, list: ListQueryState<Filter>) => QueryOptions<T>,
658
+ ): UseQueryResult<T>
659
+ ```
660
+
661
+ - `route` — The list route, usually `useListRoute(...)` from `@molecule/app-solid`.
662
+ - `inputs` — Plain values or accessors; `viewer` is the signed-in user's id, 'anonymous', or null while auth is restoring.
663
+ - `read` — Builds the page's query options, e.g. a generated `articlesPage(...)`.
664
+
665
+ **Returns:** The query state, as {@link useQuery} returns it.
666
+
592
667
  #### `QueryContent(props)`
593
668
 
594
669
  The loaded-data branch receives a non-null document. Pending, failed initial reads and
package/dist/index.d.ts CHANGED
@@ -424,6 +424,7 @@
424
424
  *
425
425
  * @module
426
426
  */
427
+ export * from './list-query.js';
427
428
  export * from './query-content.jsx';
428
429
  export * from './resource.js';
429
430
  export * from './types.js';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyaG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyaG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
package/dist/index.js CHANGED
@@ -424,6 +424,7 @@
424
424
  *
425
425
  * @module
426
426
  */
427
+ export * from './list-query.js';
427
428
  export * from './query-content.jsx';
428
429
  export * from './resource.js';
429
430
  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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyaG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyaG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
@@ -0,0 +1,56 @@
1
+ /**
2
+ * `useListQuery`: one cached read driven by a URL list route.
3
+ *
4
+ * @module
5
+ */
6
+ import type { Accessor } from 'solid-js';
7
+ import type { QueryOptions } from '@molecule/app-query';
8
+ import type { UseQueryResult } from './types.js';
9
+ /** A plain value or an accessor: each input {@link useListQuery} reads reactively. */
10
+ export type ListQuerySource<T> = T | Accessor<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 route a list query reads: `useListRoute` from `@molecule/app-solid` returns these
17
+ * accessors (and more), so its result is passed as it is.
18
+ */
19
+ export interface ListQueryRoute<Filter extends string = string> {
20
+ /** False while a protected view waits for auth, is signed out, or is unavailable. */
21
+ readonly canLoad: Accessor<boolean>;
22
+ /** The current URL filter values. */
23
+ readonly filters: Accessor<Readonly<Record<Filter, string | undefined>>>;
24
+ /** The configured items per page. */
25
+ readonly pageSize: Accessor<number>;
26
+ /** The zero-indexed item offset for the API request. */
27
+ readonly offset: Accessor<number>;
28
+ }
29
+ /** The route's current values, as `read` receives them. */
30
+ export interface ListQueryState<Filter extends string = string> {
31
+ /** The current URL filter values. */
32
+ readonly filters: Readonly<Record<Filter, string | undefined>>;
33
+ /** The configured items per page. */
34
+ readonly pageSize: number;
35
+ /** The zero-indexed item offset for the API request. */
36
+ readonly offset: number;
37
+ }
38
+ /**
39
+ * Observe the page a URL list route points at. `read` builds the query from the current value of
40
+ * each input (the signed-in `viewer`, request params, a parent record's id) and the route's
41
+ * filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
42
+ * null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
43
+ * the same observer to the new page.
44
+ *
45
+ * @param route - The list route, usually `useListRoute(...)` from `@molecule/app-solid`.
46
+ * @param inputs - Plain values or accessors; `viewer` is the signed-in user's id, 'anonymous',
47
+ * or null while auth is restoring.
48
+ * @param read - Builds the page's query options, e.g. a generated `articlesPage(...)`.
49
+ * @returns The query state, as {@link useQuery} returns it.
50
+ */
51
+ export declare function useListQuery<T, Values extends {
52
+ viewer: string | null;
53
+ }, Filter extends string = string>(route: ListQueryRoute<Filter>, inputs: ListQueryInputs<Values>, read: (values: Values & {
54
+ viewer: string;
55
+ }, list: ListQueryState<Filter>) => QueryOptions<T>): UseQueryResult<T>;
56
+ //# 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,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhD,sFAAsF;AACtF,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;AAEhD,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,QAAQ,CAAC,OAAO,CAAC,CAAA;IACnC,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;IACxE,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACnC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;CAClC;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IAC5D,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;AAWD;;;;;;;;;;;;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,cAAc,CAAC,MAAM,CAAC,EAC7B,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,cAAc,CAAC,CAAC,CAAC,CAYnB"}
@@ -0,0 +1,33 @@
1
+ import { useQuery } from './use-query.js';
2
+ /**
3
+ * Reads a plain value or an accessor; inside the query's options accessor the read is tracked.
4
+ *
5
+ * @param source - The argument as the caller passed it.
6
+ * @returns Its current value.
7
+ */
8
+ const access = (source) => typeof source === 'function' ? source() : source;
9
+ /**
10
+ * Observe the page a URL list route points at. `read` builds the query from the current value of
11
+ * each input (the signed-in `viewer`, request params, a parent record's id) and the route's
12
+ * filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
13
+ * null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
14
+ * the same observer to the new page.
15
+ *
16
+ * @param route - The list route, usually `useListRoute(...)` from `@molecule/app-solid`.
17
+ * @param inputs - Plain values or accessors; `viewer` is the signed-in user's id, 'anonymous',
18
+ * or null while auth is restoring.
19
+ * @param read - Builds the page's query options, e.g. a generated `articlesPage(...)`.
20
+ * @returns The query state, as {@link useQuery} returns it.
21
+ */
22
+ export function useListQuery(route, inputs, read) {
23
+ return useQuery(() => {
24
+ const values = {};
25
+ for (const key of Object.keys(inputs))
26
+ values[key] = access(inputs[key]);
27
+ const { viewer } = values;
28
+ if (viewer === null || !route.canLoad())
29
+ return null;
30
+ return read({ ...values, viewer }, { filters: route.filters(), pageSize: route.pageSize(), offset: route.offset() });
31
+ });
32
+ }
33
+ //# sourceMappingURL=list-query.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"list-query.js","sourceRoot":"","sources":["../src/list-query.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAmCzC;;;;;GAKG;AACH,MAAM,MAAM,GAAG,CAAI,MAA0B,EAAK,EAAE,CAClD,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAE,MAAsB,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;AAEnE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAK1B,KAA6B,EAC7B,MAA+B,EAC/B,IAA4F;IAE5F,OAAO,QAAQ,CAAI,GAAG,EAAE;QACtB,MAAM,MAAM,GAAoB,EAAE,CAAA;QAClC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAqB;YACvD,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAuB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QACzD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAgB,CAAA;QACnC,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;YAAE,OAAO,IAAI,CAAA;QACpD,OAAO,IAAI,CACT,EAAE,GAAI,MAAiB,EAAE,MAAM,EAAE,EACjC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,CACjF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-query-solid",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Solid 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-solid",
6
6
  "type": "module",