You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Deep maps extension for [Nano Stores](https://github.com/nanostores/nanostores) state manager.
6
+
Deep maps extension for [Nano Stores](https://github.com/nanostores/nanostores) state manager. It provides a store to put big nested objects or arrays and change keys by path with fine-grained reactivity.
`deepMap` provides various methods to interact with your nested state easily without mutating the original object. It supports two path syntaxes:
41
+
-**`key.subkey`:** To access a deeply nested property in a object.
42
+
-`key[0]`: To access an item in an array by index.
41
43
42
-
```
43
-
Use `updateKey` to merge new data into an existing object. If the target isn't an object, it will be replaced.
44
+
### GetKey
45
+
46
+
Use `getKey` to obtain the current value at a specific path.
44
47
45
48
```ts
46
-
// 'updateKey' merges, keeping 'name' and only changing 'age'
47
-
$store.updateKey('user', { age: 42 })
48
-
// -> { user: { name: 'Luke', age: 42 }, ... }
49
+
$store.getKey('user.name')
50
+
// -> "Luke"
49
51
```
50
-
To delete a property from an object or an item from an array, just set its path to `undefined`.
52
+
53
+
### SetKey
54
+
55
+
Use `setKey` to create or replace any value at a specific path.
51
56
52
57
```ts
53
-
// Deletes 'count' from the store
54
-
$store.setKey('count', undefined)
55
-
// -> { user: { name: 'Luke', age: 42 } }
58
+
// Replaces the value at 'count'
59
+
$store.setKey('count', 1)
60
+
61
+
// Note: undefined value is reserved for deletion
56
62
```
57
-
### Working with Arrays
58
-
DeepMap fully supports arrays as the root value or nested within your state. You can use standard array syntax [index] in your paths.
59
63
64
+
### UpdateKey and Update
65
+
66
+
Use `updateKey` to merge new data into an existing object or to concatenate items into an array. If the target isn't an object or array, it will simply be replaced. Use `update` to modify the root state object.
60
67
```ts
61
-
//Before
62
-
const $store =deepMap<StoreProps[]>([{}]) // Type Error
68
+
$store.updateKey('user.age', 42)
69
+
// -> { user: { name: 'Luke', age: 42 }, ... }
70
+
71
+
// Pushes/concatenates new items to an array
72
+
// Note: You need to use the [] syntax to update an array
// Autocomplete will suggest 'id' and 'settings.theme'
100
+
$user.setKey('settings.theme', 'dark')
84
101
```
85
-
Typescript automatically infers the type of the store value.
102
+
103
+
Typescript automatically infers and validates the type of the value at the specified path:
86
104
87
105
```ts
88
-
typeStoreProps= {
89
-
count?:number
90
-
}
106
+
$store.setKey('count', 'randomString')
107
+
// Type Error -> 'string' is not assignable to type 'number'
108
+
```
91
109
92
-
const $store =deepMap<StoreProps>({})
110
+
## Integrations
93
111
94
-
$store.setKey('count', 'randomString')
95
-
// Type Error -> 'string' is not assignable to 'number'
112
+
### React & Preact
96
113
97
-
// IMPORTANT: an empty path ('') is treated as the root object
98
-
$someStore.setKey('', 'randomString') // Replaces the entire store
114
+
When using a hook `useStore` you can pass an array of keys for listening to changes.
115
+
116
+
```tsx
117
+
// Reactivity in user branch, any child mutation fire a re-render
118
+
const { name } =useStore($store, { keys: ['user']})
119
+
120
+
// Specific reactivity
121
+
122
+
const { name } =useStore($store, { keys: ['user.name']}) // Only listen the exact key path
99
123
```
100
124
125
+
If your component only depends on a specific nested value, listen to the exact path. This prevents unnecessary re-renders when sibling properties change.
126
+
101
127
## License
102
128
103
129
MIT
104
130
105
131
## Credits
106
132
107
-
*[Dan Kozlov](https://github.com/dkzlv) the author of `deepmap()` in [Nano stores](https://github.com/nanostores/nanostores) core.
133
+
*[Dan Kozlov](https://github.com/dkzlv) the author of `deepmap()` in [Nano stores](https://github.com/nanostores/nanostores) core.
0 commit comments