https://github.com/jsheaven/simply-persist
Isomorphic object key/value persistence layer (browser, server) with in-memory, browser and free-tier serverless backend providers
https://github.com/jsheaven/simply-persist
isomorphic key-value-database persistence-layer storage-api
Last synced: 8 months ago
JSON representation
Isomorphic object key/value persistence layer (browser, server) with in-memory, browser and free-tier serverless backend providers
- Host: GitHub
- URL: https://github.com/jsheaven/simply-persist
- Owner: jsheaven
- License: mit
- Created: 2023-02-05T00:42:09.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-03-15T14:24:34.000Z (about 3 years ago)
- Last Synced: 2025-01-05T23:40:56.270Z (over 1 year ago)
- Topics: isomorphic, key-value-database, persistence-layer, storage-api
- Language: TypeScript
- Homepage:
- Size: 90.8 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
simply-persist
> Nano utility library for JavaScript to persist objects (POJOs) everywhere and with ease
Purpose
Accessing `localStorage` and `sessionStorage` or writing to an in-memory object seems easy,
but then there is browser private mode, there are security and quota restrictions, and if
you try to run the same code on client (in the browser) and server, fun with Errors is guaranteed.
This is, why we've built this library that only has one job: Write an object into a storage backend,
be able to read from it by key to get a value and also be able to delete data by key and make this
possible isomorphic on client and server side, no matter what.
Features
- ✅ Write to storage using simple key/value API
- ✅ Middleware function API allows to hook what is read and written
- ✅ Isomorphic, works in-browser and in Node.js
- ✅ Supports `localStorage`
- ✅ Supports `sessionStorage`
- ✅ Supports in-memory as an automatic fallback
- ✅ Supports [Upstash](https://www.upstash.com) (serverless, free-tier database backend)
- ✅ Exposes the backend API reference of each storage provider for low-level API access
- ✅ Just `592 byte` nano sized (ESM, gizpped)
- ✅ Tree-shakable, side-effect free, so maybe just `~200 byte` for you
- ✅ First class TypeScript support
- ✅ 100% Unit Test coverage
Install
- yarn: `yarn add simply-persist`
- npm: `npm install simply-persist`
Use
ESM
```ts
import { getStorage } from 'simply-persist'
const storage = getStorage('memory') // also: 'local' | 'session' | 'upstash'
// store a value
await storage.set('abc', 123)
// read a previously stored value, if not existing, return the default (0)
const valueStored = await storage.get('abc', 0)
// delete a single value
await storage.del('abc')
// delete all values
await storage.clear()
```
CommonJS
```ts
const { getStorage } = require('simply-persist')
// same API like ESM variant
```
One thing about Node.js and `localStorage` and `sessionStorage`
The web storage APIs such as `localStorage` and `sessionStorage` are not available in Node.js.
This library will gently fallback to the in-memory variant instead. Please mind the slightly
different application behaviour in this case.