Skip to content

Commit c3c68a1

Browse files
author
Alan Shaw
committed
feat: add typescript typings...your mileage may vary, PRs accepted
1 parent 6136d75 commit c3c68a1

File tree

7 files changed

+2292
-3225
lines changed

7 files changed

+2292
-3225
lines changed

‎README.md

+48-6
Original file line numberDiff line numberDiff line change
@@ -57,48 +57,90 @@ try {
5757
const abortable = require('abortable-iterator')
5858
```
5959

60-
### `abortable(iterator, signal, [options])`
60+
* [`abortable(source, signal, [options])`](#abortablesource-signal-options)
61+
* [`abortable(source, signals)`](#abortablesource-signals)
62+
* [`abortable.source(source, signal, [options])`](#abortablesource-signal-options)
63+
* [`abortable.source(source, signals)`](#abortablesource-signals)
64+
* [`abortable.sink(sink, signal, [options])`](#abortablesinksink-signal-options)
65+
* [`abortable.sink(sink, signals)`](#abortablesinksink-signals)
66+
* [`abortable.transform(transform, signal, [options])`](#abortabletransformtransform-signal-options)
67+
* [`abortable.transform(transform, signals)`](#abortabletransformtransform-signals)
68+
* [`abortable.duplex(duplex, signal, [options])`](#abortableduplexduplex-signal-options)
69+
* [`abortable.duplex(duplex, signals)`](#abortableduplex-signals)
70+
71+
### `abortable(source, signal, [options])`
72+
**(alias for `abortable.source(source, signal, [options])`)**
6173

6274
Make any iterator or iterable abortable via an `AbortSignal`.
6375

6476
#### Parameters
6577

6678
| Name | Type | Description |
6779
|------|------|-------------|
68-
| 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 |
80+
| 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 |
6981
| signal | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) | Signal obtained from `AbortController.signal` which is used to abort the iterator. |
7082
| options | `Object` | (optional) options |
7183
| options.onAbort | `Function` | An (async) function called when the iterator is being aborted, before the abort error is thrown. Default `null` |
7284
| options.abortMessage | `String` | The message that the error will have if the iterator is aborted. Default "The operation was aborted" |
7385
| 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" |
86+
| options.returnOnAbort | `Boolean` | Instead of throwing the abort error, just return from iterating over the source stream. |
7487

7588
#### Returns
7689

7790
| Type | Description |
7891
|------|-------------|
79-
| [`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. |
92+
| [`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. |
8093

8194
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.
8295

83-
### `abortable.multi(iterator, signals)`
96+
### `abortable(source, signals)`
97+
**(alias for `abortable.source(source, signals)`)**
8498

8599
Make any iterator or iterable abortable via any one of the passed `AbortSignal`'s.
86100

87101
#### Parameters
88102

89103
| Name | Type | Description |
90104
|------|------|-------------|
91-
| 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 |
105+
| 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 |
92106
| signals | `Array<{ signal, [options] }>` | An array of objects with `signal` and optional `options` properties. See above docs for expected values for these two properties. |
93107

94108
#### Returns
95109

96110
| Type | Description |
97111
|------|-------------|
98-
| [`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. |
112+
| [`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. |
99113

100114
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.
101115

116+
### `abortable.sink(sink, signal, [options])`
117+
118+
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.
119+
120+
### `abortable.sink(sink, signals)`
121+
122+
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.
123+
124+
### `abortable.transform(transform, signal, [options])`
125+
126+
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.
127+
128+
### `abortable.transform(transform, signals)`
129+
130+
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.
131+
132+
### `abortable.duplex(duplex, signal, [options])`
133+
134+
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.
135+
136+
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.
137+
138+
### `abortable.duplex(duplex, signals)`
139+
140+
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.
141+
142+
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.
143+
102144
## Related
103145

104146
* [`it-pipe`](https://www.npmjs.com/package/it-pipe) Utility to "pipe" async iterables together

‎index.d.ts

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
export class AbortError extends Error {
2+
constructor (message?: string, code?: string)
3+
type: 'aborted'
4+
code: string
5+
}
6+
7+
type Options<T> = {
8+
onAbort?: (source: Source<T>) => void
9+
abortMessage?: string
10+
abortCode?: string
11+
returnOnAbort?: boolean
12+
}
13+
14+
type Signals<T> = {
15+
signal: AbortSignal,
16+
options?: Options<T>
17+
}[]
18+
19+
type Source<T> = AsyncIterable<T> | Iterable<T>
20+
type Sink<TSource, TReturn = void> = (source: Source<TSource>) => TReturn
21+
type Transform<TSourceIn, TSourceOut> = (source: Source<TSourceIn>) => Source<TSourceOut>
22+
type Duplex<TSource, TSinkSource, TSinkReturn = void> = { sink: Sink<TSinkSource, TSinkReturn>, source: Source<TSource> }
23+
24+
declare function source<T> (
25+
source: Source<T>,
26+
signal?: AbortSignal,
27+
options?: Options<T>
28+
): AsyncIterable<T>
29+
30+
declare function source<T> (
31+
source: Source<T>,
32+
signals: Signals<T>
33+
): AsyncIterable<T>
34+
35+
declare function sink<TSource, TReturn = void> (
36+
sink: Sink<TSource, TReturn>,
37+
signal?: AbortSignal,
38+
options?: Options<TSource>
39+
): Sink<TSource, TReturn>
40+
41+
declare function sink<TSource, TReturn = void> (
42+
sink: Sink<TSource, TReturn>,
43+
signals: Signals<TSource>
44+
): Sink<TSource, TReturn>
45+
46+
declare function transform<TSourceIn, TSourceOut> (
47+
transform: Transform<TSourceIn, TSourceOut>,
48+
signal?: AbortSignal,
49+
options?: Options<TSourceIn>
50+
): Transform<TSourceIn, TSourceOut>
51+
52+
declare function transform<TSourceIn, TSourceOut> (
53+
transform: Transform<TSourceIn, TSourceOut>,
54+
signals: Signals<TSourceIn>
55+
): Transform<TSourceIn, TSourceOut>
56+
57+
declare function duplex<TSource, TSinkSource, TSinkReturn = void> (
58+
duplex: Duplex<TSource, TSinkSource, TSinkReturn>,
59+
signal?: AbortSignal,
60+
options?: Options<TSource>
61+
): Duplex<TSource, TSinkSource, TSinkReturn>
62+
63+
declare function duplex<TSource, TSinkSource, TSinkReturn = void> (
64+
duplex: Duplex<TSource, TSinkSource, TSinkReturn>,
65+
signals: Signals<TSource>
66+
): Duplex<TSource, TSinkSource, TSinkReturn>
67+
68+
export { source, sink, transform, duplex }
69+
export default source

‎index.js

+6-14
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ const AbortError = require('./AbortError')
33

44
// Wrap an iterator to make it abortable, allow cleanup when aborted via onAbort
55
const toAbortableSource = (source, signal, options) => (
6-
toMultiAbortableSource(source, [{ signal, options }])
6+
toMultiAbortableSource(source, Array.isArray(signal) ? signal : [{ signal, options }])
77
)
88

99
const toMultiAbortableSource = (source, signals) => {
@@ -80,33 +80,25 @@ const toMultiAbortableSource = (source, signals) => {
8080
}
8181

8282
const toAbortableSink = (sink, signal, options) => (
83-
toMultiAbortableSink(sink, [{ signal, options }])
83+
toMultiAbortableSink(sink, Array.isArray(signal) ? signal : [{ signal, options }])
8484
)
8585

8686
const toMultiAbortableSink = (sink, signals) => source => (
8787
sink(toMultiAbortableSource(source, signals))
8888
)
8989

90-
const toAbortableDuplex = (sink, signal, options) => (
91-
toMultiAbortableDuplex(sink, [{ signal, options }])
90+
const toAbortableDuplex = (duplex, signal, options) => (
91+
toMultiAbortableDuplex(duplex, Array.isArray(signal) ? signal : [{ signal, options }])
9292
)
9393

9494
const toMultiAbortableDuplex = (duplex, signals) => ({
95-
sink: toMultiAbortableSink(duplex.sink),
96-
source: toMultiAbortableSource(duplex.source)
95+
sink: toMultiAbortableSink(duplex.sink, signals),
96+
source: toMultiAbortableSource(duplex.source, signals)
9797
})
9898

9999
module.exports = toAbortableSource
100100
module.exports.AbortError = AbortError
101-
102101
module.exports.source = toAbortableSource
103-
module.exports.source.multi = toMultiAbortableSource
104-
105102
module.exports.sink = toAbortableSink
106-
module.exports.sink.multi = toMultiAbortableSink
107-
108103
module.exports.transform = toAbortableSink
109-
module.exports.transform.multi = toMultiAbortableSink
110-
111104
module.exports.duplex = toAbortableDuplex
112-
module.exports.duplex.multi = toMultiAbortableDuplex

0 commit comments

Comments
 (0)