nullixat / browstorjs

Persistent key/value data storage for your Browser and/or PWA, promisified, including file support and service worker support, all with IndexedDB. Perfectly suitable for your next (PWA) app.

BrowstorJS 🚀 💾 🔒

Persistent key/value data storage for your Browser and/or PWA, promisified, including file support and service worker support, all with IndexedDB. Perfectly suitable for your next (PWA) app.

Features 📣

• Simple Key/Value Data Storage in IndexedDB
• Serve any storage value as a real URL (No Data URI) for Images, Files, etc...
• Promisified for async/await support
• Cross-Browser
  • Chrome (Mobile/Desktop incl. incognito mode)
  • Firefox (Mobile/Desktop but not in private mode)
  • Safari (Mobile/Desktop incl. partially in InPrivate Mode)
  • Edge New (Chromium incl. private mode)
  • Edge Old v17+
  • WebKit
  • and every other from the last years
  • No Internet Explorer
• Super Lightweight (~400 byte when gzipped, ~4kb uncompressed)
• Notice: A word about persistence in current browsers...

Usage ⚡

const db = await BrowstorJS.open() // get instance
await db.set('mykey', 'myvalue') // set a value
await db.get('mykey') // get a value
await db.getUrl('mykey') // get a URL that serves the value from this key (eg.: for images)
await db.getDataUri('mykey') // get a data uri (to use as image src for example) for the value of this key
await db.search((key, value) => { return key.startsWith('mykey') }) // search entries with condition
await db.remove('mykey') // remove a single key
await db.reset() // clear the database, delete all entries
await db.getKeys() // ['mykey', ...]
const db = await BrowstorJS.open('myotherdb') // get instance to a separate db
const isPersistent = await BrowstorJS.requestPersistentStorage() // request persistent storage
const info = await BrowstorJS.getStorageSpaceInfo() // {available:number, used:number, free:number}

Jump to Event registration inside service worker to make the function db.getUrl() to actually work.

Demo 👾

Head to our demo page to see and test the library in action.

Install 💿

Variant Self-Hosted Self-Download

Download the latest release, unpack the dist/browstorjs.js and load it into your website <script src="browstorjs.js"></script>.

Variant using TypeScript

Download the latest release (Or use NPM to install the library) and include src/browstorjs.ts wherever you need it.

Variant using NPM

npm install browstorjs

You know how to pack the library into your website when you opt in for using npm. It depends on your environment how you integrate the dist file.

Variant using CDN (Not recommended but handy for quick tests)

Load it into your website <script src="https://cdn.jsdelivr.net/npm/browstorjs/dist/browstorjs.js"></script>.

Event registration inside service worker 🎷

To make the generation of getUrl work, you need to handle some service worker events. If you don't need getUrl you also don't necessarily need a service worker.

This is the bare minimum inside a service worker, you can add your custom code after the BrowstorJS handlers.

importScripts('scripts/browstorjs.js')

self.addEventListener('activate', event => {
  if (BrowstorJS.handleServiceWorkerEvents(event)) return
  // place your additional app code here
})

self.addEventListener('fetch', event => {
  if (BrowstorJS.handleServiceWorkerEvents(event)) return
  // place your additional app code here
})

self.addEventListener('message', event => {
  if (BrowstorJS.handleServiceWorkerEvents(event)) return
  // place your additional app code here
})

Persistence - How browsers handle it

One thing you must have definitely in mind is that, to date, persistence in browser is wanky. IndexedDB Storage is persistence over time and after browser is closed, yes, but it can be wiped easily. Even when your app is installed as a PWA. By cleanup jobs, by long inactivity, by history cleanup, etc...

For PWA (as of July 2022), unfortunetely, there is still no real 100% bullet-proof way to store data forever until the app is deleted, like you can do in native apps. We all hope that browser devs will fix this as soon as possible.

Here a few links to show how browser engines handle IndexedDB Storage, which BrowstorJS internally uses:

• https://developer.chrome.com/docs/apps/offline_storage/
• https://web.dev/indexeddb-best-practices/

Development in this library 💌

1. Create an issue for features and bugs
2. Checkout master
3. Run npm install && npm ci && npx playwright install --with-deps
4. After changing src/browserjs.ts, run npm run dist
5. Check tests and add new tests to docs/test.html when adding new features