docs: publish api docs (#36)

Update project config to publish api docs
achingbrain · Dec 16, 2022 · 76ef76d · 76ef76d
1 parent 1f5a019
commit 76ef76d
Show file tree

Hide file tree

Showing 9 changed files with 236 additions and 36 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -4,5 +4,8 @@ updates:
   directory: "/"
   schedule:
     interval: daily
-    time: "11:00"
+    time: "10:00"
   open-pull-requests-limit: 10
+  commit-message:
+    prefix: "deps"
+    prefix-development: "deps(dev)"
diff --git a/.github/workflows/automerge.yml b/.github/workflows/automerge.yml
@@ -0,0 +1,8 @@
+name: Automerge
+on: [ pull_request ]
+
+jobs:
+  automerge:
+    uses: protocol/.github/.github/workflows/automerge.yml@master
+    with:
+      job: 'automerge'
diff --git a/.github/workflows/js-test-and-release.yml b/.github/workflows/js-test-and-release.yml
@@ -0,0 +1,143 @@
+name: test & maybe release
+on:
+  push:
+    branches:
+      - master # with #262 - ${{{ github.default_branch }}}
+  pull_request:
+
+jobs:
+
+  check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-node@v3
+      with:
+        node-version: lts/*
+    - uses: ipfs/aegir/actions/cache-node-modules@master
+    - run: npm run --if-present lint
+    - run: npm run --if-present dep-check
+
+  test-node:
+    needs: check
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+        node: [lts/*]
+      fail-fast: true
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+      - uses: ipfs/aegir/actions/cache-node-modules@master
+      - run: npm run --if-present test:node
+      - uses: codecov/codecov-action@81cd2dc8148241f03f5839d295e000b8f761e378 # v3.1.0
+        with:
+          flags: node
+
+  test-chrome:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+      - uses: ipfs/aegir/actions/cache-node-modules@master
+      - run: npm run --if-present test:chrome
+      - uses: codecov/codecov-action@81cd2dc8148241f03f5839d295e000b8f761e378 # v3.1.0
+        with:
+          flags: chrome
+
+  test-chrome-webworker:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+      - uses: ipfs/aegir/actions/cache-node-modules@master
+      - run: npm run --if-present test:chrome-webworker
+      - uses: codecov/codecov-action@81cd2dc8148241f03f5839d295e000b8f761e378 # v3.1.0
+        with:
+          flags: chrome-webworker
+
+  test-firefox:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+      - uses: ipfs/aegir/actions/cache-node-modules@master
+      - run: npm run --if-present test:firefox
+      - uses: codecov/codecov-action@81cd2dc8148241f03f5839d295e000b8f761e378 # v3.1.0
+        with:
+          flags: firefox
+
+  test-firefox-webworker:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+      - uses: ipfs/aegir/actions/cache-node-modules@master
+      - run: npm run --if-present test:firefox-webworker
+      - uses: codecov/codecov-action@81cd2dc8148241f03f5839d295e000b8f761e378 # v3.1.0
+        with:
+          flags: firefox-webworker
+
+  test-electron-main:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+      - uses: ipfs/aegir/actions/cache-node-modules@master
+      - run: npx xvfb-maybe npm run --if-present test:electron-main
+      - uses: codecov/codecov-action@81cd2dc8148241f03f5839d295e000b8f761e378 # v3.1.0
+        with:
+          flags: electron-main
+
+  test-electron-renderer:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+      - uses: ipfs/aegir/actions/cache-node-modules@master
+      - run: npx xvfb-maybe npm run --if-present test:electron-renderer
+      - uses: codecov/codecov-action@81cd2dc8148241f03f5839d295e000b8f761e378 # v3.1.0
+        with:
+          flags: electron-renderer
+
+  release:
+    needs: [test-node, test-chrome, test-chrome-webworker, test-firefox, test-firefox-webworker, test-electron-main, test-electron-renderer]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master' # with #262 - 'refs/heads/${{{ github.default_branch }}}'
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+      - uses: ipfs/aegir/actions/cache-node-modules@master
+      - uses: ipfs/aegir/actions/docker-login@master
+        with:
+          docker-token: ${{ secrets.DOCKER_TOKEN }}
+          docker-username: ${{ secrets.DOCKER_USERNAME }}
+      - run: npm run --if-present release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,8 @@
 node_modules
-coverage
-.nyc_output
+build
+dist
+.docs
+.coverage
+node_modules
 package-lock.json
-dist
+yarn.lock
diff --git a/LICENSE b/LICENSE
@@ -1,2 +1,4 @@
+This project is dual licensed under MIT and Apache-2.0.
+
 MIT: https://www.opensource.org/licenses/mit
-Apache-2.0: https://www.apache.org/licenses/license-2.0
+Apache-2.0: https://www.apache.org/licenses/license-2.0
diff --git a/LICENSE-MIT b/LICENSE-MIT
@@ -16,4 +16,4 @@ 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.
+THE SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,15 +1,22 @@
-# it-stream-types
+# it-stream-types <!-- omit in toc -->
 
-[![Build Status](https://github.com/achingbrain/it-stream-types/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/achingbrain/it-stream-types/actions/workflows/main.yml)
-[![Dependencies Status](https://david-dm.org/achingbrain/it-stream-types/status.svg)](https://david-dm.org/achingbrain/it-stream-types)
-[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
+[![codecov](https://img.shields.io/codecov/c/github/achingbrain/it-stream-types.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it-stream-types)
+[![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it-stream-types/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it-stream-types/actions/workflows/js-test-and-release.yml?query=branch%3Amaster)
 
 > Typescript types for AsyncIterable sink/source/duplex streams
 
+## Table of contents <!-- omit in toc -->
+
+- [Install](#install)
+- [Usage](#usage)
+- [API Docs](#api-docs)
+- [License](#license)
+- [Contribution](#contribution)
+
 ## Install
 
-```sh
-npm i it-stream-types
+```console
+$ npm i it-stream-types
 ```
 
 ## Usage
@@ -20,10 +27,17 @@ import type { Duplex } from 'it-stream-types'
 ...
 ```
 
-## Contribute
+## API Docs
 
-Feel free to dive in! [Open an issue](https://github.com/achingbrain/it-stream-types/issues/new) or submit PRs.
+- <https://achingbrain.github.io/it-stream-types>
 
 ## License
 
-[Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT)
+Licensed under either of
+
+- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
diff --git a/package.json b/package.json
@@ -2,16 +2,31 @@
   "name": "it-stream-types",
   "version": "1.0.4",
   "description": "Typescript types for AsyncIterable sink/source/duplex streams",
+  "author": "Alex Potsides <[email protected]>",
+  "license": "Apache-2.0 OR MIT",
+  "homepage": "https://github.com/achingbrain/it-stream-types#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/achingbrain/it-stream-types.git"
+  },
+  "bugs": {
+    "url": "https://github.com/achingbrain/it-stream-types/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=7.0.0"
+  },
   "type": "module",
   "types": "./dist/src/index.d.ts",
   "files": [
     "src",
-    "dist/src",
+    "dist",
     "!dist/test",
     "!**/*.tsbuildinfo"
   ],
   "exports": {
     ".": {
+      "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     }
   },
@@ -48,15 +63,15 @@
               "release": "patch"
             },
             {
-              "type": "chore",
+              "type": "docs",
               "release": "patch"
             },
             {
-              "type": "docs",
+              "type": "test",
               "release": "patch"
             },
             {
-              "type": "test",
+              "type": "deps",
               "release": "patch"
             },
             {
@@ -86,7 +101,11 @@
               },
               {
                 "type": "docs",
-                "section": "Trivial Changes"
+                "section": "Documentation"
+              },
+              {
+                "type": "deps",
+                "section": "Dependencies"
               },
               {
                 "type": "test",
@@ -104,22 +123,12 @@
   },
   "scripts": {
     "lint": "aegir lint",
-    "dep-check": "aegir dep-check dist/src/**/*.js dist/test/**/*.js",
-    "build": "tsc",
-    "release": "semantic-release"
+    "dep-check": "aegir dep-check",
+    "build": "aegir build",
+    "release": "aegir release",
+    "docs": "aegir docs"
   },
