Micro for Effect Users

The Micro module is designed as a lighter alternative to the standard Effect module, tailored for situations where it is beneficial to reduce the bundle size.

This module is standalone and does not include more complex functionalities such as Layer, Ref, Queue, and Deferred. This feature set makes Micro especially suitable for libraries that wish to utilize Effect functionalities while keeping the bundle size to a minimum, particularly for those aiming to provide Promise-based APIs.

Micro also supports use cases where a client application uses Micro, and a server employs the full suite of Effect features, maintaining both compatibility and logical consistency across various application components.

Integrating Micro adds a minimal footprint to your bundle, starting at 5kb gzipped, which may increase depending on the features you use.

Importing Micro

Micro is a part of the Effect library and can be imported just like any other module:

import { Micro } from "effect"

You can also import it using a namespace import like this:

import * as Micro from "effect/Micro"

Both forms of import allow you to access the functionalities provided by the Micro module.

However an important consideration is tree shaking, which refers to a process that eliminates unused code during the bundling of your application. Named imports may generate tree shaking issues when a bundler doesn’t support deep scope analysis.

Here are some bundlers that support deep scope analysis and thus don’t have issues with named imports:

• Rollup
• Webpack 5+

Main Types

Micro

The Micro type uses three type parameters:

        ┌─── Represents the success type
        │        ┌─── Represents the error type
        │        │      ┌─── Represents required dependencies
        ▼        ▼      ▼
Micro<Success, Error, Requirements>

which mirror those of the Effect type.

MicroExit

The MicroExit type is a streamlined version of the Exit type, designed to capture the outcome of a Micro computation. It can either be successful, containing a value of type A, or it can fail, containing an error of type E wrapped in a MicroCause.

type MicroExit<A, E> = MicroExit.Success<A, E> | MicroExit.Failure<A, E>

MicroCause

The MicroCause type is a streamlined version of the Cause type.

Similar to how Cause is a union of types, MicroCause comes in three forms:

type MicroCause<E> = Die | Fail<E> | Interrupt

MicroSchedule

The MicroSchedule type is a streamlined version of the Schedule type.

type MicroSchedule = (attempt: number, elapsed: number) => Option<number>

Represents a function that can be used to calculate the delay between repeats.

The function takes the current attempt number and the elapsed time since the first attempt, and returns the delay for the next attempt. If the function returns None, the repetition will stop.

How to Use This Guide

Below, you’ll find a series of comparisons between the functionalities of Effect and Micro. Each table lists a functionality of Effect alongside its counterpart in Micro. The icons used have the following meanings:

• ⚠️: The feature is available in Micro, but with some differences from Effect.
• ❌: The feature is not available in Effect.

Creating Effects

Running Effects

runSyncExit

The Micro.runSyncExit function is used to execute an Effect synchronously, which means it runs immediately and returns the result as a MicroExit.

Example (Handling Results as MicroExit)

1
import { Micro } from "effect"
2

3
const result1 = Micro.runSyncExit(Micro.succeed(1))
4
console.log(result1)
5
/*
6
Output:
7
{
8
  "_id": "MicroExit",
9
  "_tag": "Success",
10
  "value": 1
11
}
12
*/
13

14
const result2 = Micro.runSyncExit(Micro.fail("my error"))
15
console.log(result2)
16
/*
17
Output:
18
{
19
  "_id": "MicroExit",
20
  "_tag": "Failure",
21
  "cause": {
22
    "_tag": "Fail",
23
    "traces": [],
24
    "name": "MicroCause.Fail",
25
    "error": "my error"
26
  }
27
}
28
*/

runPromiseExit

The Micro.runPromiseExit function is used to execute an Effect and obtain the result as a Promise that resolves to a MicroExit.

Example (Handling Results as MicroExit)

1
import { Micro } from "effect"
2

3
Micro.runPromiseExit(Micro.succeed(1)).then(console.log)
4
/*
5
Output:
6
{
7
  "_id": "MicroExit",
8
  "_tag": "Success",
9
  "value": 1
10
}
11
*/
12

13
Micro.runPromiseExit(Micro.fail("my error")).then(console.log)
14
/*
15
Output:
16
{
17
  "_id": "MicroExit",
18
  "_tag": "Failure",
19
  "cause": {
20
    "_tag": "Fail",
21
    "traces": [],
22
    "name": "MicroCause.Fail",
23
    "error": "my error"
24
  }
25
}
26
*/

runFork

The Micro.runFork function executes the effect and return a MicroFiber that can be awaited, joined, or aborted.

You can listen for the result by adding an observer using the addObserver method.

Example (Observing an Asynchronous Effect)

1
import { Micro } from "effect"
2

3
//      ┌─── MicroFiber<number, never>
4
//      ▼
5
const fiber = Micro.succeed(42).pipe(Micro.delay(1000), Micro.runFork)
6

7
// Attach an observer to log the result when the effect completes
8
fiber.addObserver((result) => {
9
  console.log(result)
10
})
11

12
console.log("observing...")
13
/*
14
Output:
15
observing...
16
{
17
  "_id": "MicroExit",
18
  "_tag": "Success",
19
  "value": 42
20
}
21
*/

Building Pipelines

Expected Errors

Unexpected Errors

Timing Out

Requirements Management

To access a service while using Micro.gen, you need to wrap the service tag using the Micro.service function:

Example (Accessing a Service in Micro.gen)

1
import { Micro, Context } from "effect"
2

3
class Random extends Context.Tag("MyRandomService")<
4
  Random,
5
  { readonly next: Micro.Micro<number> }
6
>() {}
7

8
const program = Micro.gen(function* () {
9
  // const random = yield* Random // this doesn't work
10
  const random = yield* Micro.service(Random)
11
  const randomNumber = yield* random.next
12
  console.log(`random number: ${randomNumber}`)
13
})
14

15
const runnable = Micro.provideService(program, Random, {
16
  next: Micro.sync(() => Math.random()),
17
})
18

19
Micro.runPromise(runnable)
20
/*
21
Example Output:
22
random number: 0.8241872233134417
23
*/

Scope

Retrying

Repetition

Timing out

Sandboxing

Error Channel Operations

Requirements Management

Scoping, Resources and Finalization

Concurrency