@adiwajshing/keyed-db

What is @adiwajshing/keyed-db?

@adiwajshing/keyed-db is a lightweight, in-memory database that allows you to store and query data efficiently using keys. It is designed to be simple and fast, making it suitable for applications that require quick access to data without the overhead of a full-fledged database system.

What are @adiwajshing/keyed-db's main functionalities?

Creating a Database

This feature allows you to create a new instance of KeyedDB. The first argument is a comparison function to determine if two items are equal, and the second argument is a function to extract the key from an item.

const KeyedDB = require('@adiwajshing/keyed-db');
const db = new KeyedDB((a, b) => a.id === b.id, item => item.id);

Inserting Data

This feature allows you to insert data into the database. Each item must have a unique key as defined by the key extraction function.

db.insert({ id: 1, name: 'Alice' });
db.insert({ id: 2, name: 'Bob' });

Querying Data

This feature allows you to query data from the database using the key. It returns the item associated with the given key.

const item = db.get(1); // { id: 1, name: 'Alice' }

Updating Data

This feature allows you to update an existing item in the database. The item is identified by its key.

db.update({ id: 1, name: 'Alice Updated' });

Deleting Data

This feature allows you to delete an item from the database using its key.

db.delete(1);

Other packages similar to @adiwajshing/keyed-db

nedb

NeDB is a lightweight JavaScript database that provides a simple way to store and query data. It supports indexing and querying similar to MongoDB. Compared to @adiwajshing/keyed-db, NeDB offers more features like persistence and advanced querying capabilities.

lowdb

Lowdb is a small local JSON database for Node.js, which is perfect for small projects, CLI tools, and scripts. It provides a simple API for reading and writing JSON data. Unlike @adiwajshing/keyed-db, lowdb stores data in a JSON file, making it suitable for applications that require data persistence.

lokijs

LokiJS is a fast, in-memory database for Node.js and browsers. It offers a rich set of features including indexing, querying, and data manipulation. Compared to @adiwajshing/keyed-db, LokiJS provides more advanced features and is suitable for more complex use cases.

README

Keyed DB

A light-weight node library to manage a sorted & indexed collection with pagination support. All done using Binary Search. Based off my swift code for Queenfisher

Install

npm i github:adiwajshing/keyed-db

Running Tests

npm test

Functions

db = new KeyedDB<T> (t => t.uniqueNumberKeyProperty, t => t.optionalUniqueIDProperty)
// compare with a custom function
db = new KeyedDB<T> ({  
    key: t => t.someProperty,
    compare: (t1, t2) => someComputation(t1, t2) // return -1 if t1 < t2, 0 if t1=t2 & 1 if t1 > t2
}, t => t.optionalUniqueIDProperty)

db.insert (value) // insert value in DB
db.upsert (value) // upserts value
db.insertIfAbsent (value) // only inserts if not already present in DB
db.delete (value) // delete value
db.deleteById (value.optionalUniqueIDProperty) // delete value by referencing the ID
// update the key of a value, 
// will automatically place object after key change
db.updateKey (value, value => value.uniqueKeyProperty = newValue) 
db.paginated (someCursor, 20) // get X results after the given cursor (null for the first X results)

Usage

import KeyedDB from '@adiwajshing/keyed-db'

// Let's use the db to sort & maintain a list of chats
// Chats must be accessed quickly via the chatID (the person you're chatting with)
// Chats must be sorted by recency
type Chat = {
    timestamp: Date
    chatID: string
}

// first argument -- sorting property, second argument -- ID property
const db = new KeyedDB<Chat>(value => value.timestamp.getTime()*-1, value => value.chatID)

for (let i = 0; i < 1000;i++) {
    // insert data
    db.insert (
        {
            timestamp: new Date( new Date().getTime() - Math.random()*10000 ), 
            chatID: `person ${i}`
        }
    )
}
console.log (db.all()) // return internal sorted array
console.log (db.paginated(null, 20)) // return first 20 chats
console.log (db.paginated(null, 20, null, 'before')) // return last 20 chats
console.log (db.paginated(null, 20, chat => chat.chatID.includes('something'))) // return first 20 chats where the chatID contains 'something'

const someDate = new Date().getTime()
const cursorPaginated = db.paginated(someDate, 20)
console.log (cursorPaginated) // return 20 chats after the specified date

db.delete (cursorPaginated[0]) // delete paginated chats 

// update chat timestamp
db.updateKey(cursorPaginated[1], value => value.timestamp = new Date().getTime()) 

Time Complexity

Operation	Time Complexity
db.insert()	O(logN)
db.delete()	O(logN)
db.get()	O(1)
db.updateKey()	O(logN)