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
(docs): transforms usage & example, ordering & visual
- describe usage, link to MST snapshots, show typings, and link to
internal examples of whitelist and blacklist transforms
- use commit permalink for internal transforms so it won't 404 or
change over time (though ofc will need to be updated if the
transforms API changes)
- describe ordering and show a small diagram of it end-to-end
Copy file name to clipboardExpand all lines: README.md
+36Lines changed: 36 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -62,9 +62,45 @@ persist('some', someStore, {
62
62
-**jsonify***bool* Enables serialization as JSON (default: `true`).
63
63
-**whitelist***Array\<string\>* Only these keys will be persisted (defaults to all keys).
64
64
-**blacklist***Array\<string\>* These keys will not be persisted (defaults to all keys).
65
+
-**transforms***Array\<[Transform](#transforms)\>*[Transforms]((#transforms)) to apply to snapshots on the way to and from storage.
65
66
66
67
- returns a void Promise
67
68
69
+
### Transforms
70
+
71
+
Transforms allow you to customize the [snapshot](https://github.com/mobxjs/mobx-state-tree#snapshots) that is persisted and used to hydrate your store.
72
+
73
+
Transforms are `object`s with `toStorage` and `fromStorage` functions that are called with a `snapshot`-like argument and expected to return a `snapshot`-like object:
74
+
75
+
```typescript
76
+
interfaceITransform {
77
+
readonly toStorage?:ITransformArgs,
78
+
readonly fromStorage?:ITransformArgs
79
+
}
80
+
interfaceITransformArgs {
81
+
(snapshot:StrToAnyMap):StrToAnyMap
82
+
}
83
+
```
84
+
85
+
As an example, one may see how [whitelists](https://github.com/agilgur5/mst-persist/blob/229fd2b1b472ea6a7912a5a06fa079a65e3ba6fa/src/whitelistTransform.ts#L7-L14) and [blacklists](https://github.com/agilgur5/mst-persist/blob/229fd2b1b472ea6a7912a5a06fa079a65e3ba6fa/src/blacklistTransform.ts#L7-L14) are implemented internally as transforms.
86
+
87
+
#### Transform Ordering
88
+
89
+
`toStorage` functions are called serially in the order specified in the `transforms` configuration array.
90
+
`fromStorage` functions are called in the reverse order, such that the last transform is first.
91
+
92
+
Before any `toStorage` functions are run, the snapshot will first be stripped of any keys as specified by the `whitelist` and `blacklist` configuration.
93
+
Then, once the `toStorage` functions are all run, the object will be serialized to JSON, if that configuration is enabled.
94
+
95
+
Before any `fromStorage` functions are run, the JSON will be deserialized into an object, if that configuration is enabled.
Node environments are supported so long as you configure a Storage Engine that supports Node, such as [`redux-persist-node-storage`](https://github.com/pellejacobs/redux-persist-node-storage), [`redux-persist-cookie-storage`](https://github.com/abersager/redux-persist-cookie-storage), etc.
0 commit comments