Skip to content

Commit 6d1abb5

Browse files
LadyBluenotesLadyBluenotes
committed
migrate store creation and mutable store refs
1 parent ed22b63 commit 6d1abb5

3 files changed

Lines changed: 151 additions & 139 deletions

File tree

‎src/routes/reference/store-utilities/create-mutable.mdx‎

Lines changed: 53 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,67 @@
11
---
22
title: createMutable
33
use_cases: >-
4-
mobx migration, vue compatibility, external system integration, mutable state
5-
patterns, proxy-based reactivity
4+
mutable proxy state, interop with mutable systems, object mutation through a
5+
store proxy
66
tags:
77
- store
88
- mutable
99
- proxy
1010
- state
11-
- compatibility
1211
version: "1.0"
1312
description: >-
14-
Create mutable proxy stores with automatic deep tracking. Ideal for MobX/Vue
15-
compatibility or integrating external mutable systems.
13+
Create a mutable store proxy.
1614
---
1715

18-
`createMutable` creates a new mutable Store proxy object that provides a way to selectively trigger updates only when values change.
16+
`createMutable` creates a mutable store proxy.
1917

20-
By intercepting property access, it allows automatic tracking of deep nesting via proxy making it useful for integrating external systems or serving as a compatibility layer with frameworks like MobX or Vue.
18+
## Import
2119

22-
```tsx
20+
```ts
2321
import { createMutable } from "solid-js/store";
24-
import type { Store, StoreNode } from "solid-js/store";
22+
```
23+
24+
## Type
2525

26-
function createMutable<T extends StoreNode>(state: T | Store<T>): Store<T>;
26+
```ts
27+
function createMutable<T extends Record<PropertyKey, any>>(
28+
state: T,
29+
options?: { name?: string }
30+
): T;
2731
```
2832

29-
:::note
30-
It's important to recognize that a mutable state, which can be passed around and modified anywhere, may complicate the code structure and increase the risk of breaking unidirectional flow.
33+
## Parameters
34+
35+
### `state`
36+
37+
- **Type:** `T`
38+
39+
Initial mutable state.
40+
41+
### `options`
42+
43+
#### `name`
44+
45+
- **Type:** `string`
46+
47+
Debug name used by development tooling.
48+
49+
## Return value
3150

32-
For a more robust alternative, it is generally recommended to use `createStore` instead.
33-
Additionally, the [`produce`](/reference/store-utilities/produce) utility can provide many of these same benefits without the associated downsides.
51+
- **Type:** `T`
3452

35-
:::
53+
Mutable store proxy.
54+
55+
## Behavior
56+
57+
- Property reads and writes go through a proxy.
58+
- Nested property access is reactive.
59+
- Mutations update the store in place.
60+
- Getters and setters defined on the initial object remain available on the mutable store.
61+
62+
## Examples
63+
64+
### Basic usage
3665

3766
```tsx
3867
import { createMutable } from "solid-js/store";
@@ -42,18 +71,15 @@ const state = createMutable({
4271
list: [],
4372
});
4473

