---
# System prepended metadata

title: Persisting states
tags: [brew-js]

---

---
tags: brew-js
---

# Persisting states

<span style="background: lightblue;padding:.25em .75em;border-radius:1em;font-weight:bold">v0.5</span>

Data can be restored even after leaving and revisit the app in the same tab.

:::warning
Session storage has a typical 5MB limitation. Although data is compressed, storing huge data should be avoided.
:::

:::warning
Although session storage is scoped to the document's origin and is cleared when the tab is closed, do not store critically sensitive data.
:::

## History storage

View states can be persisted through history storage so that when user revisit the app through browser history, the page can be restored .

```typescript
let storage = app.historyStorage.current;
storage.set('data', {});
```

See [Snapshots](/nHsJ5xk5Scq23dIUN6RMTQ).

### Getting for a specific state

```typescript
app.historyStorage.for(stateId)
```

## Session storage

<span style="background: lightblue;padding:.25em .75em;border-radius:1em;font-weight:bold">v0.5.3</span>

:::warning
Note that an app session is different from a browser session which typically associates to the lifetime of a tab.
:::

An app session is created for every unique visit to the single-page app, for example from a link. When the page is reloaded, or is restored by going forward or backward in browser history, previous app session is resumed.

App sessions can also be explicitly resumed when `resume` option is specified when configuring the router.

Thus it is most suitable for persisting global states in a single-page app.
         
## Cache

<span style="background: lightblue;padding:.25em .75em;border-radius:1em;font-weight:bold">v0.5.3</span>

The `app.cache` property provides additional storage slot that will persist in the same tab regardless of app sessions.

Thus it is suitable for caching resources (likely from APIs) that do not depends on current session.


## Object storage interface

It is a sub-class of `Map` object, therefore all `Map` method is callable.


### Object and circular references

Object references are maintained and circular references are supported.

### Limitations

All limitations with native JSON serialization applies (except for circular references):

- Properties with symbols as keys are not serialized
- Properties with functions as values are not serialized
- Date objects are serialized as time strings (because of `Date.prototype.toJSON`)

In addition, properties with these values are also ignored, due to commonly large amount of data:

- `Blob` objects
- DOM nodes, i.e. elements and text nodes
- the `window` object

:::info
It is recommended to only store strings, numbers and booleans values, as well as objects and arrays containing only these values.
:::

### Persisting nested object

```typescript
let storage = app.historyStorage.current;
let data = storage.get('data');
let nested = data.obj;

nested.a = 1;
storage.persist(nested);
```
