feat: add types

achingbrain · Jul 30, 2020 · 67521f0 · 67521f0
1 parent 1534330
commit 67521f0
Show file tree

Hide file tree

Showing 62 changed files with 633 additions and 90 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,4 @@ Thumbs.db
 .nyc_output
 coverage
 bin
+packages/*/dist
diff --git a/.npmignore b/.npmignore
@@ -0,0 +1,8 @@
+node_modules
+*.log
+.DS_Store
+Thumbs.db
+.vscode
+.nyc_output
+coverage
+bin
diff --git a/.travis.yml b/.travis.yml
@@ -3,5 +3,5 @@ language: node_js
 node_js:
   - '12'
 
-script: npm run lint && npm run coverage
+script: npm run lint && npm run check && npm run coverage
 after_success: coveralls-lerna
diff --git a/package.json b/package.json
@@ -12,6 +12,7 @@
     "start": "NODE_ENV=development lerna run --parallel start",
     "clean": "lerna run --parallel clean",
     "lint": "lerna run --parallel lint",
+    "check": "lerna run --parallel check",
     "publish": "lerna publish"
   },
   "devDependencies": {

diff --git a/packages/it-all/README.md b/packages/it-all/README.md
@@ -2,7 +2,7 @@
 
 [![Build status](https://travis-ci.org/achingbrain/it.svg?branch=master)](https://travis-ci.org/achingbrain/it?branch=master) [![Coverage Status](https://coveralls.io/repos/github/achingbrain/it/badge.svg?branch=master)](https://coveralls.io/github/achingbrain/it?branch=master) [![Dependencies Status](https://david-dm.org/achingbrain/it/status.svg?path=packages/it-all)](https://david-dm.org/achingbrain/it?path=packages/it-all)
 
-> Collects all values from an async iterator and returns them as an array
+> Collects all values from an (async) iterable into an array and returns it.
 
 For when you need a one-liner to collect iterable values.
 

diff --git a/packages/it-all/index.js b/packages/it-all/index.js
@@ -1,9 +1,16 @@
 'use strict'
 
-const all = async (iterator) => {
+/**
+ * Collects all values from an (async) iterable into an array and returns it.
+ *
+ * @template T
+ * @param {AsyncIterable<T>|Iterable<T>} source
+ * @returns {Promise<T[]>}
+ */
+const all = async (source) => {
   const arr = []
 
-  for await (const entry of iterator) {
+  for await (const entry of source) {
     arr.push(entry)
   }
 

diff --git a/packages/it-all/package.json b/packages/it-all/package.json
@@ -10,13 +10,25 @@
     "test": "ava",
     "lint": "standard",
     "coverage": "nyc --reporter html --reporter lcov ava",
-    "clean": "rm -rf .nyc_output coverage"
+    "clean": "rm -rf .nyc_output coverage",
+    "check": "tsc --noEmit",
+    "build": "npm run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declarationDir dist"
   },
   "author": "Alex Potsides <alex@achingbrain.net>",
   "license": "ISC",
   "devDependencies": {
     "ava": "^2.4.0",
     "nyc": "^14.0.0",
-    "standard": "^14.3.1"
+    "standard": "^14.3.1",
+    "typescript": "^3.9.7"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        ".",
+        "dist/*"
+      ]
+    }
   }
