diff --git a/README.md b/README.md index 6c2894d..adb588c 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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: @@ -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)` diff --git a/UPGRADING.md b/UPGRADING.md index 970468b..db3463e 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -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) @@ -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.**