Skip to content

Breaking: require snapshots to be created synchronously #54

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 10, 2022
Merged

Breaking: require snapshots to be created synchronously #54

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,8 +282,6 @@ Get a value from the database by `key`. The optional `options` object may contai

Returns a promise for the value. If the `key` was not found then the value will be `undefined`.

If the database indicates support of snapshots via `db.supports.snapshots` then `db.get()` _should_ read from a snapshot of the database, created at the time `db.get()` was called. This means it should not see the data of simultaneous write operations. However, this is currently not verified by the [abstract test suite](#test-suite).

### `db.getMany(keys[, options])`

Get multiple values from the database by an array of `keys`. The optional `options` object may contain:
Expand All @@ -293,8 +291,6 @@ Get multiple values from the database by an array of `keys`. The optional `optio

Returns a promise for an array of values with the same order as `keys`. If a key was not found, the relevant value will be `undefined`.

If the database indicates support of snapshots via `db.supports.snapshots` then `db.getMany()` _should_ read from a snapshot of the database, created at the time `db.getMany()` was called. This means it should not see the data of simultaneous write operations. However, this is currently not verified by the [abstract test suite](#test-suite).

### `db.put(key, value[, options])`

Add a new entry or overwrite an existing entry. The optional `options` object may contain:
Expand Down Expand Up @@ -1394,12 +1390,16 @@ The default `_close()` is an async noop. In native implementations (native addon

Get a value by `key`. The `options` object will always have the following properties: `keyEncoding` and `valueEncoding`. Must return a promise. If an error occurs, reject the promise. Otherwise resolve the promise with the value. If the `key` was not found then use `undefined` as value.

If the database indicates support of snapshots via `db.supports.snapshots` then `db._get()` must read from a snapshot of the database. That snapshot (or similar mechanism) must be created synchronously when `db._get()` is called, before asynchronously reading the value. This means it should not see the data of write operations that are scheduled immediately after `db._get()`.

The default `_get()` returns a promise for an `undefined` value. It must be overridden.

### `db._getMany(keys, options)`

Get multiple values by an array of `keys`. The `options` object will always have the following properties: `keyEncoding` and `valueEncoding`. Must return a promise. If an error occurs, reject the promise. Otherwise resolve the promise with an array of values. If a key does not exist, set the relevant value to `undefined`.

Snapshot behavior of `db._getMany()` must be the same as described for `db._get()` above.

The default `_getMany()` returns a promise for an array of values that is equal in length to `keys` and is filled with `undefined`. It must be overridden.

### `db._put(key, value, options)`
Expand Down
5 changes: 5 additions & 0 deletions UPGRADING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ This document describes breaking changes and how to upgrade. For a complete list
- [2.1. Promises all the way](#21-promises-all-the-way)
- [2.2. Ticks](#22-ticks)
- [2.3. A new way to abort iterator work](#23-a-new-way-to-abort-iterator-work)
- [2.4. Snapshots must be synchronous](#24-snapshots-must-be-synchronous)
- [1.0.0](#100)
- [1. API parity with `levelup`](#1-api-parity-with-levelup)
- [1.1. New: promises](#11-new-promises)
Expand Down Expand Up @@ -211,6 +212,10 @@ _This section is incomplete._

Closing an iterator now aborts work, if supported by implementation. The undocumented `abortOnClose` option of iterators (added as a workaround for `many-level`) has been removed in favor of AbortSignal.

#### 2.4. Snapshots must be synchronous

If an implementations indicates support of snapshots via `db.supports.snapshots` then the `db._get()` and `db._getMany()` methods are now required to synchronously create their snapshot, rather than asynchronously. For details, please see the [README](./README.md#db_getkey-options). This is a documentation-only change because the abstract test suite cannot verify it.

## 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