kv-store-db

A fast, lightweight, and easy-to-use in-memory and in-process key-value datastore for node.js

Installation

To install it, use

npm install kv-store-db

Usage

To use kv-store-db:

Import kv-store-db library

const { createDatabase } = require('kv-store-db'); // ES/JS
// or
import { createDatabase } from 'kv-store-db'; // Typescript

Create an instance

const db = createDatabase({
  name: "...", // db file name
  path: "...", // db file path
  onChange: (data) => {....} // data change handler
});

Example

import { createDatabase } from './main';
import { join } from 'path';

interface IUser {
  id: string | number;
  name: string;
  age: number;
  peers?: string[];
}

(async () => {
  const db = await createDatabase({
    name: "testDb",
    path: join(__dirname, '../data'),
    onChange: (data) => console.log(JSON.stringify(data))
  });

  // set a new collection with one entry
  console.log('==============================================================');
  console.log('* Adding a new collection with one entry');
  console.log('--------------------------------------------------------------');
  await db.set('users', {
    id: '1',
    name: 'John',
    age: 32
  } as IUser);
  console.log('users -->', await db.get('users'));                // users --> { '1': { id: '1', name: 'John', age: 32 } }
  console.log('users/1 -->', await db.get('users/1'));            // users/1 --> { id: '1', name: 'John', age: 32 }
  console.log('users/1/name -->', await db.get('users/1/name'));  // users/1/name --> John

  // set a new entry in an existing collection
  console.log('==============================================================');
  console.log('* Adding a new entry in an existing collection');
  console.log('--------------------------------------------------------------');
  await db.set('users', {
    id: '2',
    name: 'Jane',
    age: 31
  } as IUser);
  console.log('users -->', await db.get('users'));                // users --> { '1': { id: '1', name: 'John', age: 32 }, '2': { id: '2', name: 'Jane', age: 31 } }
  console.log('users/2 -->', await db.get('users/2'));            // users/2 --> { id: '2', name: 'Jane', age: 31 }
  console.log('users/2/name -->', await db.get('users/2/name'));  // users/2/name --> Jane  

  // update an entry in a collection
  console.log('==============================================================');
  console.log('* Updating an entry in a collection, (without merge)');
  console.log('--------------------------------------------------------------');
  await db.set('users/1', {
    age: 35
  } as IUser);
  console.log('users -->', await db.get('users'));                // users --> { '1': { age: 35 }, '2': { id: '2', name: 'Jane', age: 31 } }
  console.log('users/1 -->', await db.get('users/1'));            // users/1 --> { age: 35 }
  console.log('users/1/name -->', await db.get('users/1/name'));  // users/1/name --> undefined

  // update an entry in a collection with merge
  console.log('==============================================================');
  console.log('* Updating an entry in a collection (with merge)');
  console.log('--------------------------------------------------------------');
  await db.set('users/1', {
    id: '1',
    name: 'John',
  } as IUser, true);
  console.log('users -->', await db.get('users'));                // users --> { '1': { age: 35, id: '1', name: 'John' }, '2': { id: '2', name: 'Jane', age: 31 } }
  console.log('users/1 -->', await db.get('users/1'));            // users/1 --> { age: 35, id: '1', name: 'John' }
  console.log('users/1/name -->', await db.get('users/1/name'));  // users/1/name --> John

  // update a field of an entry in a collection
  console.log('==============================================================');
  console.log('* Updating a field of an entry in a collection');
  console.log('--------------------------------------------------------------');
  await db.set('users/2/age', 33);
  console.log('users -->', await db.get('users'));              // users --> { '1': { age: 35, id: '1', name: 'John' }, '2': { id: '2', name: 'Jane', age: 33 } }
  console.log('users/2/age -->', await db.get('users/2/age'));  // users/2/age --> 33

  // add a new field to an entry in a collection
  console.log('==============================================================');
  console.log('* Adding a new field to an entry in a collection');
  console.log('--------------------------------------------------------------');
  await db.set('users/2/peers', ['1']);
  console.log('users -->', await db.get('users'));                  // users --> { '1': { age: 35, id: '1', name: 'John' }, '2': { id: '2', name: 'Jane', age: 33, peers: [ '1' ] } }
  console.log('users/2/peers -->', await db.get('users/2/peers'));  // users/2/peers --> [ '1' ]

  // delete a field of an entry in a collection
  console.log('==============================================================');
  console.log('* Deleting a field of an entry in a collection');
  console.log('--------------------------------------------------------------');
  await db.delete('users/2/peers');
  console.log('users -->', await db.get('users'));                  // users --> { '1': { age: 35, id: '1', name: 'John' }, '2': { id: '2', name: 'Jane', age: 33 } }
  console.log('users/2/peers -->', await db.get('users/2/peers'));  // users/2/peers --> undefined

  console.log('==============================================================');
})();

