Skip to content

Commit 94a2a8e

Browse files
vweeversvweevers
committed
Cleanup README and add missing docs for options
Also removing mentions of levelup, in favor of abstract-level.
1 parent 59d2ab3 commit 94a2a8e

File tree

2 files changed

+28
-100
lines changed

2 files changed

+28
-100
lines changed

‎README.md

Lines changed: 27 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,52 @@
11
# level-ws
22

3-
> A basic WriteStream implementation for [levelup](https://github.com/Level/levelup)
3+
**A basic writable stream for [`abstract-level`](https://github.com/Level/abstract-level) databases, using Node.js core streams.** This is not a high-performance stream. If benchmarking shows that your particular usage does not fit then try one of the alternative writable streams that are optimized for different use cases.
4+
5+
> :pushpin: To instead write data using Web Streams, see [`level-web-stream`](https://github.com/Level/web-stream).
46
57
[![level badge][level-badge]](https://github.com/Level/awesome)
6-
[![npm](https://img.shields.io/npm/v/level-ws.svg?label=&logo=npm)](https://www.npmjs.com/package/level-ws)
8+
[![npm](https://img.shields.io/npm/v/level-ws.svg)](https://www.npmjs.com/package/level-ws)
79
[![Node version](https://img.shields.io/node/v/level-ws.svg)](https://www.npmjs.com/package/level-ws)
8-
[![Test](https://github.com/Level/level-ws/actions/workflows/test.yml/badge.svg)](https://github.com/Level/level-ws/actions/workflows/test.yml)
9-
[![npm](https://img.shields.io/npm/dm/level-ws.svg?label=dl)](https://www.npmjs.com/package/level-ws)
10-
[![Coverage Status](https://codecov.io/gh/Level/level-ws/branch/master/graph/badge.svg)](https://codecov.io/gh/Level/level-ws)
11-
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
12-
[![Funding](https://opencollective.com/level/tiers/badge.svg)](#donate)
13-
14-
`level-ws` provides the most basic general-case WriteStream for `levelup`. It was extracted from the core `levelup` at version 0.18.0.
15-
16-
`level-ws` is not a high-performance WriteStream. If your benchmarking shows that your particular usage pattern and data types do not perform well with this WriteStream then you should try one of the alternative WriteStreams available for `levelup` that are optimised for different use-cases.
17-
18-
**If you are upgrading:** please see [`UPGRADING.md`](UPGRADING.md).
10+
[![Test](https://img.shields.io/github/workflow/status/Level/level-ws/Test?label=test)](https://github.com/Level/level-ws/actions/workflows/test.yml)
11+
[![Coverage](https://img.shields.io/codecov/c/github/Level/level-ws?label=\&logo=codecov\&logoColor=fff)](https://codecov.io/gh/Level/level-ws)
12+
[![Standard](https://img.shields.io/badge/standard-informational?logo=javascript\&logoColor=fff)](https://standardjs.com)
13+
[![Common Changelog](https://common-changelog.org/badge.svg)](https://common-changelog.org)
14+
[![Donate](https://img.shields.io/badge/donate-orange?logo=open-collective\&logoColor=fff)](https://opencollective.com/level)
1915

2016
## Usage
2117

22-
```js
23-
var level = require('level')
24-
var WriteStream = require('level-ws')
25-
26-
var db = level('/path/to/db')
27-
var ws = WriteStream(db) // ...
28-
```
29-
30-
## API
31-
32-
### `ws = WriteStream(db[, options])`
33-
34-
Creates a [Writable](https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_class_stream_writable) stream which operates in **objectMode**, accepting objects with `'key'` and `'value'` pairs on its `write()` method.
35-
36-
The optional `options` argument may contain:
37-
38-
- `type` _(string, default: `'put'`)_: Default batch operation for missing `type` property during `ws.write()`.
39-
40-
The WriteStream will buffer writes and submit them as a `batch()` operations where writes occur _within the same tick_.
18+
_If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md)._
4119

4220
```js
43-
var ws = WriteStream(db)
44-
45-
ws.on('error', function (err) {
46-
console.log('Oh my!', err)
47-
})
48-
ws.on('close', function () {
49-
console.log('Stream closed')
50-
})
51-
52-
ws.write({ key: 'name', value: 'Yuri Irsenovich Kim' })
53-
ws.write({ key: 'dob', value: '16 February 1941' })
54-
ws.write({ key: 'spouse', value: 'Kim Young-sook' })
55-
ws.write({ key: 'occupation', value: 'Clown' })
56-
ws.end()
57-
```
58-
59-
The standard `write()`, `end()` and `destroy()` methods are implemented on the WriteStream. `'drain'`, `'error'`, `'close'` and `'pipe'` events are emitted.
21+
const { Level } = require('level')
22+
const WriteStream = require('level-ws')
6023

61-
You can specify encodings for individual entries by setting `.keyEncoding` and/or `.valueEncoding`:
24+
const db = new Level('./db', { valueEncoding: 'json' })
25+
const ws = WriteStream(db)
6226

63-
```js
64-
writeStream.write({
65-
key: new Buffer([1, 2, 3]),
66-
value: { some: 'json' },
67-
keyEncoding: 'binary',
68-
valueEncoding : 'json'
27+
ws.on('close', function () {
28+
console.log('Done!')
6929
})
70-
```
7130

72-
If individual `write()` operations are performed with a `'type'` property of `'del'`, they will be passed on as `'del'` operations to the batch.
31+
ws.write({ key: 'alice', value: 42 })
32+
ws.write({ key: 'bob', value: 7 })
7333

74-
```js
75-
var ws = WriteStream(db)
34+
// To delete entries, specify an explicit type
35+
ws.write({ type: 'del', key: 'tomas' })
36+
ws.write({ type: 'put', key: 'sara', value: 16 })
7637

77-
ws.on('error', function (err) {
78-
console.log('Oh my!', err)
79-
})
80-
ws.on('close', function () {
81-
console.log('Stream closed')
82-
})
83-
84-
ws.write({ type: 'del', key: 'name' })
85-
ws.write({ type: 'del', key: 'dob' })
86-
ws.write({ type: 'put', key: 'spouse' })
87-
ws.write({ type: 'del', key: 'occupation' })
8838
ws.end()
8939
```
9040

91-
If the _WriteStream_ is created with a `'type'` option of `'del'`, all `write()` operations will be interpreted as `'del'`, unless explicitly specified as `'put'`.
41+
## API
9242

93-
```js
94-
var ws = WriteStream(db, { type: 'del' })
43+
### `ws = WriteStream(db[, options])`
9544

96-
ws.on('error', function (err) {
97-
console.log('Oh my!', err)
98-
})
99-
ws.on('close', function () {
100-
console.log('Stream closed')
101-
})
45+
Create a [writable stream](https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_class_stream_writable) that operates in object mode, accepting batch operations to be committed with `db.batch()` on each tick of the Node.js event loop. The optional `options` argument may contain:
10246

103-
ws.write({ key: 'name' })
104-
ws.write({ key: 'dob' })
105-
// but it can be overridden
106-
ws.write({ type: 'put', key: 'spouse', value: 'Ri Sol-ju' })
107-
ws.write({ key: 'occupation' })
108-
ws.end()
109-
```
47+
- `type` (string, default: `'put'`): default batch operation type if not set on indididual operations.
48+
- `maxBufferLength` (number, default `Infinity`): limit the size of batches. When exceeded, the stream will stop processing writes until the current batch has been committed.
49+
- `highWaterMark` (number, default `16`): buffer level when `stream.write()` starts returning false.
11050

11151
## Contributing
11252

@@ -116,18 +56,6 @@ ws.end()
11656
11757
See the [Contribution Guide](https://github.com/Level/community/blob/master/CONTRIBUTING.md) for more details.
11858

119-
## Donate
120-
121-
Support us with a monthly donation on [Open Collective](https://opencollective.com/level) and help us continue our work. Your logo or avatar will be displayed on our 28+ [GitHub repositories](https://github.com/Level) and [npm](https://www.npmjs.com/) packages. 💖
122-
123-
**Active financial contributors**
124-
125-
[![Open Collective backers](https://opencollective.com/level/tiers/backer.svg?button=false)](https://opencollective.com/level) [![Open Collective sponsors](https://opencollective.com/level/tiers/sponsor.svg?button=false)](https://opencollective.com/level)
126-
127-
**Past financial contributors**
128-
129-
[![Open Collective sponsors](https://opencollective.com/level/sponsors.svg?button=false&avatarHeight=36)](https://opencollective.com/level) [![Open Collective backers](https://opencollective.com/level/backers.svg?button=false&avatarHeight=36)](https://opencollective.com/level)
130-
13159
## License
13260

13361
[MIT](LICENSE)

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "level-ws",
33
"version": "3.0.0",
4-
"description": "A basic WriteStream implementation for LevelUP",
4+
"description": "A basic writable stream for abstract-level databases",
55
"license": "MIT",
66
"main": "level-ws.js",
77
"scripts": {

0 commit comments

Comments
 (0)