You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
137 lines
4.5 KiB
137 lines
4.5 KiB
---
|
|
title: Getting Started
|
|
order: 1
|
|
---
|
|
|
|
This page will explain how to install the Wonka package and
|
|
its basic usage and helper functions.
|
|
|
|
## Installation
|
|
|
|
The `wonka` package from `npm` is all you need to install to use
|
|
Wonka. The process is the same with `yarn` and `esy`.
|
|
|
|
```bash
|
|
yarn add wonka
|
|
# or with npm:
|
|
npm install --save wonka
|
|
# or with esy:
|
|
esy add wonka
|
|
```
|
|
|
|
For **JavaScript projects**, the package contains both CommonJS and
|
|
ES Modules bundles. For Flow and TypeScript the package also contains
|
|
typings files already, so if you're using either you're already done and
|
|
ready to go.
|
|
|
|
If you're using **BuckleScript** or `bs-native` you will need to add `"wonka"`
|
|
to your `bs-dependencies` in your `bsconfig.json` configuration file:
|
|
|
|
```diff
|
|
{
|
|
"name": "<some_name>",
|
|
"version": "0.1.0",
|
|
"sources": ["src"],
|
|
"bsc-flags": ["-bs-super-errors"],
|
|
"bs-dependencies": [
|
|
+ "wonka"
|
|
]
|
|
}
|
|
```
|
|
|
|
If you're using **Dune** and **Esy** you will need to add `wonka` to
|
|
your `libraries` entry in the respective `dune` configuration file:
|
|
|
|
```diff
|
|
(library
|
|
(name some_name)
|
|
(public_name some_name)
|
|
+ (libraries wonka)
|
|
)
|
|
```
|
|
|
|
## Usage with JavaScript
|
|
|
|
In most cases you'll simply import or require `wonka` and use its exposed
|
|
methods and utilities. In both CommonJS and ES Modules the Wonka package
|
|
simply exposes all its utilities.
|
|
|
|
```js
|
|
// With CommonJS
|
|
const { fromArray } = require('wonka');
|
|
// With ES Modules
|
|
import { fromArray } from 'wonka';
|
|
```
|
|
|
|
There are also some special operators in Wonka that will only be exposed in
|
|
Web/JavaScript environments, like `fromPromise`, `toPromise`,
|
|
or `fromEvent`, or even `debounce` and `throttle`.
|
|
In TypeScript and Flow the typings also expose all types.
|
|
|
|
There's also a special utility in JavaScript environments to replace the pipeline
|
|
operator. This function is called `pipe` and simply calls functions that it's
|
|
being passed in order with the previous return value.
|
|
|
|
```js
|
|
import { pipe } from 'wonka';
|
|
|
|
const output = pipe(
|
|
'test',
|
|
x => x + ' this',
|
|
x => x.toUpperCase()
|
|
);
|
|
|
|
output; // "TEST THIS"
|
|
```
|
|
|
|
As shown above, the `pipe` function takes the first argument and passes it
|
|
in order to the other function arguments. The return value of one function will
|
|
be passed on to the next function.
|
|
|
|
In TypeScript and Flow the `pipe` function is also typed to handle all generics
|
|
in Wonka utilities correctly. Using it will ensure that most of the time you won't
|
|
have to specify the types of any generics manually.
|
|
|
|
If you're using Babel and the [pipeline proposal plugin](https://babeljs.io/docs/en/babel-plugin-proposal-pipeline-operator), you can just use
|
|
the pipeline operator to do the same and not use the `pipe` helper.
|
|
|
|
## Usage with Reason
|
|
|
|
Everything in the Wonka package is exposed under a single module called `Wonka`.
|
|
This module also contains `Wonka.Types`, which contains all internal types of the Wonka
|
|
library, but you will typically not need it.
|
|
|
|
In `BuckleScript` when you're compiling to JavaScript you will also have access to
|
|
more utilities like `fromPromise`, `toPromise`, `fromEvent`, or even `debounce` and `throttle`.
|
|
These utilities are missing in native compilation, like Dune or `bsb-native`, since they're
|
|
relying on JavaScript APIs like Promises, `window.addEventListener`, and `setTimeout`.
|
|
|
|
When using Wonka you'd simply either open the module and use its utilities or just
|
|
access them from the `Wonka` module:
|
|
|
|
```reason
|
|
Wonka.fromValue("test")
|
|
|> Wonka.map((.x) => x ++ " this")
|
|
|> Wonka.forEach((.x) => print_endline(x));
|
|
```
|
|
|
|
It's worth noting that most callbacks in Wonka need to be explicitly uncurried, since
|
|
this will help them compile cleanly to JavaScript.
|
|
|
|
## Interoperability
|
|
|
|
In JavaScript environments, Wonka comes with several utilities that make it easier
|
|
to interoperate with JavaScript primitives and other libraries:
|
|
|
|
- [`fromPromise`](./api/sources.md#frompromise) & [`toPromise`](./api/sinks.md#topromise) can be used to interoperate with Promises
|
|
- [`fromObservable`](./api/sources.md#fromobservable) & [`toObservable`](./api/sinks.md#toobservable) can be used to interoperate with spec-compliant Observables
|
|
- [`fromCallbag`](./api/sources.md#fromcallbag) & [`toCallbag`](./api/sinks.md#tocallbag) can be used to interoperate with spec-compliant Callbags
|
|
|
|
Furthermore there are a couple of operators that only work in JavaScript environments
|
|
since they need timing primitives, like `setTimeout` and `setInterval`:
|
|
|
|
- [`delay`](./api/operators.md#delay)
|
|
- [`debounce`](./api/operators.md#debounce)
|
|
- [`throttle`](./api/operators.md#throttle)
|
|
- [`interval`](./api/sources.md#interval)
|