45-
// read value
46-
state.someValue;
47-
48-
// set value
4974
state.someValue = 5;
50-
51-
state.list.push(anotherValue);
75+
state.list.push("item");
5276
```
5377

54-
Mutables support setters along with getters.
78+
### Getter and setter
5579

5680
```tsx
81+
import { createMutable } from "solid-js/store";
82+
5783
const user = createMutable({
5884
firstName: "John",
5985
lastName: "Smith",
@@ -65,3 +91,8 @@ const user = createMutable({
6591
},
6692
});
6793
```
94+
95+
## Related
96+
97+
- [`modifyMutable`](/reference/store-utilities/modify-mutable)
98+
- [`createStore`](/reference/store-utilities/create-store)

‎src/routes/reference/store-utilities/create-store.mdx‎

Lines changed: 60 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,88 @@
11
---
22
title: createStore
33
use_cases: >-
4-
complex state management, nested data, arrays and objects, derived values,
5-
application state
4+
object state, array state, nested state, structured application state
65
tags:
76
- store
87
- state
9-
- data-structures
108
- objects
119
- arrays
1210
version: "1.0"
1311
description: >-
14-
Manage complex application state with createStore. Handle nested objects,
15-
arrays, and derived values with fine-grained reactivity.
12+
Create a reactive store and a setter function for structured state.
1613
---
1714

18-
Stores were intentionally designed to manage data structures like objects and arrays but are capable of handling other data types, such as strings and numbers.
15+
`createStore` creates a reactive store and setter function for structured state.
1916

20-
## Types Signature
17+
## Import
2118

22-
```tsx
19+
```ts
2320
import { createStore } from "solid-js/store";
24-
import type { StoreNode, Store, SetStoreFunction } from "solid-js/store";
21+
```
22+
23+
## Type
2524

26-
function createStore<T extends StoreNode>(
27-
state: T | Store<T>
28-
): [get: Store<T>, set: SetStoreFunction<T>];
25+
```ts
26+
type Store<T> = T;
2927

30-
type Store<T> = T; // conceptually readonly, but not typed as such
28+
interface SetStoreFunction<T> {
29+
(setter: T | Partial<T> | ((prev: T) => T | Partial<T>)): void;
30+
}
31+
32+
function createStore<T extends object = {}>(
33+
store?: T | Store<T>,
34+
options?: { name?: string }
35+
): [Store<T>, SetStoreFunction<T>];
3136
```
3237

33-
## Usage
38+
## Parameters
39+
40+
### `store`
41+
42+
- **Type:** `T | Store<T>`
43+
44+
Initial store value.
45+
46+
### `options`
47+
48+
#### `name`
49+
50+
- **Type:** `string`
51+
52+
Debug name used by development tooling.
53+
54+
## Return value
55+
56+
- **Type:** `[Store<T>, SetStoreFunction<T>]`
57+
58+
Tuple containing the store proxy and its setter.
59+
60+
## Behavior
61+
62+
- The returned store is read through a proxy.
63+
- The setter can update the whole store or specific paths.
64+
- Object updates are shallowly merged by the setter.
65+
- Getters defined on the initial object remain available on the store.
66+
67+
## Examples
68+
69+
### Basic usage
3470

3571
```tsx
3672
import { createStore } from "solid-js/store";
3773

38-
// Initialize store
39-
const [store, setStore] = createStore({
40-
userCount: 3,
41-
users: [
42-
{
43-
id: 0,
44-
username: "felix909",
45-
location: "England",
46-
loggedIn: false,
47-
},
48-
{
49-
id: 1,
50-
username: "tracy634",
51-
location: "Canada",
52-
loggedIn: true,
53-
},
54-
{
55-
id: 1,
56-
username: "johny123",
57-
location: "India",
58-
loggedIn: true,
59-
},
60-
],
74+
const [state, setState] = createStore({
75+
firstName: "John",
76+
lastName: "Smith",
6177
});
6278
```
6379

64-
## Getter
65-
66-
Store objects support the use of getters to store derived values.
80+
### Getter
6781

6882
```tsx
69-
const [state, setState] = createStore({
83+
import { createStore } from "solid-js/store";
84+
85+
const [state] = createStore({
7086
user: {
7187
firstName: "John",
7288
lastName: "Smith",
@@ -77,25 +93,7 @@ const [state, setState] = createStore({
7793
});
7894
```
7995

80-
## Setter
81-
82-
Changes can take the form of function that passes previous state and returns new state or a value.
83-
Objects are always shallowly merged. Set values to undefined to delete them from the Store.
84-
In TypeScript, you can delete a value by using a non-null assertion, like `undefined!`.
85-
86-
```tsx
87-
const [state, setState] = createStore({
88-
firstName: "John",
89-
lastName: "Miller",
90-
});
91-
92-
setState({ firstName: "Johnny", middleName: "Lee" });
93-
// ({ firstName: 'Johnny', middleName: 'Lee', lastName: 'Miller' })
94-
95-
setState((state) => ({ preferredName: state.firstName, lastName: "Milner" }));
96-
// ({ firstName: 'Johnny', preferredName: 'Johnny', middleName: 'Lee', lastName: 'Milner' })
97-
```
98-
99-
---
96+
## Related
10097

101-
To learn more about using stores check the [Stores Guide](/concepts/stores), and the **Store utilities** section for more advanced APIs.
98+
- [`createMutable`](/reference/store-utilities/create-mutable)
99+
- [Stores](/concepts/stores)

0 commit comments

Comments
 (0)