@real-router/persistent-params-plugin 0.1.40 → 0.1.41

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 (2) hide show
  1. package/README.md +43 -79
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,37 +1,33 @@
1
1
  # @real-router/persistent-params-plugin
2
2
 
3
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
3
+ [![npm](https://img.shields.io/npm/v/@real-router/persistent-params-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/persistent-params-plugin)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@real-router/persistent-params-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/persistent-params-plugin)
5
+ [![bundle size](https://deno.bundlejs.com/?q=@real-router/persistent-params-plugin&treeshake=[*]&badge=detailed)](https://bundlejs.com/?q=@real-router/persistent-params-plugin&treeshake=[*])
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](../../LICENSE)
5
7
 
6
- Automatically persists query parameters across all navigation transitions.
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 ← lang and theme are lost
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 ← automatically preserved
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
- // Option 1: Parameter names (values set on first use)
39
+ // Array — values set on first navigation
44
40
  router.usePlugin(persistentParamsPluginFactory(["lang", "theme"]));
45
41
 
46
- // Option 2: With default values
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 | Description | Example |
62
- | --------------------------- | ------------------------------------------- | ------------------- |
63
- | `string[]` | Parameter names, initial values `undefined` | `["lang", "theme"]` |
64
- | `Record<string, primitive>` | Parameter names with defaults | `{ lang: "en" }` |
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
- See [Wiki](https://github.com/greydragon888/real-router/wiki/persistent-params-plugin#3-configuration-options) for details.
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
- router.navigate("page", { lang: "fr" }); // Updates saved value
85
- ```
86
-
87
- ### Remove
58
+ // Persist — saved on first navigation
59
+ router.navigate("page1", { lang: "en" }); // saved: lang=en
88
60
 
89
- ```typescript
90
- router.navigate("page", { lang: undefined }); // Removes from persistent params
91
- ```
61
+ // Carry — auto-injected into subsequent navigations
62
+ router.navigate("page2"); // URL: /page2?lang=en
92
63
 
93
- ### Priority
64
+ // Update — explicit values override saved ones
65
+ router.navigate("page3", { lang: "fr" }); // URL: /page3?lang=fr, saved: lang=fr
94
66
 
95
- Explicit values override saved ones:
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
- See [Wiki](https://github.com/greydragon888/real-router/wiki/persistent-params-plugin#8-behavior) for edge cases and guarantees.
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
- ## Usage Examples
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"); // ?lang=fr
115
- router.navigate("cart"); // ?lang=fr
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"); // UTM params preserved
127
- router.navigate("checkout"); // UTM params preserved
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: restore original router behavior
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 on [Wiki](https://github.com/greydragon888/real-router/wiki/persistent-params-plugin):
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
- - [@real-router/core](https://www.npmjs.com/package/@real-router/core) — Core router
159
- - [@real-router/browser-plugin](https://www.npmjs.com/package/@real-router/browser-plugin) — Browser history
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)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@real-router/persistent-params-plugin",
3
- "version": "0.1.40",
3
+ "version": "0.1.41",
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.36.0"
48
+ "@real-router/core": "^0.37.0"
49
49
  },
50
50
  "devDependencies": {
51
- "type-guards": "^0.3.5"
51
+ "type-guards": "^0.3.7"
52
52
  },
53
53
  "scripts": {
54
54
  "test": "vitest",