npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

kv-store-db

v1.1.0

Published

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

Downloads

23

Readme

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