Skip to content

Commit

Permalink
Breaking: add hooks and deprecate batch, put & del events (#45)
Browse files Browse the repository at this point in the history
- 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`.
  • Loading branch information
vweevers committed Jan 27, 2024
1 parent a56d2ae commit bcb4192
Show file tree
Hide file tree
Showing 27 changed files with 2,736 additions and 219 deletions.
432 changes: 392 additions & 40 deletions README.md

Large diffs are not rendered by default.

34 changes: 34 additions & 0 deletions UPGRADING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ This document describes breaking changes and how to upgrade. For a complete list

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

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

</details>

## Upcoming

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`:

```js
const indexes = db.sublevel('idx')
const colorIndex = indexes.sublevel('colors')
```

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.

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`:

```js
const colorIndex = db.sublevel(['idx', 'colors'])
```

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`:

```js
const colorIndex = indexes.sublevel('colors')
const flavorIndex = indexes.sublevel('flavors')

// No longer works because colorIndex isn't a descendant of flavorIndex
flavorIndex.batch([{ type: 'del', key: 'blue', sublevel: colorIndex }])

// OK
indexes.batch([{ type: 'del', key: 'blue', sublevel: colorIndex }])

// OK
db.batch([{ type: 'del', key: 'blue', sublevel: colorIndex }])
```

## 1.0.0

**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.**
Expand Down
Loading

0 comments on commit bcb4192

Please sign in to comment.