@plumile/router 0.1.12 → 0.1.13

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.
Files changed (68) hide show
  1. package/README.md +426 -13
  2. package/lib/esm/index.d.ts +4 -0
  3. package/lib/esm/index.d.ts.map +1 -1
  4. package/lib/esm/index.js +5 -1
  5. package/lib/esm/routing/createRouter.d.ts +1 -0
  6. package/lib/esm/routing/createRouter.d.ts.map +1 -1
  7. package/lib/esm/routing/createRouter.js +399 -359
  8. package/lib/esm/routing/devtools.d.ts +20 -0
  9. package/lib/esm/routing/devtools.d.ts.map +1 -0
  10. package/lib/esm/routing/devtools.js +678 -0
  11. package/lib/esm/routing/filters.d.ts +97 -0
  12. package/lib/esm/routing/filters.d.ts.map +1 -0
  13. package/lib/esm/routing/filters.js +557 -0
  14. package/lib/esm/routing/index.d.ts +6 -0
  15. package/lib/esm/routing/index.d.ts.map +1 -1
  16. package/lib/esm/routing/index.js +7 -1
  17. package/lib/esm/routing/useActiveFilters.d.ts +9 -0
  18. package/lib/esm/routing/useActiveFilters.d.ts.map +1 -0
  19. package/lib/esm/routing/useActiveFilters.js +38 -0
  20. package/lib/esm/routing/useFilterState.d.ts +10 -0
  21. package/lib/esm/routing/useFilterState.d.ts.map +1 -0
  22. package/lib/esm/routing/useFilterState.js +14 -0
  23. package/lib/esm/routing/useNavigate.d.ts +7 -0
  24. package/lib/esm/routing/useNavigate.d.ts.map +1 -1
  25. package/lib/esm/routing/useNavigate.js +1 -1
  26. package/lib/esm/routing/useNavigateWithQuery.d.ts +15 -0
  27. package/lib/esm/routing/useNavigateWithQuery.d.ts.map +1 -0
  28. package/lib/esm/routing/useNavigateWithQuery.js +95 -0
  29. package/lib/esm/routing/useQueryObject.d.ts +18 -0
  30. package/lib/esm/routing/useQueryObject.d.ts.map +1 -0
  31. package/lib/esm/routing/useQueryObject.js +107 -0
  32. package/lib/esm/routing/useStableRefEquality.d.ts +5 -0
  33. package/lib/esm/routing/useStableRefEquality.d.ts.map +1 -0
  34. package/lib/esm/routing/useStableRefEquality.js +47 -0
  35. package/lib/esm/tools/buildSearch.d.ts +8 -2
  36. package/lib/esm/tools/buildSearch.d.ts.map +1 -1
  37. package/lib/esm/tools/buildSearch.js +216 -12
  38. package/lib/esm/types.d.ts +19 -0
  39. package/lib/esm/types.d.ts.map +1 -1
  40. package/lib/esm/types.js +1 -1
  41. package/lib/tsconfig.esm.tsbuildinfo +1 -1
  42. package/lib/types/index.d.ts +4 -0
  43. package/lib/types/index.d.ts.map +1 -1
  44. package/lib/types/routing/createRouter.d.ts +1 -0
  45. package/lib/types/routing/createRouter.d.ts.map +1 -1
  46. package/lib/types/routing/devtools.d.ts +20 -0
  47. package/lib/types/routing/devtools.d.ts.map +1 -0
  48. package/lib/types/routing/filters.d.ts +97 -0
  49. package/lib/types/routing/filters.d.ts.map +1 -0
  50. package/lib/types/routing/index.d.ts +6 -0
  51. package/lib/types/routing/index.d.ts.map +1 -1
  52. package/lib/types/routing/useActiveFilters.d.ts +9 -0
  53. package/lib/types/routing/useActiveFilters.d.ts.map +1 -0
  54. package/lib/types/routing/useFilterState.d.ts +10 -0
  55. package/lib/types/routing/useFilterState.d.ts.map +1 -0
  56. package/lib/types/routing/useNavigate.d.ts +7 -0
  57. package/lib/types/routing/useNavigate.d.ts.map +1 -1
  58. package/lib/types/routing/useNavigateWithQuery.d.ts +15 -0
  59. package/lib/types/routing/useNavigateWithQuery.d.ts.map +1 -0
  60. package/lib/types/routing/useQueryObject.d.ts +18 -0
  61. package/lib/types/routing/useQueryObject.d.ts.map +1 -0
  62. package/lib/types/routing/useStableRefEquality.d.ts +5 -0
  63. package/lib/types/routing/useStableRefEquality.d.ts.map +1 -0
  64. package/lib/types/tools/buildSearch.d.ts +8 -2
  65. package/lib/types/tools/buildSearch.d.ts.map +1 -1
  66. package/lib/types/types.d.ts +19 -0
  67. package/lib/types/types.d.ts.map +1 -1
  68. package/package.json +3 -3
