@real-router/persistent-params-plugin 0.1.40 → 0.1.42
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 +43 -79
- package/dist/cjs/metafile-cjs.json +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,37 +1,33 @@
|
|
|
1
1
|
# @real-router/persistent-params-plugin
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/@real-router/persistent-params-plugin)
|
|
4
|
+
[](https://www.npmjs.com/package/@real-router/persistent-params-plugin)
|
|
5
|
+
[](https://bundlejs.com/?q=@real-router/persistent-params-plugin&treeshake=[*])
|
|
6
|
+
[](../../LICENSE)
|
|
5
7
|
|
|
6
|
-
Automatically
|
|
7
|
-
|
|
8
|
-
## Problem & Solution
|
|
8
|
+
> Automatically persist query parameters across all navigation transitions in [Real-Router](https://github.com/greydragon888/real-router).
|
|
9
9
|
|
|
10
10
|
```typescript
|
|
11
11
|
// Without plugin:
|
|
12
12
|
router.navigate("products", { lang: "en", theme: "dark" });
|
|
13
13
|
router.navigate("cart");
|
|
14
|
-
// URL: /cart
|
|
14
|
+
// URL: /cart — lang and theme are lost
|
|
15
15
|
|
|
16
16
|
// With plugin:
|
|
17
17
|
router.usePlugin(persistentParamsPluginFactory(["lang", "theme"]));
|
|
18
18
|
router.navigate("products", { lang: "en", theme: "dark" });
|
|
19
19
|
router.navigate("cart");
|
|
20
|
-
// URL: /cart?lang=en&theme=dark
|
|
20
|
+
// URL: /cart?lang=en&theme=dark — automatically preserved
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
## Installation
|
|
24
24
|
|
|
25
25
|
```bash
|
|
26
26
|
npm install @real-router/persistent-params-plugin
|
|
27
|
-
# or
|
|
28
|
-
pnpm add @real-router/persistent-params-plugin
|
|
29
|
-
# or
|
|
30
|
-
yarn add @real-router/persistent-params-plugin
|
|
31
|
-
# or
|
|
32
|
-
bun add @real-router/persistent-params-plugin
|
|
33
27
|
```
|
|
34
28
|
|
|
29
|
+
**Peer dependency:** `@real-router/core`
|
|
30
|
+
|
|
35
31
|
## Quick Start
|
|
36
32
|
|
|
37
33
|
```typescript
|
|
@@ -40,70 +36,41 @@ import { persistentParamsPluginFactory } from "@real-router/persistent-params-pl
|
|
|
40
36
|
|
|
41
37
|
const router = createRouter(routes);
|
|
42
38
|
|
|
43
|
-
//
|
|
39
|
+
// Array — values set on first navigation
|
|
44
40
|
router.usePlugin(persistentParamsPluginFactory(["lang", "theme"]));
|
|
45
41
|
|
|
46
|
-
//
|
|
47
|
-
router.usePlugin(
|
|
48
|
-
persistentParamsPluginFactory({
|
|
49
|
-
lang: "en",
|
|
50
|
-
theme: "light",
|
|
51
|
-
}),
|
|
52
|
-
);
|
|
53
|
-
|
|
54
|
-
router.start();
|
|
42
|
+
// Object — with default values
|
|
43
|
+
router.usePlugin(persistentParamsPluginFactory({ lang: "en", theme: "light" }));
|
|
55
44
|
```
|
|
56
45
|
|
|
57
|
-
---
|
|
58
|
-
|
|
59
46
|
## Configuration
|
|
60
47
|
|
|
61
|
-
| Config Type
|
|
62
|
-
|
|
63
|
-
| `string[]`
|
|
64
|
-
| `Record<string, primitive>` | Parameter names with defaults
|
|
65
|
-
|
|
66
|
-
**Allowed value types:** `string`, `number`, `boolean`, `undefined` (to remove)
|
|
48
|
+
| Config Type | Description | Example |
|
|
49
|
+
|-------------|-------------|---------|
|
|
50
|
+
| `string[]` | Parameter names, initial values `undefined` | `["lang", "theme"]` |
|
|
51
|
+
| `Record<string, primitive>` | Parameter names with defaults | `{ lang: "en" }` |
|
|
67
52
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
---
|
|
53
|
+
**Allowed value types:** `string`, `number`, `boolean`, `undefined` (to remove a param).
|
|
71
54
|
|
|
72
55
|
## Behavior
|
|
73
56
|
|
|
74
|
-
### Persistence
|
|
75
|
-
|
|
76
|
-
```typescript
|
|
77
|
-
router.navigate("page1", { lang: "en" }); // Saved: lang=en
|
|
78
|
-
router.navigate("page2"); // URL: /page2?lang=en
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
### Update
|
|
82
|
-
|
|
83
57
|
```typescript
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
### Remove
|
|
58
|
+
// Persist — saved on first navigation
|
|
59
|
+
router.navigate("page1", { lang: "en" }); // saved: lang=en
|
|
88
60
|
|
|
89
|
-
|
|
90
|
-
router.navigate("
|
|
91
|
-
```
|
|
61
|
+
// Carry — auto-injected into subsequent navigations
|
|
62
|
+
router.navigate("page2"); // URL: /page2?lang=en
|
|
92
63
|
|
|
93
|
-
|
|
64
|
+
// Update — explicit values override saved ones
|
|
65
|
+
router.navigate("page3", { lang: "fr" }); // URL: /page3?lang=fr, saved: lang=fr
|
|
94
66
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
```typescript
|
|
98
|
-
// Saved: lang=en
|
|
99
|
-
router.navigate("page", { lang: "de" }); // URL: /page?lang=de
|
|
67
|
+
// Remove — pass undefined to stop persisting
|
|
68
|
+
router.navigate("page4", { lang: undefined }); // lang removed permanently
|
|
100
69
|
```
|
|
101
70
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
---
|
|
71
|
+
> **Note:** Removal is permanent for the plugin lifetime. Once `undefined` is passed, the param is no longer tracked — even if passed again in a later navigation.
|
|
105
72
|
|
|
106
|
-
##
|
|
73
|
+
## Use Cases
|
|
107
74
|
|
|
108
75
|
### Multilingual App
|
|
109
76
|
|
|
@@ -111,8 +78,8 @@ See [Wiki](https://github.com/greydragon888/real-router/wiki/persistent-params-p
|
|
|
111
78
|
router.usePlugin(persistentParamsPluginFactory({ lang: "en" }));
|
|
112
79
|
|
|
113
80
|
router.navigate("settings", { lang: "fr" });
|
|
114
|
-
router.navigate("products");
|
|
115
|
-
router.navigate("cart");
|
|
81
|
+
router.navigate("products"); // ?lang=fr
|
|
82
|
+
router.navigate("cart"); // ?lang=fr
|
|
116
83
|
```
|
|
117
84
|
|
|
118
85
|
### UTM Tracking
|
|
@@ -123,41 +90,38 @@ router.usePlugin(
|
|
|
123
90
|
);
|
|
124
91
|
|
|
125
92
|
// User arrives: /?utm_source=google&utm_medium=cpc
|
|
126
|
-
router.navigate("products");
|
|
127
|
-
router.navigate("checkout");
|
|
93
|
+
router.navigate("products"); // UTM params preserved
|
|
94
|
+
router.navigate("checkout"); // UTM params preserved
|
|
128
95
|
```
|
|
129
96
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
## Lifecycle
|
|
97
|
+
### Cleanup
|
|
133
98
|
|
|
134
99
|
```typescript
|
|
135
100
|
const unsubscribe = router.usePlugin(persistentParamsPluginFactory(["mode"]));
|
|
136
101
|
|
|
137
|
-
// Later
|
|
102
|
+
// Later — restore original router behavior
|
|
138
103
|
unsubscribe();
|
|
139
104
|
```
|
|
140
105
|
|
|
141
|
-
**Note:** Double initialization throws an error. Call `unsubscribe()` first.
|
|
142
|
-
|
|
143
|
-
---
|
|
144
|
-
|
|
145
106
|
## Documentation
|
|
146
107
|
|
|
147
|
-
Full documentation
|
|
108
|
+
Full documentation: [Wiki — persistent-params-plugin](https://github.com/greydragon888/real-router/wiki/persistent-params-plugin)
|
|
148
109
|
|
|
149
110
|
- [Configuration Options](https://github.com/greydragon888/real-router/wiki/persistent-params-plugin#3-configuration-options)
|
|
150
|
-
- [Lifecycle Hooks](https://github.com/greydragon888/real-router/wiki/persistent-params-plugin#4-lifecycle-hooks)
|
|
151
111
|
- [Behavior & Edge Cases](https://github.com/greydragon888/real-router/wiki/persistent-params-plugin#8-behavior)
|
|
152
112
|
- [Migration from router5](https://github.com/greydragon888/real-router/wiki/persistent-params-plugin#11-migration-from-router5)
|
|
153
113
|
|
|
154
|
-
---
|
|
155
|
-
|
|
156
114
|
## Related Packages
|
|
157
115
|
|
|
158
|
-
|
|
159
|
-
|
|
116
|
+
| Package | Description |
|
|
117
|
+
|---------|-------------|
|
|
118
|
+
| [@real-router/core](https://www.npmjs.com/package/@real-router/core) | Core router (required peer dependency) |
|
|
119
|
+
| [@real-router/browser-plugin](https://www.npmjs.com/package/@real-router/browser-plugin) | Browser History API integration |
|
|
120
|
+
|
|
121
|
+
## Contributing
|
|
122
|
+
|
|
123
|
+
See [contributing guidelines](../../CONTRIBUTING.md) for development setup and PR process.
|
|
160
124
|
|
|
161
125
|
## License
|
|
162
126
|
|
|
163
|
-
MIT © [Oleg Ivanov](https://github.com/greydragon888)
|
|
127
|
+
[MIT](../../LICENSE) © [Oleg Ivanov](https://github.com/greydragon888)
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.
|
|
1
|
+
{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"src/constants.ts":{"bytes":178,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/param-utils.ts":{"bytes":1731,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"../type-guards/dist/esm/index.mjs":{"bytes":3451,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/validation.ts":{"bytes":3773,"imports":[{"path":"../type-guards/dist/esm/index.mjs","kind":"import-statement","original":"type-guards"},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/plugin.ts":{"bytes":4457,"imports":[{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"src/param-utils.ts","kind":"import-statement","original":"./param-utils"},{"path":"src/validation.ts","kind":"import-statement","original":"./validation"},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/factory.ts":{"bytes":3231,"imports":[{"path":"@real-router/core/api","kind":"import-statement","external":true},{"path":"src/plugin.ts","kind":"import-statement","original":"./plugin"},{"path":"src/validation.ts","kind":"import-statement","original":"./validation"},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/index.ts":{"bytes":166,"imports":[{"path":"src/factory.ts","kind":"import-statement","original":"./factory"},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js.map":{"imports":[],"exports":[],"inputs":{},"bytes":18710},"dist/cjs/index.js":{"imports":[{"path":"@real-router/core/api","kind":"import-statement","external":true}],"exports":["persistentParamsPluginFactory"],"entryPoint":"src/index.ts","inputs":{"src/factory.ts":{"bytesInOutput":826},"src/constants.ts":{"bytesInOutput":104},"src/param-utils.ts":{"bytesInOutput":604},"../type-guards/dist/esm/index.mjs":{"bytesInOutput":118},"src/validation.ts":{"bytesInOutput":2130},"src/plugin.ts":{"bytesInOutput":3126},"src/index.ts":{"bytesInOutput":0}},"bytes":7441}}}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@real-router/persistent-params-plugin",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.42",
|
|
4
4
|
"type": "commonjs",
|
|
5
5
|
"description": "Persist query parameters across route transitions",
|
|
6
6
|
"main": "./dist/cjs/index.js",
|
|
@@ -45,10 +45,10 @@
|
|
|
45
45
|
"homepage": "https://github.com/greydragon888/real-router",
|
|
46
46
|
"sideEffects": false,
|
|
47
47
|
"dependencies": {
|
|
48
|
-
"@real-router/core": "^0.
|
|
48
|
+
"@real-router/core": "^0.38.0"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
|
-
"type-guards": "^0.3.
|
|
51
|
+
"type-guards": "^0.3.7"
|
|
52
52
|
},
|
|
53
53
|
"scripts": {
|
|
54
54
|
"test": "vitest",
|