.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: [isaacs]

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        node-version: [12.x, 14.x, 16.x, 17.x]
+        platform:
+        - os: ubuntu-latest
+          shell: bash
+        - os: macos-latest
+          shell: bash
+        - os: windows-latest
+          shell: bash
+        - os: windows-latest
+          shell: powershell
+      fail-fast: false
+
+    runs-on: ${{ matrix.platform.os }}
+    defaults:
+      run:
+        shell: ${{ matrix.platform.shell }}
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v1.1.0
+
+      - name: Use Nodejs ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run Tests
+        run: npm test -- -c -t0

.github/workflows/commit-if-modified.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+git config --global user.email "$1"
+shift
+git config --global user.name "$1"
+shift
+message="$1"
+shift
+if [ $(git status --porcelain "$@" | egrep '^ M' | wc -l) -gt 0 ]; then
+  git add "$@"
+  git commit -m "$message"
+  git push || git pull --rebase
+  git push
+fi

.github/workflows/copyright-year.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+dir=${1:-$PWD}
+dates=($(git log --date=format:%Y --pretty=format:'%ad' --reverse | sort | uniq))
+if [ "${#dates[@]}" -eq 1 ]; then
+  datestr="${dates}"
+else
+  datestr="${dates}-${dates[${#dates[@]}-1]}"
+fi
+
+stripDate='s/^((.*)Copyright\b(.*?))((?:,\s*)?(([0-9]{4}\s*-\s*[0-9]{4})|(([0-9]{4},\s*)*[0-9]{4})))(?:,)?\s*(.*)\n$/$1$9\n/g'
+addDate='s/^.*Copyright(?:\s*\(c\))? /Copyright \(c\) '$datestr' /g'
+for l in $dir/LICENSE*; do
+  perl -pi -e "$stripDate" $l
+  perl -pi -e "$addDate" $l
+done

.github/workflows/isaacs-makework.yml

@@ -0,0 +1,37 @@
+name: "various tidying up tasks to silence nagging"
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  makework:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Use Node.js
+        uses: actions/setup-node@v2.1.4
+        with:
+          node-version: 16.x
+      - name: put repo in package.json
+        run: node .github/workflows/package-json-repo.js
+      - name: check in package.json if modified
+        run: |
+          bash -x .github/workflows/commit-if-modified.sh \
+            "package-json-repo-bot@example.com" \
+            "package.json Repo Bot" \
+            "chore: add repo to package.json" \
+            package.json package-lock.json
+      - name: put all dates in license copyright line
+        run: bash .github/workflows/copyright-year.sh
+      - name: check in licenses if modified
+        run: |
+          bash .github/workflows/commit-if-modified.sh \
+            "license-year-bot@example.com" \
+            "License Year Bot" \
+            "chore: add copyright year to license" \
+            LICENSE*