package/README.md CHANGED
@@ -37,6 +37,9 @@ import { Route, getResourcePage } from '@plumile/router';
37
37
  const routes: Route<any, any>[] = [
38
38
  {
39
39
  path: '/',
40
+
41
+ ## Advanced Hooks Deep Dive & Combined Examples
42
+
40
43
  resourcePage: getResourcePage('Home', () => import('./pages/Home')),
41
44
  },
42
45
  {
@@ -144,6 +147,9 @@ Navigation component that handles client-side routing.
144
147
 
145
148
  - `to`: string - Destination path
146
149
  - `exact?`: boolean - Exact path matching for active state
150
+
151
+ ### Combined Example: Products Listing Page
152
+
147
153
  - `activeClassName?`: string - CSS class when link is active
148
154
  - `className?`: string - Base CSS class
149
155
  - `preload?`: boolean - Preload route on hover
@@ -482,25 +488,113 @@ To encourage consistent usage of the query hooks, a custom rule is provided insi
482
488
 
483
489
  Add to your flat ESLint config:
484
490
 
485
- ```js
491
+ ````js
486
492
  import noDirectWindowLocationSearch from '@plumile/router/lib/eslint-rules/no-direct-window-location-search.js';
487
493
 
488
494
  export default [
489
495
  {
490
- plugins: {
491
- '@plumile-router/dx': {
492
- rules: {
493
- 'no-direct-window-location-search': noDirectWindowLocationSearch,
494
- },
495
- },
496
- },
497
- rules: {
498
- '@plumile-router/dx/no-direct-window-location-search': 'warn',
499
- },
500
- },
496
+
497
+ ## Batched Navigation & Provisional typedQuery Contract
498
+
499
+ The router supports two batching modes:
500
+
501
+ - Manual batching: pass `batch: true` in successive `navigate` calls within the same microtask.
502
+ - Auto batching: enable `createRouter(routes, { autoBatch: true })` and omit `immediate: true` to coalesce navigations scheduled in the same microtask.
503
+
504
+ During a batched sequence, the final history update (a single `push`/`set`) is deferred to a queued microtask. Some code (tests, imperative flows) may need to synchronously observe the merged query state before the flush occurs. To support this, the router performs a provisional in‑memory update of the current route entry on each batched `navigate`:
505
+
506
+ Guarantees (provisional phase):
507
+
508
+ 1. `context.get()` returns an entry whose `location.search`, `rawSearch`, `query` (raw parsed) and `typedQuery` reflect the merged state of all batched calls so far.
509
+ 2. Each additional batched call merges query keys (last write wins) and overwrites the entire filters object (they are considered atomic state) before recomputing `typedQuery`.
510
+ 3. The provisional `typedQuery` uses the deepest route schema of the eventual target pathname (if a batched navigation changes pathname, subsequent calls resolve the schema for that new path).
511
+ 4. Normalization (e.g. clamping `page < 1`) is only applied at the final flush listener step; the provisional `typedQuery` may briefly contain unnormalized values until flush.
512
+ 5. Subscribers (`context.subscribe`) are **not** notified until the actual history update fires (asynchronously). Reading inside the same tick requires using `context.get()` directly, not relying on subscription callbacks.
513
+
514
+ Non‑guarantees / caveats:
515
+
516
+ - If you read `window.location.search` directly (discouraged) during a batch it will still show the pre‑batch URL; use the entry returned by `context.get()`.
517
+ - If later batched calls change the pathname, earlier provisional `typedQuery` objects become stale; always re‑read after your final batched mutation if you need the merged result.
518
+ - Filters batching (from `useFilters` helpers) coalesces multiple `set/patch/clear` calls in the same microtask via an internal microtask queue. These feed into the outer navigation batching so a burst of filter helper calls plus other `navigate` calls still produce a single history entry.
519
+
520
+ Edge cases:
521
+
522
+ - Calling `navigate({ immediate: true })` inside an active batch forces an immediate flush, bypassing batching for that specific call.
523
+ - Interleaving manual `batch: true` and autoBatch calls: if autoBatch is enabled and you explicitly pass `batch: false`, that call flushes immediately; otherwise the presence of any manual `batch: true` call within the tick keeps coalescing active until flush.
524
+
525
+ Recommended usage pattern inside effects or event handlers:
526
+
527
+ ```ts
528
+ // Multiple logical updates unified into 1 URL change
529
+ context.navigate({ query: { page: 1 }, batch: true });
530
+ context.navigate({ filters: { status: { in: ['active'] } }, filterSchema, batch: true });
531
+ context.navigate({ query: { tag: 'green' }, batch: true });
532
+ // Synchronous inspection (provisional)
533
+ const merged = context.get().typedQuery; // already includes page=1, tag=green, status filter
534
+ ````
535
+
536
+ Testing note: tests asserting final URL should poll or await a microtask / tick rather than expecting synchronous `window.location.search` updates when batching is involved.
537
+
538
+ Future evolution: if normalization or additional query transformations grow more complex, the provisional recompute will remain a best‑effort mirror; code relying on _final_ normalized values should subscribe or await the flush boundary.
539
+
540
+ Summary: Provisional batching gives synchronous, allocation‑minimal read access to the in‑flight merged query & typedQuery without sacrificing a single history entry – use `context.get()` for immediate reads, and rely on subscriptions or hooks for React render updates.
541
+
542
+ ## Route-Level Filter Schemas
543
+
544
+ Attach a `filterSchema` to routes to progressively declare filterable fields along the hierarchy. Parent → child schemas are shallow merged; fields defined later override earlier ones by name.
545
+
546
+ Example:
547
+
548
+ ```ts
549
+ import { r, defineFilters, numberFilter, stringFilter } from '@plumile/router';
550
+
551
+ export const routes = [
552
+ r({
553
+ path: '/products',
554
+ filterSchema: defineFilters({
555
+ price: numberFilter({ operators: ['gte', 'lte'] }),
556
+ }),
557
+ children: [
558
+ r({
559
+ path: '/:id',
560
+ filterSchema: defineFilters({
561
+ name: stringFilter({ operators: ['contains'] }),
562
+ }),
563
+ }),
564
+ ],
565
+ }),
501
566
  ];
502
567
  ```
503
568
 
569
+ Merged result for `/products/123` is `{ price, name }` definitions. Currently, implicit serialization of new filter values still requires passing `{ filters, filterSchema }` in a navigate/helper call; the route-level merged schema is used for parsing existing keys. This keeps mutations explicit. A future enhancement may allow omitting `filterSchema` when adding new filter values on a route that already declares one.
570
+
571
+ Rules:
572
+
573
+ - Order: shallow override by field name.
574
+ - No deep merge inside a field definition.
575
+ - Omitted routes: ignored.
576
+
577
+ Limitations / current behavior:
578
+
579
+ - Initial merged schema is internal; helpers still need explicit schema to serialize new filter state.
580
+ - Empty filters object with route-level schema is treated as “no change” (no extra keys added).
581
+
582
+ Planned: implicit mode & devtools visualization of merged filter schema chain.
583
+ plugins: {
584
+ '@plumile-router/dx': {
585
+ rules: {
586
+ 'no-direct-window-location-search': noDirectWindowLocationSearch,
587
+ },
588
+ },
589
+ },
590
+ rules: {
591
+ '@plumile-router/dx/no-direct-window-location-search': 'warn',
592
+ },
593
+ },
594
+ ];
595
+
596
+ ````
597
+
504
598
  Optional configuration:
