🌜
🌞
immortal-db

immortal-db

v1.1.0

<h1> <div align="center"> <img src="logo.png" width="260px" height="435px" alt="ImmortalDB"> </div>

npm install immortal-db

README

ImmortalDB

ImmortalDB

ImmortalDB is a resilient key-value store for the browser.

ImmortalDB is the best way to store persistent key-value data in the browser. Data saved to ImmortalDB is redundantly stored in Cookies, IndexedDB, and LocalStorage, and relentlessly self heals if any data therein is deleted or corrupted.

For example, clearing cookies is a common user action, even for non-technical users. And browsers unceremoniously delete IndexedDB, LocalStorage, and/or SessionStorage without warning under storage pressure.

ImmortalDB is resilient in the face of such events.

In this way, ImmortalDB is like Evercookie, but

  1. Is actively maintained and well documented.

  2. Provides a simple, modern, Promise-based API.

  3. Strikes an equitable balance between reliability and respect for the user. Data is stored reliably but can also be voluntarily purged if the user designedly clears cookies and application storage.

  4. Doesn't use nefarious exploits nor deprecated third party plugins like Flash, Silverlight, or Java. Only standard, ratified HTML5 APIs are used.

  5. Doesn't vandalize performance or the user experience. For example, Evercookie's CSS History Knocking can beget a deluge of background HTTP requests, and loading Silverlight or Flash can raise unsought permission modals or thrash the user's disk.

How ImmortalDB works.

When you store a key-value pair in ImmortalDB, that key and value are saved redundantly in the browser's cookies, IndexedDB, and LocalStorage data stores.

When a value is retrieved via its key, ImmortalDB

  1. Looks up that key in every data store.
  2. Counts each unique returned value.
  3. Determines the most commonly returned unique value as the 'correct' value.
  4. Returns this correct value.

Then ImmortalDB self-heals: if any data store(s) returned a value different than the determined correct value, or no value at all, the correct value is rewritten to that store. In this way, consensus, reliability, and redundancy is maintained.

API

Set

ImmortalDB's API is simple. To store a value, use set(key, value):

import { ImmortalDB } from 'immortal-db'

await ImmortalDB.set('key', 'value')

key and value must be DOMStrings. ImmortalDB.set(key, value) also always returns value, so it can be chained or embedded, like

const countPlusOne = (await ImmortalDB.set('count', numberOfClowns)) + 1

Get

To retrieve a value, use get(key, default=null):

const value = await ImmortalDB.get('key', default=null)

get() returns the value associated with key, if key exists. If key doesn't exist, default is returned. key must be a DOMString.

Remove

Finally, to remove a key, use remove(key):

ImmortalDB.set('hi', 'bonjour')
console.log(await ImmortalDB.get('hi'))  // Prints 'bonjour'.

await ImmortalDB.remove('hi')

console.log(await ImmortalDB.get('hi'))  // Prints 'null'.

key must be a DOMString.

Data Stores

The data stores that ImmortalDB stores data in can also be configured. For example, to only store data reliably in cookies and LocalStorage:

import { ImmortalStorage, CookieStore, LocalStorageStore } from 'immortal-db'

const stores = [CookieStore, LocalStorageStore]
const db = new ImmortalStorage(stores)

await db.set(key, JSON.stringify({1:1}))

Stores used by ImmortalDB are:

  • CookieStore -> Keys and values are stored in document.cookie.
  • IndexedDbStore -> Keys and values are stored in window.indexedDB.
  • LocalStorageStore -> Keys and values are stored in window.localStorage.

Other, optional stores are:

  • SessionStorageStore -> Keys and values are stored in window.sessionStorage.

New storage implementations can easily be added, too; they need only implement the methods get(key, default), set(key, value), and remove(key).

Installation

Installing ImmortalDB with npm is easy.

$ npm install immortal-db

Or include dist/immortal-db[.min].js and use window.ImmortalDB directly.

<html>
  <head>
    <script src="immortal-db.min.js"></script>
    <script>
      ;(async () => {
        const db = ImmortalDB.ImmortalDB
        await db.set('hi', 'lolsup')
      })()
    </script>
  </head>

  ...
</html>

Development

To test ImmortalDB, run

npm run start

This starts a webpack dev server and opens ImmortalDB's testing website, http://localhost:9234/.

Once tested, run

npm run build

to produce production versions immortal-db.js and immortal-db.min.js in dist/.

Release Notes

1.1.0
By Ansgar Grunseid • Published on August 20, 2020

v1.1.0

  • Fixed: Cross-origin cookies are now stored with SameSite=None, Secure=true, as required. Other cookies remain set with SameSite=Lax and Secure=false -- the same defaults as if SameSite and Secure remained unset. Huge thank you to @zproxyz.

  • Fixed: Only add IndexedDbStore and LocalStorageStore if accessible.

  • Added: Cross-origin and same-origin tests.

General

Typescript Types
Built-in
Tree-shakeable
Yes

Popularity

GitHub Stargazers
3,002
Community Interest
3,016
Number of Forks
66

Maintenance

Commits
11/2110/2201
Last Commit
Jun 19, 2021
Open Issues
11
Closed Issues
16
Open Pull Requests
22
Closed Pull Requests
16

Versions

Versions Released
11/2110/2201
Latest Version Released
Aug 20, 2020
Current Tags
latest1.1.0

Contributors

gruns
gruns
Commits: 116
fairfieldt
fairfieldt
Commits: 4
mikheevm
mikheevm
Commits: 3
jcar787
jcar787
Commits: 3
joneschrisg
joneschrisg
Commits: 1
pruthvikar
pruthvikar
Commits: 1
kmd09
kmd09
Commits: 1
coolreader18
coolreader18
Commits: 1
zproxyz
zproxyz
Commits: 1
masaha03
masaha03
Commits: 1