Skip to content

Wonka

Getting Started

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, 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:

Furthermore there are a couple of operators that only work in JavaScript environments since they need timing primitives, like setTimeout and setInterval: