# level-spaces

> Namespaced LevelUP instances

Latest version **2.0.1** (published 2015-09-13) · MIT license · 0 weekly downloads

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

## Install

```sh
npm install level-spaces
pnpm add level-spaces
yarn add level-spaces
bun add level-spaces
```

## Health

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

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2015-09-13 |
| First published | 2014-08-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Author | Rod Vagg |
| Maintainers | rvagg |
| Keywords | level, levelup, namespaces, sublevel, tiramisu |

## Links

- npm: https://www.npmjs.com/package/level-spaces
- Repository: https://github.com/rvagg/level-spaces
- Issues: https://github.com/rvagg/level-spaces/issues
- npm.io page: https://npm.io/package/level-spaces

## Dependencies (3)

- [xtend](https://npm.io/package/xtend.md) >=4.0.0 <4.1.0-0
- [levelup](https://npm.io/package/levelup.md) >=0.19.0 <0.20.0-0
- [level-updown](https://npm.io/package/level-updown.md) >=2.0.0 <2.1.0-0

## Recent versions

- 2.0.1 (latest) — 2015-09-13
- 2.0.0 — 2015-02-10
- 1.1.1 — 2014-08-28
- 1.1.0 — 2014-08-28
- 1.0.1 — 2014-08-24
- 1.0.0 — 2014-08-24

## README

# level-spaces

**A simple namespacing solution for LevelUP**

[![NPM](https://nodei.co/npm/level-spaces.png?downloads=true&downloadRank=true)](https://nodei.co/npm/level-spaces/)
[![NPM](https://nodei.co/npm-dl/level-spaces.png?months=6&height=3)](https://nodei.co/npm/level-spaces/)

## Why?

Inspired by [level-sublevel](https://github.com/dominictarr/level-sublevel), **level-spaces** provides a simple mechanism for creating namespaced *views* of a **[LevelUP](https://github.com/rvagg/node-levelup)** data store. At a basic level this can be thought of as a way to provide the k/v store equivalent of relational database "tables".

**level-spaces** is aimed at basic use-cases and does not introduce any versioning problems by modifying the original LevelUP instance. Each instance of **level-spaces** is independent and therefore an application may include many separate versions of **level-spaces** in use by different packages. This makes it an ideal solution for storing metadata in LevelUP extensions (such as that in [level-ttl](https://github.com/rvagg/node-level-ttl/)). **level-spaces** does not provide direct mechanisms to intercept writes and turn them into batches *across* namespaces. If you need to write metadata atomically then you should consider **[level-sublevel](https://github.com/rvagg/level-sublevel)** instead.

**level-spaces** uses **[level-updown](https://github.com/rvagg/level-updown)** to implement its functionality and it can therefore return a new LevelUP instance, unmodified (un-*monkey-patched*!) in any way. You can then use that LevelUP instance to plug in additional LevelUP extensions and pass it around as if it was an entirely independent LevelUP store. In fact, you can even pass the new LevelUP instance back in to **level-spaces** to get hierarchical namespaces built on multiple levels of LevelUP / level-spaces / level-updown / LevelDOWN.

## How?

Currently **level-spaces** **only supports `String` keys** (UTF-8), although LevelUP may pass it stringified JSON objects as keys as well (this is transparent). If you have more complicated needs for your keys then you should consider **[level-sublevel](https://github.com/rvagg/level-sublevel)** instead.

A namespace is specified as a `String`. This `String` has the character `~` (configurable) prepended to the beginning and appended to the end and is then *prefixed* to all reads and writes to the underlying LevelUP.

So, if you have a namespace of `'foobar'`, all keys written will transparently be prefixed with `'~foobar~'` and all reads will have keys transparently prefixed with `'~foobar~'`. All keys that come from an iterator / read-stream will also have `'~foobar~'` removed from them, making the prefixing entirely transparent. You will not be able to see the raw keys from a **level-spaces** instance but they will be visible from the LevelUP used to create it.

Note, however, that **child namespaces will not be hidden** from within a level-spaces instance. If you have a heirarchy of namespaces, or are using additional libaries that do, take care, particularly when using read streams, to operate only on the keys you actually want.

If you have multiple levels of **level-spaces** you will end up with multiple prefixes appended one after the other, each surrounded by `~`. So a **level-spaces** instance with the prefix `'foobar'` that is passed back in to create a new **level-spaces** instance with a prefix `'doobar'` will end up using keys prefixed with `~foobar~~doobar~`.

Additionally, when you call `createReadStream()` on a LevelUP created by **level-spaces**, the options will be rewritten to properly account for the underlying namespace: `'start'`, `'end'`, `'gt'`, `'gte'`, `'lt'`, `'lte'`, so the LevelUP read-stream operates only within the namespace as if there was no other range of keys in the store.

## Examples

```js
var levelup = require('levelup')
  , spaces  = require('../')
  , after   = require('after')

var db       = levelup('foo.db')
  , space1   = spaces(db, 'space 1')
  , space2   = spaces(db, 'space 2')
  , space1_1 = spaces(space1, 'space 1.1')

var done = after(4, dump)

;[ db, space1, space2, space1_1 ].forEach(function (db, i) {
  var key = 'foo ' + i
  db.put(key, 'bar ' + i, function () {
    db.get(key, function (err, value) {
      console.log('[%s] = [%s]', key, value)
      done()
    })
  })
})

function dump () {
  db.createReadStream().on('data', console.log)
}
```

Gives us the output:

```text
[foo 0] = [bar 0]
[foo 1] = [bar 1]
[foo 2] = [bar 2]
[foo 3] = [bar 3]
{ key: 'foo 0', value: 'bar 0' }
{ key: 'ÿspace 1ÿfoo 1', value: 'bar 1' }
{ key: 'ÿspace 1ÿÿspace 1.1ÿfoo 3', value: 'bar 3' }
{ key: 'ÿspace 2ÿfoo 2', value: 'bar 2' }
```

Note how each LevelUP instance appears to be writing and reading in the same way but the underlying data store has namespaced keys.

## API

### spaces(db, namespace[, options])

Create a new LevelUP instance from an existing one (supplied as `db`) where keys are namespaced into the `namespace` string.

The optional `options` object will be passed to LevelUP but can also contain:

* `'separator'`: to override the default `'~'` separator with something custom.

## License

**level-spaces** is Copyright (c) 2014 Rod Vagg [@rvagg](https://twitter.com/rvagg) and licensed under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.

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