You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
86 lines
3.9 KiB
86 lines
3.9 KiB
# Upgrade Guide
|
|
|
|
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).
|
|
|
|
## v4
|
|
|
|
There have been two major updates to dependencies. First, `level-iterator-stream` is now based on [`readable-stream@3`](https://github.com/nodejs/readable-stream#version-3xx). Second, `deferred-leveldown` is now based on [`abstract-leveldown@6`](https://github.com/Level/abstract-leveldown/blob/master/UPGRADING.md#v6). Please follow these links for more information; both contain significant enough changes to warrant this `levelup` major. In addition, all aforementioned dependencies and by extension `levelup` have dropped support of IE10.
|
|
|
|
To get a consistent behavior between opening and opened `levelup` instances (in the former case, your store will be wrapped with `deferred-leveldown`), we recommend to pair `levelup@4` only with a store based on `abstract-leveldown` >= 6. For example, `deferred-leveldown` now rejects `null` and `undefined` values. If you pair `levelup@4` with an older store, `db.put('key', null)` would only throw an error if `db` is still opening itself.
|
|
|
|
## v3
|
|
|
|
1. Dropped support for node 4.
|
|
2. Batch operations no longer default to `'put'`. If `type` isn't specified, an error will be thrown, courtesy of `abstract-leveldown`.
|
|
|
|
## v2
|
|
|
|
### Summary
|
|
|
|
There has been quite some work done for this new major version:
|
|
|
|
1. Make `levelup` more generic by reducing focus on [`leveldown`](https://github.com/Level/leveldown) and [`LevelDB`](https://github.com/google/leveldb).
|
|
2. Make `levelup` more generic by removing code related to encodings, which would allow \*down implementations to manage encodings themselves.
|
|
3. Use [`standard`](https://github.com/standard/standard) as linter to avoid bikeshedding.
|
|
4. Add a native `Promise` API for promise using geeks. Many have been asking for this. Also `async/await` is awesome. Breaking change: previously, if you did not pass a callback to an async function and there was an error, `levelup` would emit an `error` event instead. This is no longer true.
|
|
|
|
Point `1` and `2` also helps out with reducing complexity.
|
|
|
|
### Upgrade Guide
|
|
|
|
Since `levelup` no longer tries to load `leveldown` as a default backend you have to provide a backend instance yourself.
|
|
|
|
So if you previously did:
|
|
|
|
```
|
|
$ npm i levelup leveldown --save
|
|
```
|
|
|
|
And in your code you did something like:
|
|
|
|
```js
|
|
const levelup = require('levelup')
|
|
const db = levelup('/path/to/db')
|
|
```
|
|
|
|
You should now do (for identical functionality):
|
|
|
|
```js
|
|
const levelup = require('levelup')
|
|
const encode = require('encoding-down')
|
|
const leveldown = require('leveldown')
|
|
const db = levelup(encode(leveldown('/path/to/db')))
|
|
```
|
|
|
|
Note that we have moved out encodings into [`encoding-down`](https://github.com/level/encoding-down), which in itself is a \*down that wraps a \*down (meta ftw). It basically just sits in between `levelup` and the _actual_ backend to operate on encodings for keys and values. Default encoding is `'utf8'` like before.
|
|
|
|
This obviously means everyone has to do a lot of code rewrite which is bad. So we aim to fix this by putting that code into [`level@2.0.0`](https://github.com/level/level), which already is used as a convenience package.
|
|
|
|
Switching from `levelup` and `leveldown` combo to only using `level` you would do:
|
|
|
|
```js
|
|
const level = require('level')
|
|
const db = level('/path/to/db')
|
|
```
|
|
|
|
Also, we aim to simplify using `memdown` in the same way by updating `level-mem`.
|
|
|
|
For more advanced usage with custom versions of `abstract-leveldown`, the first parameter to `levelup()` should be an `abstract-leveldown` instead of passing a factory function via `options.db`.
|
|
|
|
So if you previously did:
|
|
|
|
```js
|
|
const db = levelup('/path/to/db', {
|
|
db: function (location) {
|
|
return new CustomLevelDOWN(location)
|
|
}
|
|
})
|
|
```
|
|
|
|
You should now do (for identical functionality):
|
|
|
|
```js
|
|
const encode = require('encoding-down')
|
|
const db = levelup(encode(new CustomLevelDOWN('/path/to/db')))
|
|
```
|