Mirror: 🎩 A tiny but capable push & pull stream library for TypeScript and Flow
Add migration page and guide (#64)
authored by
Phil Plückthun
and committed by
GitHub
0c5171af
1fee50d2
+112
-2
+1
-1
docs/api/index.md
+1
-1
docs/api/index.md
+1
-1
docs/basics/index.md
+1
-1
docs/basics/index.md
+110
docs/migration.md
+110
docs/migration.md
···
1
+
---
2
+
title: Migration
3
+
order: 2
4
+
---
5
+
6
+
This page lists breaking changes and migration guides for
7
+
various major releases of Wonka.
8
+
9
+
## v4.0.0
10
+
11
+
In `v4.0.0` of Wonka, we've migrated to BuckleScript v7 and
12
+
`genType` for automatic type generation for TypeScript. The
13
+
Flow types are derived from the automatic types and are generated
14
+
by `flowgen`.
15
+
16
+
This may mean that `bsb-native` and Dune/Esy builds are temporarily
17
+
broken, as they haven't been tested yet. If so, they will be fixed
18
+
in a future minor release. Please stick with `v3.2.2` if you're having
19
+
trouble.
20
+
21
+
This release has no breaking changes for Reason/OCaml in terms of
22
+
API changes. You can use the library exactly as you have before.
23
+
24
+
**For TypeScript and Flow some APIs have changed**.
25
+
26
+
### New TypeScript and Flow typings
27
+
28
+
The type for `Subscription`, `Observer`, and `Subject` have changed.
29
+
These used to be exposed as tuples (fixed-size arrays) in the past,
30
+
but are now compiled to objects, due to the upgrade to BuckleScript v7.
31
+
32
+
If you're using `subscribe`, `makeSubject`, or `make` you will have
33
+
to change some of your types. If you don't, you won't have to update
34
+
any of your code and can even mix Wonka `v4.0.0` with `v3.2.2` in the
35
+
same bundle.
36
+
37
+
The `Subscription` type has changed from `[() => void]` to
38
+
`{ unsubscribe: (_: void) => void }`:
39
+
40
+
```ts
41
+
import { subscribe } from 'wonka';
42
+
43
+
// Before:
44
+
const [unsubscribe] = subscribe(source);
45
+
// After:
46
+
const { unsubscribe } = subscribe(source);
47
+
```
48
+
49
+
The `Observer` type has changed similarly, so you'll have to
50
+
update your code if you're using `make`:
51
+
52
+
```ts
53
+
import { make } from 'wonka';
54
+
55
+
// Before:
56
+
const source = make(([next, complete]) => /* ... */);
57
+
// After:
58
+
const source = make(({ next, complete }) => /* ... */);
59
+
```
60
+
61
+
And lastly the `Subject` type has changed as well, so update
62
+
your usage of `makeSubject`:
63
+
64
+
```ts
65
+
import { makeSubject } from 'wonka';
66
+
67
+
// Before:
68
+
const [source, next, complete] = makeSubject();
69
+
// After:
70
+
const { source, next, complete } = makeSubject();
71
+
```
72
+
73
+
### Improvements
74
+
75
+
The test suite has been rewritten from scratch to improve our
76
+
testing of some tricky edge cases. In most cases operators have
77
+
been updated to behave more nicely and closer to the spec and
78
+
as expected. This is especially true if you're using synchronous
79
+
sources or iterables a lot.
80
+
81
+
Wonka has reached a much higher test coverage and operators like
82
+
`merge` and `switchMap` will now behave as expected with synchronous
83
+
sources.
84
+
85
+
This is the list of operators that have changed. If your code has
86
+
been working before, you _shouldn't see any different behaviour_.
87
+
The changed operators will simply have received bugfixes and will
88
+
behave more predictably (and hopefully correctly) in certain edge cases!
89
+
90
+
- [`buffer`](./api/operators.md#buffer)
91
+
- [`combine`](./api/operators.md#combine)
92
+
- [`debounce`](./api/operators.md#debounce)
93
+
- [`delay`](./api/operators.md#delay)
94
+
- [`sample`](./api/operators.md#sample)
95
+
- [`skipUntil`](./api/operators.md#skipuntil)
96
+
- [`take`](./api/operators.md#take)
97
+
- [`takeLast`](./api/operators.md#takelast)
98
+
- [`takeWhile`](./api/operators.md#takewhile)
99
+
- [`switchMap`](./api/operators.md#switchmap)
100
+
- [`mergeMap`](./api/operators.md#mergemap)
101
+
- [`concatMap`](./api/operators.md#concatmap)
102
+
- [`switchAll`](./api/operators.md#switchall)
103
+
- [`mergeAll`](./api/operators.md#mergeall)
104
+
- [`concatAll`](./api/operators.md#concatall)
105
+
- [`merge`](./api/operators.md#merge)
106
+
- [`concat`](./api/operators.md#concat)
107
+
108
+
The `take` operator is the only one that has been changed to fix
109
+
a notable new usage case. It can now accept a maximum of `0` or below,
110
+
to close the source immediately.