From 2fc6f1e357d71c06d5cf693ee0dba319fdad4afa Mon Sep 17 00:00:00 2001 From: Vincent Weevers Date: Sun, 13 Oct 2019 15:49:56 +0200 Subject: [PATCH] Document manifest, iterator() and clear() Closes #161 Ref Level/community#83 Ref Level/community#79 --- README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/README.md b/README.md index 5ff7cf8..2e3f92f 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,7 @@ If you want to use [Promises](#promise-support), you will need a polyfill like [ For options specific to [`leveldown`][leveldown] and [`level-js`][level-js] ("underlying store" from here on out), please see their respective READMEs. - level() +- db.supports - db.open() - db.close() - db.put() @@ -89,6 +90,8 @@ For options specific to [`leveldown`][leveldown] and [`level-js`][level-js] ("un - db.createReadStream() - db.createKeyStream() - db.createValueStream() +- db.iterator() +- db.clear() @@ -139,6 +142,22 @@ level('my-db', { createIfMissing: false }, function (err, db) { Note that `createIfMissing` is an option specific to [`leveldown`][leveldown]. + + +### `db.supports` + +A read-only [manifest](https://github.com/Level/supports). Not [widely supported yet](https://github.com/Level/community/issues/83). Might be used like so: + +```js +if (!db.supports.permanence) { + throw new Error('Persistent storage is required') +} + +if (db.supports.bufferKeys && db.supports.promises) { + await db.put(Buffer.from('key'), 'value') +} +``` + ### `db.open([callback])` @@ -393,6 +412,29 @@ db.createReadStream({ keys: false, values: true }) }) ``` + + +### `db.iterator([options])` + +Returns an [`abstract-leveldown` iterator](https://github.com/Level/abstract-leveldown/#abstractleveldown_iteratoroptions), which is what powers the readable streams above. Options are the same as the range options of createReadStream and are passed to the underlying store. + + + +### `db.clear([options][, callback])` + +**This method is experimental. Not all underlying stores support it yet. Consult [Level/community#79](https://github.com/Level/community/issues/79) to find out if your (combination of) dependencies support `db.clear()`.** + +Delete all entries or a range. Not guaranteed to be atomic. Accepts the following range options (with the same rules as on iterators): + +- `gt` (greater than), `gte` (greater than or equal) define the lower bound of the range to be deleted. Only entries where the key is greater than (or equal to) this option will be included in the range. When `reverse=true` the order will be reversed, but the entries deleted will be the same. +- `lt` (less than), `lte` (less than or equal) define the higher bound of the range to be deleted. Only entries where the key is less than (or equal to) this option will be included in the range. When `reverse=true` the order will be reversed, but the entries deleted will be the same. +- `reverse` _(boolean, default: `false`)_: delete entries in reverse order. Only effective in combination with `limit`, to remove the last N records. +- `limit` _(number, default: `-1`)_: limit the number of entries to be deleted. This number represents a _maximum_ number of entries and may not be reached if you get to the end of the range first. A value of `-1` means there is no limit. When `reverse=true` the entries with the highest keys will be deleted instead of the lowest keys. + +If no options are provided, all entries will be deleted. The `callback` function will be called with no arguments if the operation was successful or with an `WriteError` if it failed for any reason. + +If no callback is passed, a promise is returned. + ## Promise Support `level(up)` ships with native `Promise` support out of the box. @@ -404,6 +446,7 @@ Each function taking a callback also can be used as a promise, if the callback i - `db.del(key[, options])` - `db.batch(ops[, options])` - `db.batch().write()` +- `db.clear(options)` The only exception is the `level` constructor itself, which if no callback is passed will lazily open the underlying store in the background.