Skip to content

Commit

Permalink
Add db.keys(), .values(), iterator.nextv() and .all()
Browse files Browse the repository at this point in the history
I'm squeezing this in for similar reasons as #8. I wondered whether
these additions would be breaking. The short answer is no. In
addition, adding this now means `level-read-stream` can make use of
it without conditional code paths based on `db.supports.*`.

Ref Level/abstract-leveldown#380

Adds key and value iterators: `db.keys()` and `db.values()`. As
a replacement for levelup's `db.create{Key,Value}Stream()`. Example:

```
for await (const key of db.keys({ gte: 'a' }) {
  console.log(key)
}
```

Adds two new methods to all three types of iterators: `nextv()` for
getting many items (entries, keys or values) in one call and `all()`
for getting all (remaining) items. These methods have functional
but suboptimal defaults: `all()` falls back to repeatedly calling
`nextv()` and that in turn falls back to `next()`. Example:

```
const values = await db.values({ limit: 10 }).all()
```

Adds a lot of new code, with unfortunately some duplicate code
because I wanted to avoid mixins and other forms of complexity,
which means key and value iterators use classes that are separate
from preexisting iterators. For example, a method like `_seek()`
must now be implemented on three classes: `AbstractIterator`,
`AbstractKeyIterator` and `AbstractValueIterator`. This (small?)
problem extends to implementations and their subclasses, if they
choose to override key and value iterators to improve performance.

On the flip side, the new methods are supported across the board:
on sublevels, with encodings, with deferred open, and fully
functional. This may demonstrate one of the major benefits of
`abstract-level` over `abstract-leveldown` paired with `levelup`.

Yet todo:

- [ ] Tests
- [ ] Replace use of `level-concat-iterator` in existing tests
- [ ] After that, try another approach with a `mode` property on
      iterators, that is one of entries, keys or values (moving
      logic to if-branches... I already don't like it but it may
      result in cleaner logic downstream).
  • Loading branch information
vweevers committed Jan 9, 2022
1 parent df94011 commit d542126
Show file tree
Hide file tree
Showing 13 changed files with 1,129 additions and 153 deletions.
283 changes: 242 additions & 41 deletions README.md

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions UPGRADING.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,8 @@ super({

Node.js readable streams must now be created with a new standalone module called [`level-read-stream`](https://github.com/Level/read-stream), rather than database methods like `db.createReadStream()`. Please see its [upgrade guide](https://github.com/Level/read-stream/blob/main/UPGRADING.md#100) for details.

To offer an alternative to `db.createKeyStream()` and `db.createValueStream()`, two new types of iterators have been added: `db.keys()` and `db.values()`. Their default implementations are functional but implementors may want to override them for optimal performance. The same goes for two new methods on iterators: `nextv()` and `all()`. Please see the README for details.

### 4. Zero-length keys and range options are now valid

These keys sort before anything else. Historically they weren't supported for causing segmentation faults in `leveldown`. That doesn't apply to today's codebase. Implementations must now support:
Expand Down
Loading

0 comments on commit d542126

Please sign in to comment.