.github/workflows/package-json-repo.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+const pf = require.resolve(`${process.cwd()}/package.json`)
+const pj = require(pf)
+
+if (!pj.repository && process.env.GITHUB_REPOSITORY) {
+  const fs = require('fs')
+  const server = process.env.GITHUB_SERVER_URL || 'https://github.com'
+  const repo = `${server}/${process.env.GITHUB_REPOSITORY}`
+  pj.repository = repo
+  const json = fs.readFileSync(pf, 'utf8')
+  const match = json.match(/^\s*\{[\r\n]+([ \t]*)"/)
+  const indent = match[1]
+  const output = JSON.stringify(pj, null, indent || 2) + '\n'
+  fs.writeFileSync(pf, output)
+}

LICENSE

@@ -1,6 +1,6 @@
 The ISC License
 
-Copyright (c) npm, Inc. and Contributors
+Copyright (c) 2017-2022 npm, Inc., Isaac Z. Schlueter, and Contributors
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

README.md

@@ -17,9 +17,6 @@ from this stream via `'data'` events or by calling `pipe()` into some other
 stream.  Calling `read()` requires the buffer to be flattened in some
 cases, which requires copying memory.
 
-There is also no `unpipe()` method.  Once you start piping, there is no
-stopping it!
-
 If you set `objectMode: true` in the options, then whatever is written will
 be emitted.  Otherwise, it'll do a minimal amount of Buffer copying to
 ensure proper Streams semantics when `read(n)` is called.
@@ -63,6 +60,10 @@ some ways superior to) Node.js core streams.
 Please read these caveats if you are familiar with node-core streams and
 intend to use Minipass streams in your programs.
 
+You can avoid most of these differences entirely (for a very
+small performance penalty) by setting `{async: true}` in the
+constructor options.
+
 ### Timing
 
 Minipass streams are designed to support synchronous use-cases.  Thus, data
@@ -82,6 +83,82 @@ This non-deferring approach makes Minipass streams much easier to reason
 about, especially in the context of Promises and other flow-control
 mechanisms.
 
+Example:
+
+```js
+const Minipass = require('minipass')
+const stream = new Minipass({ async: true })
+stream.on('data', () => console.log('data event'))
+console.log('before write')
+stream.write('hello')
+console.log('after write')
+// output:
+// before write
+// data event
+// after write
+```
+
+### Exception: Async Opt-In
+
+If you wish to have a Minipass stream with behavior that more
+closely mimics Node.js core streams, you can set the stream in
+async mode either by setting `async: true` in the constructor
+options, or by setting `stream.async = true` later on.
+
+```js
+const Minipass = require('minipass')
+const asyncStream = new Minipass({ async: true })
+asyncStream.on('data', () => console.log('data event'))
+console.log('before write')
+asyncStream.write('hello')
+console.log('after write')
+// output:
+// before write
+// after write
+// data event <-- this is deferred until the next tick
+```
+
+Switching _out_ of async mode is unsafe, as it could cause data
+corruption, and so is not enabled.  Example:
+
+```js
+const Minipass = require('minipass')
+const stream = new Minipass({ encoding: 'utf8' })
+stream.on('data', chunk => console.log(chunk))
+stream.async = true
+console.log('before writes')
+stream.write('hello')
+setStreamSyncAgainSomehow(stream) // <-- this doesn't actually exist!
+stream.write('world')
+console.log('after writes')
+// hypothetical output would be:
+// before writes
+// world
+// after writes
+// hello
+// NOT GOOD!
+```
+
+To avoid this problem, once set into async mode, any attempt to
+make the stream sync again will be ignored.
+
+```js
+const Minipass = require('minipass')
+const stream = new Minipass({ encoding: 'utf8' })
+stream.on('data', chunk => console.log(chunk))
+stream.async = true
+console.log('before writes')
+stream.write('hello')
+stream.async = false // <-- no-op, stream already async
+stream.write('world')
+console.log('after writes')
+// actual output:
+// before writes
+// after writes
+// hello
+// world
+```
+
 ### No High/Low Water Marks
 
 Node.js core streams will optimistically fill up a buffer, returning `true`
@@ -97,6 +174,9 @@ If the data has nowhere to go, then `write()` returns false, and the data
 sits in a buffer, to be drained out immediately as soon as anyone consumes
 it.
 
+Since nothing is ever buffered unnecessarily, there is much less
+copying data, and less bookkeeping about buffer capacity levels.
+
 ### Hazards of Buffering (or: Why Minipass Is So Fast)
 
 Since data written to a Minipass stream is immediately written all the way
@@ -181,6 +261,8 @@ moving on to the next entry in an archive parse stream, etc.) then be sure
 to call `stream.pause()` on creation, and then `stream.resume()` once you
 are ready to respond to the `end` event.
 
+However, this is _usually_ not a problem because:
+
 ### Emit `end` When Asked
 
 One hazard of immediately emitting `'end'` is that you may not yet have had
@@ -197,6 +279,18 @@ To prevent calling handlers multiple times who would not expect multiple
 ends to occur, all listeners are removed from the `'end'` event whenever it
 is emitted.
 
+### Emit `error` When Asked
+
+The most recent error object passed to the `'error'` event is
+stored on the stream.  If a new `'error'` event handler is added,
+and an error was previously emitted, then the event handler will
+be called immediately (or on `process.nextTick` in the case of
+async streams).
+
+This makes it much more difficult to end up trying to interact
+with a broken stream, if the error handler is added after an
+error was previously emitted.
+
 ### Impact of "immediate flow" on Tee-streams
 
 A "tee stream" is a stream piping to multiple destinations:
@@ -221,7 +315,7 @@ src.pipe(dest1) // 'foo' chunk flows to dest1 immediately, and is gone
 src.pipe(dest2) // gets nothing!
 ```
 
-The solution is to create a dedicated tee-stream junction that pipes to
+One solution is to create a dedicated tee-stream junction that pipes to
 both locations, and then pipe to _that_ instead.
 
 ```js