API

---

• set(key: string, value: any, merge?: boolean): Promise<any>

Sets a (new or existing) value by key in the DB store.

db.set(key: string, value: any, merge?: boolean): Promise<any>;

The key is a string in a format like collectionName/:recId/:fieldName, where the collectionName is the identifier of a collection in the store, while the recId identifies a specific record (entry) in the data collection, and the fieldName identifies a specific field of the specific record (entry) in the data collection.

Both recId and fieldName are optional, and if not provided, the key is assumed to indicate the name of the collection. In this case, the value is expected to be an object that contains the new data entries for the collection (a TDataCollectionEntry compatible object).

However, if the key contains both collectionName and recId components, it is assumed to refer to a particular record (entry) in the collection. In this case the value must be a data collection entry (a object compatible with a Map of TDataRecord items).

If the key contains all three components, it is assumed to refer to a specific data field of the given record (entry) in the data collection.

The merge flag is optional as well, and it serves when setting entries (records) in a collection, (e.g. using the collectionName/:recId key variant), to indicate whether to merge the new fields with the existing fields of the identified record in the collection, or to replace all its existing fields with the new ones. By default merge is false, which means that the new data fields passed as value replace the existing ones.

---

• get(key: string): Promise<any>

Gets (retrieves) the data of the collection, record or the field identified by the given key in the store.

db.get(key: string): Promise<any>;

The key is a string in this collectionName/:recId/:fieldName format, where the collectionName is required and is the collection identifier.

The recId, which is optional, is the identifier of the record (entry) in the collection, and the fieldName, optional as well, is the identifier of a particular field of the given record (entry) in the collection.

If the given key only contains the collectionName it returns all the data from the collection identified. If the given key only contains the collectionName and the recId it returns the data of the identified record (entry) in the collection.

If the given key only all three components, the collectionName, the recId and fieldNameit returns the value of the named field in the identified record (entry) in the collection.

If the key does not identify any collection, record or field in the store, it returns undefined.

---

• has(key: string): Promise<boolean>

Returns true if the DB store has a collection, a collection with a record or a collection with a record with a field that is identified by the given key.

db.has(key: string): Promise<boolean>;

The key is a string in this collectionName/:recId/:fieldName format, where the collectionName is required and is the collection identifier.

The recId, which is optional, is the identifier of the record (entry) in the collection, and the fieldName, optional as well, is the identifier of a particular field of the given record (entry) in the collection.

If the key does not identify any collection, record or field in the store, it returns false.

---

• delete(key: string): Promise<boolean>

Deletes from the DB store the collection, the record or the data field specified by the key, and returns true to indicate that the operation is successful.

db.delete(key: string): Promise<boolean>;

The key is a string in this collectionName/:recId/:fieldName format, where the collectionName is required and is the collection identifier.

The recId, which is optional, is the identifier of the record (entry) in the collection, and the fieldName, optional as well, is the identifier of a particular field of the given record (entry) in the collection.

If the key does not identify any collection, record or field in the store, it returns false, indicating that nothing was deleted.

---

• clear(key: string): Promise<any>

Clears the collection or collection record identified by key in the store.

db.clear(key: string): Promise<any>;

The key is a string in a format like collectionName/:recId, where the collectionName is the identifier of a collection in the store, while the recId identifies a specific record (entry) in the data collection.

---

• entries(key: string): Promise<[string, any][]>

Returns an iterator with all entries of the collection or record identified by the key in the store.

db.entries(key: string): Promise<[string, any][]>;

The key is a string in a format like collectionName/:recId, where the collectionName is the identifier of a collection in the store, while the recId identifies a specific record (entry) in the data collection.

---

• collection(name: string): Promise<TDataCollectionEntry | undefined>

Returns the data collection object with the given name, or undefined if the collection does not exist in the store.

db.collection(name: string): Promise<TDataCollectionEntry | undefined>;

---

• collections

A read-only property that returns an array containing the names of all data collections in the store.

db.collections; // string[]

---

• dataFile

A read-only property that returns the name and path of the data file.

dataFile; // string

Version

1.1.0