Skip to content

Commit bcb4192

Browse files
committed
Breaking: add hooks and deprecate batch, put & del events (#45)
- Adds postopen, prewrite and newsub hooks that allow userland "hook functions" to customize behavior of the database. - Introduces a new `write` event that is emitted on `db.batch()`, `db.put()` and `db.del()`. - Restores support of userland options on batch operations. - Changes nested sublevels to be actually nested. Comes with two low-impact breaking changes, described in `UPGRADING.md`.
1 parent a56d2ae commit bcb4192

27 files changed

+2736
-219
lines changed

README.md

Lines changed: 392 additions & 40 deletions
Large diffs are not rendered by default.

UPGRADING.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ This document describes breaking changes and how to upgrade. For a complete list
66

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

9+
- [Upcoming](#upcoming)
910
- [1.0.0](#100)
1011
- [1. API parity with `levelup`](#1-api-parity-with-levelup)
1112
- [1.1. New: promises](#11-new-promises)
@@ -31,6 +32,39 @@ This document describes breaking changes and how to upgrade. For a complete list
3132

3233
</details>
3334

35+
## Upcoming
36+
37+
The next major release adds [hooks](./README.md#hooks). To achieve hooks, two low-impact breaking changes have been made to nested sublevels. Nested sublevels, no matter their depth, were previously all connected to the same parent database rather than forming a tree. In the following example, the `colorIndex` sublevel would previously forward its operations directly to `db`:
38+
39+
```js
40+
const indexes = db.sublevel('idx')
41+
const colorIndex = indexes.sublevel('colors')
42+
```
43+
44+
It will now forward its operations to `indexes`, which in turn forwards them to `db`. At each step, hooks and events are available to transform and react to data from a different perspective. Which comes at a (typically small) performance cost that increases with further nested sublevels. This decreased performance is the **first breaking change** and mainly affects sublevels nested at a depth of more than 2.
45+
46+
To optionally negate it, a new feature has been added to `db.sublevel(name)`: it now also accepts a `name` that is an array. If the `indexes` sublevel is only used to organize keys and not directly interfaced with, operations on `colorIndex` can be made faster by skipping `indexes`:
47+
48+
```js
49+
const colorIndex = db.sublevel(['idx', 'colors'])
50+
```
51+
52+
The **second breaking change** is that if a `sublevel` is provided as an option to `db.batch()`, that sublevel must now be a descendant of `db`:
53+
54+
```js
55+
const colorIndex = indexes.sublevel('colors')
56+
const flavorIndex = indexes.sublevel('flavors')
57+
58+
// No longer works because colorIndex isn't a descendant of flavorIndex
59+
flavorIndex.batch([{ type: 'del', key: 'blue', sublevel: colorIndex }])
60+
61+
// OK
62+
indexes.batch([{ type: 'del', key: 'blue', sublevel: colorIndex }])
63+
64+
// OK
65+
db.batch([{ type: 'del', key: 'blue', sublevel: colorIndex }])
66+
```
67+
3468
## 1.0.0
3569

3670
**Introducing `abstract-level`: a fork of [`abstract-leveldown`](https://github.com/Level/abstract-leveldown) that removes the need for [`levelup`](https://github.com/Level/levelup), [`encoding-down`](https://github.com/Level/encoding-down) and more. An `abstract-level` database is a complete solution that doesn't need to be wrapped. It has the same API as `level(up)` including encodings, promises and events. In addition, implementations can now choose to use Uint8Array instead of Buffer. Consumers of an implementation can use both. Sublevels are builtin.**

0 commit comments

Comments
 (0)