# subleveldown

> Split a levelup database into sublevels with their own keyspace, encoding and events

Latest version **6.0.1** (published 2021-10-02) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install subleveldown
pnpm add subleveldown
yarn add subleveldown
bun add subleveldown
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 6.0.1 |
| Published | 2021-10-02 |
| First published | 2014-12-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/subleveldown) |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 6 |
| Unpacked size | 36.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 119 |
| Author | Mathias Buus |
| Maintainers | vweevers, mafintosh, ralphtheninja |
| Keywords | level |

## Links

- npm: https://www.npmjs.com/package/subleveldown
- Repository: https://github.com/Level/subleveldown
- Issues: https://github.com/Level/subleveldown/issues
- npm.io page: https://npm.io/package/subleveldown

## Dependencies (6)

- [levelup](https://npm.io/package/levelup.md) ^5.1.1
- [inherits](https://npm.io/package/inherits.md) ^2.0.3
- [reachdown](https://npm.io/package/reachdown.md) ^1.1.0
- [encoding-down](https://npm.io/package/encoding-down.md) ^7.1.0
- [level-option-wrap](https://npm.io/package/level-option-wrap.md) ^1.1.0
- [abstract-leveldown](https://npm.io/package/abstract-leveldown.md) ^7.2.0

## Recent versions

- 6.0.1 (latest) — 2021-10-02
- 6.0.0 — 2021-10-01
- 5.0.1 — 2020-06-26
- 5.0.0 — 2020-04-05
- 4.1.4 — 2019-10-08
- 4.1.3 — 2019-09-17
- 4.1.2 — 2019-09-12
- 4.1.1 — 2019-08-18
- 4.1.0 — 2019-06-28
- 4.0.0 — 2019-04-06
- 3.0.1 — 2018-07-27
- 3.0.0 — 2018-06-07
- 3.0.0-rc1 — 2018-06-03
- 2.1.0 — 2015-10-30
- 2.0.0 — 2015-02-03
- … 8 more at https://npm.io/package/subleveldown/versions

## README

# subleveldown

> Split a [`levelup`][levelup] database into _sublevels_ with their own keyspace, encoding and events.

[![level badge][level-badge]](https://github.com/Level/awesome)
[![npm](https://img.shields.io/npm/v/subleveldown.svg)](https://www.npmjs.com/package/subleveldown)
[![Node version](https://img.shields.io/node/v/subleveldown.svg)](https://www.npmjs.com/package/subleveldown)
[![Test](https://img.shields.io/github/workflow/status/Level/subleveldown/Test?label=test)](https://github.com/Level/subleveldown/actions/workflows/test.yml)
[![Coverage](https://img.shields.io/codecov/c/github/Level/subleveldown?label=&logo=codecov&logoColor=fff)](https://codecov.io/gh/Level/subleveldown)
[![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)

## Table of Contents

<details><summary>Click to expand</summary>

- [Usage](#usage)
- [Background](#background)
- [API](#api)
  - [`subdb = sub(db[, prefix][, options])`](#subdb--subdb-prefix-options)
- [Install](#install)
- [Contributing](#contributing)
- [Donate](#donate)
- [License](#license)

</details>

## Usage

_If you are upgrading: please see [UPGRADING.md](UPGRADING.md)._

```js
const sub = require('subleveldown')
const level = require('level')

const db = level('db')
const example = sub(db, 'example')
const nested = sub(example, 'nested')
```

The `example` and `nested` db's are just regular [`levelup`][levelup] instances:

```js
example.put('hello', 'world', function () {
  nested.put('hi', 'welt', function () {
    // Prints { key: 'hi', value: 'welt' }
    nested.createReadStream().on('data', console.log)
  })
})
```

Or with promises and iterators:

```js
await example.put('hello', 'world')
await nested.put('hi', 'welt')

for await (const [key, value] of nested.iterator()) {
  // Prints ['hi', 'welt']
  console.log([key, value])
}
```

Sublevels see their own keys as well as keys of any nested sublevels:

```js
// Prints:
// { key: '!nested!hi', value: 'welt' }
// { key: 'hello', value: 'world' }
example.createReadStream().on('data', console.log)
```

They also support `db.clear()` which is very useful to empty a bucket of stuff:

```js
example.clear(function (err) {})

// Or delete a range within `example`
example.clear({ gt: 'hello' }, function (err) {})

// With promises
await example.clear()
```

## Background

`subleveldown` separates a [`levelup`][levelup] database into sections - or _sublevels_ from here on out. Think SQL tables, but evented, ranged and realtime!

Each sublevel is a `levelup` of its own. This means it has the exact same interface as its parent database, but its own keyspace and [events](https://github.com/Level/levelup#events). In addition, sublevels are individually wrapped with [`encoding-down`][encoding-down], giving us per-sublevel encodings. For example, it's possible to have one sublevel with Buffer keys and another with `'utf8'` encoded keys. The same goes for values. Like so:

```js
sub(db, 'one', { valueEncoding: 'json' })
sub(db, 'two', { keyEncoding: 'binary' })
```

There is one limitation, however: keys must _encode to_ either strings or Buffers. This is not likely to affect you, unless you use custom encodings or the `id` encoding (which bypasses encodings and thus makes it your responsibility to ensure keys are either strings or Buffers). If in that case you do pass in a key that is not a string or Buffer, it will be irreversibly converted to a string.

Authored by [@mafintosh](https://github.com/mafintosh) and inspired by [`level-sublevel`][level-sublevel] by [@dominictarr](https://github.com/dominictarr), `subleveldown` has become an official part of [Level][level-org]. As `level-sublevel` is no longer under active development, we recommend switching to `subleveldown` to get the latest and greatest of the Level ecosystem. These two modules largely offer the same functionality, except for [hooks](https://github.com/dominictarr/level-sublevel#hooks) and [per-batch prefixes](https://github.com/dominictarr/level-sublevel#batches).

## API

### `subdb = sub(db[, prefix][, options])`

Returns a `levelup` instance that uses subleveldown to prefix the keys of the underlying store of `db`. The required `db` parameter must be a `levelup` instance. Any layers that this instance may have (like `encoding-down` or `subleveldown` itself) are peeled off to get to the innermost [`abstract-leveldown`][abstract-leveldown] compliant store (like `leveldown`). This ensures there is no double encoding step.

The `prefix` must be a string. If omitted, the effective prefix is two separators, e.g. `'!!'`. If `db` is already a subleveldown-powered instance, the effective prefix is a combined prefix, e.g. `'!one!!two!'`.

The optional `options` parameter has the following `subleveldown` specific properties:

- `separator` _(string, default: `'!'`)_ Character for separating sublevel prefixes from user keys and each other. Must sort before characters used in prefixes. An error will be thrown if that's not the case.
- `open` _(function)_ Optional open hook called when the underlying `levelup` instance has been opened. The hook receives a callback which must be called to finish opening.

Any other `options` are passed along to the underlying [`levelup`][levelup] and [`encoding-down`][encoding-down] constructors. See their documentation for further details.

## Install

With [npm](https://npmjs.org) do:

```
npm i subleveldown -S
```

## Contributing

[`Level/subleveldown`](https://github.com/Level/subleveldown) is an **OPEN Open Source Project**. This means that:

> Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the [Contribution Guide](https://github.com/Level/community/blob/master/CONTRIBUTING.md) for more details.

## Donate

Support us with a monthly donation on [Open Collective](https://opencollective.com/level) and help us continue our work.

## License

[MIT](LICENSE)

[level-badge]: https://leveljs.org/img/badge.svg

[levelup]: https://github.com/Level/levelup

[encoding-down]: https://github.com/Level/encoding-down

[abstract-leveldown]: https://github.com/Level/abstract-leveldown

[level-sublevel]: https://github.com/dominictarr/level-sublevel

[level-org]: https://github.com/Level

---
_Source: https://npm.io/package/subleveldown · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._