Add TypeScript type declarations (#3)

Author: vweevers

README.md

@@ -67,6 +67,8 @@ With [npm](https://npmjs.org) do:
 npm install level-read-stream
 ```
 
+Usage from TypeScript also requires `npm install @types/readable-stream`.
+
 ## API
 
 ### `stream = new EntryStream(db[, options])`
@@ -93,7 +95,7 @@ An instance of `EntryStream`, `KeyStream` or `ValueStream` has the following spe
 
 #### `stream.db`
 
-A read-only reference to the `db` that was passed to the stream constructor.
+A read-only reference to the database that this stream is reading from.
 
 ## Contributing
 

index.d.ts

@@ -0,0 +1,88 @@
+import { Readable } from 'readable-stream'
+
+// Assumed to be installed side-by-side, declared as an optional peerDependency.
+import {
+  AbstractLevel,
+  AbstractIteratorOptions,
+  AbstractKeyIteratorOptions,
+  AbstractValueIteratorOptions
+} from 'abstract-level'
+
+// NOTE: the types of readable-stream don't have generic type parameters
+declare class LevelReadStream<T, TDatabase> extends Readable {
+  /**
+   * A read-only reference to the database that this stream is reading from.
+   */
+  get db (): TDatabase
+
+  [Symbol.asyncIterator] (): AsyncIterableIterator<T>
+}
+
+/**
+ * A Node.js readable stream that yields entries.
+ */
+export class EntryStream<K, V, TDatabase = AbstractLevel<any, any, any>> extends LevelReadStream<{ key: K, value: V }, TDatabase> {
+  /**
+   * Create a Node.js readable stream 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?: (ReadStreamOptions & 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>, options?: LevelReadStreamOptions | undefined)
+}
+
+/**
+ * A Node.js readable stream that yields keys.
+ */
+export class KeyStream<K, TDatabase = AbstractLevel<any, any, any>> extends LevelReadStream<K, TDatabase> {
+  /**
+   * Create a Node.js readable stream 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?: (ReadStreamOptions & AbstractKeyIteratorOptions<K>) | undefined)
+}
+
+/**
+ * A Node.js readable stream that yields values.
+ */
+export class ValueStream<K, V, TDatabase = AbstractLevel<any, any, any>> extends LevelReadStream<V, TDatabase> {
+  /**
+   * Create a Node.js readable stream 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?: (ReadStreamOptions & AbstractValueIteratorOptions<K, V>) | undefined)
+}
+
+export interface ReadStreamOptions {
+  /**
+   * 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
+}

package.json

@@ -4,20 +4,33 @@
   "description": "Read from an abstract-level database using Node.js streams",
   "license": "MIT",
   "scripts": {
-    "test": "standard && hallmark && (nyc -s node test.js | faucet) && nyc report",
+    "test": "standard && ts-standard *.ts && hallmark && (nyc -s node test.js | faucet) && nyc report",
     "test-browsers-local": "airtap --coverage test.js",
     "coverage": "nyc report -r lcovonly",
     "hallmark": "hallmark fix"
   },
+  "main": "index.js",
+  "types": "./index.d.ts",
   "files": [
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md",
     "UPGRADING.md"
   ],
   "dependencies": {
     "readable-stream": "^3.4.0"
   },
+  "peerDependencies": {
+    "abstract-level": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "abstract-level": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/readable-stream": "^2.3.13",
+    "@voxpelli/tsconfig": "^3.1.0",
     "airtap": "^4.0.3",
     "airtap-playwright": "^1.0.1",
     "faucet": "^0.0.1",
@@ -26,7 +39,9 @@
     "nyc": "^15.1.0",
     "secret-event-listener": "^1.0.0",
     "standard": "^16.0.3",
-    "tape": "^5.0.1"
+    "tape": "^5.0.1",
+    "ts-standard": "^11.0.0",
+    "typescript": "^4.5.5"
   },
   "repository": "Level/read-stream",
   "homepage": "https://github.com/Level/read-stream",

tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@voxpelli/tsconfig/node12.json",
+  "compilerOptions": {
+    "checkJs": false
+  },
+  "include": ["*.ts", "types/*.ts"]
+}