crxdelv / indexed

Minimally-touched indexed database library structured after WebStorage.

Indexed

Minimalistic API for IndexedDB that acts like WebStorage.

const db = await Indexed.open("testdb");

await db.set("name", "John Doe");
await db.set("email", "[e-mail]");

const name = await db.get("name");
const email = await db.get("email");
console.log(name, email);

db.close();

Installation

For server-side, install it with NPM:

npm install @creuserr/indexed

Then import it. Using require for example:

const Indexed = require("@creuserr/indexed");

For client-side, import it using CDN:

<script src="https://cdn.jsdelivr.net/gh/creuserr/indexed@main/dist/indexed.min.js"></script>

Documentation

Indexed class

open(name, version=1) static async

Returns a promise. This method attempts to open a database. If successful, an Indexed.Database instance will be returned.

const db = await Indexed.open("testdb");

delete(name) static async

Returns a promise. This method attempts to delete a database.

await Indexed.delete("testdb");

all() static async

Returns a promise. This method returns all the existing database. If successful, a list of objects will be returned. The objects would contain the following properties: name, version.

await Indexed.all();
// [{ name: "testdb", version: 1 }]

check(name, version=1) static async

Returns a promise. This method attempts to check if the database follows *Indexed scheme. If successful, a boolean will be returned.

Note

This method attempts to open the database in order to check its scheme.

await Indexed.check("testdb");
// true

Indexed.Database static class

set(key, value) async

Returns a promise. This method attempts to update or create a data inside the database.

await db.set("name", "John Doe");

get(key, default_value) async

Returns a promise. This method attempts to retrieve a data inside the database. default_value will be returned if the key doesn't exist.

await db.get("name");
// "John Doe"

await db.get("bio", "No bio found");
// "No bio found"

all() async

Returns a promise. This method attempts to retrieve all the data inside the database. If successful, an object will be returned.

await db.all();
// { name: "John Doe", email: "[e-mail]" }

delete(key) async

Returns a promise. This method attempts to delete a data from the database.

await db.delete("name");

close() async

This method closes the database.

Important

If you are deleting a database, make sure to close its connection first.

db.close();
// This method doesn't return a promise
// so it's unnecessary to use await

Scheme

Database
└── Object Stores:
    └── "main"
        └── Indexes:
            ├── "key" (keyPath) (unique)
            └── "value"

Fallbacks v1.1.0

Fallbacks are objects containing functions that will be triggered when the enviromment does not support indexed database.

By default, you can statically use Indexed methods. However, if you want to use fallbacks, you need to construct a new instance.

const index = new Indexed();

Now, define fallback. This should be an object. Here is a template:

index.fallback = {
  async all() {
    // ...
    return [{
      name: String,
      version: Number
    }, ...];
  },
  async check(db) {
    // ...
    return Boolean
  },
  async delete(db, version) {
    // ...
  },
  open: {
    async set(db, key, value) {
      // ...
    },
    async get(db, key, default_value) {
      // ...
    },
    async delete(db, key) {
      // ...
    },
    async all(db) {
      // ...
      return Object
    }
  }
}

Tip

For consistent use, you should make the fallback functions as asynchronous. Since Indexed methods are asynchronous, fallbacks should also be asynchronous to prevent errors when using then and catch methods.

Fallback for web storages

Indexed has a static function where you can generate a fallback object for web storages (localStorage and sessionStorage).

const fallback = Indexed.fallbackForWebStorage(window.localStorage);
const index = new Indexed();
index.fallback = fallback;
// ...

Fallback for objects

Indexed has a static function where you can generate a fallback object for objects.

const database = {};
const getter = key => {
  return database[key];
}
const setter = (key, value) => {
  database[key] = value;
}

const fallback = Indexed.fallbackForObject(getter, setter);
const index = new Indexed();
index.fallback = fallback;
// ...

It follows this structure:

{
  database_name: {
    key: value,
    key_2: value_2
    // ...
  },
  database_name_2: {
    key: value,
    key_2: value_2
    // ...
  }
}