kitten.sh
1---
2title: Sources
3order: 0
4---
5
6A "source" in Wonka is a provider of data. It provides data to a "sink" when the "sink" requests it. This is called a pull signal and for synchronous sources no time will pass between the sink pulling a new value and a source sending it. For asynchronous sources, the source may either ignore pull signals and just push values or send one some time after the pull signal.
7
8## fromArray
9
10`fromArray` transforms an array into a source, emitting each item synchronously.
11
12```typescript
13import { fromArray } from 'wonka';
14fromArray([1, 2, 3]);
15```
16
17## fromValue
18
19`fromValue` takes a single value and creates a source that emits the value and
20completes immediately afterwards.
21
22```typescript
23import { fromValue } from 'wonka';
24fromValue(1);
25```
26
27## make
28
29`make` can be used to create an arbitrary source. It allows you to make a source
30from any other data.
31It accepts a function that receives an "observer" and should return a teardown
32function. It's very similar to creating an [Observable in `zen-observable`](https://github.com/zenparsing/zen-observable#new-observablesubscribe).
33
34The function you pass to `make` is called lazily when a sink subscribes to the
35source you're creating. The first argument `observer` is a tuple with two methods:
36
37- `next(value)` emits a value on the sink
38- `complete()` ends the source and completes the sink
39
40The subscriber function also needs to return a `teardown` function. This function
41is called when either `complete()` is called and the source ends, or if the source
42is being cancelled, since the sink unsubscribed.
43
44In this example we create a source that waits for a promise to resolve and emits
45values from the array of that promise.
46
47```typescript
48import { make } from 'wonka';
49
50const waitForArray = () => Promise.resolve([1, 2, 3]);
51
52const source = make((observer) => {
53 const { next, complete } = observer;
54 let cancelled = false;
55
56 waitForArray().then((arr) => {
57 if (!cancelled) {
58 arr.forEach(next);
59 complete();
60 }
61 });
62
63 return () => {
64 cancelled = true;
65 };
66});
67```
68
69## makeSubject
70
71`makeSubject` can be used to create a subject. This is similar to [`make`](#make) without
72having to define a source function. Instead a subject is a tuple of a source and
73the observer's `next` and `complete` functions combined.
74
75A subject can be very useful as a full event emitter. It allows you to pass a source
76around but also have access to the observer functions to emit events away from
77the source itself.
78
79```typescript
80import { makeSubject } from 'wonka';
81const subject = makeSubject();
82const { source, next, complete } = subject;
83
84/* This will push the values synchronously to any subscribers of source */
85next(1);
86next(2);
87next(complete);
88```
89
90## fromDomEvent
91
92`fromDomEvent` will turn a DOM event into a Wonka source, emitting the DOM events
93on the source whenever the DOM emits them on the passed element.
94
95```typescript
96import { pipe, fromDomEvent, subscribe } from 'wonka';
97
98const element = document.getElementById('root');
99
100pipe(
101 fromDomEvent(element, 'click'),
102 subscribe((e) => console.log(e))
103);
104```
105
106## fromPromise
107
108`fromPromise` transforms a promise into a source, emitting the promisified value on
109the source once it resolves.
110
111```typescript
112import { pipe, fromPromise, subscribe } from 'wonka';
113
114const promise = Promise.resolve(1); // Just an example promise
115
116pipe(
117 fromPromise(promise),
118 subscribe((e) => console.log(e))
119); // Prints 1 to the console.
120```
121
122## fromObservable
123
124`fromObservable` transforms a [spec-compliant JS Observable](https://github.com/tc39/proposal-observable) into a source.
125The resulting source will behave exactly the same as the Observable that it was
126passed, so it will start, end, and push values identically.
127
128```typescript
129import { pipe, fromObservable, subscribe } from 'wonka';
130
131// This example uses zen-observable for illustrative purposes
132import Observable from 'zen-observable';
133
134const observable = Observable.from([1, 2, 3]);
135
136pipe(
137 fromObservable(observable),
138 subscribe((e) => console.log(e))
139); // Prints 1 2 3 to the console
140```
141
142## fromCallbag
143
144`fromCallbag` transforms a [spec-compliant JS Callbag](https://github.com/callbag/callbag) into a source.
145
146Since Wonka's sources are very similar to callbags and only diverge from the specification
147minimally, Callbags map to Wonka's sources very closely and the `fromCallbag` wrapper
148is very thin and mostly concerned with converting between the type signatures.
149
150```typescript
151import { pipe, fromCallbag, subscribe } from 'wonka';
152
153// This example uses the callbag-from-iter package for illustrative purposes
154import callbagFromArray from 'callbag-from-iter';
155
156const callbag = callbagFromArray([1, 2, 3]);
157
158pipe(
159 fromCallbag(callbag),
160 subscribe((e) => console.log(e))
161); // Prints 1 2 3 to the console.
162```
163
164## interval
165
166`interval` creates a source that emits values after the given amount of milliseconds.
167Internally it uses `setInterval` to accomplish this.
168
169```typescript
170import { pipe, interval, subscribe } from 'wonka';
171
172pipe(
173 interval(50),
174 subscribe((e) => console.log(e))
175); // Prints 0 1 2... to the console.
176// The incrementing number is logged every 50ms
177```
178
179## empty
180
181This is a source that doesn't emit any values when subscribed to and
182immediately completes.
183
184```typescript
185import { pipe, empty, forEach } from 'wonka';
186
187pipe(
188 empty,
189 forEach((value) => {
190 /* This will never be called */
191 })
192);
193```
194
195## never
196
197This is source is similar to [`empty`](#empty).
198It doesn't emit any values but also never completes.
199
200```typescript
201import { pipe, never, forEach } from 'wonka';
202
203pipe(
204 never,
205 forEach((value) => {
206 /* This will never be called */
207 })
208);
209```