@wessberg/localdb NPM

LocalDB

An Offline-First local keyed database based on IndexedDB with a Promise API.

Installation

Simply do: npm install @wessberg/localdb.

DISCLAIMER

It is still very early days for this package. The API may change. Use with caution.

Usage

Here's a basic example

const db = new LocalDB({databaseName: "my_database"});
await db.addStore("todos");
await db.add("todos", {text: "write README", done: false});
await db.getAll("todos");
db.observe(change => {
	console.log("db changed:", change);
})

Observing the database for changes

You can hook on to the observe hook to receive change notifications whenever the database changes:

db.observe(change => {
	// Called whenever the database changes!
	switch (change.changeKind) {
		case LocalDBChangeKind.ADD:
			// An item was added to a store.
		case LocalDBChangeKind.DELETE:
            // An item was deleted from a store.
        case LocalDBChangeKind.PUT:
        	// An item was updated.
        case LocalDBChangeKind.REMOVE_STORE:
        	// A store was removed.
		case LocalDBChangeKind.ADD_STORE:
			// A store was added.
		case LocalDBChangeKind.CLEAR_STORE:
			// A store was cleared.
	}
});

Getting items

You can of course query the database.

Getting by ID

const store = "todos";
const id = "12345678abcdefghij";
await db.get(store, id);

Getting all entries in a store

await db.getAll("todos");

Getting the newest/oldest inserted entry in a store

const newest = await db.getNewest("todos");
const oldest = await db.getOldest("todos");

Getting one arbitrary entry from a store

const todo = await db.getOne("todos");

Finding a specific entry in a store

const record = await db.find("todos", (value, key) => value.someProperty === "foo");

An optional 3rd argument to findOne() takes a direction kind, so you can find ascending or descending:

const record = await db.find("todos", (value, key) => value.someProperty === "foo", CursorDirectionKind.DESCENDING);

Filtering/finding multiple items in a store

You can query a store with the filter operation:

const records = await db.filter("todos", (value, key) => value.someProperty === "foo");

This will return an array of all entries that passes the filter condition.

Mapping items in a store.

You can also perform a map operation. For example:

const records = await db.map("todos", (value, key) => value.something * 2);

Getting the size of a store

The size is equal to the amount of records within the store.

const size = await db.size("todos");

Adding records

You can add records to a store or associate a single value with it.

Adding a record to a store

const todo = {
	text: "buy lunch",
	done: false
};

await db.add("todos", todo);

Adding multiple records to a store

const todos = [
	{
		text: "buy lunch",
		done: false
	},
	{
    	text: "have fun",
    	done: false
    }
];
await db.addAll("todos", todos);

Associating a key with a single value

You can also have stores that only contain one record. This is useful for scenarios where you want to persist a single value, like you are used to with localStorage and cookies:

await db.set("lastActive", {
	ip: "123.456.789",
	date: new Date()
});

Updating records

You can update the value associated with a key easily:

const todo = await db.getOne("todos");

// ...later on
// Update it:
todo.done = true;
await db.put("todos", todo.id, todo);

Removing records

You can either remove individual records or clear a store all-together.

Removing a record

const id = "12345678abcdefghijklmnop";
await db.remove("todos", id);

Clearing all records from a store

await db.clear("todos");

Roadmap

Observing the database for changes
Adding/Removing stores and automatic versioning of the database.
Adding, setting, getting and removing entries from stores.
has checks on Stores for checking for the existence of a key-value pair.
Clearing all items in a Store
Basic querying with the findOne operation. Behaves like Array.find.
< O(n) querying for large datasets
Limiting results from multi-record operations
Sorting entries by a given key upon retrieval.

Changelog:

v0.0.20:

Fixed a bug where 'set' would fail if the new item didn't have an id associated with it.

v0.0.19:

Added new set and getOne operations as specified here
Added size method for retrieving the amount of records in a store.

v0.0.18:

Fixed Safari bug where !await expressions wasn't understood.
Clearing a store will inform observers.

v0.0.17:

Fixed a wrong interface signature for 'hasStore'.

v0.0.16:

Large refactoring. Bug fixes.

v0.0.15:

Added further checks.

v0.0.14:

Added checks for running operations before closing databases. Operations that remain open will be awaited before proceeding with performing schema updates.

v0.0.13: