SQLite-backed Abstract LevelDB

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ...sqlite-level/build/index.js from ... not supported.

  cause Attempting to `require()` an ESM-only package from a CommonJS module.
  fix Change your importing code from `const { Level } = require('sqlite-level');` to `import { Level } from 'sqlite-level';`. Ensure your `package.json` for the consuming project has `"type": "module"` or dynamically import with `const { Level } = await import('sqlite-level');`.

• Error: SQLITE_BUSY: database is locked

  cause Multiple concurrent write operations or an active read transaction holding a lock prevents other operations from proceeding.
  fix This often occurs in concurrent environments. Implement basic retry logic with a short delay for write operations. Ensure database connections are managed properly and closed when not in use. Consider using WAL mode if not already active.

• Error: Database is closed

  cause An attempt was made to perform an operation (put, get, iterate) on a `Level` instance that has already been `close()`d or failed to `open()`.
  fix Ensure all database operations are completed before `db.close()` is called. Use `db.isOpen()` to check the database state if you suspect it might be closed prematurely. Wrap operations in `try...finally` to ensure `db.close()` is called only when needed.

Warnings

• gotcha Installation issues can occur due to the native bindings of `better-sqlite3`, which `sqlite-level` relies on. Users may encounter compilation errors on certain platforms or specific Node.js versions.
  Fix: Ensure you have C++ build tools installed (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, or Visual Studio Build Tools on Windows). Consider using a Docker environment for consistent builds.
• gotcha As `sqlite-level` uses SQLite internally, it inherits SQLite's concurrency model. While WAL (Write-Ahead Logging) can improve read concurrency, writes are still serialized. Aggressive concurrent writes can lead to `SQLITE_BUSY` errors if not handled properly.
  Fix: Implement retry logic for write operations, or design your application to minimize concurrent writes to the same database. Consider moving to a more robust database solution if high-volume, concurrent writes are a core requirement.
• breaking `sqlite-level` is distributed as an ECMAScript Module (ESM). Direct `require()` statements in CommonJS environments will fail with a runtime error, indicating it's an ESM module.
  Fix: For Node.js projects, ensure your `package.json` specifies `"type": "module"` or use dynamic `import()` for `sqlite-level`. If using TypeScript, configure `"module": "NodeNext"` or `"ESNext"` in `tsconfig.json`.
• gotcha Forgetting to `await db.close()` can lead to data corruption or locks on the SQLite database file, especially if the application exits abruptly. This is critical for persistent, file-based databases.
  Fix: Always ensure `db.close()` is called and awaited in a `finally` block or on application shutdown hooks. For long-running processes, consider implementing graceful shutdown procedures.

Install

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

Imports

• Level
  wrong:

  const { Level } = require('sqlite-level');

  correct:

  import { Level } from 'sqlite-level';

  sqlite-level is an ESM-first package. Use `import` syntax. CommonJS `require` will result in a runtime error or require an import shim.
• LevelOptions
  wrong:

  import { LevelOptions } from 'sqlite-level';

  correct:

  import type { LevelOptions } from 'sqlite-level';

  When importing types in TypeScript, explicitly use `import type` for clarity and to prevent bundling issues in environments that do not support type stripping.

Quickstart

Demonstrates opening a SQLite-backed LevelDB, performing basic put, get, delete operations, and iterating over stored keys and values, ensuring proper database closure.

import { Level } from 'sqlite-level';
import { join } from 'path';
import { tmpdir } from 'os';

async function runExample() {
  const dbPath = join(tmpdir(), 'my_sqlite_level_db.sqlite');
  const db = new Level(dbPath);

  try {
    console.log(`Opening database at: ${dbPath}`);
    await db.open();
    console.log('Database opened.');

    await db.put('name', 'Alice');
    await db.put('age', '30');

    const name = await db.get('name');
    const age = await db.get('age');
    console.log(`Name: ${name}, Age: ${age}`);

    // Iterate over entries
    console.log('Iterating over entries:');
    for await (const [key, value] of db.iterator({ gte: 'a', lt: 'z' })) {
      console.log(`  Key: ${key}, Value: ${value}`);
    }

    await db.del('age');
    const newAge = await db.get('age');
    console.log(`Age after deletion: ${newAge}`); // Should be undefined
  } catch (error) {
    console.error('An error occurred:', error);
  } finally {
    if (!db.isClosed()) {
      await db.close();
      console.log('Database closed.');
    }
  }
}

runExample();