level

What is level?

The 'level' npm package is a fast and simple key-value storage library for Node.js. It provides a persistent storage solution that is easy to use and integrates well with other Node.js modules. It is built on top of LevelDB, a fast key-value storage library developed by Google.

What are level's main functionalities?

Basic CRUD Operations

This feature allows you to perform basic Create, Read, Update, and Delete (CRUD) operations on the database. The code sample demonstrates how to put a key-value pair, retrieve a value by key, and delete a key-value pair.

const level = require('level');
const db = level('./mydb');

// Put a key-value pair
await db.put('name', 'Alice');

// Get a value by key
const value = await db.get('name');
console.log(value); // 'Alice'

// Delete a key-value pair
await db.del('name');

Batch Operations

Batch operations allow you to perform multiple operations in a single atomic action. The code sample demonstrates how to use the batch method to put and delete multiple key-value pairs in one go.

const level = require('level');
const db = level('./mydb');

// Perform batch operations
await db.batch()
  .put('name', 'Alice')
  .put('age', 30)
  .del('name')
  .write();

Streams

Streams provide a way to read and write data in a continuous flow. The code sample demonstrates how to create a read stream to iterate over all key-value pairs in the database.

const level = require('level');
const db = level('./mydb');

// Create a read stream
const stream = db.createReadStream();

stream.on('data', ({ key, value }) => {
  console.log(`${key} = ${value}`);
});

Other packages similar to level

nedb

NeDB is a lightweight, in-memory database that provides a MongoDB-like API. It is suitable for small projects and can be used as an embedded database. Unlike Level, NeDB stores data in memory by default, which can be less performant for large datasets.

sqlite3

SQLite3 is a self-contained, serverless, and zero-configuration SQL database engine. It is more feature-rich compared to Level, offering SQL query capabilities. However, it may be overkill for simple key-value storage needs.

pouchdb

PouchDB is an open-source JavaScript database inspired by CouchDB. It is designed to run in the browser and Node.js, providing a NoSQL database solution. PouchDB offers more advanced features like synchronization with CouchDB, which Level does not provide.

README

level

Universal abstract-level database for Node.js and browsers. This is a convenience package that exports classic-level in Node.js and browser-level in browsers, making it an ideal entry point to start creating lexicographically sorted key-value databases.

:pushpin: Which module should I use? What is abstract-level? Head over to the FAQ.

Usage

If you are upgrading: please see UPGRADING.md.

const { Level } = require('level')

// Create a database
const db = new Level('example', { valueEncoding: 'json' })

// Add an entry with key 'a' and value 1
await db.put('a', 1)

// Add multiple entries
await db.batch([{ type: 'put', key: 'b', value: 2 }])

// Get value of key 'a': 1
const value = await db.get('a')

// Iterate entries with keys that are greater than 'a'
for await (const [key, value] of db.iterator({ gt: 'a' })) {
  console.log(value) // 2
}

TypeScript type declarations are included and cover the methods that are common between classic-level and browser-level. Usage from TypeScript requires generic type parameters.

TypeScript example

// Specify types of keys and values (any, in the case of json).
// The generic type parameters default to Level<string, string>.
const db = new Level<string, any>('./db', { valueEncoding: 'json' })

// All relevant methods then use those types
await db.put('a', { x: 123 })

// Specify different types when overriding encoding per operation
await db.get<string, string>('a', { valueEncoding: 'utf8' })

// Though in some cases TypeScript can infer them
await db.get('a', { valueEncoding: db.valueEncoding('utf8') })

// It works the same for sublevels
const abc = db.sublevel('abc')
const xyz = db.sublevel<string, any>('xyz', { valueEncoding: 'json' })

Install

With npm do:

npm install level

For use in browsers, this package is best used with browserify, webpack, rollup or similar bundlers. For a quick start, visit browserify-starter or webpack-starter.

Supported Platforms

At the time of writing, level works in Node.js 18+ and Electron 30+ on Linux, Mac OS and Windows, including any future Node.js and Electron release thanks to Node-API, including ARM platforms like Raspberry Pi and Android, as well as in Chromium, Firefox and Safari. For details, see Supported Platforms of classic-level and Browser Support of browser-level.

Binary keys and values are supported across the board.

API

The API of level follows that of abstract-level. For additional options and methods specific to classic-level or browser-level, please see their respective READMEs. The documentation below only covers the common constructor.

db = new Level(location[, options])

Create a new database or open an existing database. The location argument must be a directory path (relative or absolute) where LevelDB will store its files, or in browsers, the name of the IDBDatabase to be opened.

Contributing

Level/level is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the Contribution Guide for more details.

Donate

Support us with a monthly donation on Open Collective and help us continue our work.

License

MIT

Changelog

[9.0.0] - 2024-12-01

If you are upgrading: please see UPGRADING.md.

Changed

• Breaking: upgrade to abstract-level 2 (#247) (7d8c962) (Vincent Weevers)