-  "author": "Alex Potsides <[email protected]>",
-  "license": "Apache-2.0 OR MIT",
   "devDependencies": {
-    "aegir": "^36.1.3"
-  },
-  "dependencies": {},
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/achingbrain/it-stream-types.git"
-  },
-  "bugs": {
-    "url": "https://github.com/achingbrain/it-stream-types/issues"
-  },
-  "homepage": "https://github.com/achingbrain/it-stream-types#readme"
+    "aegir": "^37.7.8"
+  }
 }
diff --git a/src/index.ts b/src/index.ts
@@ -1,13 +1,31 @@
+/**
+ * A "transform" is both a sink and a source where the values it consumes
+ * and the values that can be consumed from it are connected in some way.
+ * It is a function that takes a source and returns a source.
+ */
 export interface Transform<A, B = A> {
   (source: Source<A>): Source<B>
 }
 
+/**
+ * A "sink" is something that consumes (or drains) a source. It is a
+ * function that takes a source and iterates over it. It optionally returns
+ * a value.
+ */
 export interface Sink<T, R = Promise<void>> {
   (source: Source<T>): R
 }
 
+/**
+ * A "source" is something that can be consumed. It is an iterable object.
+ */
 export type Source<T> = AsyncIterable<T> | Iterable<T>
 
+/**
+ * A "duplex" is similar to a transform but the values it consumes are not
+ * necessarily connected to the values that can be consumed from it. It is
+ * an object with two properties, sink and source.
+ */
 export interface Duplex<TSource, TSink = TSource, RSink = Promise<void>> {
   source: Source<TSource>
   sink: Sink<TSink, RSink>