feat: add typescript typings...your mileage may vary, PRs accepted

README.md

@@ -57,48 +57,90 @@ try {
 const abortable = require('abortable-iterator')
 ```
 
-### `abortable(iterator, signal, [options])`
+* [`abortable(source, signal, [options])`](#abortablesource-signal-options)
+* [`abortable(source, signals)`](#abortablesource-signals)
+* [`abortable.source(source, signal, [options])`](#abortablesource-signal-options)
+* [`abortable.source(source, signals)`](#abortablesource-signals)
+* [`abortable.sink(sink, signal, [options])`](#abortablesinksink-signal-options)
+* [`abortable.sink(sink, signals)`](#abortablesinksink-signals)
+* [`abortable.transform(transform, signal, [options])`](#abortabletransformtransform-signal-options)
+* [`abortable.transform(transform, signals)`](#abortabletransformtransform-signals)
+* [`abortable.duplex(duplex, signal, [options])`](#abortableduplexduplex-signal-options)
+* [`abortable.duplex(duplex, signals)`](#abortableduplex-signals)
+
+### `abortable(source, signal, [options])`
+**(alias for `abortable.source(source, signal, [options])`)**
 
 Make any iterator or iterable abortable via an `AbortSignal`.
 
 #### Parameters
 
 | Name | Type | Description |
 |------|------|-------------|
-| iterator | [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol)\|[`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | The iterator or iterable object to make abortable |
+| source | [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol)\|[`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | The iterator or iterable object to make abortable |
 | signal | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) | Signal obtained from `AbortController.signal` which is used to abort the iterator. |
 | options | `Object` | (optional) options |
 | options.onAbort | `Function` | An (async) function called when the iterator is being aborted, before the abort error is thrown. Default `null` |
 | options.abortMessage | `String` | The message that the error will have if the iterator is aborted. Default "The operation was aborted" |
 | options.abortCode | `String`\|`Number` | The value assigned to the `code` property of the error that is thrown if the iterator is aborted. Default "ABORT_ERR" |
+| options.returnOnAbort | `Boolean` | Instead of throwing the abort error, just return from iterating over the source stream. |
 
 #### Returns
 
 | Type | Description |
 |------|-------------|
-| [`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | An iterator that wraps the passed `iterator` parameter that makes it abortable via the passed `signal` parameter. |
+| [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | An iterator that wraps the passed `source` parameter that makes it abortable via the passed `signal` parameter. |
 
 The returned iterator will `throw` an `AbortError` when it is aborted that has a `type` with the value `aborted` and `code` property with the value `ABORT_ERR` by default.
 
-### `abortable.multi(iterator, signals)`
+### `abortable(source, signals)`
+**(alias for `abortable.source(source, signals)`)**
 
 Make any iterator or iterable abortable via any one of the passed `AbortSignal`'s.
 
 #### Parameters
 
 | Name | Type | Description |
 |------|------|-------------|
-| iterator | [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol)\|[`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | The iterator or iterable object to make abortable |
+| source | [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol)\|[`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | The iterator or iterable object to make abortable |
 | signals | `Array<{ signal, [options] }>` | An array of objects with `signal` and optional `options` properties. See above docs for expected values for these two properties. |
 
 #### Returns
 
 | Type | Description |
 |------|-------------|
-| [`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | An iterator that wraps the passed `iterator` parameter that makes it abortable via the passed `signal` parameters. |
+| [`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) | An iterator that wraps the passed `source` parameter that makes it abortable via the passed `signal` parameters. |
 
 The returned iterator will `throw` an `AbortError` when it is aborted on _any_ one of the passed abort signals. The error object has a `type` with the value `aborted` and `code` property with the value `ABORT_ERR` by default.
 
+### `abortable.sink(sink, signal, [options])`
+
+The same as [`abortable.source`](#abortablesource-signal-options) except this makes the passed [`sink`](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#sink-it) abortable. Returns a new sink that wraps the passed `sink` and makes it abortable via the passed `signal` parameter.
+
+### `abortable.sink(sink, signals)`
+
+The same as [`abortable.source`](#abortablesource-signals) except this makes the passed [`sink`](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#sink-it) abortable via any one of the passed `AbortSignal`'s. Returns a new sink that wraps the passed `sink` and makes it abortable via the passed `signal` parameters.
+
+### `abortable.transform(transform, signal, [options])`
+
+The same as [`abortable.source`](#abortablesource-signal-options) except this makes the passed [`transform`](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#transform-it) abortable. Returns a new transform that wraps the passed `transform` and makes it abortable via the passed `signal` parameter.
+
+### `abortable.transform(transform, signals)`
+
+The same as [`abortable.source`](#abortablesource-signals) except this makes the passed [`transform`](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#transform-it) abortable via any one of the passed `AbortSignal`'s. Returns a new transform that wraps the passed `transform` and makes it abortable via the passed `signal` parameters.
+
+### `abortable.duplex(duplex, signal, [options])`
+
+The same as [`abortable.source`](#abortablesource-signal-options) except this makes the passed [`duplex`](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#duplex-it) abortable. Returns a new duplex that wraps the passed `duplex` and makes it abortable via the passed `signal` parameter.
+
+Note that this will abort _both_ sides of the duplex. Use `duplex.sink = abortable.sink(duplex.sink)` or `duplex.source = abortable.source(duplex.source)` to abort just the sink or the source.
+
+### `abortable.duplex(duplex, signals)`
+
+The same as [`abortable.source`](#abortablesource-signals) except this makes the passed [`duplex`](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#duplex-it) abortable via any one of the passed `AbortSignal`'s. Returns a new duplex that wraps the passed `duplex` and makes it abortable via the passed `signal` parameters.
+
+Note that this will abort _both_ sides of the duplex. Use `duplex.sink = abortable.sink(duplex.sink)` or `duplex.source = abortable.source(duplex.source)` to abort just the sink or the source.
+
 ## Related
 
 * [`it-pipe`](https://www.npmjs.com/package/it-pipe) Utility to "pipe" async iterables together

index.d.ts

@@ -0,0 +1,69 @@
+export class AbortError extends Error {
+  constructor (message?: string, code?: string)
+  type: 'aborted'
+  code: string
+}
+
+type Options<T> = {
+  onAbort?: (source: Source<T>) => void
+  abortMessage?: string
+  abortCode?: string
+  returnOnAbort?: boolean
+}
+
+type Signals<T> = {
+  signal: AbortSignal,
+  options?: Options<T>
+}[]
+
+type Source<T> = AsyncIterable<T> | Iterable<T>
+type Sink<TSource, TReturn = void> = (source: Source<TSource>) => TReturn
+type Transform<TSourceIn, TSourceOut> = (source: Source<TSourceIn>) => Source<TSourceOut>
+type Duplex<TSource, TSinkSource, TSinkReturn = void> = { sink: Sink<TSinkSource, TSinkReturn>, source: Source<TSource> }
+
+declare function source<T> (
+  source: Source<T>,
+  signal?: AbortSignal,
+  options?: Options<T>
+): AsyncIterable<T>
+
+declare function source<T> (
+  source: Source<T>,
+  signals: Signals<T>
+): AsyncIterable<T>
+
+declare function sink<TSource, TReturn = void> (
+  sink: Sink<TSource, TReturn>,
+  signal?: AbortSignal,
+  options?: Options<TSource>
+): Sink<TSource, TReturn>
+
+declare function sink<TSource, TReturn = void> (
+  sink: Sink<TSource, TReturn>,
+  signals: Signals<TSource>
+): Sink<TSource, TReturn>
+
+declare function transform<TSourceIn, TSourceOut> (
+  transform: Transform<TSourceIn, TSourceOut>,
+  signal?: AbortSignal,
+  options?: Options<TSourceIn>
+): Transform<TSourceIn, TSourceOut>
+
+declare function transform<TSourceIn, TSourceOut> (
+  transform: Transform<TSourceIn, TSourceOut>,
+  signals: Signals<TSourceIn>
+): Transform<TSourceIn, TSourceOut>
+
+declare function duplex<TSource, TSinkSource, TSinkReturn = void> (
+  duplex: Duplex<TSource, TSinkSource, TSinkReturn>,
+  signal?: AbortSignal,
+  options?: Options<TSource>
+): Duplex<TSource, TSinkSource, TSinkReturn>
+
+declare function duplex<TSource, TSinkSource, TSinkReturn = void> (
+  duplex: Duplex<TSource, TSinkSource, TSinkReturn>,
+  signals: Signals<TSource>
+): Duplex<TSource, TSinkSource, TSinkReturn>
+
+export { source, sink, transform, duplex }
+export default source

index.js

@@ -3,7 +3,7 @@ const AbortError = require('./AbortError')
 
 // Wrap an iterator to make it abortable, allow cleanup when aborted via onAbort
 const toAbortableSource = (source, signal, options) => (
-  toMultiAbortableSource(source, [{ signal, options }])
+  toMultiAbortableSource(source, Array.isArray(signal) ? signal : [{ signal, options }])
 )
 
 const toMultiAbortableSource = (source, signals) => {
@@ -80,33 +80,25 @@ const toMultiAbortableSource = (source, signals) => {
 }
 
 const toAbortableSink = (sink, signal, options) => (
-  toMultiAbortableSink(sink, [{ signal, options }])
+  toMultiAbortableSink(sink, Array.isArray(signal) ? signal : [{ signal, options }])
 )
 
 const toMultiAbortableSink = (sink, signals) => source => (
   sink(toMultiAbortableSource(source, signals))
 )
 
-const toAbortableDuplex = (sink, signal, options) => (
-  toMultiAbortableDuplex(sink, [{ signal, options }])
+const toAbortableDuplex = (duplex, signal, options) => (
+  toMultiAbortableDuplex(duplex, Array.isArray(signal) ? signal : [{ signal, options }])
 )
 
 const toMultiAbortableDuplex = (duplex, signals) => ({
-  sink: toMultiAbortableSink(duplex.sink),
-  source: toMultiAbortableSource(duplex.source)
+  sink: toMultiAbortableSink(duplex.sink, signals),
+  source: toMultiAbortableSource(duplex.source, signals)
 })
 
 module.exports = toAbortableSource
 module.exports.AbortError = AbortError
-
 module.exports.source = toAbortableSource
-module.exports.source.multi = toMultiAbortableSource
-
 module.exports.sink = toAbortableSink
-module.exports.sink.multi = toMultiAbortableSink
-
 module.exports.transform = toAbortableSink
-module.exports.transform.multi = toMultiAbortableSink
-
 module.exports.duplex = toAbortableDuplex
-module.exports.duplex.multi = toMultiAbortableDuplex