Skip to content

Commit

Permalink
(docs): transforms usage & example, ordering & visual
Browse files Browse the repository at this point in the history
- 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
  • Loading branch information
agilgur5 committed Nov 10, 2019
1 parent 901f214 commit acb80e2
Showing 1 changed file with 36 additions and 0 deletions.
36 changes: 36 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,45 @@ persist('some', someStore, {
- **jsonify** *bool* Enables serialization as JSON (default: `true`).
- **whitelist** *Array\<string\>* Only these keys will be persisted (defaults to all keys).
- **blacklist** *Array\<string\>* These keys will not be persisted (defaults to all keys).
- **transforms** *Array\<[Transform](#transforms)\>* [Transforms]((#transforms)) to apply to snapshots on the way to and from storage.

- returns a void Promise

### Transforms

Transforms allow you to customize the [snapshot](https://github.com/mobxjs/mobx-state-tree#snapshots) that is persisted and used to hydrate your store.

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:

```typescript
interface ITransform {
readonly toStorage?: ITransformArgs,
readonly fromStorage?: ITransformArgs
}
interface ITransformArgs {
(snapshot: StrToAnyMap): StrToAnyMap
}
```

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.

#### Transform Ordering

`toStorage` functions are called serially in the order specified in the `transforms` configuration array.
`fromStorage` functions are called in the reverse order, such that the last transform is first.

Before any `toStorage` functions are run, the snapshot will first be stripped of any keys as specified by the `whitelist` and `blacklist` configuration.
Then, once the `toStorage` functions are all run, the object will be serialized to JSON, if that configuration is enabled.

Before any `fromStorage` functions are run, the JSON will be deserialized into an object, if that configuration is enabled.

To put this visually with some pseudo-code:

```text
onSnapshot -> whitelist -> blacklist -> transforms toStorage -> JSON.stringify -> Storage.setItem
Storage.getItem -> JSON.parse -> transforms.reverse() fromStorage -> applySnapshot
```

### Node and Server-Side Rendering (SSR) Usage

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.
Expand Down

0 comments on commit acb80e2

Please sign in to comment.