@@ -258,6 +352,13 @@ tee.on('data', handler2)
 src.pipe(tee)
 ```
 
+All of the hazards in this section are avoided by setting `{
+async: true }` in the Minipass constructor, or by setting
+`stream.async = true` afterwards.  Note that this does add some
+overhead, so should only be done in cases where you are willing
+to lose a bit of performance in order to avoid having to refactor
+program logic.
+
 ## USAGE
 
 It's a stream!  Use it like a stream and it'll most likely do what you
@@ -279,6 +380,10 @@ mp.end('bar')
   by default if you write() something other than a string or Buffer at any
   point.  Setting `objectMode: true` will prevent setting any encoding
   value.
+* `async` Defaults to `false`.  Set to `true` to defer data
+  emission until next tick.  This reduces performance slightly,
+  but makes Minipass streams use timing behavior closer to Node
+  core streams.  See [Timing](#timing) for more details.
 
 ### API
 
@@ -300,9 +405,19 @@ streams.
   from being emitted for empty streams until the stream is resumed.
 * `resume()` - Resume the stream.  If there's data in the buffer, it is all
   discarded.  Any buffered events are immediately emitted.
-* `pipe(dest)` - Send all output to the stream provided.  There is no way
-  to unpipe.  When data is emitted, it is immediately written to any and
-  all pipe destinations.
+* `pipe(dest)` - Send all output to the stream provided.  When
+  data is emitted, it is immediately written to any and all pipe
+  destinations.  (Or written on next tick in `async` mode.)
+* `unpipe(dest)` - Stop piping to the destination stream.  This
+  is immediate, meaning that any asynchronously queued data will
+  _not_ make it to the destination when running in `async` mode.
+    * `options.end` - Boolean, end the destination stream when
+      the source stream ends.  Default `true`.
+    * `options.proxyErrors` - Boolean, proxy `error` events from
+      the source stream to the destination stream.  Note that
+      errors are _not_ proxied after the pipeline terminates,
+      either due to the source emitting `'end'` or manually
+      unpiping with `src.unpipe(dest)`.  Default `false`.
 * `on(ev, fn)`, `emit(ev, fn)` - Minipass streams are EventEmitters.  Some
   events are given special treatment, however.  (See below under "events".)
 * `promise()` - Returns a Promise that resolves when the stream emits

bench/README.md

@@ -0,0 +1,31 @@
+Stream Benchmarks
+
+Run `node index.js` to benchmark all the different stream implementations
+with the following configurations:
+
+- `implementation` One of the implementations in `./impls`
+- `case` How is the data emitted and how is it consumed?
+    - `fast-fast` Source emits data as fast as possible, destination
+      consumes it immediately.
+    - `fast-slow` Source emits data as fast as possible, destination
+      consumes one chunk per Promise cycle.
+    - `slow-fast` Source emits one data per Promise cycle, destination
+      consumes it immediately.
+    - `slow-slow` Source emits one data per Promise cycle, destination
+      consumes one chunk per Promise cycle.
+    - `fast-mixed` Source emits data as fast as possible, data is piped to
+      one fast destination stream and one slow destination stream.
+- `pipeline` How many instances of the tested implementation are piped
+  together between the source and destination?  Tested with `1` and `20` by
+  default.
+- `type` What kind of data is written?
+    - `defaults` a buffer
+    - `str` a string
+    - `obj` the object `{i: 'object'}`
+
+Results are written to the `./results` folder for each test case, and to
+`results.json` and `results.tab`.
+
+See [this google
+sheet](https://docs.google.com/spreadsheets/d/1K_HR5oh3r80b8WVMWCPPjfuWXUgfkmhlX7FGI6JJ8tY/edit?usp=sharing)
+for analysis and comparisons.

bench/impls/README.md

@@ -0,0 +1,14 @@
+To add a new stream type to test, create a file here that exports a
+function or class that can be called with `s = new Class(options)`, where
+`options` can include `{encoding: 'utf8'}` or `{objectMode: true}`.
+
+The returned object must implement at minimum the following subset of the
+stream interface:
+
+* `on(event, fn)` call `fn` when `event` happens
+* `write(data)` where `data` will be an object, string, or buffer.  Return
+  `true` if more data should be written, `false` otherwise.  Emit `drain`
+  when ready for more data if `false` is written.
+* `end()` no further data will be written, emit `'finish'` when all data
+  processed
+* `pipe(dest)` pipe all output to `dest` stream