Tutorial

Let's write our first program using Effection.

import { call, useAbortSignal } from "effection";

export function* fetchWeekDay(timezone) {
  let signal = yield* useAbortSignal();

  let response = yield* call(fetch(`http://worldclockapi.com/api/json/${timezone}/now`, { signal }));

  let time = yield* call(response.json());

  return time.dayOfTheWeek;
}

To start using Effection, use the main function as an entry point. In this example, we'll use the previously defined fetchWeekDay.

import { main } from 'effection';
import { fetchWeekDay } from './fetch-week-day';

await main(function*() {

  let dayOfTheWeek = yield* fetchWeekDay('est');
  
  console.log(`It is ${dayOfTheWeek}, my friends!`);
});

Even with such a simple program, Effection is still providing critical power-ups that you don't get with callbacks, promises, or async/await. For example, notice how the Effection fetchWeekDay() operation does not accept an abort signal as a second argument. That's because there is no need to manually wire up any signal handlers and trigger an AbortController at the right time.

If you run the above code in NodeJS and hit CTRL-C while the request to http://worldclockapi.com is still in progress, it will properly cancel the in-flight request as a well-behaved HTTP client should. All without you ever having to think about it. This is because every Effection operation contains the information on how to dispose of itself, and so the actual act of cancellation can be automated.

This has powerful consequences when it comes to composing new operations out of existing ones. For example, we can add a time out of 1000 milliseconds to our fetchWeekDay operation (or any operation for that matter) by wrapping it in a withTimeout operation.

import { main, call, race } from 'effection';
import { fetchWeekDay } from './fetch-week-day';

await main(function*() {
  let dayOfTheWeek = yield* withTimeout(fetchWeekDay('est'), 1000);
  console.log(`It is ${dayOfTheWeek}, my friends!`);
});

function withTimeout(operation, delay) {
  return race([operation, call(function*() {
    yield* sleep(delay);
    throw new Error(`timeout!`);
  })]);
}

If more than 1000 milliseconds passes before the fetchWeekDay() operation completes, then an error will be raised.

What's important to note however, is that when we actually defined our fetchWeekDay() operation, we never once had to worry about timeouts, or request cancellation. And in order to achieve both we didn't have to gum up our API by passing around cancellation tokens or abort controllers. We just got it all for free.

Discover more

This is just the tip of the iceberg when it comes to the seemingly complex things that Effection can make simple. To find out more, jump into the conversation in our Discord server. We're really excited about the things that Effection has enabled us to accomplish, and we'd love to hear your thoughts on it, and how you might see it working for you.