You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Dec 1, 2024. It is now read-only.
- Add `for await...of` example
- Remove notice that `db.supports` isn't (wasn't) widely supported
- Remove notice that `db.clear()` is (was) experimental
- Simplify Promise Support section
- Document `status` in preference over `isXX()` utilities
- Remove redundant API table of contents
-[What happened to `db.createWriteStream`?](#what-happened-to-dbcreatewritestream)
37
+
-[What happened to `db.createWriteStream`?](#what-happened-to-dbcreatewritestream)
39
38
-[Promise Support](#promise-support)
40
39
-[Events](#events)
41
40
-[Multi-process Access](#multi-process-access)
@@ -52,7 +51,7 @@
52
51
53
52
LevelDB is a simple key-value store built by Google. It's used in Google Chrome and many other products. LevelDB supports arbitrary byte arrays as both keys and values, singular _get_, _put_ and _delete_ operations, _batched put and delete_, bi-directional iterators and simple compression using the very fast [Snappy](http://google.github.io/snappy/) algorithm.
54
53
55
-
LevelDB stores entries sorted lexicographically by keys. This makes the <ahref="#createReadStream">streaming interface</a> of `levelup` - which exposes LevelDB iterators as [Readable Streams](https://nodejs.org/docs/latest/api/stream.html#stream_readable_streams) - a very powerful query mechanism.
54
+
LevelDB stores entries sorted lexicographically by keys. This makes the streaming interface of `levelup` - which exposes LevelDB iterators as [Readable Streams](https://nodejs.org/docs/latest/api/stream.html#stream_readable_streams) - a very powerful query mechanism.
56
55
57
56
The most common store is [`leveldown`](https://github.com/Level/leveldown/) which provides a pure C++ binding to LevelDB. [Many alternative stores are available](https://github.com/Level/awesome/#stores) such as [`level.js`](https://github.com/Level/level.js) in the browser or [`memdown`](https://github.com/Level/memdown) for an in-memory store. They typically support strings and Buffers for both keys and values. For a richer set of data types you can wrap the store with [`encoding-down`](https://github.com/Level/encoding-down).
58
57
@@ -66,7 +65,7 @@ We aim to support Active LTS and Current Node.js releases as well as browsers. F
66
65
67
66
## Usage
68
67
69
-
**If you are upgrading:** please see [`UPGRADING.md`](UPGRADING.md).
68
+
_If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md)._
70
69
71
70
First you need to install `levelup`! No stores are included so you must also install `leveldown` (for example).
72
71
@@ -99,29 +98,6 @@ db.put('name', 'levelup', function (err) {
- <ahref="#writeStreams">What happened to <code><b>db.createWriteStream()</b></code></a>
122
-
123
-
<aname="ctor"></a>
124
-
125
101
### `levelup(db[, options[, callback]])`
126
102
127
103
The main entry point for creating a new `levelup` instance.
@@ -156,11 +132,9 @@ db.get('foo', function (err, value) {
156
132
})
157
133
```
158
134
159
-
<aname="supports"></a>
160
-
161
135
### `db.supports`
162
136
163
-
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:
137
+
A read-only [manifest](https://github.com/Level/supports). Might be used like so:
164
138
165
139
```js
166
140
if (!db.supports.permanence) {
@@ -172,38 +146,28 @@ if (db.supports.bufferKeys && db.supports.promises) {
172
146
}
173
147
```
174
148
175
-
<aname="open"></a>
176
-
177
149
### `db.open([options][, callback])`
178
150
179
-
Opens the underlying store. In general you should never need to call this method directly as it's automatically called by <ahref="#ctor"><code>levelup()</code></a>.
180
-
181
-
However, it is possible to _reopen_ the store after it has been closed with <ahref="#close"><code>close()</code></a>, although this is not generally advised.
151
+
Opens the underlying store. In general you shouldn't need to call this method directly as it's automatically called by [`levelup()`](#levelupdb-options-callback). However, it is possible to reopen the store after it has been closed with [`close()`](#dbclosecallback).
182
152
183
153
If no callback is passed, a promise is returned.
184
154
185
-
<aname="close"></a>
186
-
187
155
### `db.close([callback])`
188
156
189
-
<code>close()</code> closes the underlying store. The callback will receive any error encountered during closing as the first argument.
157
+
`close()` closes the underlying store. The callback will receive any error encountered during closing as the first argument.
190
158
191
159
You should always clean up your `levelup` instance by calling `close()` when you no longer need it to free up resources. A store cannot be opened by multiple instances of `levelup` simultaneously.
192
160
193
161
If no callback is passed, a promise is returned.
194
162
195
-
<aname="put"></a>
196
-
197
163
### `db.put(key, value[, options][, callback])`
198
164
199
-
<code>put()</code> is the primary method for inserting data into the store. Both `key` and `value` can be of any type as far as `levelup` is concerned.
165
+
`put()` is the primary method for inserting data into the store. Both `key` and `value` can be of any type as far as `levelup` is concerned.
200
166
201
167
`options` is passed on to the underlying store.
202
168
203
169
If no callback is passed, a promise is returned.
204
170
205
-
<aname="get"></a>
206
-
207
171
### `db.get(key[, options][, callback])`
208
172
209
173
Get a value from the store by `key`. The `key` can be of any type. If it doesn't exist in the store then the callback or promise will receive an error. A not-found err object will be of type `'NotFoundError'` so you can `err.type == 'NotFoundError'` or you can perform a truthy test on the property `err.notFound`.
@@ -227,8 +191,6 @@ The optional `options` object is passed on to the underlying store.
227
191
228
192
If no callback is passed, a promise is returned.
229
193
230
-
<aname="get_many"></a>
231
-
232
194
### `db.getMany(keys[, options][, callback])`
233
195
234
196
Get multiple values from the store by an array of `keys`. The optional `options` object is passed on to the underlying store.
@@ -237,11 +199,9 @@ The `callback` function will be called with an `Error` if the operation failed f
237
199
238
200
If no callback is provided, a promise is returned.
239
201
240
-
<aname="del"></a>
241
-
242
202
### `db.del(key[, options][, callback])`
243
203
244
-
<code>del()</code> is the primary method for removing data from the store.
204
+
`del()` is the primary method for removing data from the store.
245
205
246
206
```js
247
207
db.del('foo', function (err) {
@@ -254,16 +214,14 @@ db.del('foo', function (err) {
<code>batch()</code> can be used for very fast bulk-write operations (both _put_ and _delete_). The `array` argument should contain a list of operations to be executed sequentially, although as a whole they are performed as an atomic operation inside the underlying store.
219
+
`batch()` can be used for very fast bulk-write operations (both _put_ and _delete_). The `array` argument should contain a list of operations to be executed sequentially, although as a whole they are performed as an atomic operation inside the underlying store.
262
220
263
221
Each operation is contained in an object having the following properties: `type`, `key`, `value`, where the _type_ is either `'put'` or `'del'`. In the case of `'del'` the `value` property is ignored. Any entries with a `key` of `null` or `undefined` will cause an error to be returned on the `callback` and any `type: 'put'` entry with a `value` of `null` or `undefined` will return an error.
{ type:'put', key:'dob', value:'16 February 1941' },
@@ -281,11 +239,9 @@ db.batch(ops, function (err) {
281
239
282
240
If no callback is passed, a promise is returned.
283
241
284
-
<aname="batch_chained"></a>
285
-
286
242
### `db.batch()`_(chained form)_
287
243
288
-
<code>batch()</code>, when called with no arguments will return a `Batch` object which can be used to build, and eventually commit, an atomic batch operation. Depending on how it's used, it is possible to obtain greater performance when using the chained form of `batch()` over the array form.
244
+
`batch()`, when called with no arguments will return a `Batch` object which can be used to build, and eventually commit, an atomic batch operation. Depending on how it's used, it is possible to obtain greater performance when using the chained form of `batch()` over the array form.
289
245
290
246
```js
291
247
db.batch()
@@ -325,29 +281,19 @@ The optional `options` object is passed to the `.write()` operation of the under
325
281
326
282
If no callback is passed, a promise is returned.
327
283
328
-
<aname="isOpen"></a>
329
-
330
-
### `db.isOpen()`
331
-
332
-
A `levelup` instance can be in one of the following states:
333
-
334
-
-_"new"_ - newly created, not opened or closed
335
-
-_"opening"_ - waiting for the underlying store to be opened
336
-
-_"open"_ - successfully opened the store, available for use
337
-
-_"closing"_ - waiting for the store to be closed
338
-
-_"closed"_ - store has been successfully closed, should not be used
284
+
### `db.status`
339
285
340
-
`isOpen()` will return `true` only when the state is "open".
286
+
A readonly string that is one of:
341
287
342
-
<aname="isClosed"></a>
288
+
-`new` - newly created, not opened or closed
289
+
-`opening` - waiting for the underlying store to be opened
290
+
-`open` - successfully opened the store, available for use
291
+
-`closing` - waiting for the store to be closed
292
+
-`closed` - store has been successfully closed.
343
293
344
-
### `db.isClosed()`
294
+
### `db.isOperational()`
345
295
346
-
_See <ahref="#put"><code>isOpen()</code></a>_
347
-
348
-
`isClosed()` will return `true` only when the state is "closing" _or_ "closed", it can be useful for determining if read and write operations are permissible.
349
-
350
-
<aname="createReadStream"></a>
296
+
Returns `true` if the store accepts operations, which in the case of `levelup` means that `status` is either `opening` or `open`, because it opens itself and queues up operations until opened.
351
297
352
298
### `db.createReadStream([options])`
353
299
@@ -383,11 +329,9 @@ You can supply an options object as the first parameter to `createReadStream()`
383
329
384
330
-`values`_(boolean, default: `true`)_: whether the results should contain values. If set to `true` and `keys` set to `false` then results will simply be values, rather than objects with a `value` property. Used internally by the `createValueStream()` method.
385
331
386
-
<aname="createKeyStream"></a>
387
-
388
332
### `db.createKeyStream([options])`
389
333
390
-
Returns a [Readable Stream](https://nodejs.org/docs/latest/api/stream.html#stream_readable_streams) of keys rather than key-value pairs. Use the same options as described for <ahref="#createReadStream"><code>createReadStream</code></a> to control the range and direction.
334
+
Returns a [Readable Stream](https://nodejs.org/docs/latest/api/stream.html#stream_readable_streams) of keys rather than key-value pairs. Use the same options as described for [`createReadStream()`](#dbcreatereadstreamoptions) to control the range and direction.
391
335
392
336
You can also obtain this stream by passing an options object to `createReadStream()` with `keys` set to `true` and `values` set to `false`. The result is equivalent; both streams operate in [object mode](https://nodejs.org/docs/latest/api/stream.html#stream_object_mode).
Returns a [Readable Stream](https://nodejs.org/docs/latest/api/stream.html#stream_readable_streams) of values rather than key-value pairs. Use the same options as described for <ahref="#createReadStream"><code>createReadStream</code></a> to control the range and direction.
353
+
Returns a [Readable Stream](https://nodejs.org/docs/latest/api/stream.html#stream_readable_streams) of values rather than key-value pairs. Use the same options as described for [`createReadStream()`](#dbcreatereadstreamoptions) to control the range and direction.
412
354
413
355
You can also obtain this stream by passing an options object to `createReadStream()` with `values` set to `true` and `keys` set to `false`. The result is equivalent; both streams operate in [object mode](https://nodejs.org/docs/latest/api/stream.html#stream_object_mode).
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 <ahref="#createReadStream"><code>createReadStream</code></a> and are passed to the underlying store.
372
+
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()`](#dbcreatereadstreamoptions) and are passed to the underlying store.
433
373
434
-
<aname="clear"></a>
374
+
These iterators support [`for await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of):
435
375
436
-
### `db.clear([options][, callback])`
376
+
```js
377
+
forawait (const [key, value] ofdb.iterator()) {
378
+
console.log(value)
379
+
}
380
+
```
437
381
438
-
**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()`.**
382
+
### `db.clear([options][, callback])`
439
383
440
384
Delete all entries or a range. Not guaranteed to be atomic. Accepts the following range options (with the same rules as on iterators):
441
385
@@ -448,9 +392,7 @@ If no options are provided, all entries will be deleted. The `callback` function
448
392
449
393
If no callback is passed, a promise is returned.
450
394
451
-
<aname="writeStreams"></a>
452
-
453
-
#### What happened to `db.createWriteStream`?
395
+
## What happened to `db.createWriteStream`?
454
396
455
397
`db.createWriteStream()` has been removed in order to provide a smaller and more maintainable core. It primarily existed to create symmetry with `db.createReadStream()` but through much [discussion](https://github.com/Level/levelup/issues/199), removing it was the best course of action.
456
398
@@ -460,38 +402,14 @@ Check out the implementations that the community has produced [here](https://git
460
402
461
403
## Promise Support
462
404
463
-
`levelup` ships with native `Promise` support out of the box.
464
-
465
-
Each function accepting a callback returns a promise if the callback is omitted. This applies for:
466
-
467
-
-`db.get(key[, options])`
468
-
-`db.put(key, value[, options])`
469
-
-`db.del(key[, options])`
470
-
-`db.batch(ops[, options])`
471
-
-`db.batch().write()`
472
-
473
-
The only exception is the `levelup` constructor itself, which if no callback is passed will lazily open the underlying store in the background.
405
+
Each function accepting a callback returns a promise if the callback is omitted. The only exception is the `levelup` constructor itself, which if no callback is passed will lazily open the underlying store in the background.
0 commit comments