Classic LevelDB Database

Common errors

• Error: IO error: While lock file: /path/to/db/LOCK: Resource temporarily unavailable

  cause Another process or `ClassicLevel` instance is currently holding a lock on the database directory, preventing it from being opened.
  fix Ensure that no other applications or database instances are accessing the same database location. Verify that previous database instances were properly closed. You might need to manually remove the `LOCK` file if a process crashed and left it behind, but do so with caution.

• TypeError: db.put is not a function

  cause This usually indicates an attempt to use `db.put()` with a callback function, which was removed in v2.0.0.
  fix Update your code to use the Promise-based API for all database operations. For `db.put`, simply `await db.put(key, value)` without a callback.

• Error: N-API library not found, trying to rebuild from source...

  cause The package failed to find a prebuilt binary for your platform and is attempting to compile the native LevelDB module, but the `node-gyp` build tools are missing or misconfigured.
  fix Install the necessary `node-gyp` dependencies, including Python, `make`/`build-essential` (Linux), Xcode Command Line Tools (macOS), or Visual C++ Build Tools (Windows). Refer to the `node-gyp` GitHub page for detailed installation instructions for your OS.

Warnings

• breaking Version 3.0.0 introduced a breaking change by upgrading to `abstract-level` v3. This might require updating your code if you are interacting directly with `abstract-level`'s low-level API or specific features that changed.
  Fix: Consult the `UPGRADING.md` guide in the classic-level repository for detailed instructions and potential breaking changes in `abstract-level` v3. Review your database operations and ensure compatibility with the new abstract-level API.
• breaking Version 2.0.0 removed traditional callback-style APIs for database operations, favoring Promises. Additionally, the `LEVEL_NOT_FOUND` error constant was removed.
  Fix: Migrate all database operations to use Promises (e.g., `await db.get(...)`). Handle 'not found' cases by catching the `LevelNotFoundError` (or similar error type, depending on `abstract-level` version) instead of checking for `LEVEL_NOT_FOUND`.
• gotcha For platforms without prebuilt binaries (e.g., specific architectures or older OS versions), `classic-level` will attempt to compile from source. This requires a valid `node-gyp` installation, which can be a common source of installation issues.
  Fix: Ensure you have a complete build environment for `node-gyp`, including Python, `make` (or equivalent), and a C/C++ compiler. Refer to the `node-gyp` installation guide. Alternatively, use `npm install classic-level --build-from-source` to explicitly trigger a source build for debugging purposes.
• gotcha Attempting to open a `ClassicLevel` database at a `location` that is already exclusively locked by another process or another `ClassicLevel` instance will result in a `LEVEL_LOCKED` error.
  Fix: Ensure only one `ClassicLevel` instance attempts to open a database at a given file system location simultaneously. Properly close database instances when they are no longer needed to release the lock. Consider using `db.open()` and `db.close()` within `try...finally` blocks to guarantee cleanup.
• gotcha The `UPGRADING.md` file in the repository contains critical information for migrating between major versions. Neglecting to consult it can lead to unexpected behavior or errors.
  Fix: Always review the `UPGRADING.md` document for your target version when upgrading `classic-level` or any related `Level` packages to understand breaking changes, new features, and migration paths.

Install

• npm install classic-level npm
• yarn add classic-level yarn
• pnpm add classic-level pnpm

Imports

• ClassicLevel
  wrong:

  const ClassicLevel = require('classic-level')

  correct:

  import { ClassicLevel } from 'classic-level'

  While CommonJS `require` still works for basic usage, prefer ESM `import` in modern Node.js environments (>=18).
• ClassicLevel
  wrong:

  import ClassicLevel from 'classic-level'

  correct:

  const { ClassicLevel } = require('classic-level')

  This is the CommonJS `require` syntax as shown in the package's README example for Node.js. It's a named export, not a default export.
• ClassicLevel
  wrong:

  import { ClassicLevel } from 'classic-level/types'

  correct:

  import type { ClassicLevel } from 'classic-level'

  TypeScript types are shipped with the package and can be imported directly from the main package entrypoint.

Quickstart

This example demonstrates how to initialize a `ClassicLevel` database, perform basic `put`, `batch`, `get`, and `iterator` operations, and handle database opening and closing. It uses ESM syntax and includes a cleanup step for repeated execution.

import { ClassicLevel } from 'classic-level';
import { rmSync } from 'node:fs';

const dbPath = './my-classic-level-db';

async function runExample() {
  // Clean up previous run if any
  try { rmSync(dbPath, { recursive: true, force: true }); } catch (e) {}

  // Create a database instance with JSON value encoding
  const db = new ClassicLevel(dbPath, { valueEncoding: 'json' });

  try {
    // Open the database
    await db.open();
    console.log('Database opened.');

    // Add a single entry
    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: 25 } },
      { type: 'put', key: 'user:3', value: { name: 'Charlie', age: 35 } }
    ]);
    console.log('Added user:2 and user:3 via batch');

    // Retrieve a value
    const user1 = await db.get('user:1');
    console.log('Retrieved user:1:', user1);

    // Iterate over entries with keys greater than 'user:1'
    console.log('Iterating users > user:1:');
    for await (const [key, value] of db.iterator({ gt: 'user:1' })) {
      console.log(`  Key: ${key}, Value:`, value);
    }

  } catch (error) {
    console.error('An error occurred:', error);
  } finally {
    // Close the database
    await db.close();
    console.log('Database closed.');
  }
}

runExample();