browser-level

3.0.0 · active · verified Wed Apr 22

`browser-level` is a JavaScript library providing an `abstract-level` compliant database interface designed specifically for web browsers, utilizing IndexedDB as its backend. The current stable version is 3.0.0. It serves as the spiritual successor to `level-js`, offering a modern, `abstract-level`-compatible API for client-side data persistence. Releases typically align with major upgrades to its underlying `abstract-level` dependency, ensuring compatibility with the broader Level ecosystem. A key differentiator is its seamless integration with browser environments, providing first-class support for both Uint8Array and Buffer (via an optional shim) for keys and values. However, due to IndexedDB's inherent limitations, `browser-level` iterators do not offer strict snapshot guarantees across multiple `next()` or `nextv()` calls, which means concurrent writes might be visible to an ongoing iteration. This necessitates careful handling for applications requiring strict transactional isolation during iteration.

Common errors

```
TypeError: db.getSync is not a function
```
cause Attempting to use the synchronous `getSync` method which is not implemented in `browser-level`.

fix Replace `db.getSync(key)` with `await db.get(key)` for asynchronous retrieval.
```
Error: The `createIfMissing` option is not supported by this database.
```
cause Passing the `createIfMissing` or `errorIfExists` options to the `BrowserLevel` constructor.

fix Remove these options from the `BrowserLevel` constructor. IndexedDB manages database creation internally without these specific flags.
```
DOMException: Failed to execute 'transaction' on 'IDBDatabase': The database connection is closing.
```
cause Attempting database operations after `db.close()` has been called or while the database is in a closing state.

fix Ensure that `db.open()` is called and awaited before any database operations, and that `db.close()` is called only when all operations are complete. Avoid performing operations during database shutdown.

Warnings

breaking Version 3.0.0 introduces a breaking change by upgrading to `abstract-level` version 3. This may require updating your code to align with `abstract-level` v3's API changes.
Fix: Consult the `UPGRADING.md` guides for both `browser-level` and `abstract-level` to understand necessary API adjustments and potential behavior changes.
breaking Version 2.0.0 introduced breaking changes by upgrading to `abstract-level` version 2. This impacted API compatibility with previous versions of `abstract-level`.
Fix: Refer to the `UPGRADING.md` documents for `browser-level` v2 and `abstract-level` v2 to adapt your application code.
gotcha `browser-level` iterators do not provide strict snapshot guarantees across successive calls to `iterator.next()` or `iterator.nextv()` due to IndexedDB limitations. Concurrent writes might be visible during an ongoing iteration.
Fix: If strict snapshotting is critical, use `iterator.all()` immediately after creation to fetch all relevant entries within a single, atomic operation.
gotcha The synchronous `db.getSync()` method is not supported in `browser-level`, unlike some other `abstract-level` implementations.
Fix: Always use the asynchronous `db.get(key)` method and `await` its result.
gotcha The constructor options `createIfMissing` and `errorIfExists` are not supported by `browser-level`.
Fix: Remove `createIfMissing` and `errorIfExists` from your `BrowserLevel` constructor options. IndexedDB inherently handles database creation and existence.

Install

npm install browser-level npm
yarn add browser-level yarn
pnpm add browser-level pnpm

Imports

BrowserLevel
wrong:
```
const { BrowserLevel } = require('browser-level')
```
correct:
```
import { BrowserLevel } from 'browser-level'
```
Preferred import style for TypeScript and modern ES module contexts. CommonJS `require` is also supported but not recommended for new TypeScript projects.
AbstractLevel
```
import type { AbstractLevel } from 'abstract-level'
```
While `BrowserLevel` extends `AbstractLevel`, directly importing types from `abstract-level` is common for type declarations when interacting with the generic Level API.
LevelUp compatibility
wrong:
```
import leveljs from 'level-js'
```
correct:
```
import { BrowserLevel } from 'browser-level'
```
`browser-level` is the successor to `level-js` and is `abstract-level` compliant. Do not attempt to use `level-js` specific APIs or compatibility layers if migrating.

Quickstart

This quickstart demonstrates how to create a `BrowserLevel` database, perform basic `put`, `batch`, `get`, and `iterator` operations, and properly open and close the database in a browser environment using TypeScript.

import { BrowserLevel } from 'browser-level';
import type { BatchOperation } from 'abstract-level';

async function runDbExample() {
  // Create a database called 'example' with JSON encoding
  const db = new BrowserLevel('example', { valueEncoding: 'json' });

  // Ensure the database is opened before operations
  await db.open();

  try {
    // Add an entry with key 'a' and value 1
    await db.put('a', 1);
    console.log('Put key 'a':', await db.get('a'));

    // Add multiple entries using batch
    const batchOperations: BatchOperation<string, number>[] = [
      { type: 'put', key: 'b', value: 2 },
      { type: 'put', key: 'c', value: 3 }
    ];
    await db.batch(batchOperations);
    console.log('Batch operations completed.');

    // Get value of key 'b'
    const valueB = await db.get('b');
    console.log('Value of key 'b':', valueB); // Expected: 2

    // Iterate entries with keys that are greater than 'a'
    console.log('Iterating entries > 'a':');
    for await (const [key, value] of db.iterator({ gt: 'a' })) {
      console.log(`  Key: ${key}, Value: ${value}`);
    } // Expected: b, 2 and c, 3

  } catch (error) {
    console.error('Database operation failed:', error);
  } finally {
    // Always close the database when done
    await db.close();
    console.log('Database closed.');
  }
}

runDbExample();

view raw JSON →