fix!: be explicit about sync/async behaviour (#45)

Crossing async boundaries is not free so allow the `Duplex` type to
specify whether it is sync or async.

BREAKING CHANGE: the `TSource` and `TSink` generic arguments to the `Duplex` type now refer to the stream type and not the type of objects yielded by the stream

package.json

@@ -122,13 +122,14 @@
     ]
   },
   "scripts": {
+    "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
     "build": "aegir build",
     "release": "aegir release",
     "docs": "aegir docs"
   },
   "devDependencies": {
-    "aegir": "^37.7.8"
+    "aegir": "^38.1.8"
   }
 }

src/index.ts

@@ -4,20 +4,26 @@
  * It is a function that takes a source and returns a source.
  */
 export interface Transform<A, B = A> {
-  (source: Source<A>): Source<B>
+  (source: A): 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
+export interface Sink<Source, R = Promise<void>> {
+  (source: Source): R
 }
 
 /**
  * A "source" is something that can be consumed. It is an iterable object.
+ *
+ * This type is a union of both sync and async sources - it is useful to keep
+ * code concise but declared types should prefer to specify whether they
+ * accept sync or async sources since treating a synchronous source as an
+ * asynchronous one can lead to performance degradation due to artificially
+ * induced asynchronous behaviour.
  */
 export type Source<T> = AsyncIterable<T> | Iterable<T>
 
@@ -26,7 +32,7 @@ export type Source<T> = AsyncIterable<T> | Iterable<T>
  * 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>
+export interface Duplex<TSource = unknown, TSink = TSource, RSink = Promise<void>> {
+  source: TSource
   sink: Sink<TSink, RSink>
 }