Initial

Author: vweevers

.airtap.yml

@@ -0,0 +1,9 @@
+providers:
+  - airtap-playwright
+
+browsers:
+  - name: chromium
+  - name: webkit
+  # Firefox does not support WritableStream
+  # See https://developer.mozilla.org/en-US/docs/Web/API/WritableStream/WritableStream
+  # - name: firefox

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: monthly
+    ignore:
+      - dependency-name: standard
+      - dependency-name: hallmark
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

.github/workflows/release.yml

@@ -0,0 +1,17 @@
+name: Release
+on:
+  push:
+    tags: ['*']
+permissions:
+  contents: write
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Create GitHub release
+        uses: docker://antonyurchenko/git-release:v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Test
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [16]
+    name: Node ${{ matrix.node }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Use node ${{ matrix.node }}
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Install
+        run: npm install
+      - name: Test
+        run: npm test
+      - name: Coverage
+        run: npm run coverage
+      - name: Codecov
+        uses: codecov/codecov-action@v2
+        with:
+          file: coverage/lcov.info

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+.nyc_output/
+coverage

CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) The contributors to level-web-stream.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,103 @@
+# level-web-stream
+
+**Read from an [`abstract-level`](https://github.com/Level/abstract-level) database using [Web Streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API).** Compatible with browsers and Node.js.
+
+> :pushpin: To instead consume data using Node.js streams, see [`level-read-stream`](https://github.com/Level/read-stream).
+
+[![level badge][level-badge]](https://github.com/Level/awesome)
+[![npm](https://img.shields.io/npm/v/level-web-stream.svg)](https://www.npmjs.com/package/level-web-stream)
+[![Node version](https://img.shields.io/node/v/level-web-stream.svg)](https://www.npmjs.com/package/level-web-stream)
+[![Test](https://img.shields.io/github/workflow/status/Level/web-stream/Test?label=test)](https://github.com/Level/web-stream/actions/workflows/test.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/Level/web-stream?label=&logo=codecov&logoColor=fff)](https://codecov.io/gh/Level/web-stream)
+[![Standard](https://img.shields.io/badge/standard-informational?logo=javascript&logoColor=fff)](https://standardjs.com)
+[![Common Changelog](https://common-changelog.org/badge.svg)](https://common-changelog.org)
+[![Donate](https://img.shields.io/badge/donate-orange?logo=open-collective&logoColor=fff)](https://opencollective.com/level)
+
+## Usage
+
+```js
+const { EntryStream } = require('level-web-stream')
+const { MemoryLevel } = require('memory-level')
+
+const db = new MemoryLevel()
+
+// Write sample data
+await db.put('a', '1')
+await db.put('b', '2')
+await db.put('c', '3')
+
+// Create a ReadableStream
+const src = new EntryStream(db, {
+  gte: 'b'
+})
+
+// Pipe to a stream of choice
+const dst = new WritableStream({
+  write ([key, value]) {
+    console.log('%s: %s', key, value)
+  }
+})
+
+await src.pipeTo(dst)
+```
+
+Yields:
+
+```
+b: 2
+c: 3
+```
+
+To only read keys or values rather than entries:
+
+```js
+const { KeyStream, ValueStream } = require('level-web-stream')
+
+await new KeyStream(db).pipeTo(new WritableStream({
+  write (key) {
+    console.log(key)
+  }
+}))
+```
+
+Note that [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) is a global in browsers. In Node.js it can be imported from [`stream/web`](https://nodejs.org/api/webstreams.html).
+
+## Install
+
+With [npm](https://npmjs.org) do:
+
+```
+npm install level-web-stream
+```
+
+## API
+
+### `stream = new EntryStream(db[, options])`
+
+Create a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) that will yield entries. An entry is an array with `key` and `value` properties. The `db` argument must be an `abstract-level` database. The optional `options` object may contain:
+
+- `highWaterMark` (number): the maximum number of entries to buffer internally before ceasing to read further entries. Default 1000.
+
+Any other options are forwarded to `db.iterator(options)`. The stream wraps that iterator. If you prefer to consume entries with `for await...of` then it's recommended to directly use `db.iterator()`. In either case, most databases will read from a snapshot (thus unaffected by simultaneous writes) as indicated by `db.supports.snapshots`.
+
+### `stream = new KeyStream(db[, options])`
+
+Same as `EntryStream` but yields keys instead of entries, using `db.keys()` instead of `db.iterator()`. If only keys are needed, using `KeyStream` may increase performance because values won't have to be fetched.
+
+### `stream = new ValueStream(db[, options])`
+
+Same as `EntryStream` but yields values instead of entries, using `db.values()` instead of `db.iterator()`. If only values are needed, using `ValueStream` may increase performance because keys won't have to be fetched.
+
+## Contributing
+
+[`Level/web-stream`](https://github.com/Level/web-stream) is an **OPEN Open Source Project**. This means that:
+
+> Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.
+
+See the [Contribution Guide](https://github.com/Level/community/blob/master/CONTRIBUTING.md) for more details.
+
+## License
+
+[MIT](LICENSE)
+
+[level-badge]: https://leveljs.org/img/badge.svg

UPGRADING.md

@@ -0,0 +1,7 @@
+# Upgrade Guide
+
+This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the [changelog](CHANGELOG.md).
+
+## 1.0.0
+
+_:seedling: Initial release._

index.d.ts

@@ -0,0 +1,76 @@
+// Assumed to be installed side-by-side, declared as an optional peerDependency.
+import {
+  AbstractLevel,
+  AbstractIteratorOptions,
+  AbstractKeyIteratorOptions,
+  AbstractValueIteratorOptions
+} from 'abstract-level'
+
+/**
+ * A {@link ReadableStream} that yields entries.
+ */
+export class EntryStream<K, V, TDatabase = AbstractLevel<any, any, any>> extends ReadableStream<{ key: K, value: V }> {
+  /**
+   * Create a {@link ReadableStream} that yields entries from {@link db}.
+   * @param db Database to read from.
+   * @param options Options for the stream and its underlying iterator.
+   */
+  constructor (db: TDatabase, options?: (LevelReadableStreamOptions & Omit<AbstractIteratorOptions<K, V>, 'keys' | 'values'>) | undefined)
+
+  // TODO: support passing in an iterator so that its implementation-specific options are typed?
+  // constructor (iterator: AbstractIterator<TDatabase, K, V>, ...)
+}
+
+/**
+ * A {@link ReadableStream} that yields keys.
+ */
+export class KeyStream<K, TDatabase = AbstractLevel<any, any, any>> extends ReadableStream<K> {
+  /**
+   * Create a {@link ReadableStream} that yields keys from {@link db}.
+   * @param db Database to read from.
+   * @param options Options for the stream and its underlying iterator.
+   */
+  constructor (db: TDatabase, options?: (LevelReadableStreamOptions & AbstractKeyIteratorOptions<K>) | undefined)
+}
+
+/**
+ * A {@link ReadableStream} that yields values.
+ */
+export class ValueStream<K, V, TDatabase = AbstractLevel<any, any, any>> extends ReadableStream<V> {
+  /**
+   * Create a {@link ReadableStream} that yields values from {@link db}.
+   * @param db Database to read from.
+   * @param options Options for the stream and its underlying iterator.
+   */
+  constructor (db: TDatabase, options?: (LevelReadableStreamOptions & AbstractValueIteratorOptions<K, V>) | undefined)
+}
+
+declare interface LevelReadableStreamOptions {
+  /**
+   * The maximum number of items to buffer internally before ceasing to read further
+   * items.
+   *
+   * @defaultValue `1000`
+   */
+  highWaterMark?: number | undefined
+
+  /**
+   * Limit the amount of data that the underlying iterator will hold in memory.
+   *
+   * Only supported by [`classic-level`][1] and [`rocks-level`][2], and possibly by
+   * similar `abstract-level` implementations that are backed by a database on disk.
+   *
+   * [1]: https://github.com/Level/classic-level
+   * [2]: https://github.com/Level/rocks-level
+   */
+  highWaterMarkBytes?: number | undefined
+
+  /**
+   * Only supported by [`classic-level`][1] and [`rocks-level`][2], and possibly by
+   * similar `abstract-level` implementations that are backed by a database on disk.
+   *
+   * [1]: https://github.com/Level/classic-level
+   * [2]: https://github.com/Level/rocks-level
+   */
+  fillCache?: boolean | undefined
+}

index.js

@@ -0,0 +1,86 @@
+'use strict'
+
+const { ReadableStream, CountQueuingStrategy } = require('./streams')
+
+const kCanceled = Symbol('canceled')
+const kIterator = Symbol('iterator')
+const kDb = Symbol('db')
+
+class LevelReadableSource {
+  constructor (iterator) {
+    this[kIterator] = iterator
+    this[kCanceled] = false
+  }
+
+  /**
+   * @param {ReadableStreamDefaultController} controller
+   */
+  async pull (controller) {
+    let items
+
+    try {
+      items = await this[kIterator].nextv(controller.desiredSize)
+    } catch (err) {
+      await this[kIterator].close()
+      throw err
+    }
+
+    // Nothing to do if cancel() was called
+    if (this[kCanceled]) {
+      return
+    }
+
+    if (items.length === 0) {
+      // Reached the natural end of the iterator
+      await this[kIterator].close()
+      controller.close()
+    } else {
+      for (const item of items) {
+        controller.enqueue(item)
+      }
+    }
+  }
+
+  cancel () {
+    this[kCanceled] = true
+    return this[kIterator].close()
+  }
+}
+
+class LevelReadableStream extends ReadableStream {
+  constructor (db, method, options) {
+    const { highWaterMark, ...rest } = options || {}
+    const iterator = db[method](rest)
+    const source = new LevelReadableSource(iterator)
+    const queueingStrategy = new CountQueuingStrategy({
+      highWaterMark: highWaterMark || 1000
+    })
+
+    super(source, queueingStrategy)
+
+    // Keep db around to prevent GC
+    this[kDb] = db
+  }
+}
+
+class EntryStream extends LevelReadableStream {
+  constructor (db, options) {
+    super(db, 'iterator', { ...options, keys: true, values: true })
+  }
+}
+
+class KeyStream extends LevelReadableStream {
+  constructor (db, options) {
+    super(db, 'keys', options)
+  }
+}
+
+class ValueStream extends LevelReadableStream {
+  constructor (db, options) {
+    super(db, 'values', options)
+  }
+}
+
+exports.EntryStream = EntryStream
+exports.KeyStream = KeyStream
+exports.ValueStream = ValueStream