505
599
 
506
600
  ```js
@@ -511,7 +605,7 @@ rules: {
511
605
  { allowInFiles: ['legacy-entry.ts'] },
512
606
  ],
513
607
  },
514
- ```
608
+ ````
515
609
 
516
610
  When triggered, replace patterns like:
517
611
 
@@ -569,6 +663,242 @@ Behavior:
569
663
  Options:
570
664
  `{ defaultValue?, omitIfDefault?: boolean = true, replace?: boolean, raw?: boolean }`
571
665
 
666
+ ### Filters DSL (Experimental Advanced Filtering)
667
+
668
+ Structured multi‑operator filtering can be expressed via query keys using the pattern `field.operator`.
669
+
670
+ 1. Define a schema
671
+
672
+ ```ts
673
+ import { defineFilters, numberFilter, stringFilter } from '@plumile/router';
674
+
675
+ export const filters = defineFilters({
676
+ price: numberFilter(), // numeric: eq, neq, gt, gte, lt, lte, in, nin, between, exists
677
+ status: stringFilter({ operators: ['eq', 'in', 'nin'] }),
678
+ name: stringFilter({ operators: ['contains', 'starts', 'ends'] }),
679
+ // Provide default operator values to omit them from serialization when matched
680
+ availability: numberFilter({
681
+ operators: ['exists'],
682
+ defaults: { exists: true },
683
+ }),
684
+ priceRange: numberFilter({
685
+ operators: ['between'],
686
+ defaults: { between: [[0, 100]] },
687
+ }),
688
+ });
689
+ ```
690
+
691
+ 2. Read & update filters
692
+
693
+ ```tsx
694
+ import { useFilters } from '@plumile/router';
695
+
696
+ function Products() {
697
+ const [f, { patch, clear }] = useFilters(filters);
698
+ // f.price.gt => number[] | undefined
699
+ // f.status.in => string[] | undefined
700
+ return (
701
+ <button
702
+ onClick={() => {
703
+ patch({ price: { gt: [10] } });
704
+ }}
705
+ >
706
+ Price &gt; 10
707
+ </button>
708
+ );
709
+ }
710
+ ```
711
+
712
+ 3. Narrow to a single operator
713
+
714
+ ```tsx
715
+ import { useFilterState } from '@plumile/router';
716
+
717
+ function PriceGt() {
718
+ const [gt, setGt] = useFilterState(filters, 'price', 'gt');
719
+ return (
720
+ <input
721
+ value={gt?.[0] ?? ''}
722
+ onChange={(e) => setGt([Number(e.target.value)])}
723
+ />
724
+ );
725
+ }
726
+ ```
727
+
728
+ 4. Supported operators
729
+
730
+ | Kind | Operators |
731
+ | ------ | ------------------------------------------------------------------------------------ |
732
+ | number | eq, neq, gt, gte, lt, lte, in, nin, between (tuples), exists |
733
+ | string | eq, neq, in, nin, between (tuples of strings), exists, contains, starts, ends, regex |
734
+
735
+ `exists` expects a boolean; presence of key defaults to `true` if value unrecognized.
736
+
737
+ 5. Query string format
738
+
739
+ ```
740
+ ?price.gt=10&price.between=10&price.between=20&price.between=30&price.between=40&status.in=active&status.in=pending
741
+ ```
742
+
743
+ 6. Between operator
744
+
745
+ Pairs of values create ranges: four values → two ranges. Odd final value is ignored.
746
+
747
+ 7. Clearing
748
+
749
+ `clear()` → remove all filters. `clear(['price'])` → remove only price.\* keys.
750
+
751
+ 8. Patching
752
+
753
+ `patch({ price: { gt: [20], between: [[10,20]] } })` merges at field level, replacing individual operator arrays.
754
+
755
+ 9. Serialization rules
756
+
757
+ - Previous filter keys (`field.op`) are dropped before adding new ones.
758
+ - Multiple values produce repeated keys (same as existing query arrays).
759
+ - Boolean `exists` serialized as `1` / `0`.
760
+ - Optional omission of default operator values: if a filter definition supplies a `defaults` object
761
+ (e.g. `{ defaults: { gt: [10] } }` or `{ defaults: { exists: true } }`), and the current operator
762
+ value is shallow‑equal to that default, the `field.operator` key is skipped during serialization.
763
+ Applies to array operators (exact ordered match) and `exists` boolean. `between` defaults compare
764
+ tuple pairs (`[[a,b]]`) element-wise.
765
+
766
+ 10. Type inference
767
+
768
+ `InferFilters<typeof filters.schema>` gives `{ price: { gt?: number[]; between?: [number, number][]; ... } }`.
769
+
770
+ 11. Opt‑in / Backward Compatible
771
+
772
+ No change to existing query parameter behavior. Filter keys are just additional query entries; legacy code reading raw `useQuery()` continues to function.
773
+
774
+ 12. Limitations / Future
775
+
776
+ - Sorting deliberately excluded (would be separate DSL).
777
+ - No date operator specialization yet.
778
+ - Regex values are passed through verbatim (URL decoding handled upstream).
779
+ - Default omission currently uses shallow equality (ordered array match). For number arrays
780
+ canonicalization (sorting + optional dedupe) happens prior to comparison, ensuring stable omission.
781
+
782
+ Tests cover parsing (including multiple ranges) and building; extend as needed for your domain.
783
+
784
+ ### New Hooks (Phase 4)
785
+
786
+ #### `useQueryObject(opts?)`
787
+
788
+ High-level accessor returning the entire current query object (typed when the matched deepest route declares a `query` schema). It also returns a stable setter that merges partial updates.
789
+
790
+ ```tsx
791
+ import { useQueryObject } from '@plumile/router';
792
+
793
+ function Panel() {
794
+ const [query, setQuery] = useQueryObject({ omitDefaults: true });
795
+ // query: typed (if schema) else raw record
796
+ return (
797
+ <button
798
+ onClick={() => {
799
+ setQuery({ page: (query.page ?? 1) + 1 });
800
+ }}
801
+ >
802
+ Next page
803
+ </button>
804
+ );
805
+ }
806
+ ```
807
+
808
+ Options:
809
+
810
+ - `raw?: boolean` Use aggregated raw query even if a schema exists.
811
+ - `replace?: boolean` Default navigation mode for all subsequent `setQuery` calls.
812
+ - `omitDefaults?: boolean` When true, schema keys whose value equals their declared default are omitted from the URL.
813
+
814
+ Setter semantics:
815
+
816
+ - Accepts an object or function `(prev) => next`.
817
+ - Keys set to `undefined` are removed from the URL.
818
+ - Partial objects are shallow‑merged with previous query state (post-merge omission rules are applied if `omitDefaults` is enabled).
819
+
820
+ #### `useActiveFilters(filterSchema)`
821
+
822
+ Returns a flat array of currently active filter operator entries derived from the structured filters state returned by `useFilters`.
823
+
824
+ ```tsx
825
+ import { useActiveFilters } from '@plumile/router';
826
+ import { filters } from './filters-schema';
827
+
828
+ function ActiveChips() {
829
+ const active = useActiveFilters(filters);
830
+ return (
831
+ <ul>
832
+ {active.map((f) => (
833
+ <li key={f.field + f.operator}>
834
+ {f.field}.{f.operator}: {f.values.join(', ')}
835
+ </li>
836
+ ))}
837
+ </ul>
838
+ );
839
+ }
840
+ ```
841
+
842
+ Each entry: `{ field: string; operator: string; values: any[] }` where `values` is the already normalized array (for non‑array primitives a singleton array is produced). Empty arrays / undefined operators are skipped.
843
+
844
+ #### `useNavigateWithQuery(opts?)`
845
+
846
+ Convenience wrapper combining current query (typed if possible) with partial updates before invoking `navigate`.
847
+
848
+ ```tsx
849
+ import { useNavigateWithQuery } from '@plumile/router';
850
+
851
+ function Incrementer() {
852
+ const update = useNavigateWithQuery({ omitDefaults: true });
853
+ return (
854
+ <button
855
+ onClick={() => {
856
+ update((prev) => ({ page: (prev.page ?? 1) + 1 }));
857
+ }}
858
+ >
859
+ Next
860
+ </button>
861
+ );
862
+ }
863
+ ```
864
+
865
+ Behavior:
866
+
867
+ - Reads existing (typed or raw) query as base.
868
+ - Accepts object or functional update.
869
+ - Keys set to `undefined` are removed.
870
+ - `omitDefaults` removes schema-default valued keys.
871
+ - `raw` forces ignoring the schema (raw aggregation base).
872
+ - `replace` option (global or per call) controls history mode.
873
+
874
+ #### `useStableRefEquality(value, areEqual?)`
875
+
876
+ Utility hook that preserves the reference of the latest value (object or array) as long as shallow equality holds. When a new value is passed whose own enumerable keys (and their primitive or reference-equal values) match the previous one, the previous stable reference is returned. If they differ, the new value becomes the stored reference.
877
+
878
+ Designed for niche interop cases (e.g. passing derived objects to dependency arrays of third-party hooks) where you can't or don't want the upstream producer to handle memoization. Most consumers of the router do NOT need this because `useQuery`, `useTypedQuery`, `useFilters` already return stable references.
879
+
880
+ ```ts
881
+ import { useStableRefEquality } from '@plumile/router';
882
+
883
+ function Chart({ data }) {
884
+ // Avoid re-renders in a heavy child when parent recreates equivalent arrays
885
+ const stableData = useStableRefEquality(data);
886
+ return <ExpensiveChart data={stableData} />;
887
+ }
888
+ ```
889
+
890
+ Custom comparator:
891
+
892
+ ```ts
893
+ const value = useStableRefEquality(complex, (a, b) => deepCustomCompare(a, b));
894
+ ```
895
+
896
+ Notes:
897
+
898
+ - Only shallow by default (no deep traversal) for perf.
899
+ - Non-object/array inputs are returned as-is (no caching layer needed).
900
+ - Avoid overuse; prefer structuring code so sources themselves are stable.
901
+
572
902
  ### Data Preloading
