diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 6f12a34..f66fb3f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -5,7 +5,8 @@ updates: schedule: interval: monthly ignore: - - dependency-name: dependency-check + - dependency-name: standard + - dependency-name: hallmark - package-ecosystem: github-actions directory: / schedule: diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 813987c..ae79a42 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -5,7 +5,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - node: [10, 12, 14, 16] + node: [12, 14, 16] name: Node ${{ matrix.node }} steps: - name: Checkout @@ -16,8 +16,14 @@ jobs: node-version: ${{ matrix.node }} - name: Install run: npm install + - name: Install Playwright + if: matrix.node == 16 + run: npx playwright install-deps - name: Test run: npm test + - name: Test browsers + if: matrix.node == 16 + run: npm run test-browsers-local - name: Coverage run: npm run coverage - name: Codecov diff --git a/.gitignore b/.gitignore index a446924..787b422 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ node_modules yarn.lock .nyc_output/ coverage +db/ diff --git a/README.md b/README.md index 5fae78f..5cb37a5 100644 --- a/README.md +++ b/README.md @@ -1,449 +1,603 @@ # level -> Fast & simple storage. A Node.js-style `LevelDB` wrapper for Node.js, Electron and browsers. +**Universal [`abstract-level`](https://github.com/Level/abstract-level) database for Node.js and browsers.** This is a convenience package that exports [`classic-level`](https://github.com/Level/classic-level) in Node.js and [`browser-level`](https://github.com/Level/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](https://github.com/Level/community#faq). [![level badge][level-badge]](https://github.com/Level/awesome) [![npm](https://img.shields.io/npm/v/level.svg)](https://www.npmjs.com/package/level) [![Node version](https://img.shields.io/node/v/level.svg)](https://www.npmjs.com/package/level) [![Test](https://img.shields.io/github/workflow/status/Level/level/Test?label=test)](https://github.com/Level/level/actions/workflows/test.yml) -[![Coverage](https://img.shields.io/codecov/c/github/Level/level?label=&logo=codecov&logoColor=fff)](https://codecov.io/gh/Level/level) -[![Standard](https://img.shields.io/badge/standard-informational?logo=javascript&logoColor=fff)](https://standardjs.com) +[![Coverage](https://img.shields.io/codecov/c/github/Level/level?label=\&logo=codecov\&logoColor=fff)](https://codecov.io/gh/Level/level) +[![Standard](https://img.shields.io/badge/standard-informational?logo=javascript\&logoColor=fff)](https://standardjs.com) [![Common Changelog](https://common-changelog.org/badge.svg)](https://common-changelog.org) -[![Donate](https://img.shields.io/badge/donate-orange?logo=open-collective&logoColor=fff)](https://opencollective.com/level) +[![Donate](https://img.shields.io/badge/donate-orange?logo=open-collective\&logoColor=fff)](https://opencollective.com/level) ## Table of Contents
Click to expand -- [Introduction](#introduction) - [Usage](#usage) +- [Install](#install) - [Supported Platforms](#supported-platforms) - [API](#api) - - [`db = level(location[, options[, callback]])`](#db--levellocation-options-callback) - - [`db.supports`](#dbsupports) + - [`db = new Level(location[, options])`](#db--new-levellocation-options) + - [`db.status`](#dbstatus) - [`db.open([callback])`](#dbopencallback) - [`db.close([callback])`](#dbclosecallback) - - [`db.put(key, value[, options][, callback])`](#dbputkey-value-options-callback) + - [`db.supports`](#dbsupports) - [`db.get(key[, options][, callback])`](#dbgetkey-options-callback) - [`db.getMany(keys[, options][, callback])`](#dbgetmanykeys-options-callback) + - [`db.put(key, value[, options][, callback])`](#dbputkey-value-options-callback) - [`db.del(key[, options][, callback])`](#dbdelkey-options-callback) - - [`db.batch(array[, options][, callback])` _(array form)_](#dbbatcharray-options-callback-array-form) - - [`db.batch()` _(chained form)_](#dbbatch-chained-form) - - [`db.status`](#dbstatus) - - [`db.isOperational()`](#dbisoperational) - - [`db.createReadStream([options])`](#dbcreatereadstreamoptions) - - [`db.createKeyStream([options])`](#dbcreatekeystreamoptions) - - [`db.createValueStream([options])`](#dbcreatevaluestreamoptions) - - [`db.iterator([options])`](#dbiteratoroptions) + - [`db.batch(operations[, options][, callback])`](#dbbatchoperations-options-callback) + - [`chainedBatch = db.batch()`](#chainedbatch--dbbatch) + - [`iterator = db.iterator([options])`](#iterator--dbiteratoroptions) + - [`keyIterator = db.keys([options])`](#keyiterator--dbkeysoptions) + - [`valueIterator = db.values([options])`](#valueiterator--dbvaluesoptions) - [`db.clear([options][, callback])`](#dbclearoptions-callback) -- [Promise Support](#promise-support) -- [Events](#events) + - [`sublevel = db.sublevel(name[, options])`](#sublevel--dbsublevelname-options) + - [`chainedBatch`](#chainedbatch) + - [`chainedBatch.put(key, value[, options])`](#chainedbatchputkey-value-options) + - [`chainedBatch.del(key[, options])`](#chainedbatchdelkey-options) + - [`chainedBatch.clear()`](#chainedbatchclear) + - [`chainedBatch.write([options][, callback])`](#chainedbatchwriteoptions-callback) + - [`chainedBatch.close([callback])`](#chainedbatchclosecallback) + - [`chainedBatch.length`](#chainedbatchlength) + - [`chainedBatch.db`](#chainedbatchdb) + - [`iterator`](#iterator) + - [`for await...of iterator`](#for-awaitof-iterator) + - [`iterator.next([callback])`](#iteratornextcallback) + - [`iterator.nextv(size[, options][, callback])`](#iteratornextvsize-options-callback) + - [`iterator.all([options][, callback])`](#iteratoralloptions-callback) + - [`iterator.seek(target[, options])`](#iteratorseektarget-options) + - [`iterator.close([callback])`](#iteratorclosecallback) + - [`iterator.db`](#iteratordb) + - [`iterator.count`](#iteratorcount) + - [`iterator.limit`](#iteratorlimit) + - [`keyIterator`](#keyiterator) + - [`valueIterator`](#valueiterator) + - [`sublevel`](#sublevel) + - [`sublevel.prefix`](#sublevelprefix) + - [`sublevel.db`](#subleveldb) - [Contributing](#contributing) - [Donate](#donate) - [License](#license)
-## Introduction +## Usage -This is a convenience package that: +_If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md)._ -- exports a function that returns a [`levelup`](https://github.com/Level/levelup) instance when invoked -- bundles the current release of [`leveldown`][leveldown] and [`level-js`][level-js] -- leverages encodings using [`encoding-down`][encoding-down]. +```js +const { Level } = require('level') -Use this package to avoid having to explicitly install `leveldown` or `level-js` when you just want to use `levelup`. It uses `leveldown` in Node.js or Electron and `level-js` in browsers (when bundled by [`browserify`](https://github.com/browserify/browserify), [`webpack`](https://webpack.js.org/), [`rollup`](https://rollupjs.org/) or similar). For a quick start, visit [`browserify-starter`](https://github.com/Level/browserify-starter) or [`webpack-starter`](https://github.com/Level/webpack-starter). Note: `rollup` currently fails to properly resolve the [`browser`](package.json) field. +// Create a database +const db = new Level('example', { valueEncoding: 'json' }) -## Usage +// Add an entry with key 'a' and value 1 +await db.put('a', 1) -**If you are upgrading:** please see [`UPGRADING.md`](UPGRADING.md). +// Add multiple entries +await db.batch([{ type: 'put', key: 'b', value: 2 }]) -```js -const level = require('level') +// Get value of key 'a': 1 +const value = await db.get('a') -// 1) Create our database, supply location and options. -// This will create or open the underlying store. -const db = level('my-db') +// Iterate entries with keys that are greater than 'a' +for await (const [key, value] of db.iterator({ gt: 'a' })) { + console.log(value) // 2 +} +``` -// 2) Put a key & value -db.put('name', 'Level', function (err) { - if (err) return console.log('Ooops!', err) // some kind of I/O error +All asynchronous methods also support callbacks. - // 3) Fetch by key - db.get('name', function (err, value) { - if (err) return console.log('Ooops!', err) // likely the key was not found +
Callback example + +```js +db.put('a', { x: 123 }, function (err) { + if (err) throw err - // Ta da! - console.log('name=' + value) + db.get('a', function (err, value) { + console.log(value) // { x: 123 } }) }) ``` -With `async/await`: +
-```js -await db.put('name', 'Level') -const value = await db.get('name') +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 + +```ts +// Specify types of keys and values (any, in the case of json). +// The generic type parameters default to Level. +const db = new Level('./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('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('xyz', { valueEncoding: 'json' }) +``` + +
+ +## Install + +With [npm](https://npmjs.org) do: + +```bash +npm install level ``` +For use in browsers, this package is best used with [`browserify`](https://github.com/browserify/browserify), [`webpack`](https://webpack.js.org/), [`rollup`](https://rollupjs.org/) or similar bundlers. For a quick start, visit [`browserify-starter`](https://github.com/Level/browserify-starter) or [`webpack-starter`](https://github.com/Level/webpack-starter). + ## Supported Platforms -At the time of writing, `level` works in Node.js 10+ and Electron 5+ on Linux, Mac OS, Windows and FreeBSD, including any future Node.js and Electron release thanks to [N-API](https://nodejs.org/api/n-api.html), including ARM platforms like Raspberry Pi and Android, as well as in Chrome, Firefox, Edge, Safari, iOS Safari and Chrome for Android. For details, see [Supported Platforms](https://github.com/Level/leveldown#supported-platforms) of `leveldown` and [Browser Support](https://github.com/Level/level-js#browser-support) of `level-js`. +At the time of writing, `level` works in Node.js 12+ and Electron 5+ on Linux, Mac OS, Windows and FreeBSD, including any future Node.js and Electron release thanks to [Node-API](https://nodejs.org/api/n-api.html), including ARM platforms like Raspberry Pi and Android, as well as in Chrome, Firefox, Edge, Safari, iOS Safari and Chrome for Android. For details, see [Supported Platforms](https://github.com/Level/classic-level#supported-platforms) of `classic-level` and [Browser Support](https://github.com/Level/browser-level#browser-support) of `browser-level`. Binary keys and values are supported across the board. ## API -For options specific to [`leveldown`][leveldown] and [`level-js`][level-js] ("underlying store" from here on out), please see their respective READMEs. +The API of `level` follows that of [`abstract-level`](https://github.com/Level/abstract-level). The documentation below covers it all except for [Encodings](https://github.com/Level/abstract-level#encodings), [Events](https://github.com/Level/abstract-level#events) and [Errors](https://github.com/Level/abstract-level#errors) which are exclusively documented in `abstract-level`. For options and additional methods specific to [`classic-level`](https://github.com/Level/classic-level) and [`browser-level`](https://github.com/Level/browser-level), please see their respective READMEs. -### `db = level(location[, options[, callback]])` +An `abstract-level` and thus `level` database is at its core a [key-value database](https://en.wikipedia.org/wiki/Key%E2%80%93value_database). A key-value pair is referred to as an _entry_ here and typically returned as an array, comparable to [`Object.entries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries). -The main entry point for creating a new `levelup` instance. +### `db = new Level(location[, options])` -- `location` is a string pointing to the LevelDB location to be opened or in browsers, the name of the [`IDBDatabase`](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase) to be opened. -- `options` is passed on to the underlying store. -- `options.keyEncoding` and `options.valueEncoding` are passed to [`encoding-down`][encoding-down], default encoding is `'utf8'` +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`](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase) to be opened. -Calling `level('my-db')` will also open the underlying store. This is an asynchronous operation which will trigger your callback if you provide one. The callback should take the form `function (err, db) {}` where `db` is the `levelup` instance. If you don't provide a callback, any read & write operations are simply queued internally until the store is fully opened. +The optional `options` object may contain: -This leads to two alternative ways of managing a `levelup` instance: +- `keyEncoding` (string or object, default `'utf8'`): encoding to use for keys +- `valueEncoding` (string or object, default `'utf8'`): encoding to use for values. -```js -level(location, options, function (err, db) { - if (err) throw err +See [Encodings](https://github.com/Level/abstract-level#encodings) for a full description of these options. Other `options` (except `passive`) are forwarded to `db.open()` which is automatically called in a next tick after the constructor returns. Any read & write operations are queued internally until the database has finished opening. If opening fails, those queued operations will yield errors. - db.get('foo', function (err, value) { - if (err) return console.log('foo does not exist') - console.log('got foo =', value) - }) -}) -``` +### `db.status` -Versus the equivalent: +Read-only getter that returns a string reflecting the current state of the database: -```js -// Will throw if an error occurs -var db = level(location, options) +- `'opening'` - waiting for the database to be opened +- `'open'` - successfully opened the database +- `'closing'` - waiting for the database to be closed +- `'closed'` - successfully closed the database. -db.get('foo', function (err, value) { - if (err) return console.log('foo does not exist') - console.log('got foo =', value) -}) -``` +### `db.open([callback])` -The constructor function has a `.errors` property which provides access to the different error types from [`level-errors`](https://github.com/Level/errors#api). See example below on how to use it: +Open the database. The `callback` function will be called with no arguments when successfully opened, or with a single error argument if opening failed. If no callback is provided, a promise is returned. Options passed to `open()` take precedence over options passed to the database constructor. The `createIfMissing` and `errorIfExists` options are not supported by [`browser-level`](https://github.com/Level/browser-level). -```js -level('my-db', { createIfMissing: false }, function (err, db) { - if (err instanceof level.errors.OpenError) { - console.log('failed to open database') - } -}) -``` +The optional `options` object may contain: + +- `createIfMissing` (boolean, default: `true`): If `true`, create an empty database if one doesn't already exist. If `false` and the database doesn't exist, opening will fail. +- `errorIfExists` (boolean, default: `false`): If `true` and the database already exists, opening will fail. +- `passive` (boolean, default: `false`): Wait for, but do not initiate, opening of the database. + +It's generally not necessary to call `open()` because it's automatically called by the database constructor. It may however be useful to capture an error from failure to open, that would otherwise not surface until another method like `db.get()` is called. It's also possible to reopen the database after it has been closed with [`close()`](#dbclosecallback). Once `open()` has then been called, any read & write operations will again be queued internally until opening has finished. + +The `open()` and `close()` methods are idempotent. If the database is already open, the `callback` will be called in a next tick. If opening is already in progress, the `callback` will be called when that has finished. If closing is in progress, the database will be reopened once closing has finished. Likewise, if `close()` is called after `open()`, the database will be closed once opening has finished and the prior `open()` call will receive an error. + +### `db.close([callback])` -Note that `createIfMissing` is an option specific to [`leveldown`][leveldown]. +Close the database. The `callback` function will be called with no arguments if closing succeeded or with a single `error` argument if closing failed. If no callback is provided, a promise is returned. + +A database may have associated resources like file handles and locks. When the database is no longer needed (for the remainder of a program) it's recommended to call `db.close()` to free up resources. + +After `db.close()` has been called, no further read & write operations are allowed unless and until `db.open()` is called again. For example, `db.get(key)` will yield an error with code [`LEVEL_DATABASE_NOT_OPEN`](https://github.com/Level/abstract-level#errors). Any unclosed iterators or chained batches will be closed by `db.close()` and can then no longer be used even when `db.open()` is called again. ### `db.supports` -A read-only [manifest](https://github.com/Level/supports). Might be used like so: +A [manifest](https://github.com/Level/supports) describing the features supported by this database. Might be used like so: ```js if (!db.supports.permanence) { throw new Error('Persistent storage is required') } - -if (db.supports.bufferKeys && db.supports.promises) { - await db.put(Buffer.from('key'), 'value') -} ``` -### `db.open([callback])` +### `db.get(key[, options][, callback])` -Opens the underlying store. In general you shouldn't need to call this method directly as it's automatically called by [`level()`](#db--levellocation-options-callback). However, it is possible to reopen the store after it has been closed with [`close()`](#dbclosecallback). +Get a value from the database by `key`. The optional `options` object may contain: -If no callback is passed, a promise is returned. +- `keyEncoding`: custom key encoding for this operation, used to encode the `key`. +- `valueEncoding`: custom value encoding for this operation, used to decode the value. -### `db.close([callback])` +The `callback` function will be called with an error if the operation failed. If the key was not found, the error will have code [`LEVEL_NOT_FOUND`](https://github.com/Level/abstract-level#errors). If successful the first argument will be `null` and the second argument will be the value. If no callback is provided, a promise is returned. -`close()` closes the underlying store. The callback will receive any error encountered during closing as the first argument. +### `db.getMany(keys[, options][, callback])` -A `levelup` instance has associated resources like file handles and locks. When you no longer need your `levelup` instance (for the remainder of your program) call `close()` to free up resources. The underlying store cannot be opened by multiple instances of `levelup` simultaneously. +Get multiple values from the database by an array of `keys`. The optional `options` object may contain: -If no callback is passed, a promise is returned. +- `keyEncoding`: custom key encoding for this operation, used to encode the `keys`. +- `valueEncoding`: custom value encoding for this operation, used to decode values. + +The `callback` function will be called with an error if the operation failed. If successful the first argument will be `null` and the second argument will be an array of values with the same order as `keys`. If a key was not found, the relevant value will be `undefined`. If no callback is provided, a promise is returned. ### `db.put(key, value[, options][, callback])` -`put()` is the primary method for inserting data into the store. Both `key` and `value` can be of any type as far as `levelup` is concerned. +Add a new entry or overwrite an existing entry. The optional `options` object may contain: -- `options` is passed on to the underlying store -- `options.keyEncoding` and `options.valueEncoding` are passed to [`encoding-down`][encoding-down], allowing you to override the key- and/or value encoding for this `put` operation. +- `keyEncoding`: custom key encoding for this operation, used to encode the `key`. +- `valueEncoding`: custom value encoding for this operation, used to encode the `value`. -If no callback is passed, a promise is returned. +The `callback` function will be called with no arguments if the operation was successful or with an error if it failed. If no callback is provided, a promise is returned. -### `db.get(key[, options][, callback])` +### `db.del(key[, options][, callback])` + +Delete an entry by `key`. The optional `options` object may contain: + +- `keyEncoding`: custom key encoding for this operation, used to encode the `key`. + +The `callback` function will be called with no arguments if the operation was successful or with an error if it failed. If no callback is provided, a promise is returned. + +### `db.batch(operations[, options][, callback])` -Get a value from the store by `key`. The `key` can be of any type. If it doesn't exist in the store then the callback or promise will receive an error. A not-found err object will be of type `'NotFoundError'` so you can `err.type == 'NotFoundError'` or you can perform a truthy test on the property `err.notFound`. +Perform multiple _put_ and/or _del_ operations in bulk. The `operations` argument must be an array containing a list of operations to be executed sequentially, although as a whole they are performed as an atomic operation. + +Each operation must be an object with at least a `type` property set to either `'put'` or `'del'`. If the `type` is `'put'`, the operation must have `key` and `value` properties. It may optionally have `keyEncoding` and / or `valueEncoding` properties to encode keys or values with a custom encoding for just that operation. If the `type` is `'del'`, the operation must have a `key` property and may optionally have a `keyEncoding` property. + +An operation of either type may also have a `sublevel` property, to prefix the key of the operation with the prefix of that sublevel. This allows atomically committing data to multiple sublevels. Keys and values will be encoded by the sublevel, to the same effect as a `sublevel.batch(..)` call. In the following example, the first `value` will be encoded with `'json'` rather than the default encoding of `db`: ```js -db.get('foo', function (err, value) { - if (err) { - if (err.notFound) { - // handle a 'NotFoundError' here - return - } - // I/O or other error, pass it up the callback chain - return callback(err) +const people = db.sublevel('people', { valueEncoding: 'json' }) +const nameIndex = db.sublevel('names') + +await db.batch([{ + type: 'put', + sublevel: people, + key: '123', + value: { + name: 'Alice' } +}, { + type: 'put', + sublevel: nameIndex, + key: 'Alice', + value: '123' +}]) +``` - // .. handle `value` here -}) +The optional `options` object may contain: + +- `keyEncoding`: custom key encoding for this batch, used to encode keys. +- `valueEncoding`: custom value encoding for this batch, used to encode values. + +Encoding properties on individual operations take precedence. In the following example, the first value will be encoded with the `'utf8'` encoding and the second with `'json'`. + +```js +await db.batch([ + { type: 'put', key: 'a', value: 'foo' }, + { type: 'put', key: 'b', value: 123, valueEncoding: 'json' } +], { valueEncoding: 'utf8' }) ``` -- `options` is passed on to the underlying store. -- `options.keyEncoding` and `options.valueEncoding` are passed to [`encoding-down`][encoding-down], allowing you to override the key- and/or value encoding for this `get` operation. +The `callback` function will be called with no arguments if the batch was successful or with an error if it failed. If no callback is provided, a promise is returned. -If no callback is passed, a promise is returned. +### `chainedBatch = db.batch()` -### `db.getMany(keys[, options][, callback])` +Create a [chained batch](#chainedbatch), when `batch()` is called with zero arguments. A chained batch can be used to build and eventually commit an atomic batch of operations. Depending on how it's used, it is possible to obtain greater performance with this form of `batch()`. On `browser-level` however, it is just sugar. -Get multiple values from the store by an array of `keys`. The optional `options` object is the same as for [`get()`](#dbgetkey-options-callback). +```js +await db.batch() + .del('bob') + .put('alice', 361) + .put('kim', 220) + .write() +``` -The `callback` function will be called with an `Error` if the operation failed for any reason. If successful the first argument will be `null` and the second argument will be an array of values with the same order as `keys`. If a key was not found, the relevant value will be `undefined`. +### `iterator = db.iterator([options])` -If no callback is provided, a promise is returned. +Create an [iterator](#iterator). The optional `options` object may contain the following _range options_ to control the range of entries to be iterated: -### `db.del(key[, options][, callback])` +- `gt` (greater than) or `gte` (greater than or equal): define the lower bound of the range to be iterated. Only entries where the key is greater than (or equal to) this option will be included in the range. When `reverse` is true the order will be reversed, but the entries iterated will be the same. +- `lt` (less than) or `lte` (less than or equal): define the higher bound of the range to be iterated. Only entries where the key is less than (or equal to) this option will be included in the range. When `reverse` is true the order will be reversed, but the entries iterated will be the same. +- `reverse` (boolean, default: `false`): iterate entries in reverse order. Beware that a reverse seek can be slower than a forward seek. +- `limit` (number, default: `Infinity`): limit the number of entries yielded. This number represents a _maximum_ number of entries and will not be reached if the end of the range is reached first. A value of `Infinity` or `-1` means there is no limit. When `reverse` is true the entries with the highest keys will be returned instead of the lowest keys. + +The `gte` and `lte` range options take precedence over `gt` and `lt` respectively. If no range options are provided, the iterator will visit all entries of the database, starting at the lowest key and ending at the highest key (unless `reverse` is true). In addition to range options, the `options` object may contain: + +- `keys` (boolean, default: `true`): whether to return the key of each entry. If set to `false`, the iterator will yield keys that are `undefined`. Prefer to use `db.keys()` instead. +- `values` (boolean, default: `true`): whether to return the value of each entry. If set to `false`, the iterator will yield values that are `undefined`. Prefer to use `db.values()` instead. +- `keyEncoding`: custom key encoding for this iterator, used to encode range options, to encode `seek()` targets and to decode keys. +- `valueEncoding`: custom value encoding for this iterator, used to decode values. -`del()` is the primary method for removing data from the store. +> :pushpin: To instead consume data using streams, see [`level-read-stream`](https://github.com/Level/read-stream) and [`level-web-stream`](https://github.com/Level/web-stream). + +### `keyIterator = db.keys([options])` + +Create a [key iterator](#keyiterator), having the same interface as `db.iterator()` except that it yields keys instead of entries. If only keys are needed, using `db.keys()` may increase performance because values won't have to fetched, copied or decoded. Options are the same as for `db.iterator()` except that `db.keys()` does not take `keys`, `values` and `valueEncoding` options. + +```js +// Iterate lazily +for await (const key of db.keys({ gt: 'a' })) { + console.log(key) +} + +// Get all at once. Setting a limit is recommended. +const keys = await db.keys({ gt: 'a', limit: 10 }).all() +``` + +### `valueIterator = db.values([options])` + +Create a [value iterator](#valueiterator), having the same interface as `db.iterator()` except that it yields values instead of entries. If only values are needed, using `db.values()` may increase performance because keys won't have to fetched, copied or decoded. Options are the same as for `db.iterator()` except that `db.values()` does not take `keys` and `values` options. Note that it _does_ take a `keyEncoding` option, relevant for the encoding of range options. ```js -db.del('foo', function (err) { - if (err) - // handle I/O or other error -}); +// Iterate lazily +for await (const value of db.values({ gt: 'a' })) { + console.log(value) +} + +// Get all at once. Setting a limit is recommended. +const values = await db.values({ gt: 'a', limit: 10 }).all() ``` -- `options` is passed on to the underlying store. -- `options.keyEncoding` is passed to [`encoding-down`][encoding-down], allowing you to override the key encoding for this `del` operation. +### `db.clear([options][, callback])` -If no callback is passed, a promise is returned. +Delete all entries or a range. Not guaranteed to be atomic. Accepts the following options (with the same rules as on iterators): -### `db.batch(array[, options][, callback])` _(array form)_ +- `gt` (greater than) or `gte` (greater than or equal): define the lower bound of the range to be deleted. Only entries where the key is greater than (or equal to) this option will be included in the range. When `reverse` is true the order will be reversed, but the entries deleted will be the same. +- `lt` (less than) or `lte` (less than or equal): define the higher bound of the range to be deleted. Only entries where the key is less than (or equal to) this option will be included in the range. When `reverse` is true the order will be reversed, but the entries deleted will be the same. +- `reverse` (boolean, default: `false`): delete entries in reverse order. Only effective in combination with `limit`, to delete the last N entries. +- `limit` (number, default: `Infinity`): limit the number of entries to be deleted. This number represents a _maximum_ number of entries and will not be reached if the end of the range is reached first. A value of `Infinity` or `-1` means there is no limit. When `reverse` is true the entries with the highest keys will be deleted instead of the lowest keys. +- `keyEncoding`: custom key encoding for this operation, used to encode range options. -`batch()` can be used for fast bulk-write operations (both _put_ and _delete_). The `array` argument should contain a list of operations to be executed sequentially, although as a whole they are performed as an atomic operation inside the underlying store. +The `gte` and `lte` range options take precedence over `gt` and `lt` respectively. If no options are provided, all entries will be deleted. The `callback` function will be called with no arguments if the operation was successful or with an error if it failed. If no callback is provided, a promise is returned. -Each operation is contained in an object having the following properties: `type`, `key`, `value`, where the _type_ is either `'put'` or `'del'`. In the case of `'del'` the `value` property is ignored. Any entries with a `key` of `null` or `undefined` will cause an error to be returned on the `callback` and any `type: 'put'` entry with a `value` of `null` or `undefined` will return an error. +### `sublevel = db.sublevel(name[, options])` + +Create a [sublevel](#sublevel) that has the same interface as `db` (except for additional methods specific to `classic-level` or `browser-level`) and prefixes the keys of operations before passing them on to `db`. The `name` argument is required and must be a string. ```js -const ops = [ - { type: 'del', key: 'father' }, - { type: 'put', key: 'name', value: 'Yuri Irsenovich Kim' }, - { type: 'put', key: 'dob', value: '16 February 1941' }, - { type: 'put', key: 'spouse', value: 'Kim Young-sook' }, - { type: 'put', key: 'occupation', value: 'Clown' } -] - -db.batch(ops, function (err) { - if (err) return console.log('Ooops!', err) - console.log('Great success dear leader!') -}) +const example = db.sublevel('example') + +await example.put('hello', 'world') +await db.put('a', '1') + +// Prints ['hello', 'world'] +for await (const [key, value] of example.iterator()) { + console.log([key, value]) +} ``` -- `options` is passed on to the underlying store. -- `options.keyEncoding` and `options.valueEncoding` are passed to [`encoding-down`][encoding-down], allowing you to override the key- and/or value encoding of operations in this batch. +Sublevels effectively separate a database into sections. Think SQL tables, but evented, ranged and real-time! Each sublevel is an `AbstractLevel` instance with its own keyspace, [events](https://github.com/Level/abstract-level#events) and [encodings](https://github.com/Level/abstract-level#encodings). For example, it's possible to have one sublevel with `'buffer'` keys and another with `'utf8'` keys. The same goes for values. Like so: -If no callback is passed, a promise is returned. +```js +db.sublevel('one', { valueEncoding: 'json' }) +db.sublevel('two', { keyEncoding: 'buffer' }) +``` -### `db.batch()` _(chained form)_ +An own keyspace means that `sublevel.iterator()` only includes entries of that sublevel, `sublevel.clear()` will only delete entries of that sublevel, and so forth. Range options get prefixed too. -`batch()`, when called with no arguments will return a `Batch` object which can be used to build, and eventually commit, an atomic batch operation. Depending on how it's used, it is possible to obtain greater performance when using the chained form of `batch()` over the array form. +Fully qualified keys (as seen from the parent database) take the form of `prefix + key` where `prefix` is `separator + name + separator`. If `name` is empty, the effective prefix is two separators. Sublevels can be nested: if `db` is itself a sublevel then the effective prefix is a combined prefix, e.g. `'!one!!two!'`. Note that a parent database will see its own keys as well as keys of any nested sublevels: ```js -db.batch() - .del('father') - .put('name', 'Yuri Irsenovich Kim') - .put('dob', '16 February 1941') - .put('spouse', 'Kim Young-sook') - .put('occupation', 'Clown') - .write(function () { console.log('Done!') }) +// Prints ['!example!hello', 'world'] and ['a', '1'] +for await (const [key, value] of db.iterator()) { + console.log([key, value]) +} ``` -**`batch.put(key, value[, options])`** +> :pushpin: The key structure is equal to that of [`subleveldown`](https://github.com/Level/subleveldown) which offered sublevels before they were built-in to `abstract-level`. This means that an `abstract-level` sublevel can read sublevels previously created with (and populated by) `subleveldown`. -Queue a _put_ operation on the current batch, not committed until a `write()` is called on the batch. The `options` argument is passed on to the underlying store; `options.keyEncoding` and `options.valueEncoding` are passed to [`encoding-down`][encoding-down], allowing you to override the key- and/or value encoding of this operation. +Internally, sublevels operate on keys that are either a string, Buffer or Uint8Array, depending on parent database and choice of encoding. Which is to say: binary keys are fully supported. The `name` must however always be a string and can only contain ASCII characters. -This method may `throw` a `WriteError` if there is a problem with your put (such as the `value` being `null` or `undefined`). +The optional `options` object may contain: -**`batch.del(key[, options])`** +- `separator` (string, default: `'!'`): Character for separating sublevel names from user keys and each other. Must sort before characters used in `name`. An error will be thrown if that's not the case. +- `keyEncoding` (string or object, default `'utf8'`): encoding to use for keys +- `valueEncoding` (string or object, default `'utf8'`): encoding to use for values. -Queue a _del_ operation on the current batch, not committed until a `write()` is called on the batch. The `options` argument is passed on to the underlying store; `options.keyEncoding` is passed to [`encoding-down`][encoding-down], allowing you to override the key encoding of this operation. +The `keyEncoding` and `valueEncoding` options are forwarded to the `AbstractLevel` constructor and work the same, as if a new, separate database was created. They default to `'utf8'` regardless of the encodings configured on `db`. Other options are forwarded too but `abstract-level` (and therefor `level`) has no relevant options at the time of writing. For example, setting the `createIfMissing` option will have no effect. Why is that? -This method may `throw` a `WriteError` if there is a problem with your delete. +Like regular databases, sublevels open themselves but they do not affect the state of the parent database. This means a sublevel can be individually closed and (re)opened. If the sublevel is created while the parent database is opening, it will wait for that to finish. If the parent database is closed, then opening the sublevel will fail and subsequent operations on the sublevel will yield errors with code [`LEVEL_DATABASE_NOT_OPEN`](https://github.com/Level/abstract-level#errors). -**`batch.clear()`** +### `chainedBatch` -Clear all queued operations on the current batch, any previous operations will be discarded. +#### `chainedBatch.put(key, value[, options])` -**`batch.length`** +Queue a `put` operation on this batch, not committed until `write()` is called. This will throw a [`LEVEL_INVALID_KEY`](https://github.com/Level/abstract-level#errors) or [`LEVEL_INVALID_VALUE`](https://github.com/Level/abstract-level#errors) error if `key` or `value` is invalid. The optional `options` object may contain: -The number of queued operations on the current batch. +- `keyEncoding`: custom key encoding for this operation, used to encode the `key`. +- `valueEncoding`: custom value encoding for this operation, used to encode the `value`. +- `sublevel` (sublevel instance): act as though the `put` operation is performed on the given sublevel, to similar effect as `sublevel.batch().put(key, value)`. This allows atomically committing data to multiple sublevels. The `key` will be prefixed with the `prefix` of the sublevel, and the `key` and `value` will be encoded by the sublevel (using the default encodings of the sublevel unless `keyEncoding` and / or `valueEncoding` are provided). -**`batch.write([options][, callback])`** +#### `chainedBatch.del(key[, options])` -Commit the queued operations for this batch. All operations not _cleared_ will be written to the underlying store atomically, that is, they will either all succeed or fail with no partial commits. +Queue a `del` operation on this batch, not committed until `write()` is called. This will throw a [`LEVEL_INVALID_KEY`](https://github.com/Level/abstract-level#errors) error if `key` is invalid. The optional `options` object may contain: -- `options` is passed on to the underlying store. -- `options.keyEncoding` and `options.valueEncoding` are not supported here. +- `keyEncoding`: custom key encoding for this operation, used to encode the `key`. +- `sublevel` (sublevel instance): act as though the `del` operation is performed on the given sublevel, to similar effect as `sublevel.batch().del(key)`. This allows atomically committing data to multiple sublevels. The `key` will be prefixed with the `prefix` of the sublevel, and the `key` will be encoded by the sublevel (using the default key encoding of the sublevel unless `keyEncoding` is provided). -If no callback is passed, a promise is returned. +#### `chainedBatch.clear()` -### `db.status` +Clear all queued operations on this batch. -A readonly string that is one of: +#### `chainedBatch.write([options][, callback])` -- `new` - newly created, not opened or closed -- `opening` - waiting for the underlying store to be opened -- `open` - successfully opened the store, available for use -- `closing` - waiting for the store to be closed -- `closed` - store has been successfully closed. +Commit the queued operations for this batch. All operations will be written atomically, that is, they will either all succeed or fail with no partial commits. -### `db.isOperational()` +There are no `options` (that are common between `classic-level` and `browser-level`). Note that `write()` does not take encoding options. Those can only be set on `put()` and `del()`. -Returns `true` if the store accepts operations, which in the case of `level(up)` means that `status` is either `opening` or `open`, because it opens itself and queues up operations until opened. +The `callback` function will be called with no arguments if the batch was successful or with an error if it failed. If no callback is provided, a promise is returned. -### `db.createReadStream([options])` +After `write()` or `close()` has been called, no further operations are allowed. -Returns a [Readable Stream](https://nodejs.org/docs/latest/api/stream.html#stream_readable_streams) of key-value pairs. A pair is an object with `key` and `value` properties. By default it will stream all entries in the underlying store from start to end. Use the options described below to control the range, direction and results. +#### `chainedBatch.close([callback])` -```js -db.createReadStream() - .on('data', function (data) { - console.log(data.key, '=', data.value) - }) - .on('error', function (err) { - console.log('Oh my!', err) - }) - .on('close', function () { - console.log('Stream closed') - }) - .on('end', function () { - console.log('Stream ended') - }) -``` +Free up underlying resources. This should be done even if the chained batch has zero queued operations. Automatically called by `write()` so normally not necessary to call, unless the intent is to discard a chained batch without committing it. The `callback` function will be called with no arguments. If no callback is provided, a promise is returned. Closing the batch is an idempotent operation, such that calling `close()` more than once is allowed and makes no difference. -You can supply an options object as the first parameter to `createReadStream()` with the following properties: +#### `chainedBatch.length` -- `gt` (greater than), `gte` (greater than or equal) define the lower bound of the range to be streamed. Only entries where the key is greater than (or equal to) this option will be included in the range. When `reverse=true` the order will be reversed, but the entries streamed will be the same. +The number of queued operations on the current batch. -- `lt` (less than), `lte` (less than or equal) define the higher bound of the range to be streamed. Only entries where the key is less than (or equal to) this option will be included in the range. When `reverse=true` the order will be reversed, but the entries streamed will be the same. +#### `chainedBatch.db` -- `reverse` _(boolean, default: `false`)_: stream entries in reverse order. Beware that due to the way that stores like LevelDB work, a reverse seek can be slower than a forward seek. +A reference to the database that created this chained batch. -- `limit` _(number, default: `-1`)_: limit the number of entries collected by this stream. This number represents a _maximum_ number of entries and may not be reached if you get to the end of the range first. A value of `-1` means there is no limit. When `reverse=true` the entries with the highest keys will be returned instead of the lowest keys. +### `iterator` -- `keys` _(boolean, default: `true`)_: whether the results should contain keys. If set to `true` and `values` set to `false` then results will simply be keys, rather than objects with a `key` property. Used internally by the `createKeyStream()` method. +An iterator allows one to lazily read a range of entries stored in the database. The entries will be sorted by keys in [lexicographic order](https://en.wikipedia.org/wiki/Lexicographic_order) (in other words: byte order) which in short means key `'a'` comes before `'b'` and key `'10'` comes before `'2'`. -- `values` _(boolean, default: `true`)_: whether the results should contain values. If set to `true` and `keys` set to `false` then results will simply be values, rather than objects with a `value` property. Used internally by the `createValueStream()` method. +A `classic-level` iterator reads from a snapshot of the database, created at the time `db.iterator()` was called. This means the iterator will not see the data of simultaneous write operations. A `browser-level` iterator does not offer such guarantees, as is indicated by `db.supports.snapshots`. That property will be true in Node.js and false in browsers. -Underlying stores may have additional options. +Iterators can be consumed with [`for await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) and `iterator.all()`, or by manually calling `iterator.next()` or `nextv()` in succession. In the latter case, `iterator.close()` must always be called. In contrast, finishing, throwing, breaking or returning from a `for await...of` loop automatically calls `iterator.close()`, as does `iterator.all()`. -### `db.createKeyStream([options])` +An iterator reaches its natural end in the following situations: -Returns a [Readable Stream](https://nodejs.org/docs/latest/api/stream.html#stream_readable_streams) of keys rather than key-value pairs. Use the same options as described for [`createReadStream()`](#dbcreatereadstreamoptions) to control the range and direction. +- The end of the database has been reached +- The end of the range has been reached +- The last `iterator.seek()` was out of range. -You can also obtain this stream by passing an options object to `createReadStream()` with `keys` set to `true` and `values` set to `false`. The result is equivalent; both streams operate in [object mode](https://nodejs.org/docs/latest/api/stream.html#stream_object_mode). +An iterator keeps track of calls that are in progress. It doesn't allow concurrent `next()`, `nextv()` or `all()` calls (including a combination thereof) and will throw an error with code [`LEVEL_ITERATOR_BUSY`](https://github.com/Level/abstract-level#errors) if that happens: ```js -db.createKeyStream() - .on('data', function (data) { - console.log('key=', data) - }) +// Not awaited and no callback provided +iterator.next() + +try { + // Which means next() is still in progress here + iterator.all() +} catch (err) { + console.log(err.code) // 'LEVEL_ITERATOR_BUSY' +} +``` -// same as: -db.createReadStream({ keys: true, values: false }) - .on('data', function (data) { - console.log('key=', data) - }) +#### `for await...of iterator` + +Yields entries, which are arrays containing a `key` and `value`. The type of `key` and `value` depends on the options passed to `db.iterator()`. + +```js +try { + for await (const [key, value] of db.iterator()) { + console.log(key) + } +} catch (err) { + console.error(err) +} ``` -### `db.createValueStream([options])` +#### `iterator.next([callback])` + +Advance to the next entry and yield that entry. If an error occurs, the `callback` function will be called with an error. Otherwise, the `callback` receives `null`, a `key` and a `value`. The type of `key` and `value` depends on the options passed to `db.iterator()`. If the iterator has reached its natural end, both `key` and `value` will be `undefined`. + +If no callback is provided, a promise is returned for either an entry array (containing a `key` and `value`) or `undefined` if the iterator reached its natural end. + +**Note:** `iterator.close()` must always be called once there's no intention to call `next()` or `nextv()` again. Even if such calls yielded an error and even if the iterator reached its natural end. Not closing the iterator will result in memory leaks and may also affect performance of other operations if many iterators are unclosed and each is holding a snapshot of the database. + +#### `iterator.nextv(size[, options][, callback])` -Returns a [Readable Stream](https://nodejs.org/docs/latest/api/stream.html#stream_readable_streams) of values rather than key-value pairs. Use the same options as described for [`createReadStream()`](#dbcreatereadstreamoptions) to control the range and direction. +Advance repeatedly and get at most `size` amount of entries in a single call. Can be faster than repeated `next()` calls. The `size` argument must be an integer and has a soft minimum of 1. There are no `options` at the moment. -You can also obtain this stream by passing an options object to `createReadStream()` with `values` set to `true` and `keys` set to `false`. The result is equivalent; both streams operate in [object mode](https://nodejs.org/docs/latest/api/stream.html#stream_object_mode). +If an error occurs, the `callback` function will be called with an error. Otherwise, the `callback` receives `null` and an array of entries, where each entry is an array containing a key and value. The natural end of the iterator will be signaled by yielding an empty array. If no callback is provided, a promise is returned. ```js -db.createValueStream() - .on('data', function (data) { - console.log('value=', data) - }) +const iterator = db.iterator() -// same as: -db.createReadStream({ keys: false, values: true }) - .on('data', function (data) { - console.log('value=', data) - }) -``` +while (true) { + const entries = await iterator.nextv(100) + + if (entries.length === 0) { + break + } -### `db.iterator([options])` + for (const [key, value] of entries) { + // .. + } +} -Returns an [`abstract-leveldown` iterator](https://github.com/Level/abstract-leveldown/#iterator), which is what powers the readable streams above. Options are the same as the range options of [`createReadStream()`](#dbcreatereadstreamoptions) and are passed to the underlying store. +await iterator.close() +``` -These iterators support [`for await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of): +#### `iterator.all([options][, callback])` + +Advance repeatedly and get all (remaining) entries as an array, automatically closing the iterator. Assumes that those entries fit in memory. If that's not the case, instead use `next()`, `nextv()` or `for await...of`. There are no `options` at the moment. If an error occurs, the `callback` function will be called with an error. Otherwise, the `callback` receives `null` and an array of entries, where each entry is an array containing a key and value. If no callback is provided, a promise is returned. ```js -for await (const [key, value] of db.iterator()) { - console.log(value) +const entries = await db.iterator({ limit: 100 }).all() + +for (const [key, value] of entries) { + // .. } ``` -### `db.clear([options][, callback])` +#### `iterator.seek(target[, options])` + +Seek to the key closest to `target`. Subsequent calls to `iterator.next()`, `nextv()` or `all()` (including implicit calls in a `for await...of` loop) will yield entries with keys equal to or larger than `target`, or equal to or smaller than `target` if the `reverse` option passed to `db.iterator()` was true. + +The optional `options` object may contain: -Delete all entries or a range. Not guaranteed to be atomic. Accepts the following range options (with the same rules as on iterators): +- `keyEncoding`: custom key encoding, used to encode the `target`. By default the `keyEncoding` option of the iterator is used or (if that wasn't set) the `keyEncoding` of the database. -- `gt` (greater than), `gte` (greater than or equal) define the lower bound of the range to be deleted. Only entries where the key is greater than (or equal to) this option will be included in the range. When `reverse=true` the order will be reversed, but the entries deleted will be the same. -- `lt` (less than), `lte` (less than or equal) define the higher bound of the range to be deleted. Only entries where the key is less than (or equal to) this option will be included in the range. When `reverse=true` the order will be reversed, but the entries deleted will be the same. -- `reverse` _(boolean, default: `false`)_: delete entries in reverse order. Only effective in combination with `limit`, to remove the last N records. -- `limit` _(number, default: `-1`)_: limit the number of entries to be deleted. This number represents a _maximum_ number of entries and may not be reached if you get to the end of the range first. A value of `-1` means there is no limit. When `reverse=true` the entries with the highest keys will be deleted instead of the lowest keys. +If range options like `gt` were passed to `db.iterator()` and `target` does not fall within that range, the iterator will reach its natural end. -If no options are provided, all entries will be deleted. The `callback` function will be called with no arguments if the operation was successful or with an `WriteError` if it failed for any reason. +#### `iterator.close([callback])` -If no callback is passed, a promise is returned. +Free up underlying resources. The `callback` function will be called with no arguments. If no callback is provided, a promise is returned. Closing the iterator is an idempotent operation, such that calling `close()` more than once is allowed and makes no difference. -## Promise Support +If a `next()` ,`nextv()` or `all()` call is in progress, closing will wait for that to finish. After `close()` has been called, further calls to `next()` ,`nextv()` or `all()` will yield an error with code [`LEVEL_ITERATOR_NOT_OPEN`](https://github.com/Level/abstract-level#errors). -Each function taking a callback can also be used as a promise, if the callback is omitted. The only exception is the `level` constructor itself, which if no callback is passed will lazily open the underlying store in the background. +#### `iterator.db` -Example: +A reference to the database that created this iterator. + +#### `iterator.count` + +Read-only getter that indicates how many keys have been yielded so far (by any method) excluding calls that errored or yielded `undefined`. + +#### `iterator.limit` + +Read-only getter that reflects the `limit` that was set in options. Greater than or equal to zero. Equals `Infinity` if no limit, which allows for easy math: ```js -const db = level('my-db') -await db.put('foo', 'bar') -console.log(await db.get('foo')) +const hasMore = iterator.count < iterator.limit +const remaining = iterator.limit - iterator.count ``` -## Events +### `keyIterator` + +A key iterator has the same interface as `iterator` except that its methods yield keys instead of entries. For the `keyIterator.next(callback)` method, this means that the `callback` will receive two arguments (an error and key) instead of three. Usage is otherwise the same. -`levelup` is an [`EventEmitter`](https://nodejs.org/api/events.html) and emits the following events. +### `valueIterator` -| Event | Description | Arguments | -| :-------- | :-------------------------- | :------------------- | -| `put` | Key has been updated | `key, value` (any) | -| `del` | Key has been deleted | `key` (any) | -| `batch` | Batch has executed | `operations` (array) | -| `clear` | Entries were deleted | `options` (object) | -| `opening` | Underlying store is opening | - | -| `open` | Store has opened | - | -| `ready` | Alias of `open` | - | -| `closing` | Store is closing | - | -| `closed` | Store has closed. | - | +A value iterator has the same interface as `iterator` except that its methods yield values instead of entries. For the `valueIterator.next(callback)` method, this means that the `callback` will receive two arguments (an error and value) instead of three. Usage is otherwise the same. -For example you can do: +### `sublevel` + +A sublevel is an instance of the `AbstractSublevel` class, which extends `AbstractLevel` and thus has the same API as documented above. Sublevels have a few additional properties. + +#### `sublevel.prefix` + +Prefix of the sublevel. A read-only string property. ```js -db.on('put', function (key, value) { - console.log('inserted', { key, value }) -}) +const example = db.sublevel('example') +const nested = example.sublevel('nested') + +console.log(example.prefix) // '!example!' +console.log(nested.prefix) // '!example!!nested!' +``` + +#### `sublevel.db` + +Parent database. A read-only property. + +```js +const example = db.sublevel('example') +const nested = example.sublevel('nested') + +console.log(example.db === db) // true +console.log(nested.db === db) // true ``` ## Contributing @@ -463,9 +617,3 @@ Support us with a monthly donation on [Open Collective](https://opencollective.c [MIT](LICENSE) [level-badge]: https://leveljs.org/img/badge.svg - -[leveldown]: https://github.com/Level/leveldown - -[level-js]: https://github.com/Level/level-js - -[encoding-down]: https://github.com/Level/encoding-down diff --git a/UPGRADING.md b/UPGRADING.md index 2ae8196..12fe215 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -2,6 +2,302 @@ This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the [changelog](CHANGELOG.md). +## 8.0.0 + +**This release replaces `leveldown` and `level-js` with [`classic-level`](https://github.com/Level/classic-level) and [`browser-level`](https://github.com/Level/browser-level). These modules implement the [`abstract-level`](https://github.com/Level/abstract-level) interface instead of [`abstract-leveldown`](https://github.com/Level/abstract-leveldown). This gives them the same API as `level@7` without having to be wrapped with [`levelup`](https://github.com/Level/levelup) or [`encoding-down`](https://github.com/Level/encoding-down). In addition, you can now choose to use Uint8Array instead of Buffer. Sublevels are built-in.** + +We've put together several upgrade guides for different modules. See the [FAQ](https://github.com/Level/community#faq) to find the best upgrade guide for you. This one describes how to upgrade `level`. + +Support of Node.js 10 has been dropped. + +### Changes to initialization + +We started using classes, which means using `new` is now required. If you previously did: + +```js +const level = require('level') +const db = level('db') +``` + +You must now do: + +```js +const { Level } = require('level') +const db = new Level('db') +``` + +### TypeScript makes a win + +TypeScript type declarations are now included in the npm package(s). For `level` it's an intersection of `classic-level` and `browser-level` types that includes their options but excludes methods like `compactRange()` that can only be found in either. JavaScript folks using VSCode will also benefit from the new types because they enable auto-completion and now include documentation. + +### Waking up from limbo + +Deferred open - meaning that a database opens itself and any operations made in the mean time are queued up in memory - remains built-in. A new behavior is that those operations will yield errors if opening failed. They'd previously end up in limbo. + +An `abstract-level` and thus `level` database is not "patch-safe". If some form of plugin monkey-patches a database method, it must now also take the responsibility of deferring the operation (as well as handling promises and callbacks) using [`db.defer()`](https://github.com/Level/abstract-level#dbdeferfn). + +### Creating the location recursively + +To align behavior between platforms, `classic-level` and therefore `level@8` creates the location directory recursively. While `leveldown` and therefore `level@7` would only do so on Windows. In the following example, the `foo` directory does not have to exist beforehand: + +```js +const db = new Level('foo/bar') +``` + +This new behavior may break expectations, given typical filesystem behavior, or it could be a convenient feature, if the database is considered to abstract away the filesystem. We're [collecting feedback](https://github.com/Level/classic-level/issues/7) to determine what to do in a next (major) version. Your vote is most welcome! + +### No constructor callback + +The database constructor no longer takes a callback argument. Instead call `db.open()` if you wish to wait for opening (which is not necessary to use the database) or to capture an error. If that's your reason for using the callback and you previously initialized a database like so: + +```js +level('fruits', function (err, db) { + // .. +}) +``` + +You must now do one of: + +```js +db.open(callback) +await db.open() +``` + +### There is only encodings + +Encodings have a new home in `abstract-level` and are now powered by [`level-transcoder`](https://github.com/Level/transcoder). The main change is that logic from the existing public API has been expanded down into the storage layer. There are however a few differences from `level@7`. Some breaking: + +- The lesser-used `'id'`, `'ascii'`, `'ucs2'` and `'utf16le'` encodings are not supported +- The undocumented `encoding` option (as an alias for `valueEncoding`) is not supported. + +And some non-breaking: + +- The `'binary'` encoding has been renamed to `'buffer'`, with `'binary'` as an alias +- The `'utf8'` encoding previously did not touch Buffers. Now it will call `buffer.toString('utf8')` for consistency. Consumers can use the `'buffer'` encoding to avoid this conversion. + +Both `classic-level` and `browser-level` support Uint8Array data, in addition to Buffer. It's a separate encoding called `'view'` that can be used interchangeably: + +```js +const db = new Level('people', { valueEncoding: 'view' }) + +await db.put('elena', new Uint8Array([97, 98, 99])) +await db.get('elena') // Uint8Array +await db.get('elena', { valueEncoding: 'utf8' }) // 'abc' +await db.get('elena', { valueEncoding: 'buffer' }) // Buffer +``` + +For browsers you can choose to use Uint8Array exclusively and omit the [`buffer`](https://github.com/feross/buffer) shim from your JavaScript bundle (through configuration of Webpack, Browserify or other). + +### Streams have moved + +Node.js readable streams must now be created with a new standalone module called [`level-read-stream`](https://github.com/Level/read-stream) rather than database methods like `db.createReadStream()`. For browsers you might prefer [`level-web-stream`](https://github.com/Level/web-stream) which does not require bundling the [`buffer`](https://github.com/feross/buffer) or [`readable-stream`](https://github.com/nodejs/readable-stream) shims. Both `level-read-stream` and `level-web-stream` can be used in Node.js and browsers. The former is significantly faster (also compared to `level@7`, thanks to a new `nextv()` method on iterators). The latter is a step towards a standard library for JavaScript across Node.js, Deno and browsers. + +To offer an alternative to `db.createKeyStream()` and `db.createValueStream()`, two new types of iterators have been added: `db.keys()` and `db.values()`. + +### State checks for safety + +On any operation, an `abstract-level` and thus `level` database checks if it's open. If not, it will either throw an error (if the relevant API is synchronous) or asynchronously yield an error. For example: + +```js +await db.close() + +try { + db.iterator() +} catch (err) { + console.log(err.code) // LEVEL_DATABASE_NOT_OPEN +} +``` + +_Errors now have a `code` property. More on that below\._ + +### Zero-length keys and range options are now valid + +These keys sort before anything else. Historically they weren't supported for causing segmentation faults in `leveldown`. That doesn't apply to today's codebase. You can now do: + +```js +await db.put('', 'abc') + +console.log(await db.get('')) // 'abc' +console.log(await db.get(new Uint8Array(0), { keyEncoding: 'view' })) // 'abc' + +for await (const [key, value] of db.iterator({ lte: '' })) { + console.log(value) // 'abc' +} +``` + +### It doesn't end there + +The `iterator.end()` method has been renamed to `iterator.close()`, with `end()` being an alias until a next major version. The term "close" makes it easier to differentiate between the iterator having reached its natural end (data-wise) versus closing it to cleanup resources. If you previously did: + +```js +const iterator = db.iterator() +iterator.end(callback) +``` + +You should now do one of: + +```js +iterator.close(callback) +await iterator.close() +``` + +On `db.close()`, non-closed iterators are now automatically closed (only for safety reasons). If a call like `next()` is in progress, closing the iterator or database will wait for that. Calling `iterator.close()` more than once is now allowed and makes no difference. + +### Other changes to iterators + +- In browsers, backpressure is now preferred over snapshot guarantees. For details, please see [`browser-level@1`](https://github.com/Level/browser-level/blob/main/UPGRADING.md#100). On the flip side, `iterator.seek()` now also works in browsers. +- Use of [`level-concat-iterator`](https://github.com/Level/concat-iterator) can be replaced with [`iterator.all()`](https://github.com/Level/level#iteratoralloptions-callback). The former does support `abstract-level` databases but the latter is optimized and always has snapshot guarantees. +- The previously undocumented `highWaterMark` option of `leveldown` is called [`highWaterMarkBytes`](https://github.com/Level/classic-level#about-high-water) in `classic-level` to remove a conflict with streams. +- On iterators with `{ keys: false }` or `{ values: false }` options, the yielded key or value is now consistently `undefined`. + +### A chained batch should be closed + +Chained batch has a new method `close()` which is an idempotent operation and automatically called after `write()` (for backwards compatibility) or on `db.close()`. This to ensure batches can't be used after closing and reopening a db. If a `write()` is in progress, closing will wait for that. If `write()` is never called then `close()` must be and that's a breaking change because inaction will cause memory leaks. For example: + +```js +const batch = db.batch() + .put('elena', 'abc') + .del('steve') + +if (someCondition) { + await batch.write() +} else { + // Decided not to commit + await batch.close() +} + +// In either case this will throw +batch.put('daniel', 'xyz') +``` + +### Errors now use codes + +The [`level-errors`](https://github.com/Level/errors) module is no longer used or exposed by `level@8`. Instead errors thrown or yielded from a database [have a `code` property](https://github.com/Level/abstract-level#errors). Going forward, the semver contract will be on `code` and error messages will change without a semver-major bump. + +To minimize breakage, the most used error as yielded by `get()` when an entry is not found, has the same properties that `level-errors` added (`notFound` and `status`) in addition to code `LEVEL_NOT_FOUND`. Those properties will be removed in a future version. If you previously did: + +```js +db.get('abc', function (err, value) { + if (err && err.notFound) { + // Handle missing entry + } +}) +``` + +That will still work but it's preferred to do: + +```js +db.get('abc', function (err, value) { + if (err && err.code === 'LEVEL_NOT_FOUND') { + // Handle missing entry + } +}) +``` + +Or using promises: + +```js +try { + const value = await db.get('abc') +} catch (err) { + if (err.code === 'LEVEL_NOT_FOUND') { + // Handle missing entry + } +} +``` + +Side note: it's been suggested more than once to remove this error altogether and we likely will after the dust has settled on `abstract-level`. + +### Changes to lesser-used properties and methods + +The following properties and methods can no longer be accessed, as they've been removed, renamed or replaced with internal [symbols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol). + +| Object | Property or method | Original module | New module | +| :------------ | :------------------------ | :------------------- | :--------------- | +| db | `_setupIteratorOptions()` | `abstract-leveldown` | `abstract-level` | +| db | `prefix` 1 | `level-js` | `browser-level` | +| db | `upgrade()` | `level-js` | `browser-level` | +| iterator | `_nexting` | `abstract-leveldown` | `abstract-level` | +| iterator | `_ended` | `abstract-leveldown` | `abstract-level` | +| iterator | `cache` 2 | `leveldown` | `classic-level` | +| iterator | `finished` | `leveldown` | `classic-level` | +| chained batch | `_written` | `abstract-leveldown` | `abstract-level` | +| chained batch | `_checkWritten()` | `abstract-leveldown` | `abstract-level` | +| chained batch | `_operations` | `abstract-leveldown` | `abstract-level` | + + + +1. Conflicted with the `db.prefix` property of sublevels. Renamed to `db.namePrefix`. +2. If you were using this then you'll want to checkout the new [`nextv()`](https://github.com/Level/level#iteratornextvsize-options-callback) method. + + + +The following properties are now read-only getters. + +| Object | Property | Original module | New module | +| :------------ | :----------------- | :------------------- | :--------------- | +| db | `status` | `abstract-leveldown` | `abstract-level` | +| db | `location` | `leveldown` | `classic-level` | +| db | `location` | `level-js` | `browser-level` | +| db | `namePrefix` | `level-js` | `browser-level` | +| db | `version` | `level-js` | `browser-level` | +| db | `db` (IDBDatabase) | `level-js` | `browser-level` | +| chained batch | `length` | `levelup` | `abstract-level` | + +### Sublevels are built-in + +_This section is only relevant if you use [`subleveldown`](https://github.com/Level/subleveldown), which can not wrap a `level@8` database._ + +If you previously did: + +```js +const sub = require('subleveldown') +const example1 = sub(db, 'example1') +const example2 = sub(db, 'example2', { valueEncoding: 'json' }) +``` + +You must now do: + +```js +const example1 = db.sublevel('example1') +const example2 = db.sublevel('example2', { valueEncoding: 'json' }) +``` + +The key structure is equal to that of `subleveldown`. This means that a sublevel can read sublevels previously created with (and populated by) `subleveldown`. There are some new features: + +- `db.batch(..)` takes a `sublevel` option on operations, to atomically commit data to multiple sublevels +- Sublevels support Uint8Array in addition to Buffer. + +To reduce function overloads, the prefix argument (`example1` above) is now required and it's called `name` here. If you previously did one of the following, resulting in an empty name: + +```js +subleveldown(db) +subleveldown(db, { separator: '@' }) +``` + +You must now use an explicit empty name: + +```js +db.sublevel('') +db.sublevel('', { separator: '@' }) +``` + +The string shorthand for `{ separator }` has also been removed. If you previously did: + +```js +subleveldown(db, 'example', '@') +``` + +You must now do: + +```js +db.sublevel('example', { separator: '@' }) +``` + +Third, the `open` option has been removed. If you need an asynchronous open hook, feel free to open an issue to discuss restoring this API. + +Lastly, the error message `Parent database is not open` (courtesy of `subleveldown` which had to check open state to prevent segmentation faults from underlying databases) changed to error code [`LEVEL_DATABASE_NOT_OPEN`](https://github.com/Level/abstract-level#errors) (courtesy of `abstract-level` which does those checks on any database). + ## 7.0.0 Legacy range options have been removed ([Level/community#86](https://github.com/Level/community/issues/86)). If you previously did: diff --git a/browser.js b/browser.js index 5974f4d..9d2a3c3 100644 --- a/browser.js +++ b/browser.js @@ -1 +1 @@ -module.exports = require('level-packager')(require('level-js')) +exports.Level = require('browser-level').BrowserLevel diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 0000000..d8e049f --- /dev/null +++ b/index.d.ts @@ -0,0 +1,87 @@ +import * as AbstractLevel from 'abstract-level' +import * as ClassicLevel from 'classic-level' +import * as BrowserLevel from 'browser-level' + +/** + * Universal {@link AbstractLevel} database for Node.js and browsers. + * + * @template KDefault The default type of keys if not overridden on operations. + * @template VDefault The default type of values if not overridden on operations. + */ +export class Level + extends AbstractLevel.AbstractLevel { + /** + * Database constructor. + * + * @param location Directory path (relative or absolute) where LevelDB will store its + * files, or in browsers, the name of the + * [`IDBDatabase`](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase) to be + * opened. + * @param options Options, of which some will be forwarded to {@link open}. + */ + constructor (location: string, options?: DatabaseOptions | undefined) + + /** + * Location that was passed to the constructor. + */ + get location (): string + + open (): Promise + open (options: OpenOptions): Promise + open (callback: AbstractLevel.NodeCallback): void + open (options: OpenOptions, callback: AbstractLevel.NodeCallback): void + + get (key: KDefault): Promise + get (key: KDefault, callback: AbstractLevel.NodeCallback): void + get (key: K, options: GetOptions): Promise + get (key: K, options: GetOptions, callback: AbstractLevel.NodeCallback): void + + getMany (keys: KDefault[]): Promise + getMany (keys: KDefault[], callback: AbstractLevel.NodeCallback): void + getMany (keys: K[], options: GetManyOptions): Promise + getMany (keys: K[], options: GetManyOptions, callback: AbstractLevel.NodeCallback): void + + put (key: KDefault, value: VDefault): Promise + put (key: KDefault, value: VDefault, callback: AbstractLevel.NodeCallback): void + put (key: K, value: V, options: PutOptions): Promise + put (key: K, value: V, options: PutOptions, callback: AbstractLevel.NodeCallback): void + + del (key: KDefault): Promise + del (key: KDefault, callback: AbstractLevel.NodeCallback): void + del (key: K, options: DelOptions): Promise + del (key: K, options: DelOptions, callback: AbstractLevel.NodeCallback): void + + batch (operations: Array>): Promise + batch (operations: Array>, callback: AbstractLevel.NodeCallback): void + batch (operations: Array>, options: BatchOptions): Promise + batch (operations: Array>, options: BatchOptions, callback: AbstractLevel.NodeCallback): void + batch (): ChainedBatch + + iterator (): Iterator + iterator (options: IteratorOptions): Iterator + + keys (): KeyIterator + keys (options: KeyIteratorOptions): KeyIterator + + values (): ValueIterator + values (options: ValueIteratorOptions): ValueIterator +} + +export type DatabaseOptions = ClassicLevel.DatabaseOptions & BrowserLevel.DatabaseOptions +export type OpenOptions = ClassicLevel.OpenOptions & BrowserLevel.OpenOptions +export type GetOptions = ClassicLevel.GetOptions & BrowserLevel.GetOptions +export type GetManyOptions = ClassicLevel.GetManyOptions & BrowserLevel.GetManyOptions +export type PutOptions = ClassicLevel.PutOptions & BrowserLevel.PutOptions +export type DelOptions = ClassicLevel.DelOptions & BrowserLevel.DelOptions + +export type BatchOptions = ClassicLevel.BatchOptions & BrowserLevel.BatchOptions +export type BatchOperation = ClassicLevel.BatchOperation & BrowserLevel.BatchOperation +export type ChainedBatch = ClassicLevel.ChainedBatch & BrowserLevel.ChainedBatch + +export type Iterator = ClassicLevel.Iterator & BrowserLevel.Iterator +export type KeyIterator = ClassicLevel.KeyIterator & BrowserLevel.KeyIterator +export type ValueIterator = ClassicLevel.ValueIterator & BrowserLevel.ValueIterator + +export type IteratorOptions = ClassicLevel.IteratorOptions & BrowserLevel.IteratorOptions +export type KeyIteratorOptions = ClassicLevel.KeyIteratorOptions & BrowserLevel.KeyIteratorOptions +export type ValueIteratorOptions = ClassicLevel.ValueIteratorOptions & BrowserLevel.ValueIteratorOptions diff --git a/index.js b/index.js new file mode 100644 index 0000000..f374cea --- /dev/null +++ b/index.js @@ -0,0 +1 @@ +exports.Level = require('classic-level').ClassicLevel diff --git a/level.js b/level.js deleted file mode 100644 index 08e6e56..0000000 --- a/level.js +++ /dev/null @@ -1 +0,0 @@ -module.exports = require('level-packager')(require('leveldown')) diff --git a/package.json b/package.json index 1da9e4c..f1e9489 100644 --- a/package.json +++ b/package.json @@ -1,37 +1,38 @@ { "name": "level", "version": "7.0.1", - "description": "Fast & simple storage - a Node.js-style LevelDB wrapper (a convenience package bundling LevelUP & LevelDOWN)", + "description": "Universal abstract-level database for Node.js and browsers", "license": "MIT", - "main": "level.js", + "main": "index.js", + "types": "./index.d.ts", "scripts": { - "test": "standard && nyc node test.js", - "test-browsers-local": "airtap --verbose test-browser.js", - "coverage": "nyc report -r lcovonly", - "hallmark": "hallmark --fix", - "dependency-check": "dependency-check --no-dev . browser.js", - "prepublishOnly": "npm run dependency-check" + "test": "standard && ts-standard *.ts && nyc node test.js", + "test-browsers-local": "airtap --coverage test.js && nyc report", + "coverage": "nyc report -r lcovonly" }, "files": [ "browser.js", - "level.js", + "index.js", + "index.d.ts", "CHANGELOG.md", "UPGRADING.md" ], "browser": "browser.js", "dependencies": { - "level-js": "^6.1.0", - "level-packager": "^6.0.1", - "leveldown": "^6.1.0" + "browser-level": "^1.0.1", + "classic-level": "^1.2.0" }, "devDependencies": { + "@types/node": "^17.0.23", + "@voxpelli/tsconfig": "^3.1.0", "airtap": "^4.0.1", "airtap-playwright": "^1.0.1", - "dependency-check": "^4.1.0", "hallmark": "^4.0.0", "nyc": "^15.0.0", "standard": "^16.0.3", "tape": "^5.0.1", + "ts-standard": "^11.0.0", + "typescript": "^4.5.5", "uuid": "^8.3.2" }, "funding": { @@ -54,6 +55,6 @@ "json" ], "engines": { - "node": ">=10.12.0" + "node": ">=12" } } diff --git a/test-browser.js b/test-browser.js deleted file mode 100644 index f694829..0000000 --- a/test-browser.js +++ /dev/null @@ -1,71 +0,0 @@ -'use strict' - -const test = require('tape') -const { v4: uuid } = require('uuid') -const level = require('.') - -require('level-packager/abstract/base-test')(test, level) -require('level-packager/abstract/db-values-test')(test, level) - -function factory (opts) { - return level(uuid(), opts) -} - -test('level put', function (t) { - t.plan(4) - - const db = factory() - - db.put('name', 'level', function (err) { - t.ifError(err, 'no put error') - - db.get('name', function (err, value) { - t.ifError(err, 'no get error') - t.is(value, 'level') - - db.close(function (err) { - t.ifError(err, 'no close error') - }) - }) - }) -}) - -test('level Buffer value', function (t) { - t.plan(5) - - const db = factory({ valueEncoding: 'binary' }) - const buf = Buffer.from('00ff', 'hex') - - db.put('binary', buf, function (err) { - t.ifError(err, 'no put error') - - db.get('binary', function (err, value) { - t.ifError(err, 'no get error') - t.ok(Buffer.isBuffer(value), 'is a buffer') - t.same(value, buf) - - db.close(function (err) { - t.ifError(err, 'no close error') - }) - }) - }) -}) - -test('level Buffer key', function (t) { - const db = factory({ keyEncoding: 'binary' }) - const key = Buffer.from('00ff', 'hex') - - db.put(key, 'value', function (err) { - t.ifError(err, 'no put error') - - db.get(key, function (err, value) { - t.ifError(err, 'no get error') - t.is(value, 'value') - - db.close(function (err) { - t.ifError(err, 'no close error') - t.end() - }) - }) - }) -}) diff --git a/test.js b/test.js index 1fceddd..828c692 100644 --- a/test.js +++ b/test.js @@ -1 +1,14 @@ -require('level-packager/abstract/test')(require('tape'), require('./')) +'use strict' + +const test = require('tape') +const { v4: uuid } = require('uuid') +const { Level } = require('.') + +// Because we directly export classic-level or browser-level +// without wrapping them, there's no need for further tests here. +test('smoke test', async function (t) { + const db = new Level('db/' + uuid()) + await db.put('abc', '123') + t.is(await db.get('abc'), '123') + return db.close() +}) diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..cb87215 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,7 @@ +{ + "extends": "@voxpelli/tsconfig/node12.json", + "compilerOptions": { + "checkJs": false + }, + "include": ["*.ts", "types/*.ts"] +}