Skip to content

Commit acb80e2

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 901f214 commit acb80e2

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
@@ -62,9 +62,45 @@ persist('some', someStore, {
6262
- **jsonify** *bool* Enables serialization as JSON (default: `true`).
6363
- **whitelist** *Array\<string\>* Only these keys will be persisted (defaults to all keys).
6464
- **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.
6566

6667
- returns a void Promise
6768

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+
interface ITransform {
77+
readonly toStorage?: ITransformArgs,
78+
readonly fromStorage?: ITransformArgs
79+
}
80+
interface ITransformArgs {
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.
96+
97+
To put this visually with some pseudo-code:
98+
99+
```text
100+
onSnapshot -> whitelist -> blacklist -> transforms toStorage -> JSON.stringify -> Storage.setItem
101+
Storage.getItem -> JSON.parse -> transforms.reverse() fromStorage -> applySnapshot
102+
```
103+
68104
### Node and Server-Side Rendering (SSR) Usage
69105

70106
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)