573
903
 
574
904
  ```typescript
@@ -616,6 +946,89 @@ function MyComponent() {
616
946
  }
617
947
  ```
618
948
 
949
+ ### Navigation With Filters & Batching (Phase 5)
950
+
951
+ You can atomically update query parameters and structured filters via the extended `navigate` API and related hooks.
952
+
953
+ ```tsx
954
+ import {
955
+ useNavigate,
956
+ useFilters,
957
+ defineFilters,
958
+ numberFilter,
959
+ } from '@plumile/router';
960
+
961
+ const filterSchema = defineFilters({ price: numberFilter() });
962
+
963
+ function PriceBump() {
964
+ const navigate = useNavigate();
965
+ const [filters, { patch }] = useFilters(filterSchema);
966
+ return (
967
+ <button
968
+ onClick={() => {
969
+ // Update both query & filters in a single URL change
970
+ navigate({
971
+ query: { page: 1 },
972
+ filters: { price: { gt: [10] } },
973
+ filterSchema,
974
+ });
975
+ }}
976
+ >
977
+ Apply
978
+ </button>
979
+ );
980
+ }
981
+ ```
982
+
983
+ Batch multiple navigations issued during the same micro‑task into _one_ history update by passing `batch: true`:
984
+
985
+ ```tsx
986
+ function ComplexMutation() {
987
+ const navigate = useNavigate();
988
+ return (
989
+ <button
990
+ onClick={() => {
991
+ navigate({ query: { page: 1 }, batch: true });
992
+ navigate({
993
+ filters: { price: { gt: [20] } },
994
+ filterSchema,
995
+ batch: true,
996
+ });
997
+ navigate({
998
+ filters: { price: {} /* clear price */ },
999
+ filterSchema,
1000
+ batch: true,
1001
+ });
1002
+ // All three coalesce into one push
1003
+ }}
1004
+ >
1005
+ Run sequence
1006
+ </button>
1007
+ );
1008
+ }
1009
+ ```
1010
+
1011
+ Hooks `useQueryObject` and `useFilters` also accept a `batch` flag in their nav options:
1012
+
1013
+ ```tsx
1014
+ const [query, setQuery] = useQueryObject();
1015
+ const [f, { patch, clear }] = useFilters(filterSchema);
1016
+
1017
+ // Coalesce three operations
1018
+ setQuery({ page: 2 }, { batch: true });
1019
+ patch({ price: { gt: [30] } }, { batch: true });
1020
+ clear(['price'], { batch: true });
1021
+ ```
1022
+
1023
+ Notes:
1024
+
1025
+ - Batching is opt‑in: default behavior is immediate navigation (backward compatible).
1026
+ - The last non‑undefined `replace` flag wins inside a batch group.
1027
+ - The last provided `query` object and `filters` snapshot in the batch are used for serialization.
1028
+ - Provide `filterSchema` whenever you include `filters`.
1029
+
1030
+ `buildSearch(query, schema, { filters, filterSchema })` merges filters deterministically with query keys (schema‑ordered keys first, then extras).
1031
+
619
1032
  ### Route Preloading
