Skip to content

Commit 595d74e

Browse files
committed
(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
1 parent 28473e6 commit 595d74e

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed

README.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,45 @@ persist('some', someStore, {
6363
- **jsonify** *bool* Enables serialization as JSON (default: `true`).
6464
- **whitelist** *Array\<string\>* Only these keys will be persisted (defaults to all keys).
6565
- **blacklist** *Array\<string\>* These keys will not be persisted (defaults to all keys).
66+
- **transforms** *Array\<[Transform](#transforms)\>* [Transforms]((#transforms)) to apply to snapshots on the way to and from storage.
6667

6768
- returns a void Promise
6869

70+
### Transforms
71+
72+
Transforms allow you to customize the [snapshot](https://github.com/mobxjs/mobx-state-tree#snapshots) that is persisted and used to hydrate your store.
73+
74+
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:
75+
76+
```typescript
77+
interface ITransform {
78+
readonly toStorage?: ITransformArgs,
79+
readonly fromStorage?: ITransformArgs
80+
}
81+
interface ITransformArgs {
82+
(snapshot: StrToAnyMap): StrToAnyMap
83+
}
84+
```
85+
86+
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.
87+
88+
#### Transform Ordering
89+
90+
`toStorage` functions are called serially in the order specified in the `transforms` configuration array.
91+
`fromStorage` functions are called in the reverse order, such that the last transform is first.
92+
93+
Before any `toStorage` functions are run, the snapshot will first be stripped of any keys as specified by the `whitelist` and `blacklist` configuration.
94+
Then, once the `toStorage` functions are all run, the object will be serialized to JSON, if that configuration is enabled.
95+
96+
Before any `fromStorage` functions are run, the JSON will be deserialized into an object, if that configuration is enabled.
97+
98+
To put this visually with some pseudo-code:
99+
100+
```text
101+
onSnapshot -> whitelist -> blacklist -> transforms toStorage -> JSON.stringify -> Storage.setItem
102+
Storage.getItem -> JSON.parse -> transforms.reverse() fromStorage -> applySnapshot
103+
```
104+
69105
### Node and Server-Side Rendering (SSR) Usage
70106

71107
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

Comments
 (0)