Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Level
✓ import { Level } from 'level'
✗ import Level from 'level'
`Level` is a named export, not a default export. For TypeScript, remember to specify generic parameters, e.g., `Level<string, any>`.
Level (CommonJS)
✓ const { Level } = require('level')
✗ const Level = require('level')
Even in CommonJS, `Level` is destructured from the module export.
AbstractLevel (type)
✓ import type { AbstractLevel } from 'abstract-level'
✗ import { AbstractLevel } from 'level'
While `level` implements `AbstractLevel`, the type definition itself is exported by `abstract-level`.
This quickstart demonstrates creating a database, performing `put` and `batch` operations, retrieving data with `get`, iterating over entries, and using `sublevel` for nested data, all with TypeScript type safety. It also includes database opening and closing.
import { Level } from 'level';
// Specify types of keys and values for better type safety.
// The generic type parameters default to Level<string, string>.
// Use { valueEncoding: 'json' } for objects, otherwise 'utf8' is common.
const db = new Level<string, any>('./my-database', { valueEncoding: 'json' });
async function runExample() {
try {
// Ensure the database is open before operations
if (db.status === 'closed') {
await db.open();
}
// Add an entry with key 'user:1' and a JSON object value
await db.put('user:1', { name: 'Alice', age: 30 });
console.log('Added user:1');
// Add multiple entries using batch operation
await db.batch([
{ type: 'put', key: 'user:2', value: { name: 'Bob', age: 24 } },
{ type: 'put', key: 'user:3', value: { name: 'Charlie', age: 35 } }
]);
console.log('Added user:2 and user:3');
// Get value of key 'user:1'
const user1 = await db.get('user:1');
console.log('Value of user:1:', user1);
// Iterate entries with keys greater than 'user:1'
console.log('Users greater than user:1:');
for await (const [key, value] of db.iterator({ gt: 'user:1' })) {
console.log(` Key: ${key}, Value:`, value);
}
// Example of a sublevel
const userEmails = db.sublevel<string, string>('emails', { valueEncoding: 'utf8' });
await userEmails.put('alice', 'alice@example.com');
const aliceEmail = await userEmails.get('alice');
console.log('Alice email:', aliceEmail);
} catch (error) {
console.error('Database operation failed:', error);
} finally {
// Always close the database when done
if (db.status === 'open') {
await db.close();
console.log('Database closed.');
}
}
}
runExample();
Debug
Known issues
breakingVersion 10.0.0 introduced a breaking change by upgrading to `abstract-level` v3. This may require changes to code interacting directly with the `abstract-level` API or relying on specific behaviors of earlier versions.fixConsult the `UPGRADING.md` file in the `level` repository and the `abstract-level` documentation for v3 changes. Update `abstract-level` specific code or options.
affects: >=10.0.0
breakingVersion 9.0.0 included a breaking change by upgrading to `abstract-level` v2. This involved significant API changes in how `abstract-level` databases operate and are instantiated.fixRefer to the `UPGRADING.md` for v9 and the `abstract-level` v2 documentation. Key changes involved database options and some method signatures.
affects: >=9.0.0 <10.0.0
breakingVersion 8.0.0 fundamentally changed `level` to use `classic-level` in Node.js and `browser-level` in browsers. If your application previously relied on specific `leveldown` behaviors or direct `leveldown` imports, this will be a breaking change.fixMigrate any direct `leveldown` interactions to the `abstract-level` interface provided by `level`. Ensure `valueEncoding` and other options are compatible with the new backend implementations. Review `UPGRADING.md` for v8.
affects: >=8.0.0
breakingVersion 7.0.0 included multiple breaking changes, including bumps to `leveldown` and `level-packager`, and a major upgrade of `level-js` from 5.x to 6.x. It also modernized syntax, potentially affecting older Node.js environments.fixReview the `UPGRADING.md` for v7. Ensure your Node.js environment meets the minimum requirement (Node.js 18+ for current versions). Check for API changes in `level-js` if targeting browsers.
affects: >=7.0.0 <8.0.0
gotchaIncorrectly using `require('level')` without destructuring `Level` can lead to runtime errors, as `level` exports `Level` as a named property.fixAlways use `const { Level } = require('level')` or `import { Level } from 'level'`. affects: All versions
gotchaWhen using TypeScript, omitting generic type parameters for `Level` or `sublevel` will default to `Level<string, string>`, leading to type errors if you store or retrieve non-string values (e.g., objects with `valueEncoding: 'json'`).fixExplicitly define key and value types, e.g., `new Level<string, any>('./db', { valueEncoding: 'json' })` or `db.sublevel<string, number>('counts')`. affects: All versions with TypeScript
Errors
Common errors & fixes
TypeError: Level is not a constructor
Attempting to instantiate `level` with `new require('level')()` instead of `new Level()` after destructuring.
fixEnsure you are destructuring the `Level` class from the `level` module: `const { Level } = require('level')` or `import { Level } from 'level'`. Error: Database is not open
Attempting database operations (like `put`, `get`, `iterator`) before the database has been successfully opened.
fixAlways call `await db.open()` before performing any operations. Check `db.status` to ensure it's `open`.
Property 'put' does not exist on type 'Level<string, string>'
In TypeScript, the `Level` instance was inferred or explicitly typed as `Level<string, string>`, but you are attempting to store values that are not strings (e.g., objects with `valueEncoding: 'json'`).
fixExplicitly define the value type when creating the `Level` instance: `new Level<string, any>('./db', { valueEncoding: 'json' })` if storing objects, or `new Level<string, Buffer>('./db', { valueEncoding: 'binary' })` for binary data. Audit
Dependencies
classic-levelrequiredProvides the underlying LevelDB binding for Node.js environments. Automatically used when `level` is run in Node.js.
browser-levelrequiredProvides the underlying IndexedDB/Web SQL binding for browser environments. Automatically used when `level` is run in a browser.
abstract-levelrequiredDefines the abstract interface that `level` implements and exposes, ensuring consistent API across different backend implementations.