@plumile/router 0.1.12 → 0.1.14
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 +426 -13
- package/lib/esm/index.d.ts +4 -0
- package/lib/esm/index.d.ts.map +1 -1
- package/lib/esm/index.js +5 -1
- package/lib/esm/routing/createRouter.d.ts +1 -0
- package/lib/esm/routing/createRouter.d.ts.map +1 -1
- package/lib/esm/routing/createRouter.js +447 -360
- package/lib/esm/routing/devtools.d.ts +21 -0
- package/lib/esm/routing/devtools.d.ts.map +1 -0
- package/lib/esm/routing/devtools.js +690 -0
- package/lib/esm/routing/filters.d.ts +97 -0
- package/lib/esm/routing/filters.d.ts.map +1 -0
- package/lib/esm/routing/filters.js +557 -0
- package/lib/esm/routing/index.d.ts +6 -0
- package/lib/esm/routing/index.d.ts.map +1 -1
- package/lib/esm/routing/index.js +7 -1
- package/lib/esm/routing/useActiveFilters.d.ts +9 -0
- package/lib/esm/routing/useActiveFilters.d.ts.map +1 -0
- package/lib/esm/routing/useActiveFilters.js +38 -0
- package/lib/esm/routing/useFilterState.d.ts +10 -0
- package/lib/esm/routing/useFilterState.d.ts.map +1 -0
- package/lib/esm/routing/useFilterState.js +14 -0
- package/lib/esm/routing/useNavigate.d.ts +7 -0
- package/lib/esm/routing/useNavigate.d.ts.map +1 -1
- package/lib/esm/routing/useNavigate.js +1 -1
- package/lib/esm/routing/useNavigateWithQuery.d.ts +15 -0
- package/lib/esm/routing/useNavigateWithQuery.d.ts.map +1 -0
- package/lib/esm/routing/useNavigateWithQuery.js +95 -0
- package/lib/esm/routing/useQueryObject.d.ts +18 -0
- package/lib/esm/routing/useQueryObject.d.ts.map +1 -0
- package/lib/esm/routing/useQueryObject.js +107 -0
- package/lib/esm/routing/useStableRefEquality.d.ts +5 -0
- package/lib/esm/routing/useStableRefEquality.d.ts.map +1 -0
- package/lib/esm/routing/useStableRefEquality.js +47 -0
- package/lib/esm/tools/buildSearch.d.ts +8 -2
- package/lib/esm/tools/buildSearch.d.ts.map +1 -1
- package/lib/esm/tools/buildSearch.js +216 -12
- package/lib/esm/types.d.ts +19 -0
- package/lib/esm/types.d.ts.map +1 -1
- package/lib/esm/types.js +1 -1
- package/lib/tsconfig.esm.tsbuildinfo +1 -1
- package/lib/types/index.d.ts +4 -0
- package/lib/types/index.d.ts.map +1 -1
- package/lib/types/routing/createRouter.d.ts +1 -0
- package/lib/types/routing/createRouter.d.ts.map +1 -1
- package/lib/types/routing/devtools.d.ts +21 -0
- package/lib/types/routing/devtools.d.ts.map +1 -0
- package/lib/types/routing/filters.d.ts +97 -0
- package/lib/types/routing/filters.d.ts.map +1 -0
- package/lib/types/routing/index.d.ts +6 -0
- package/lib/types/routing/index.d.ts.map +1 -1
- package/lib/types/routing/useActiveFilters.d.ts +9 -0
- package/lib/types/routing/useActiveFilters.d.ts.map +1 -0
- package/lib/types/routing/useFilterState.d.ts +10 -0
- package/lib/types/routing/useFilterState.d.ts.map +1 -0
- package/lib/types/routing/useNavigate.d.ts +7 -0
- package/lib/types/routing/useNavigate.d.ts.map +1 -1
- package/lib/types/routing/useNavigateWithQuery.d.ts +15 -0
- package/lib/types/routing/useNavigateWithQuery.d.ts.map +1 -0
- package/lib/types/routing/useQueryObject.d.ts +18 -0
- package/lib/types/routing/useQueryObject.d.ts.map +1 -0
- package/lib/types/routing/useStableRefEquality.d.ts +5 -0
- package/lib/types/routing/useStableRefEquality.d.ts.map +1 -0
- package/lib/types/tools/buildSearch.d.ts +8 -2
- package/lib/types/tools/buildSearch.d.ts.map +1 -1
- package/lib/types/types.d.ts +19 -0
- package/lib/types/types.d.ts.map +1 -1
- 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
|
-
|
|
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
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
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 > 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
|
package/lib/esm/index.d.ts
CHANGED
|
@@ -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
|
package/lib/esm/index.d.ts.map
CHANGED
|
@@ -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;
|
|
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
|
-
|
|
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==
|
|
@@ -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;
|
|
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,CAkxBpB"}
|