620
1033
 
621
1034
  ```tsx
@@ -5,5 +5,9 @@ export * from './builder.js';
5
5
  export * from './ResourcePage.js';
6
6
  export * from './tools.js';
7
7
  export { q, parseTypedQuery } from './tools/query-dsl.js';
8
+ export { defineFilters, numberFilter, stringFilter, useFilters, useQueryFilters, } from './routing/filters.js';
9
+ export { default as useFilterState } from './routing/useFilterState.js';
10
+ export { default as useActiveFilters } from './routing/useActiveFilters.js';
11
+ export { default as useQueryObject } from './routing/useQueryObject.js';
8
12
  export type * from './types.js';
9
13
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,mBAAmB,CAAC;AAGlC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,CAAC,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG1D,mBAAmB,YAAY,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,mBAAmB,CAAC;AAGlC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,CAAC,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAGxE,mBAAmB,YAAY,CAAC"}
package/lib/esm/index.js CHANGED
@@ -5,4 +5,8 @@ export * from './builder.js';
5
5
  export * from './ResourcePage.js';
6
6
  export * from './tools.js';
7
7
  export { q, parseTypedQuery } from './tools/query-dsl.js';
8
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsY0FBYyxtQkFBbUIsQ0FBQztBQUdsQyxjQUFjLG9CQUFvQixDQUFDO0FBR25DLGNBQWMsb0JBQW9CLENBQUM7QUFHbkMsY0FBYyxjQUFjLENBQUM7QUFHN0IsY0FBYyxtQkFBbUIsQ0FBQztBQUdsQyxjQUFjLFlBQVksQ0FBQztBQUMzQixPQUFPLEVBQUUsQ0FBQyxFQUFFLGVBQWUsRUFBRSxNQUFNLHNCQUFzQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gRXhwb3J0IGVycm9yIGhhbmRsaW5nIHV0aWxpdGllc1xuZXhwb3J0ICogZnJvbSAnLi9lcnJvcnMvaW5kZXguanMnO1xuXG4vLyBFeHBvcnQgYnJvd3NlciBoaXN0b3J5IG1hbmFnZW1lbnRcbmV4cG9ydCAqIGZyb20gJy4vaGlzdG9yeS9pbmRleC5qcyc7XG5cbi8vIEV4cG9ydCByb3V0aW5nIGNvbXBvbmVudHMgYW5kIHV0aWxpdGllc1xuZXhwb3J0ICogZnJvbSAnLi9yb3V0aW5nL2luZGV4LmpzJztcblxuLy8gRXhwb3J0IHJvdXRlIGJ1aWxkaW5nIHV0aWxpdGllc1xuZXhwb3J0ICogZnJvbSAnLi9idWlsZGVyLmpzJztcblxuLy8gRXhwb3J0IHJlc291cmNlIHBhZ2UgbWFuYWdlbWVudCBmb3IgbGF6eSBsb2FkaW5nXG5leHBvcnQgKiBmcm9tICcuL1Jlc291cmNlUGFnZS5qcyc7XG5cbi8vIEV4cG9ydCB1dGlsaXR5IGZ1bmN0aW9uc1xuZXhwb3J0ICogZnJvbSAnLi90b29scy5qcyc7XG5leHBvcnQgeyBxLCBwYXJzZVR5cGVkUXVlcnkgfSBmcm9tICcuL3Rvb2xzL3F1ZXJ5LWRzbC5qcyc7XG5cbi8vIEV4cG9ydCBhbGwgVHlwZVNjcmlwdCB0eXBlc1xuZXhwb3J0IHR5cGUgKiBmcm9tICcuL3R5cGVzLmpzJztcbiJdfQ==
8
+ export { defineFilters, numberFilter, stringFilter, useFilters, useQueryFilters, } from './routing/filters.js';
9
+ export { default as useFilterState } from './routing/useFilterState.js';
10
+ export { default as useActiveFilters } from './routing/useActiveFilters.js';
11
+ export { default as useQueryObject } from './routing/useQueryObject.js';
12
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsY0FBYyxtQkFBbUIsQ0FBQztBQUdsQyxjQUFjLG9CQUFvQixDQUFDO0FBR25DLGNBQWMsb0JBQW9CLENBQUM7QUFHbkMsY0FBYyxjQUFjLENBQUM7QUFHN0IsY0FBYyxtQkFBbUIsQ0FBQztBQUdsQyxjQUFjLFlBQVksQ0FBQztBQUMzQixPQUFPLEVBQUUsQ0FBQyxFQUFFLGVBQWUsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBQzFELE9BQU8sRUFDTCxhQUFhLEVBQ2IsWUFBWSxFQUNaLFlBQVksRUFDWixVQUFVLEVBQ1YsZUFBZSxHQUNoQixNQUFNLHNCQUFzQixDQUFDO0FBQzlCLE9BQU8sRUFBRSxPQUFPLElBQUksY0FBYyxFQUFFLE1BQU0sNkJBQTZCLENBQUM7QUFDeEUsT0FBTyxFQUFFLE9BQU8sSUFBSSxnQkFBZ0IsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBQzVFLE9BQU8sRUFBRSxPQUFPLElBQUksY0FBYyxFQUFFLE1BQU0sNkJBQTZCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBFeHBvcnQgZXJyb3IgaGFuZGxpbmcgdXRpbGl0aWVzXG5leHBvcnQgKiBmcm9tICcuL2Vycm9ycy9pbmRleC5qcyc7XG5cbi8vIEV4cG9ydCBicm93c2VyIGhpc3RvcnkgbWFuYWdlbWVudFxuZXhwb3J0ICogZnJvbSAnLi9oaXN0b3J5L2luZGV4LmpzJztcblxuLy8gRXhwb3J0IHJvdXRpbmcgY29tcG9uZW50cyBhbmQgdXRpbGl0aWVzXG5leHBvcnQgKiBmcm9tICcuL3JvdXRpbmcvaW5kZXguanMnO1xuXG4vLyBFeHBvcnQgcm91dGUgYnVpbGRpbmcgdXRpbGl0aWVzXG5leHBvcnQgKiBmcm9tICcuL2J1aWxkZXIuanMnO1xuXG4vLyBFeHBvcnQgcmVzb3VyY2UgcGFnZSBtYW5hZ2VtZW50IGZvciBsYXp5IGxvYWRpbmdcbmV4cG9ydCAqIGZyb20gJy4vUmVzb3VyY2VQYWdlLmpzJztcblxuLy8gRXhwb3J0IHV0aWxpdHkgZnVuY3Rpb25zXG5leHBvcnQgKiBmcm9tICcuL3Rvb2xzLmpzJztcbmV4cG9ydCB7IHEsIHBhcnNlVHlwZWRRdWVyeSB9IGZyb20gJy4vdG9vbHMvcXVlcnktZHNsLmpzJztcbmV4cG9ydCB7XG4gIGRlZmluZUZpbHRlcnMsXG4gIG51bWJlckZpbHRlcixcbiAgc3RyaW5nRmlsdGVyLFxuICB1c2VGaWx0ZXJzLFxuICB1c2VRdWVyeUZpbHRlcnMsXG59IGZyb20gJy4vcm91dGluZy9maWx0ZXJzLmpzJztcbmV4cG9ydCB7IGRlZmF1bHQgYXMgdXNlRmlsdGVyU3RhdGUgfSBmcm9tICcuL3JvdXRpbmcvdXNlRmlsdGVyU3RhdGUuanMnO1xuZXhwb3J0IHsgZGVmYXVsdCBhcyB1c2VBY3RpdmVGaWx0ZXJzIH0gZnJvbSAnLi9yb3V0aW5nL3VzZUFjdGl2ZUZpbHRlcnMuanMnO1xuZXhwb3J0IHsgZGVmYXVsdCBhcyB1c2VRdWVyeU9iamVjdCB9IGZyb20gJy4vcm91dGluZy91c2VRdWVyeU9iamVjdC5qcyc7XG5cbi8vIEV4cG9ydCBhbGwgVHlwZVNjcmlwdCB0eXBlc1xuZXhwb3J0IHR5cGUgKiBmcm9tICcuL3R5cGVzLmpzJztcbiJdfQ==
@@ -9,5 +9,6 @@ export default function createRouter(routes: Route<any, any>[], opts?: {
9
9
  panel?: boolean;
10
10
  shortcut?: string;
11
11
  };
12
+ autoBatch?: boolean;
12
13
  }): CreateRouterReturn;
13
14
  //# sourceMappingURL=createRouter.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"createRouter.d.ts","sourceRoot":"","sources":["../../../src/routing/createRouter.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,KAAK,EAEL,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAKrB,MAAM,MAAM,kBAAkB,GAAG;IAE/B,OAAO,EAAE,MAAM,IAAI,CAAC;IAEpB,OAAO,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC;CAClC,CAAC;AAkCF,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EACzB,IAAI,GAAE;IACJ,QAAQ,CAAC,EACL,OAAO,GACP;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD,GACL,kBAAkB,CA4nBpB"}
1
+ {"version":3,"file":"createRouter.d.ts","sourceRoot":"","sources":["../../../src/routing/createRouter.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,KAAK,EAEL,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAKrB,MAAM,MAAM,kBAAkB,GAAG;IAE/B,OAAO,EAAE,MAAM,IAAI,CAAC;IAEpB,OAAO,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC;CAClC,CAAC;AAkCF,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EACzB,IAAI,GAAE;IACJ,QAAQ,CAAC,EACL,OAAO,GACP;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE7D,SAAS,CAAC,EAAE,OAAO,CAAC;CAChB,GACL,kBAAkB,CAmuBpB"}