kitten.sh
1---
2title: Getting Started
3order: 1
4---
5
6This page will explain how to install the Wonka package and
7its basic usage and helper functions.
8
9## Installation
10
11The `wonka` package from `npm` is all you need to install to use
12Wonka. The process is the same with `yarn` and `esy`.
13
14```bash
15yarn add wonka
16# or with npm:
17npm install --save wonka
18# or with esy:
19esy add wonka
20```
21
22For **JavaScript projects**, the package contains both CommonJS and
23ES Modules bundles. For Flow and TypeScript the package also contains
24typings files already, so if you're using either you're already done and
25ready to go.
26
27If you're using **BuckleScript** or `bs-native` you will need to add `"wonka"`
28to your `bs-dependencies` in your `bsconfig.json` configuration file:
29
30```diff
31{
32 "name": "<some_name>",
33 "version": "0.1.0",
34 "sources": ["src"],
35 "bsc-flags": ["-bs-super-errors"],
36 "bs-dependencies": [
37+ "wonka"
38 ]
39}
40```
41
42If you're using **Dune** and **Esy** you will need to add `wonka` to
43your `libraries` entry in the respective `dune` configuration file:
44
45```diff
46(library
47 (name some_name)
48 (public_name some_name)
49+ (libraries wonka)
50)
51```
52
53## Usage with JavaScript
54
55In most cases you'll simply import or require `wonka` and use its exposed
56methods and utilities. In both CommonJS and ES Modules the Wonka package
57simply exposes all its utilities.
58
59```js
60// With CommonJS
61const { fromArray } = require('wonka');
62// With ES Modules
63import { fromArray } from 'wonka';
64```
65
66There are also some special operators in Wonka that will only be exposed in
67Web/JavaScript environments, like `fromPromise`, `toPromise`,
68or `fromEvent`, or even `debounce` and `throttle`.
69In TypeScript and Flow the typings also expose all types.
70
71There's also a special utility in JavaScript environments to replace the pipeline
72operator. This function is called `pipe` and simply calls functions that it's
73being passed in order with the previous return value.
74
75```js
76import { pipe } from 'wonka';
77
78const output = pipe(
79 'test',
80 (x) => x + ' this',
81 (x) => x.toUpperCase()
82);
83
84output; // "TEST THIS"
85```
86
87As shown above, the `pipe` function takes the first argument and passes it
88in order to the other function arguments. The return value of one function will
89be passed on to the next function.
90
91In TypeScript and Flow the `pipe` function is also typed to handle all generics
92in Wonka utilities correctly. Using it will ensure that most of the time you won't
93have to specify the types of any generics manually.
94
95If you're using Babel and the [pipeline proposal plugin](https://babeljs.io/docs/en/babel-plugin-proposal-pipeline-operator), you can just use
96the pipeline operator to do the same and not use the `pipe` helper.
97
98## Usage with Reason
99
100Everything in the Wonka package is exposed under a single module called `Wonka`.
101This module also contains `Wonka.Types`, which contains all internal types of the Wonka
102library, but you will typically not need it.
103
104In `BuckleScript` when you're compiling to JavaScript you will also have access to
105more utilities like `fromPromise`, `toPromise`, `fromEvent`, or even `debounce` and `throttle`.
106These utilities are missing in native compilation, like Dune or `bsb-native`, since they're
107relying on JavaScript APIs like Promises, `window.addEventListener`, and `setTimeout`.
108
109When using Wonka you'd simply either open the module and use its utilities or just
110access them from the `Wonka` module:
111
112```reason
113Wonka.fromValue("test")
114 |> Wonka.map((.x) => x ++ " this")
115 |> Wonka.forEach((.x) => print_endline(x));
116```
117
118It's worth noting that most callbacks in Wonka need to be explicitly uncurried, since
119this will help them compile cleanly to JavaScript.
120
121## Interoperability
122
123In JavaScript environments, Wonka comes with several utilities that make it easier
124to interoperate with JavaScript primitives and other libraries:
125
126- [`fromPromise`](./api/sources.md#frompromise) & [`toPromise`](./api/sinks.md#topromise) can be used to interoperate with Promises
127- [`fromObservable`](./api/sources.md#fromobservable) & [`toObservable`](./api/sinks.md#toobservable) can be used to interoperate with spec-compliant Observables
128- [`fromCallbag`](./api/sources.md#fromcallbag) & [`toCallbag`](./api/sinks.md#tocallbag) can be used to interoperate with spec-compliant Callbags
129
130Furthermore there are a couple of operators that only work in JavaScript environments
131since they need timing primitives, like `setTimeout` and `setInterval`:
132
133- [`delay`](./api/operators.md#delay)
134- [`debounce`](./api/operators.md#debounce)
135- [`throttle`](./api/operators.md#throttle)
136- [`interval`](./api/sources.md#interval)