kitten.sh
1/**
2 * Talkback signal that sends instructions from a sink to a source.
3 *
4 * @remarks
5 * This signal is issued via {@link TalkbackFn | talkback functions} that a {@link Sink} receives via
6 * the {@link Start} signal, to tell a {@link Source} to either send a new value (pulling) or stop
7 * sending values altogether (cancellation).
8 */
9export declare enum TalkbackKind {
10 /** Instructs the {@link Source} to send the next value. */
11 Pull = 0,
12 /** Instructs the {@link Source} to stop sending values and cancels it. */
13 Close = 1,
14}
15
16/**
17 * Talkback callback that sends instructions to a source.
18 *
19 * @remarks
20 * This function sends a {@link TalkbackKind} signal to the source to instruct it to send a new value
21 * (pulling) or to be cancelled and stop sending values altogether.
22 */
23export type TalkbackFn = (signal: TalkbackKind) => void;
24
25/**
26 * Callback that is called when a source is cancelled.
27 *
28 * @remarks
29 * This is used, in particular, in the {@link make | make Source} and is a returned function that is
30 * called when the {@link TalkbackKind.Close} signal is received by the source.
31 */
32export type TeardownFn = () => void;
33
34/**
35 * Tag enum that is used to on signals that are sent from a source to a sink.
36 *
37 * @remarks
38 * This signal is issued by a {@link Source} and {@link Sink | Sinks} are called with it. The signals
39 * carrying values ({@link Start} and {@link Push}) are sent as a unary `[T]` tuple tagged with
40 * {@link Tag}. The {@link End} signal carries no value and is sent as a raw `0` value.
41 * @see {@link Start} for the data structure of the start signal.
42 * @see {@link Push} for the data structure of the push signal, carrying values.
43 */
44export declare enum SignalKind {
45 /**
46 * Informs the {@link Sink} that it's being called by a {@link Source}.
47 *
48 * @remarks
49 * This starts the stream of values and carries a {@link TalkbackFn | talkback function} with it
50 * that is used by the {@link Sink} to communicate back to the {@link Source}.
51 * @see {@link Start} for the data structure of the signal.
52 */
53 Start = 0,
54 /**
55 * Informs the {@link Sink} of a new values that's incoming from the {@link Source}.
56 *
57 * @remarks
58 * This informs the {@link Sink} of new values that are sent by the {@link Source}.
59 * @see {@link Push} for the data structure of the signal.
60 */
61 Push = 1,
62 /**
63 * Informs the {@link Sink} that the {@link Source} has ended and that it won't send more values.
64 *
65 * @remarks
66 * This signal signifies that the stream has stopped and that no more values are expected. Some
67 * sources don't have a set end or limit on how many values will be sent. This signal is not sent
68 * when the {@link Source} is cancelled with a {@link TalkbackKind.Close | Close talkback signal}.
69 */
70 End = 0,
71}
72
73/**
74 * The tag property that's put on unary `[T]` tuple to turn them into signals carrying values.
75 *
76 * @internal
77 */
78export interface Tag<T> {
79 tag: T;
80}
81
82/**
83 * Indicates the start of a stream to a {@link Sink}.
84 *
85 * @remarks
86 * This signal is sent from a {@link Source} to a {@link Sink} at the start of a stream to inform it
87 * that values can be pulled and/or will be sent. This signal carries a
88 * {@link TalkbackFn | talkback function} that is used by the {@link Sink} to communicate back to the
89 * {@link Source} as a callback. The talkback accepts {@link TalkbackKind.Pull | Pull} and
90 * {@link TalkbackKind.Close | Close} signals.
91 */
92export type Start<_T> = Tag<SignalKind.Start> & [TalkbackFn];
93
94/**
95 * Sends a new value to a {@link Sink}.
96 *
97 * @remarks
98 * This signal is sent from a {@link Source} to a {@link Sink} to send a new value to it. This is
99 * essentially the signal that wraps new values coming in, like an event. Values are carried on
100 * unary tuples and can be accessed using `signal[0]`.
101 */
102export type Push<T> = Tag<SignalKind.Push> & [T];
103
104/**
105 * Signals are sent from {@link Source | Sources} to {@link Sink | Sinks} to inform them of changes.
106 *
107 * @remarks
108 * A {@link Source}, when consumed, sends a sequence of events to {@link Sink | Sinks}. In order, a
109 * {@link SignalKind.Start | Start} signal will always be sent first, followed optionally by one or
110 * more {@link SignalKind.Push | Push signals}, carrying values and representing the stream. A
111 * {@link Source} will send the {@link SignalKind.End | End signal} when it runs out of values. The
112 * End signal will be omitted if the Source is cancelled by a
113 * {@link TalkbackKind.Close | Close signal}, sent back from the {@link Sink}.
114 * @see {@link SignalKind} for the kinds signals sent by {@link Source | Sources}.
115 * @see {@link Start} for the data structure of the start signal.
116 * @see {@link Push} for the data structure of the push signal.
117 */
118export type Signal<T> = Start<T> | Push<T> | SignalKind.End;
119
120/**
121 * Callback function that is called by a {@link Source} with {@link Signal | Signals}.
122 *
123 * @remarks
124 * A Sink is a function that is called repeatedly with signals from a {@link Source}. It represents
125 * the receiver of the stream of signals/events coming from a {@link Source}.
126 * @see {@link Signal} for the data structure of signals.
127 */
128export type Sink<T> = (signal: Signal<T>) => void;
129
130/** Factory function that calls {@link Sink | Sinks} with {@link Signal | Signals} when invoked.
131 * @remarks
132 * A Source is a factory function that when invoked with a {@link Sink}, calls it with
133 * {@link Signal | Signals} to create a stream of events, informing it of new values and the
134 * potential end of the stream of values. The first signal a Source sends is always a
135 * {@link Start | Start signal} that sends a talkback function to the {@link Sink}, so it may request
136 * new values or cancel the source.
137 *
138 * @see {@link Signal} for the data structure of signals.
139 * @see {@link Sink} for the data structure of sinks.
140 */
141export type Source<T> = (sink: Sink<T>) => void;
142
143/** Transform function that accepts a {@link Source} and returns a new one.
144 * @remarks
145 * Wonka comes with several helper operators that transform a given {@link Source} into a new one,
146 * potentially changing its outputs, or the outputs' timing. An "operator" in Wonka typically
147 * accepts arguments and then returns this kind of function, so they can be chained and composed.
148 *
149 * @see {@link pipe | `pipe`} for the helper used to compose operators.
150 */
151export type Operator<In, Out> = (a: Source<In>) => Source<Out>;
152
153/** Type utility to determine the type of a {@link Source}. */
154export type TypeOfSource<T> = T extends Source<infer U> ? U : never;
155
156/** Subscription object that can be used to cancel a {@link Source}.
157 * @see {@link subscribe | subscribe sink} for a helper that returns this structure.
158 */
159export interface Subscription {
160 /**
161 * Cancels a {@link Source} to stop the subscription from receiving new values.
162 *
163 * @see {@link TalkbackKind.Close | Close signal} This uses the {@link TalkbackFn | talkback function} to send a {@link TalkbackKind.Close | Close signal}
164 * to the subscribed-to {@link Source} to stop it from sending new values. This cleans up the subscription
165 * and ends it immediately.
166 */
167 unsubscribe(): void;
168}
169
170/** An Observer represents sending signals manually to a {@link Sink}.
171 * @remarks
172 * The Observer is used whenever a utility allows for signals to be sent manually as a {@link Source}
173 * would send them.
174 *
175 * @see {@link make | `make` source} for a helper that uses this structure.
176 */
177export interface Observer<T> {
178 /** Sends a new value to the receiving Sink.
179 * @remarks
180 * This creates a {@link Push | Push signal} that is sent to a {@link Sink}.
181 */
182 next(value: T): void;
183 /** Indicates to the receiving Sink that no more values will be sent.
184 * @remarks
185 * This creates an {@link SignalKind.End | End signal} that is sent to a {@link Sink}. The Observer
186 * will accept no more values via {@link Observer.next | `next` calls} once this method has been
187 * invoked.
188 */
189 complete(): void;
190}
191
192/** Subjects combine a {@link Source} with the {@link Observer} that is used to send values on said Source.
193 * @remarks
194 * A Subject is used whenever an event hub-like structure is needed, as it both provides the
195 * {@link Observer}'s methods to send signals, as well as the `source` to receive said signals.
196 *
197 * @see {@link makeSubject | `makeSubject` source} for a helper that creates this structure.
198 */
199export interface Subject<T> extends Observer<T> {
200 /** The {@link Source} that issues the signals as the {@link Observer} methods are called. */
201 source: Source<T>;
202}
203
204/** Async Iterable/Iterator after having converted a {@link Source}.
205 * @see {@link toAsyncIterable} for a helper that creates this structure.
206 */
207export interface SourceIterable<T> extends AsyncIterator<T>, AsyncIterable<T> {}