Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wave-play/stashy

Storage API for Node, React Native, and the browser
https://github.com/wave-play/stashy

async-storage expo javascript nextjs node nodejs react react-native reactjs storage waveplay

Last synced: 23 days ago
JSON representation

Storage API for Node, React Native, and the browser

Awesome Lists containing this project

README 

        
Stashy






[![GitHub license](https://img.shields.io/github/license/Wave-Play/stashy?style=flat)](https://github.com/Wave-Play/stashy/blob/main/LICENSE) [![Tests](https://github.com/Wave-Play/stashy/workflows/CI/badge.svg)](https://github.com/Wave-Play/stashy/actions) ![npm](https://img.shields.io/npm/v/@waveplay/stashy) [![minizipped size](https://badgen.net/bundlephobia/minzip/@waveplay/stashy)](https://bundlephobia.com/result?p=@waveplay/stashy)



**Storage API for Node, React Native, and the browser**



Stashy uses the best storage backend for each environment.



Live demo project for web






## Getting started



Install the package:



```bash

npm install @waveplay/stashy

```



Use functions such as `get(key)` or `set(key, value)`. These will be delegated to the correct backend based on the environment your code is running in. 



```ts

import stashy from '@waveplay/stashy'



// Get a value from storage

const displayName = stashy.getString('name')

console.log(`Your username is ${displayName}`)



// Update a value in storage

// It'll be saved and available when you come back later

stashy.set('name', 'Pkmmte Xeleon')

```



See the [sample project](https://github.com/Wave-Play/stashy/tree/master/examples/basic-example) for more usage examples.



## API reference



| Function          | Description                                              |

| ----------------- | -------------------------------------------------------- |

| `clearAll`        | Clears all data from the backend.                        |

| `delete`          | Deletes the value for the given key.                     |

| `get`             | Gets the value for the given key.                        |

| `getAsync`        | Gets the value for the given key asynchronously.         |

| `getBoolean`      | Gets the boolean value for the given key.                |

| `getBooleanAsync` | Gets the boolean value for the given key asynchronously. |

| `getNumber`       | Gets the number value for the given key.                 |

| `getNumberAsync`  | Gets the number value for the given key asynchronously.  |

| `getString`       | Gets the string value for the given key.                 |

| `getStringAsync`  | Gets the string value for the given key asynchronously.  |

| `set`             | Sets the value for the given key.                        |



## Default instance



When you use `import stashy from '@waveplay/stashy'`, you're importing the default instance of Stashy. This instance is created with the default options and will use the best backend for your environment.



This may be considered unnecessary overhead if you're creating new instances of Stashy in your code instead of using the default instance. Import from `@waveplay/stashy/core` instead to avoid this overhead.



```ts

import { Stashy } from '@waveplay/stashy/core'



const stashy = new Stashy({

	// ... your custom options

})

```



## Backends



Stashy comes with a few backends available out of the box. You can also create your own backend by implementing the `StashyBackend` interface.



```ts

import { Stashy } from '@waveplay/stashy'

import { StashyBackend } from '@waveplay/stashy/backend'



class CustomBackend implements StashyBackend {

  // ... your custom backend implementation

}



const stashy = new Stashy({

  backend: new CustomBackend()

})



// or with different backends per environment

const stashy = new Stashy({

  backend: {

    native: new MmkvBackend(),

    ssr: new CookieBackend(),

    web: new CustomBackend()

  }

})

```



#### AsyncStorage



This backend uses [@react-native-async-storage/async-storage](https://github.com/react-native-async-storage/async-storage) to store data. It is the default backend for native and only works with async functions such as `getStringAsync()`.



```ts

import { AsyncStorageBackend } from '@waveplay/stashy/backend/async-storage'

```



#### Cookie



Cookie-backed storage perfect for server-side environments. It is the default backend for SSR and requires a `context` object to be passed with every function call.



```ts

import { CookieBackend } from '@waveplay/stashy/backend/cookie'

```



#### Env



Meant to use `process.env` variables. Supports dot notation for nested objects. 



```ts

import { EnvBackend } from '@waveplay/stashy/backend/env'

```



> **Note:** This will not load the `.env` file for you. Use with [dotenv](https://github.com/motdotla/dotenv) if you need to load the `.env` file. Frameworks like [Next.js](https://nextjs.org/) and [Pilot.js](https://github.com/Wave-Play/pilot/) do this automatically.



#### LocalStorage



Relies on `localStorage` to store data. It is the default backend for web.



```ts

import { LocalStorageBackend } from '@waveplay/stashy/backend/local-storage'

```



#### MMKV



Extremely fast and efficient storage for React Native, but requires that you install [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) separately. If you're using Expo, you will also need to generate a new development client build.



```ts

import { MmkvBackend } from '@waveplay/stashy/backend/mmkv'

```



## Debugging



You can pass your own logger (such as [pino](https://github.com/pinojs/pino)) to Stashy when creating a new instance and it will be used to log events. This is useful for debugging backend and environment issues. 



The `id` property is included in each log message to help you differentiate between multiple instances of Stashy.



```ts

import { Stashy } from '@waveplay/stashy'

import pino from 'pino'



const stashy = new Stashy({

  id: 'my-stash',

  logger: pino({ level: 'debug' })

})

```



## Credits



This project was originally developed for [WavePlay](https://waveplay.com).



## License



The MIT License.