-}
+}
diff --git a/packages/it-all/tsconfig.json b/packages/it-all/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../typescript.json",
+  "include": [
+    "."
+  ]
+}
diff --git a/packages/it-batch/README.md b/packages/it-batch/README.md
@@ -2,7 +2,8 @@
 
 [![Build status](https://travis-ci.org/achingbrain/it.svg?branch=master)](https://travis-ci.org/achingbrain/it?branch=master) [![Coverage Status](https://coveralls.io/repos/github/achingbrain/it/badge.svg?branch=master)](https://coveralls.io/github/achingbrain/it?branch=master) [![Dependencies Status](https://david-dm.org/achingbrain/it/status.svg?path=packages/it-batch)](https://david-dm.org/achingbrain/it?path=packages/it-batch)
 
-> Takes an async iterator that emits things and emits them as fixed-size batches
+> Takes an (async) iterable that emits things and returns an async iterable that
+> emits those things in fixed-sized batches.
 
 The final batch may be smaller than the max.
 

diff --git a/packages/it-batch/index.js b/packages/it-batch/index.js
@@ -1,12 +1,23 @@
 'use strict'
 
+/**
+ * Takes an (async) iterable that emits things and returns an async iterable that
+ * emits those things in fixed-sized batches.
+ *
+ * @template T
+ * @param {AsyncIterable<T>|Iterable<T>} source
+ * @param {number|string} [size=1]
+ * @returns {AsyncIterable<T[]>}
+ */
 async function * batch (source, size) {
+  // @ts-ignore - parseInt expects string
   size = parseInt(size)
 
   if (isNaN(size) || size < 1) {
     size = 1
   }
 
+  /** @type {T[]} */
   let things = []
 
   for await (const thing of source) {

diff --git a/packages/it-batch/package.json b/packages/it-batch/package.json
@@ -10,14 +10,26 @@
     "test": "ava",
     "lint": "standard",
     "coverage": "nyc --reporter html --reporter lcov ava",
-    "clean": "rm -rf .nyc_output coverage"
+    "clean": "rm -rf .nyc_output coverage",
+    "check": "tsc --noEmit",
+    "build": "npm run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declarationDir dist"
   },
   "author": "Alex Potsides <alex@achingbrain.net>",
   "license": "ISC",
   "devDependencies": {
     "ava": "^2.4.0",
     "it-all": "^1.0.2",
     "nyc": "^14.0.0",
-    "standard": "^14.3.1"
+    "standard": "^14.3.1",
+    "typescript": "^3.9.7"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./",
+        "dist/*"
+      ]
+    }
   }
-}
+}
diff --git a/packages/it-batch/tsconfig.json b/packages/it-batch/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../typescript.json",
+  "include": [
+    "."
+  ]
+}
diff --git a/packages/it-buffer-stream/README.md b/packages/it-buffer-stream/README.md
@@ -2,7 +2,7 @@
 
 [![Build status](https://travis-ci.org/achingbrain/it.svg?branch=master)](https://travis-ci.org/achingbrain/it?branch=master) [![Coverage Status](https://coveralls.io/repos/github/achingbrain/it/badge.svg?branch=master)](https://coveralls.io/github/achingbrain/it?branch=master) [![Dependencies Status](https://david-dm.org/achingbrain/it/status.svg?path=packages/it-buffer-stream)](https://david-dm.org/achingbrain/it?path=packages/it-buffer-stream)
 
-> An async iterator that emits buffers containing bytes up to a certain length
+> An async iterable that emits buffers containing bytes up to a certain length
 
 ## Install
 

diff --git a/packages/it-buffer-stream/index.js b/packages/it-buffer-stream/index.js
@@ -1,13 +1,29 @@
 'use strict'
 
+// @ts-ignore - untyped dependency
 const randomBytes = require('iso-random-stream/src/random')
 
+/**
+ * @typedef {Object} Options
+ * @property {number} [chunkSize]
+ * @property {function(Buffer):void} [collector]
+ * @property {function(number):Promise<Buffer>|Buffer} [generator]
+ */
+
+/** @type {Options} */
 const defaultOptions = {
   chunkSize: 4096,
   collector: () => {},
   generator: (size) => Promise.resolve(randomBytes(size))
 }
 
+/**
+ * An async iterable that emits buffers containing bytes up to a certain length.
+ *
+ * @param {number} limit
+ * @param {Options} [options]
+ * @returns {AsyncIterable<Buffer>}
+ */
 async function * bufferStream (limit, options = {}) {
   options = Object.assign({}, defaultOptions, options)
   let emitted = 0

diff --git a/packages/it-buffer-stream/package.json b/packages/it-buffer-stream/package.json
@@ -10,17 +10,29 @@
     "test": "ava",
     "lint": "standard",
     "coverage": "nyc --reporter html --reporter lcov ava",
-    "clean": "rm -rf .nyc_output coverage"
+    "clean": "rm -rf .nyc_output coverage",
+    "check": "tsc --noEmit",
+    "build": "npm run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declarationDir dist"
   },
   "author": "Alex Potsides <alex@achingbrain.net>",
   "license": "ISC",
   "devDependencies": {
     "ava": "^2.4.0",
     "buffer": "^5.5.0",
     "nyc": "^14.0.0",
-    "standard": "^14.3.1"
+    "standard": "^14.3.1",
+    "typescript": "^3.9.7"
   },
   "dependencies": {
     "iso-random-stream": "^1.1.1"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        ".",
+        "dist/*"
+      ]
+    }
   }
