npm package: @fooxly/persistn
Description: Persist and rehydrate the ReactN global state.
Author: Fooxly
Latest version: 1.0.2
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# PersistN

Persist and rehydrate the [ReactN] global state, with support for [LoggerN].

A package by [Fooxly](https://www.fooxly.com), based on [redux-persist].

[![pipeline status](https://gitlab.com/fooxly/persistn/badges/master/pipeline.svg)](https://gitlab.com/fooxly/persistn/commits/master)
[![coverage report](https://gitlab.com/fooxly/persistn/badges/master/coverage.svg)](https://gitlab.com/fooxly/persistn/commits/master)
![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)
[![npm version](https://img.shields.io/npm/v/@fooxly/persistn.svg?style=flat)](https://www.npmjs.com/package/@fooxly/persistn)
![npm bundle size](https://img.shields.io/bundlephobia/min/@fooxly/persistn.svg)

## :cloud: Installation

### using npm

```sh
npm install --save @fooxly/persistn
```

### using yarn

```sh
yarn add @fooxly/persistn
```

## :paperclip: Importing

### ES6 and up

The module uses an ES6 style export statement, simply use `import` to load the module.

```js
import PersistN from '@fooxly/persistn';
```

### ES5

If you're using an ES5 require statement to load the module, please add `default`. Look [here](https://stackoverflow.com/a/38459264/7448923) for more details.

**Note**: The remaining documentation is written in ES6.

```js
var PersistN = require('@fooxly/persistn').default;
```

## :triangular_ruler: Usage

**Note**: This part of the documentation is incomplete

### Basic Usage

PersistN configuration replaces the initial `setGlobal()` call for simplicity.

**Example File**: index.js

```js
import setGlobal from './persist'

setGlobal({
  foo: 'bar'
})

// ... your code
```

Check [Storage Engines](#storage-engines) for more information about the storage import.

**Example File**: persist.js

```js
import reactn from 'reactn'
import PersistN from '@fooxly/persistn'
import storage from '@fooxly/persistn/storage'

const persistConfig = {
  key: 'root',
  storage
}

export default initial => {
  PersistN(persistConfig, reactn, initial)
}
```

### Use Actions

The following actions are available:

* **Purge**: Reset the state to the initial state
* **Pause**: Pause the persistance of the state (also paused on reload)
* **Resume**: Resume the persistance of the state

**Example File**: App.js

```js
import { useGlobal } from 'reactn'
import { PERSIST_KEY, PURGE } from '@fooxly/persistn'

export default () => {
  const persist = useGlobal(PERSIST_KEY)

  return (
    <button onClick={() => persist(PURGE)} />
  )
}
```

<!-- ## Transforms

**Important Note**: When the state object gets persisted, it first gets serialized with `JSON.stringify()`. If parts of your state object are not mappable to JSON objects, the serialization process may transform these parts of your state in unexpected ways. For example, the [JavaScript Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) type does not exist in JSON. When you try to serialize a Set via `JSON.stringify()`, it gets converted to an empty object. Probably not what you want.

Transforms allow you to customize the state object that gets persisted and rehydrated.

PersistN supports all of the transforms made for [redux-persist]! There are [several libraries](https://github.com/rt2zz/redux-persist#transforms) that tackle some of the common implementations for transforms. -->

## :package: Storage Engines

* [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
  
  `import storage from '@fooxly/persistn/storage'`

* [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
  
  `import storage from '@fooxly/persistn/storage/session'`

* [AsyncStorage](https://github.com/react-native-community/react-native-async-storage)
  
  `import AsyncStorage from '@react-native-community/async-storage'`

Check [here](https://github.com/rt2zz/redux-persist#storage-engines) for more suggestions.

## :closed_book: API

**Note**: This part of the documentation is incomplete

## :clipboard: To-do

* Add `actionTransformer` export for better [LoggerN] support
* `transforms` option, customize the state object that gets persisted and rehydrated
* `stateReconciler` option, to define how the rehydrated state object is merged with the initial state
* `predicate` option, to determine whether or not to persist a change in the global state
* `whitelist` option, to whitelist certain keys in the state object for persistance
* `blacklist` option, to blacklist certain keys in the state object from persistance, this also improves support for [RequestN]

## :heart: Support our projects

You can support us by donating through BuyMeACoffee [here](https://www.buymeacoffee.com/fooxly).

![BuyMeACoffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)

<!-- External Links -->
[ReactN]: https://github.com/CharlesStover/reactn
[LoggerN]: https://gitlab.com/fooxly/loggern
[RequestN]: https://gitlab.com/fooxly/requestn
[redux-persist]: https://github.com/rt2zz/redux-persist