npm package: @pikapower9080/easy-storage
Description: Lightweight library of localStorage helper functions.
Author: pikapower9080
Latest version: 1.1.1

# @pikapower9080/easy-storage

`easy-storage` is a JavaScript library that makes localStorage better by storing multiple values under one key.

### Advantages of single-key storage
- Reduces risk of conflict between keys when multiple apps are running on one domain (e.g. localhost)
- Allows for the backing up, overwriting, and clearing of all stored data without touching data stored by other apps or userscripts

## Usage
EasyStorage is made for use with ESM modules. It is documented with JSDoc for smart intellisense features. Here is a basic example of how to use the library:
```javascript
import EasyStorage from '@pikapower9080/easy-storage'

const storage = new EasyStorage({
    key: "my-app-name"
})

if (!storage.get("first-visit", false)) {
    alert("Welcome!")
    storage.set("first-visit", new Date().getTime())
}
```
Additional methods are available and should be auto-completed by your editor.

## Options
You can pass these options when you call `new EasyStorage({})`

| Key                 | Description                                                                        | Default  |
| ------------------- | ---------------------------------------------------------------------------------- | -------- |
| `key`               | Key to store all data in, a good key is unique to your app                         | `config` |
| `default`           | Default values to set if there is no data stored or the data is corrupted          | `{}`     |
| `useSessionStorage` | Store all data in sessionStorage instead of localStorage                           | `false`  |
| `migration.enabled` | Enables the migration system which can move user data from an old key to a new one | `false`  |
| `migration.old_key` | The old key to migrate old user data from (migration.enabled must be true)         | N/A      |

# Documentation

## EasyStorage
Main class for EasyStorage.

**Kind**: global class  

* [EasyStorage](#EasyStorage)
    * [.keys](#EasyStorage+keys)
    * [.getAll()](#EasyStorage+getAll) ⇒ <code>object</code>
    * [.set(key, value)](#EasyStorage+set)
    * [.get(key, [defaultValue])](#EasyStorage+get) ⇒ <code>any</code>
    * [.clearAll()](#EasyStorage+clearAll)
    * [.setAll(data)](#EasyStorage+setAll)
    * [.getAllOfType(type)](#EasyStorage+getAllOfType) ⇒ <code>object</code>
    * [.getAllIf(predicate)](#EasyStorage+getAllIf)
    * [.toArray([flat])](#EasyStorage+toArray) ⇒ <code>object</code>
    * [.forEach(callback)](#EasyStorage+forEach)

### easyStorage.keys
Array of keys present in storage.

**Kind**: instance property of [<code>EasyStorage</code>](#EasyStorage)  
**Example**  
```js
console.log(storage.keys.length)
```
<a name="EasyStorage+getAll"></a>

### easyStorage.getAll() ⇒ <code>object</code>
Gets all stored data as an object.

**Kind**: instance method of [<code>EasyStorage</code>](#EasyStorage)  
<a name="EasyStorage+set"></a>

### easyStorage.set(key, value)
Set the value for a key and save it to localStorage.

**Kind**: instance method of [<code>EasyStorage</code>](#EasyStorage)  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | The key to be stored inside of the main localStorage key |
| value | <code>any</code> | Value to set |

<a name="EasyStorage+get"></a>

### easyStorage.get(key, [defaultValue]) ⇒ <code>any</code>
Get the value for a key.

**Kind**: instance method of [<code>EasyStorage</code>](#EasyStorage)  
**Returns**: <code>any</code> - The stored value  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | The key to get the value from inside of the main localStorage key |
| [defaultValue] | <code>any</code> | Value to return if the data is not present |

<a name="EasyStorage+clearAll"></a>

### easyStorage.clearAll()
Clear all stored data.

**Kind**: instance method of [<code>EasyStorage</code>](#EasyStorage)  
<a name="EasyStorage+setAll"></a>

### easyStorage.setAll(data)
Replace all stored data with an object.

**Kind**: instance method of [<code>EasyStorage</code>](#EasyStorage)  

| Param | Type | Description |
| --- | --- | --- |
| data | <code>object</code> | Object to replace stored data with |

<a name="EasyStorage+getAllOfType"></a>

### easyStorage.getAllOfType(type) ⇒ <code>object</code>
Gets all values of a certain type.

**Kind**: instance method of [<code>EasyStorage</code>](#EasyStorage)  
**Returns**: <code>object</code> - Object with filtered values  

| Param | Type | Description |
| --- | --- | --- |
| type | <code>string</code> | Type to get |

<a name="EasyStorage+getAllIf"></a>

### easyStorage.getAllIf(predicate)
Gets all key/value pairs where the specified condition is true.

**Kind**: instance method of [<code>EasyStorage</code>](#EasyStorage)  

| Param | Type | Description |
| --- | --- | --- |
| predicate | <code>function</code> | Predicate to check for key/value pairs to be included |

**Example**  
```js
storage.getAllIf((key, value, index) => key.includes('@'))
```
**Example**  
```js
storage.getAllIf((key, value, index) => {
      if (index % 2 === 0) {
        return true
      }
   })
```
<a name="EasyStorage+toArray"></a>

### easyStorage.toArray([flat]) ⇒ <code>object</code>
Returns all values in array format.

**Kind**: instance method of [<code>EasyStorage</code>](#EasyStorage)  
**Returns**: <code>object</code> - Array of keys and values  

| Param | Type | Description |
| --- | --- | --- |
| [flat] | <code>boolean</code> | Makes the array a list of objects with key and value properties |

<a name="EasyStorage+forEach"></a>

### easyStorage.forEach(callback)
Executes a callback function for each stored key/value pair.

**Kind**: instance method of [<code>EasyStorage</code>](#EasyStorage)  

| Param | Type | Description |
| --- | --- | --- |
| callback | <code>function</code> | Function to be executed for each key |