-}
+}
diff --git a/packages/it-buffer-stream/tsconfig.json b/packages/it-buffer-stream/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../typescript.json",
+  "include": [
+    "."
+  ]
+}
diff --git a/packages/it-drain/README.md b/packages/it-drain/README.md
@@ -2,7 +2,7 @@
 
 [![Build status](https://travis-ci.org/achingbrain/it.svg?branch=master)](https://travis-ci.org/achingbrain/it?branch=master) [![Coverage Status](https://coveralls.io/repos/github/achingbrain/it/badge.svg?branch=master)](https://coveralls.io/github/achingbrain/it?branch=master) [![Dependencies Status](https://david-dm.org/achingbrain/it/status.svg?path=packages/it-drain)](https://david-dm.org/achingbrain/it?path=packages/it-drain)
 
-> Drains an async iterator without returning anything
+> Drains an (async) iterable discarding its' content and does not return anything.
 
 Mostly useful for tests or when you want to be explicit about consuming an iterable without doing anything with any yielded values.
 

diff --git a/packages/it-drain/index.js b/packages/it-drain/index.js
@@ -1,5 +1,13 @@
 'use strict'
 
+/**
+ * Drains an (async) iterable discarding its' content and does not return
+ * anything.
+ *
+ * @template T
+ * @param {AsyncIterable<T>|Iterable<T>} iterator
+ * @returns {Promise<void>}
+ */
 const drain = async (iterator) => {
   for await (const _ of iterator) { } // eslint-disable-line no-unused-vars
 }

diff --git a/packages/it-drain/package.json b/packages/it-drain/package.json
@@ -10,13 +10,25 @@
     "test": "ava",
     "lint": "standard",
     "coverage": "nyc --reporter html --reporter lcov ava",
-    "clean": "rm -rf .nyc_output coverage"
+    "clean": "rm -rf .nyc_output coverage",
+    "check": "tsc --noEmit",
+    "build": "npm run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declarationDir dist"
   },
   "author": "Alex Potsides <alex@achingbrain.net>",
   "license": "ISC",
   "devDependencies": {
     "ava": "^2.4.0",
     "nyc": "^14.0.0",
-    "standard": "^14.3.1"
+    "standard": "^14.3.1",
+    "typescript": "^3.9.7"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        ".",
+        "dist/*"
+      ]
+    }
   }
-}
+}
diff --git a/packages/it-drain/tsconfig.json b/packages/it-drain/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../typescript.json",
+  "include": [
+    "."
+  ]
+}
diff --git a/packages/it-filter/README.md b/packages/it-filter/README.md
@@ -2,7 +2,7 @@
 
 [![Build status](https://travis-ci.org/achingbrain/it.svg?branch=master)](https://travis-ci.org/achingbrain/it?branch=master) [![Coverage Status](https://coveralls.io/repos/github/achingbrain/it/badge.svg?branch=master)](https://coveralls.io/github/achingbrain/it?branch=master) [![Dependencies Status](https://david-dm.org/achingbrain/it/status.svg?path=packages/it-all)](https://david-dm.org/achingbrain/it?path=packages/it-all)
 
-> Filters the passed iterable by using the filter function
+> Filters the passed (async) iterable by using the filter function
 
 ## Install
 

diff --git a/packages/it-filter/index.js b/packages/it-filter/index.js
@@ -1,7 +1,14 @@
 'use strict'
 
-const filter = async function * (iterator, fn) {
-  for await (const entry of iterator) {
+/**
+ * Filters the passed (async) iterable by using the filter function
+ *
+ * @template T
+ * @param {AsyncIterable<T>|Iterable<T>} source
+ * @param {function(T):boolean|Promise<boolean>} fn
+ */
+const filter = async function * (source, fn) {
+  for await (const entry of source) {
     if (await fn(entry)) {
       yield entry
     }

diff --git a/packages/it-filter/package.json b/packages/it-filter/package.json
@@ -10,14 +10,26 @@
     "test": "ava",
     "lint": "standard",
     "coverage": "nyc --reporter html --reporter lcov ava",
-    "clean": "rm -rf .nyc_output coverage"
+    "clean": "rm -rf .nyc_output coverage",
+    "check": "tsc --noEmit",
+    "build": "npm run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declarationDir dist"
   },
   "author": "Alex Potsides <alex@achingbrain.net>",
   "license": "ISC",
   "devDependencies": {
     "ava": "^2.4.0",
     "it-all": "^1.0.2",
     "nyc": "^14.0.0",
-    "standard": "^14.3.1"
+    "standard": "^14.3.1",
+    "typescript": "^3.9.7"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        ".",
+        "dist/*"
+      ]
+    }
   }
-}
+}
diff --git a/packages/it-filter/tsconfig.json b/packages/it-filter/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../typescript.json",
+  "include": [
+    "."
+  ]
+}
diff --git a/packages/it-first/README.md b/packages/it-first/README.md
@@ -2,7 +2,7 @@
 
 [![Build status](https://travis-ci.org/achingbrain/it.svg?branch=master)](https://travis-ci.org/achingbrain/it?branch=master) [![Coverage Status](https://coveralls.io/repos/github/achingbrain/it/badge.svg?branch=master)](https://coveralls.io/github/achingbrain/it?branch=master) [![Dependencies Status](https://david-dm.org/achingbrain/it/status.svg?path=packages/it-first)](https://david-dm.org/achingbrain/it?path=packages/it-first)
 
-> Returns the first result from an async iterator
+> Returns the first result from an (async) iterable.
 
 Mostly useful for tests.