Skip to content

Micro

A lightweight alternative to the Effect data type, with a subset of the functionality.

193 exports Added in v3.4.0 Source

Collecting & Elements

all

Added in v3.4.0 Source

Runs all the provided effects in sequence respecting the structure provided in input.

Supports multiple arguments, a single argument tuple / array or record / struct.

Signature

declare function all<
  Arg extends Iterable<Micro<any, any, any>, any, any> | Record<string, Micro<any, any, any>>,
  O extends NoExcessProperties<
    {
      readonly concurrency?: Concurrency;
      readonly discard?: boolean;
    },
    O
  >,
>(arg: Arg, options?: O): Return<Arg, O>;

filter

Added in v3.4.0 Source

Effectfully filter the elements of the provided iterable.

Use the concurrency option to control how many elements are processed concurrently.

Signature

declare function filter<A, E, R>(
  iterable: Iterable<A>,
  f: (a: NoInfer<A>) => Micro<boolean, E, R>,
  options?: {
    readonly concurrency?: Concurrency;
    readonly negate?: boolean;
  },
): Micro<Array<A>, E, R>;

filterMap

Added in v3.4.0 Source

Effectfully filter the elements of the provided iterable.

Use the concurrency option to control how many elements are processed concurrently.

Signature

declare function filterMap<A, B, E, R>(
  iterable: Iterable<A>,
  f: (a: NoInfer<A>) => Micro<Option<B>, E, R>,
  options?: {
    readonly concurrency?: Concurrency;
  },
): Micro<Array<B>, E, R>;

forEach

Added in v3.4.0 Source

For each element of the provided iterable, run the effect and collect the results.

If the discard option is set to true, the results will be discarded and the effect will return void.

The concurrency option can be set to control how many effects are run concurrently. By default, the effects are run sequentially.

Signature

declare const forEach: {
  <A, B, E, R>(
    iterable: Iterable<A>,
    f: (a: A, index: number) => Micro<B, E, R>,
    options?: {
      readonly concurrency?: Concurrency;
      readonly discard?: false;
    },
  ): Micro<Array<B>, E, R>;
  <A, B, E, R>(
    iterable: Iterable<A>,
    f: (a: A, index: number) => Micro<B, E, R>,
    options: {
      readonly concurrency?: Concurrency;
      readonly discard: true;
    },
  ): Micro<void, E, R>;
};

whileLoop

Added in v3.11.0 Source

Signature

declare const whileLoop: <A, E, R>(options: {
  readonly body: LazyArg<Micro<A, E, R>>;
  readonly step: (a: A) => void;
  readonly while: LazyArg<boolean>;
}) => Micro<void, E, R>;

Constructors

async

Added in v3.4.0 Source

Create a Micro effect from an asynchronous computation.

You can return a cleanup effect that will be run when the effect is aborted. It is also passed an AbortSignal that is triggered when the effect is aborted.

Signature

declare function async<A, E = never, R = never>(
  register: (
    resume: (effect: Micro<A, E, R>) => void,
    signal: AbortSignal,
  ) => void | Micro<void, never, R>,
): Micro<A, E, R>;

die

Added in v3.4.0 Source

Creates a Micro effect that will die with the specified error.

This results in a Die variant of the MicroCause type, where the error is not tracked at the type level.

Signature

declare function die(defect: unknown): Micro<never>;

fail

Added in v3.4.0 Source

Creates a Micro effect that fails with the given error.

This results in a Fail variant of the MicroCause type, where the error is tracked at the type level.

Signature

declare function fail<E>(error: E): Micro<never, E>;

failCause

Added in v3.4.6 Source

Creates a Micro effect that will fail with the specified MicroCause.

Signature

declare const failCause: <E>(cause: MicroCause<E>) => Micro<never, E>;

Creates a Micro effect that will fail with the lazily evaluated MicroCause.

Signature

declare function failCauseSync<E>(evaluate: LazyArg<MicroCause<E>>): Micro<never, E>;

failSync

Added in v3.4.6 Source

Creates a Micro effect that will fail with the lazily evaluated error.

This results in a Fail variant of the MicroCause type, where the error is tracked at the type level.

Signature

declare function failSync<E>(error: LazyArg<E>): Micro<never, E>;

fromEither

Added in v3.4.0 Source

Converts an Either into a Micro effect, that will fail with the left side of the either if it is a Left. Otherwise, it will succeed with the right side of the either.

Signature

declare function fromEither<R, L>(either: Either<R, L>): Micro<R, L>;

fromOption

Added in v3.4.0 Source

Converts an Option into a Micro effect, that will fail with NoSuchElementException if the option is None. Otherwise, it will succeed with the value of the option.

Signature

declare function fromOption<A>(option: Option<A>): Micro<A, NoSuchElementException>;

gen

Added in v3.4.0 Source

Signature

declare function gen<Self, Eff extends YieldWrap<Micro<any, any, any>>, AEff>(
  ...args:
    | [self: Self, body: (this: Self) => Generator<Eff, AEff, never>]
    | [body: () => Generator<Eff, AEff, never>]
): Micro<
  AEff,
  [Eff] extends [never] ? never : [Eff] extends [YieldWrap<Micro<_A, E, _R>>] ? E : never,
  [Eff] extends [never] ? never : [Eff] extends [YieldWrap<Micro<_A, _E, R>>] ? R : never
>;

never

Added in v3.4.0 Source

A Micro that will never succeed or fail. It wraps setInterval to prevent the Javascript runtime from exiting.

Signature

declare const never: Micro<never>;

promise

Added in v3.4.0 Source

Wrap a Promise into a Micro effect.

Any errors will result in a Die variant of the MicroCause type, where the error is not tracked at the type level.

Signature

declare function promise<A>(evaluate: (signal: AbortSignal) => PromiseLike<A>): Micro<A>;

succeed

Added in v3.4.0 Source

Creates a Micro effect that will succeed with the specified constant value.

Signature

declare const succeed: <A>(value: A) => Micro<A>;

succeedNone

Added in v3.4.0 Source

Creates a Micro effect that succeeds with None.

Signature

declare const succeedNone: Micro<Option.Option<never>>;

succeedSome

Added in v3.4.0 Source

Creates a Micro effect that will succeed with the value wrapped in Some.

Signature

declare function succeedSome<A>(a: A): Micro<Option<A>>;

suspend

Added in v3.4.0 Source

Lazily creates a Micro effect from the given side-effect.

Signature

declare const suspend: <A, E, R>(evaluate: LazyArg<Micro<A, E, R>>) => Micro<A, E, R>;

sync

Added in v3.4.0 Source

Creates a Micro effect that succeeds with a lazily evaluated value.

If the evaluation of the value throws an error, the effect will fail with a Die variant of the MicroCause type.

Signature

declare const sync: <A>(evaluate: LazyArg<A>) => Micro<A>;

tryPromise

Added in v3.4.0 Source

Wrap a Promise into a Micro effect. Any errors will be caught and converted into a specific error type.

Signature

declare function tryPromise<A, E>(options: {
  readonly catch: (error: unknown) => E;
  readonly try: (signal: AbortSignal) => PromiseLike<A>;
}): Micro<A, E>;

Example

import { Micro } from "effect"

Micro.tryPromise({
  try: () => Promise.resolve("success"),
  catch: (cause) => new Error("caught", { cause }),
})

Create a Micro effect using the current MicroFiber.

Signature

declare const withMicroFiber: <A, E = never, R = never>(
  evaluate: (fiber: MicroFiberImpl<A, E>) => Micro<A, E, R>,
) => Micro<A, E, R>;

yieldFlush

Added in v3.4.0 Source

Flush any yielded effects that are waiting to be executed.

Signature

declare const yieldFlush: Micro<void>;

yieldNow

Added in v3.4.0 Source

Pause the execution of the current Micro effect, and resume it on the next scheduler tick.

Signature

declare const yieldNow: Micro<void>;

yieldNowWith

Added in v3.4.0 Source

Pause the execution of the current Micro effect, and resume it on the next scheduler tick.

Signature

declare const yieldNowWith: (priority?: number) => Micro<void>;

Delays & Timeouts

delay

Added in v3.4.0 Source

Returns an effect that will delay the execution of this effect by the specified duration.

Signature

declare const delay: {
  (millis: number): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, R>;
  <A, E, R>(self: Micro<A, E, R>, millis: number): Micro<A, E, R>;
};

sleep

Added in v3.4.0 Source

Create a Micro effect that will sleep for the specified duration.

Signature

declare function sleep(millis: number): Micro<void>;

timeout

Added in v3.4.0 Source

Returns an effect that will timeout this effect, that will fail with a TimeoutException if the timeout elapses before the effect has produced a value.

If the timeout elapses, the running effect will be safely interrupted.

Signature

declare const timeout: {
  (millis: number): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E | TimeoutException, R>;
  <A, E, R>(self: Micro<A, E, R>, millis: number): Micro<A, E | TimeoutException, R>;
};

Returns an effect that will timeout this effect, succeeding with a None if the timeout elapses before the effect has produced a value; and Some of the produced value otherwise.

If the timeout elapses, the running effect will be safely interrupted.

Signature

declare const timeoutOption: {
  (millis: number): <A, E, R>(self: Micro<A, E, R>) => Micro<Option<A>, E, R>;
  <A, E, R>(self: Micro<A, E, R>, millis: number): Micro<Option<A>, E, R>;
};

Returns an effect that will timeout this effect, that will execute the fallback effect if the timeout elapses before the effect has produced a value.

If the timeout elapses, the running effect will be safely interrupted.

Signature

declare const timeoutOrElse: {
  <A2, E2, R2>(options: {
    readonly duration: number;
    readonly onTimeout: LazyArg<Micro<A2, E2, R2>>;
  }): <A, E, R>(self: Micro<A, E, R>) => Micro<A2 | A, E2 | E, R2 | R>;
  <A, E, R, A2, E2, R2>(
    self: Micro<A, E, R>,
    options: {
      readonly duration: number;
      readonly onTimeout: LazyArg<Micro<A2, E2, R2>>;
    },
  ): Micro<A | A2, E | E2, R | R2>;
};

Do Notation

bind

Added in v3.4.0 Source

Bind the success value of this Micro effect to the provided name.

Signature

declare const bind: {
  <N extends string, A extends Record<string, any>, B, E2, R2>(
    name: N,
    f: (a: NoInfer<A>) => Micro<B, E2, R2>,
  ): <E, R>(
    self: Micro<A, E, R>,
  ) => Micro<Simplify<Omit<A, N> & { [K in string]: B }>, E2 | E, R2 | R>;
  <A extends Record<string, any>, E, R, B, E2, R2, N extends string>(
    self: Micro<A, E, R>,
    name: N,
    f: (a: NoInfer<A>) => Micro<B, E2, R2>,
  ): Micro<Simplify<Omit<A, N> & { [K in string]: B }>, E | E2, R | R2>;
};

bindTo

Added in v3.4.0 Source

Bind the success value of this Micro effect to the provided name.

Signature

declare const bindTo: {
  <N extends string>(name: N): <A, E, R>(self: Micro<A, E, R>) => Micro<{ [K in string]: A }, E, R>;
  <A, E, R, N extends string>(self: Micro<A, E, R>, name: N): Micro<{ [K in string]: A }, E, R>;
};

Do

Added in v3.4.0 Source

Start a do notation block.

Signature

declare const Do: Micro<{}>;

Environment

context

Added in v3.4.0 Source

Access the current Context from the environment.

Signature

declare function context<R>(): Micro<Context<R>>;

Merge the given Context with the current context.

Signature

declare const provideContext: {
  <XR>(context: Context<XR>): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, Exclude<R, XR>>;
  <A, E, R, XR>(self: Micro<A, E, R>, context: Context<XR>): Micro<A, E, Exclude<R, XR>>;
};

Add the provided service to the current context.

Signature

declare const provideService: {
  <I, S>(tag: Tag<I, S>, service: S): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, Exclude<R, I>>;
  <A, E, R, I, S>(self: Micro<A, E, R>, tag: Tag<I, S>, service: S): Micro<A, E, Exclude<R, I>>;
};

Create a service using the provided Micro effect, and add it to the current context.

Signature

declare const provideServiceEffect: {
  <I, S, E2, R2>(
    tag: Tag<I, S>,
    acquire: Micro<S, E2, R2>,
  ): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E2 | E, R2 | Exclude<R, I>>;
  <A, E, R, I, S, E2, R2>(
    self: Micro<A, E, R>,
    tag: Tag<I, S>,
    acquire: Micro<S, E2, R2>,
  ): Micro<A, E | E2, R2 | Exclude<R, I>>;
};

service

Added in v3.4.0 Source

Access the given Context.Tag from the environment.

Signature

declare const service: {
  <I, S>(tag: Reference<I, S>): Micro<S>;
  <I, S>(tag: Tag<I, S>): Micro<S, never, I>;
};

Access the given Context.Tag from the environment, without tracking the dependency at the type level.

It will return an Option of the service, depending on whether it is available in the environment or not.

Signature

declare function serviceOption<I, S>(tag: Tag<I, S>): Micro<Option<S>>;

updateContext

Added in v3.11.0 Source

Update the Context with the given mapping function.

Signature

declare const updateContext: {
  <R2, R>(
    f: (context: Context<R2>) => Context<NoInfer<R>>,
  ): <A, E>(self: Micro<A, E, R>) => Micro<A, E, R2>;
  <A, E, R, R2>(
    self: Micro<A, E, R>,
    f: (context: Context<R2>) => Context<NoInfer<R>>,
  ): Micro<A, E, R2>;
};

updateService

Added in v3.11.0 Source

Update the service for the given Context.Tag in the environment.

Signature

declare const updateService: {
  <I, A>(
    tag: Reference<I, A>,
    f: (value: A) => A,
  ): <XA, E, R>(self: Micro<XA, E, R>) => Micro<XA, E, R>;
  <I, A>(
    tag: Tag<I, A>,
    f: (value: A) => A,
  ): <XA, E, R>(self: Micro<XA, E, R>) => Micro<XA, E, I | R>;
  <XA, E, R, I, A>(
    self: Micro<XA, E, R>,
    tag: Reference<I, A>,
    f: (value: A) => A,
  ): Micro<XA, E, R>;
  <XA, E, R, I, A>(self: Micro<XA, E, R>, tag: Tag<I, A>, f: (value: A) => A): Micro<XA, E, R | I>;
};

Environment Refs

Signature

declare class CurrentConcurrency extends TagClassShape<
  "effect/Micro/currentConcurrency",
  number | "unbounded",
  this
> {
  constructor(_: never);
}

Signature

declare class CurrentScheduler extends TagClassShape<
  "effect/Micro/currentScheduler",
  MicroScheduler,
  this
> {
  constructor(_: never);
}

If you have a Micro that uses concurrency: "inherit", you can use this api to control the concurrency of that Micro when it is run.

Signature

declare const withConcurrency: {
  (concurrency: number | "unbounded"): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, R>;
  <A, E, R>(self: Micro<A, E, R>, concurrency: number | "unbounded"): Micro<A, E, R>;
};

Example

import * as Micro from "effect/Micro"

Micro.forEach([1, 2, 3], (n) => Micro.succeed(n), {
  concurrency: "inherit",
}).pipe(
  Micro.withConcurrency(2), // use a concurrency of 2
)

Error Handling

catchAll

Added in v3.4.6 Source

Catch the error of the given Micro effect, allowing you to recover from it.

It only catches expected errors.

Signature

declare const catchAll: {
  <E, B, E2, R2>(
    f: (e: NoInfer<E>) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<B | A, E2, R2 | R>;
  <A, E, R, B, E2, R2>(
    self: Micro<A, E, R>,
    f: (e: NoInfer<E>) => Micro<B, E2, R2>,
  ): Micro<A | B, E2, R | R2>;
};

Catch the full MicroCause object of the given Micro effect, allowing you to recover from any kind of cause.

Signature

declare const catchAllCause: {
  <E, B, E2, R2>(
    f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<B | A, E2, R2 | R>;
  <A, E, R, B, E2, R2>(
    self: Micro<A, E, R>,
    f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>,
  ): Micro<A | B, E2, R | R2>;
};

Catch any unexpected errors of the given Micro effect, allowing you to recover from them.

Signature

declare const catchAllDefect: {
  <E, B, E2, R2>(
    f: (defect: unknown) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<B | A, E | E2, R2 | R>;
  <A, E, R, B, E2, R2>(
    self: Micro<A, E, R>,
    f: (defect: unknown) => Micro<B, E2, R2>,
  ): Micro<A | B, E | E2, R | R2>;
};

catchCauseIf

Added in v3.4.6 Source

Selectively catch a MicroCause object of the given Micro effect, using the provided predicate to determine if the failure should be caught.

Signature

declare const catchCauseIf: {
  <E, B, E2, R2, EB extends MicroCause<E>>(
    refinement: Refinement<MicroCause<E>, EB>,
    f: (cause: EB) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<B | A, E2 | Exclude<E, Error<EB>>, R2 | R>;
  <E, B, E2, R2>(
    predicate: Predicate<MicroCause<NoInfer<E>>>,
    f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<B | A, E | E2, R2 | R>;
  <A, E, R, B, E2, R2, EB extends MicroCause<E>>(
    self: Micro<A, E, R>,
    refinement: Refinement<MicroCause<E>, EB>,
    f: (cause: EB) => Micro<B, E2, R2>,
  ): Micro<A | B, E2 | Exclude<E, Error<EB>>, R | R2>;
  <A, E, R, B, E2, R2>(
    self: Micro<A, E, R>,
    predicate: Predicate<MicroCause<NoInfer<E>>>,
    f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>,
  ): Micro<A | B, E | E2, R | R2>;
};

catchIf

Added in v3.4.0 Source

Catch any expected errors that match the specified predicate.

Signature

declare const catchIf: {
  <E, EB, A2, E2, R2>(
    refinement: Refinement<NoInfer<E>, EB>,
    f: (e: EB) => Micro<A2, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<A2 | A, E2 | Exclude<E, EB>, R2 | R>;
  <E, A2, E2, R2>(
    predicate: Predicate<NoInfer<E>>,
    f: (e: NoInfer<E>) => Micro<A2, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<A2 | A, E | E2, R2 | R>;
  <A, E, R, EB, A2, E2, R2>(
    self: Micro<A, E, R>,
    refinement: Refinement<E, EB>,
    f: (e: EB) => Micro<A2, E2, R2>,
  ): Micro<A | A2, E2 | Exclude<E, EB>, R | R2>;
  <A, E, R, A2, E2, R2>(
    self: Micro<A, E, R>,
    predicate: Predicate<E>,
    f: (e: E) => Micro<A2, E2, R2>,
  ): Micro<A | A2, E | E2, R | R2>;
};

catchTag

Added in v3.4.0 Source

Recovers from the specified tagged error.

Signature

declare const catchTag: {
  <K extends string, E, A1, E1, R1>(
    k: K,
    f: (
      e: Extract<
        E,
        {
          _tag: K;
        }
      >,
    ) => Micro<A1, E1, R1>,
  ): <A, R>(
    self: Micro<A, E, R>,
  ) => Micro<
    A1 | A,
    | E1
    | Exclude<
        E,
        {
          _tag: K;
        }
      >,
    R1 | R
  >;
  <A, E, R, K extends string, R1, E1, A1>(
    self: Micro<A, E, R>,
    k: K,
    f: (
      e: Extract<
        E,
        {
          _tag: K;
        }
      >,
    ) => Micro<A1, E1, R1>,
  ): Micro<
    A | A1,
    | E1
    | Exclude<
        E,
        {
          _tag: K;
        }
      >,
    R | R1
  >;
};

either

Added in v3.4.0 Source

Replace the success value of the given Micro effect with an Either, wrapping the success value in Right and wrapping any expected errors with a Left.

Signature

declare function either<A, E, R>(self: Micro<A, E, R>): Micro<Either<A, E>, never, R>;

ignore

Added in v3.4.0 Source

Ignore any expected errors of the given Micro effect, returning void.

Signature

declare function ignore<A, E, R>(self: Micro<A, E, R>): Micro<void, never, R>;

ignoreLogged

Added in v3.4.0 Source

Ignore any expected errors of the given Micro effect, returning void.

Signature

declare function ignoreLogged<A, E, R>(self: Micro<A, E, R>): Micro<void, never, R>;

mapError

Added in v3.4.0 Source

Transform any expected errors of the given Micro effect.

Signature

declare const mapError: {
  <E, E2>(f: (e: E) => E2): <A, R>(self: Micro<A, E, R>) => Micro<A, E2, R>;
  <A, E, R, E2>(self: Micro<A, E, R>, f: (e: E) => E2): Micro<A, E2, R>;
};

Transform the full MicroCause object of the given Micro effect.

Signature

declare const mapErrorCause: {
  <E, E2>(f: (e: MicroCause<E>) => MicroCause<E2>): <A, R>(self: Micro<A, E, R>) => Micro<A, E2, R>;
  <A, E, R, E2>(self: Micro<A, E, R>, f: (e: MicroCause<E>) => MicroCause<E2>): Micro<A, E2, R>;
};

option

Added in v3.4.0 Source

Replace the success value of the given Micro effect with an Option, wrapping the success value in Some and returning None if the effect fails with an expected error.

Signature

declare function option<A, E, R>(self: Micro<A, E, R>): Micro<Option<A>, never, R>;

orDie

Added in v3.4.0 Source

Elevate any expected errors of the given Micro effect to unexpected errors, resulting in an error type of never.

Signature

declare function orDie<A, E, R>(self: Micro<A, E, R>): Micro<A, never, R>;

Recover from all errors by succeeding with the given value.

Signature

declare const orElseSucceed: {
  <B>(f: LazyArg<B>): <A, E, R>(self: Micro<A, E, R>) => Micro<B | A, never, R>;
  <A, E, R, B>(self: Micro<A, E, R>, f: LazyArg<B>): Micro<A | B, never, R>;
};

retry

Added in v3.4.0 Source

Retry the given Micro effect using the provided options.

Signature

declare const retry: {
  <A, E>(options?: {
    schedule?: MicroSchedule;
    times?: number;
    while?: Predicate<E>;
  }): <R>(self: Micro<A, E, R>) => Micro<A, E, R>;
  <A, E, R>(
    self: Micro<A, E, R>,
    options?: {
      schedule?: MicroSchedule;
      times?: number;
      while?: Predicate<E>;
    },
  ): Micro<A, E, R>;
};

tapDefect

Added in v3.4.6 Source

Perform a side effect from unexpected errors of the given Micro.

Signature

declare const tapDefect: {
  <E, B, E2, R2>(
    f: (defect: unknown) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R2 | R>;
  <A, E, R, B, E2, R2>(
    self: Micro<A, E, R>,
    f: (defect: unknown) => Micro<B, E2, R2>,
  ): Micro<A, E | E2, R | R2>;
};

tapError

Added in v3.4.6 Source

Perform a side effect from expected errors of the given Micro.

Signature

declare const tapError: {
  <E, B, E2, R2>(
    f: (e: NoInfer<E>) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R2 | R>;
  <A, E, R, B, E2, R2>(
    self: Micro<A, E, R>,
    f: (e: NoInfer<E>) => Micro<B, E2, R2>,
  ): Micro<A, E | E2, R | R2>;
};

Perform a side effect using the full MicroCause object of the given Micro.

Signature

declare const tapErrorCause: {
  <E, B, E2, R2>(
    f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R2 | R>;
  <A, E, R, B, E2, R2>(
    self: Micro<A, E, R>,
    f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>,
  ): Micro<A, E | E2, R | R2>;
};

Perform a side effect using if a MicroCause object matches the specified predicate.

Signature

declare const tapErrorCauseIf: {
  <E, B, E2, R2, EB extends MicroCause<E>>(
    refinement: Refinement<MicroCause<E>, EB>,
    f: (a: EB) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R2 | R>;
  <E, B, E2, R2>(
    predicate: (cause: NoInfer<MicroCause<E>>) => boolean,
    f: (a: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>,
  ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R2 | R>;
  <A, E, R, B, E2, R2, EB extends MicroCause<E>>(
    self: Micro<A, E, R>,
    refinement: Refinement<MicroCause<E>, EB>,
    f: (a: EB) => Micro<B, E2, R2>,
  ): Micro<A, E | E2, R | R2>;
  <A, E, R, B, E2, R2>(
    self: Micro<A, E, R>,
    predicate: (cause: NoInfer<MicroCause<E>>) => boolean,
    f: (a: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>,
  ): Micro<A, E | E2, R | R2>;
};

withTrace

Added in v3.4.0 Source

Add a stack trace to any failures that occur in the effect. The trace will be added to the traces field of the MicroCause object.

Signature

declare const withTrace: {
  (name: string): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, R>;
  <A, E, R>(self: Micro<A, E, R>, name: string): Micro<A, E, R>;
};

Errors

Error

Added in v3.4.0 Source

Signature

declare const Error: <A extends Record<string, any> = {}>(
  args: Equals<A, {}> extends true ? void : { [P in keyof A]: A[P] },
) => YieldableError & Readonly<A>;

Represents a checked exception which occurs when an expected element was unable to be found.

Signature

declare class NoSuchElementException extends YieldableError<this> & {
  readonly _tag: "NoSuchElementException";
} & Readonly<{
  message?: string;
}> {
  constructor(args: {
    readonly message?: string;
  });
}

TaggedError

Added in v3.4.0 Source

Signature

declare function TaggedError<Tag extends string>(
  tag: Tag,
): <A extends Record<string, any> = {}>(
  args: Equals<A, {}> extends true ? void : { [P in string | number | symbol]: A[P] },
) => YieldableError & {
  readonly _tag: Tag;
} & Readonly<A>;

Represents a checked exception which occurs when a timeout occurs.

Signature

declare class TimeoutException extends YieldableError<this> & {
  readonly _tag: "TimeoutException";
} & Readonly<{}> {
  constructor(args: void);
}

YieldableError interface

Added in v3.4.0 Source

Signature

interface YieldableError extends Pipeable, Inspectable, Readonly<Error> {
  readonly [ChannelTypeId]: VarianceStruct<
    never,
    unknown,
    YieldableError,
    unknown,
    never,
    unknown,
    never
  >;
  readonly [EffectTypeId]: VarianceStruct<never, YieldableError, never>;
  readonly [SinkTypeId]: VarianceStruct<never, unknown, never, YieldableError, never>;
  readonly [StreamTypeId]: VarianceStruct<never, YieldableError, never>;
  readonly [TypeId]: Variance<never, YieldableError, never>;
  [iterator](): MicroIterator<Micro<never, YieldableError, never>>;
}

Execution

runFork

Added in v3.4.0 Source

Execute the Micro effect and return a MicroFiber that can be awaited, joined, or aborted.

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

Signature

declare function runFork<A, E>(
  effect: Micro<A, E>,
  options?: {
    readonly scheduler?: MicroScheduler;
    readonly signal?: AbortSignal;
  },
): MicroFiberImpl<A, E>;

Example

import * as Micro from "effect/Micro"

const handle = Micro.succeed(42).pipe(Micro.delay(1000), Micro.runFork)

handle.addObserver((exit) => {
  console.log(exit)
})

runPromise

Added in v3.4.0 Source

Execute the Micro effect and return a Promise that resolves with the successful value of the computation.

Signature

declare function runPromise<A, E>(
  effect: Micro<A, E>,
  options?: {
    readonly scheduler?: MicroScheduler;
    readonly signal?: AbortSignal;
  },
): Promise<A>;

Execute the Micro effect and return a Promise that resolves with the MicroExit of the computation.

Signature

declare function runPromiseExit<A, E>(
  effect: Micro<A, E>,
  options?: {
    readonly scheduler?: MicroScheduler;
    readonly signal?: AbortSignal;
  },
): Promise<MicroExit<A, E>>;

runSync

Added in v3.4.0 Source

Attempt to execute the Micro effect synchronously and return the success value.

Signature

declare function runSync<A, E>(effect: Micro<A, E>): A;

runSyncExit

Added in v3.4.6 Source

Attempt to execute the Micro effect synchronously and return the MicroExit.

If any asynchronous effects are encountered, the function will return a CauseDie containing the MicroFiber.

Signature

declare function runSyncExit<A, E>(effect: Micro<A, E>): MicroExit<A, E>;

Fiber & Forking

fork

Added in v3.4.0 Source

Run the Micro effect in a new MicroFiber that can be awaited, joined, or aborted.

When the parent Micro finishes, this Micro will be aborted.

Signature

declare function fork<A, E, R>(self: Micro<A, E, R>): Micro<MicroFiber<A, E>, never, R>;

forkDaemon

Added in v3.4.0 Source

Run the Micro effect in a new MicroFiber that can be awaited, joined, or aborted.

It will not be aborted when the parent Micro finishes.

Signature

declare function forkDaemon<A, E, R>(self: Micro<A, E, R>): Micro<MicroFiber<A, E>, never, R>;

forkIn

Added in v3.4.0 Source

Run the Micro effect in a new MicroFiber that can be awaited, joined, or aborted.

The lifetime of the handle will be attached to the provided MicroScope.

Signature

declare const forkIn: {
  (scope: MicroScope): <A, E, R>(self: Micro<A, E, R>) => Micro<MicroFiber<A, E>, never, R>;
  <A, E, R>(self: Micro<A, E, R>, scope: MicroScope): Micro<MicroFiber<A, E>, never, R>;
};

forkScoped

Added in v3.4.0 Source

Run the Micro effect in a new MicroFiber that can be awaited, joined, or aborted.

The lifetime of the handle will be attached to the current MicroScope.

Signature

declare function forkScoped<A, E, R>(
  self: Micro<A, E, R>,
): Micro<MicroFiber<A, E>, never, MicroScope | R>;

Filtering & Conditionals

filterOrFail

Added in v3.4.0 Source

Filter the specified effect with the provided function, failing with specified error if the predicate fails.

In addition to the filtering capabilities discussed earlier, you have the option to further refine and narrow down the type of the success channel by providing a

Signature

declare const filterOrFail: {
  <A, B, E2>(
    refinement: Refinement<A, B>,
    orFailWith: (a: NoInfer<A>) => E2,
  ): <E, R>(self: Micro<A, E, R>) => Micro<B, E2 | E, R>;
  <A, E2>(
    predicate: Predicate<NoInfer<A>>,
    orFailWith: (a: NoInfer<A>) => E2,
  ): <E, R>(self: Micro<A, E, R>) => Micro<A, E2 | E, R>;
  <A, E, R, B, E2>(
    self: Micro<A, E, R>,
    refinement: Refinement<A, B>,
    orFailWith: (a: A) => E2,
  ): Micro<B, E | E2, R>;
  <A, E, R, E2>(
    self: Micro<A, E, R>,
    predicate: Predicate<A>,
    orFailWith: (a: A) => E2,
  ): Micro<A, E | E2, R>;
};

Filter the specified effect with the provided function, failing with specified MicroCause if the predicate fails.

In addition to the filtering capabilities discussed earlier, you have the option to further refine and narrow down the type of the success channel by providing a

Signature

declare const filterOrFailCause: {
  <A, B, E2>(
    refinement: Refinement<A, B>,
    orFailWith: (a: NoInfer<A>) => MicroCause<E2>,
  ): <E, R>(self: Micro<A, E, R>) => Micro<B, E2 | E, R>;
  <A, E2>(
    predicate: Predicate<NoInfer<A>>,
    orFailWith: (a: NoInfer<A>) => MicroCause<E2>,
  ): <E, R>(self: Micro<A, E, R>) => Micro<A, E2 | E, R>;
  <A, E, R, B, E2>(
    self: Micro<A, E, R>,
    refinement: Refinement<A, B>,
    orFailWith: (a: A) => MicroCause<E2>,
  ): Micro<B, E | E2, R>;
  <A, E, R, E2>(
    self: Micro<A, E, R>,
    predicate: Predicate<A>,
    orFailWith: (a: A) => MicroCause<E2>,
  ): Micro<A, E | E2, R>;
};

when

Added in v3.4.0 Source

The moral equivalent of if (p) exp.

Signature

declare const when: {
  <E2 = never, R2 = never>(
    condition: LazyArg<boolean> | Micro<boolean, E2, R2>,
  ): <A, E, R>(self: Micro<A, E, R>) => Micro<Option<A>, E2 | E, R2 | R>;
  <A, E, R, E2 = never, R2 = never>(
    self: Micro<A, E, R>,
    condition: LazyArg<boolean> | Micro<boolean, E2, R2>,
  ): Micro<Option<A>, E | E2, R | R2>;
};

Flags

Flag the effect as interruptible, which means that when the effect is interrupted, it will be interrupted immediately.

Signature

declare function interruptible<A, E, R>(self: Micro<A, E, R>): Micro<A, E, R>;

Flag the effect as uninterruptible, which means that when the effect is interrupted, it will be allowed to continue running until completion.

Signature

declare function uninterruptible<A, E, R>(self: Micro<A, E, R>): Micro<A, E, R>;

Guards

isMicro

Added in v3.4.0 Source

Signature

declare function isMicro(u: unknown): u is Micro<any, any, any>;

isMicroCause

Added in v3.6.6 Source

Signature

declare function isMicroCause(self: unknown): self is MicroCause<unknown>;

Interruption

interrupt

Added in v3.4.6 Source

Abort the current Micro effect.

Signature

declare const interrupt: Micro<never>;

Wrap the given Micro effect in an uninterruptible region, preventing the effect from being aborted.

You can use the restore function to restore a Micro effect to the interruptibility state before the uninterruptibleMask was applied.

Signature

declare function uninterruptibleMask<A, E, R>(
  f: (restore: <A, E, R>(effect: Micro<A, E, R>) => Micro<A, E, R>) => Micro<A, E, R>,
): Micro<A, E, R>;

Example

import * as Micro from "effect/Micro"

Micro.uninterruptibleMask((restore) =>
  Micro.sleep(1000).pipe(
    // uninterruptible
    Micro.andThen(restore(Micro.sleep(1000))), // interruptible
  ),
)

Mapping & Sequencing

andThen

Added in v3.4.0 Source

A more flexible version of flatMap that combines map and flatMap into a single API.

It also lets you directly pass a Micro effect, which will be executed after the current effect.

Signature

declare const andThen: {
  <A, X>(
    f: (a: A) => X,
  ): <E, R>(
    self: Micro<A, E, R>,
  ) => [X] extends [Micro<A1, E1, R1>] ? Micro<A1, E | E1, R | R1> : Micro<X, E, R>;
  <X>(
    f: NotFunction<X>,
  ): <A, E, R>(
    self: Micro<A, E, R>,
  ) => [X] extends [Micro<A1, E1, R1>] ? Micro<A1, E | E1, R | R1> : Micro<X, E, R>;
  <A, E, R, X>(
    self: Micro<A, E, R>,
    f: (a: A) => X,
  ): [X] extends [Micro<A1, E1, R1>] ? Micro<A1, E | E1, R | R1> : Micro<X, E, R>;
  <A, E, R, X>(
    self: Micro<A, E, R>,
    f: NotFunction<X>,
  ): [X] extends [Micro<A1, E1, R1>] ? Micro<A1, E | E1, R | R1> : Micro<X, E, R>;
};

as

Added in v3.4.0 Source

Create a Micro effect that will replace the success value of the given effect.

Signature

declare const as: {
  <A, B>(value: B): <E, R>(self: Micro<A, E, R>) => Micro<B, E, R>;
  <A, E, R, B>(self: Micro<A, E, R>, value: B): Micro<B, E, R>;
};

asSome

Added in v3.4.0 Source

Wrap the success value of this Micro effect in a Some.

Signature

declare function asSome<A, E, R>(self: Micro<A, E, R>): Micro<Option<A>, E, R>;

asVoid

Added in v3.4.0 Source

Replace the success value of the Micro effect with void.

Signature

declare function asVoid<A, E, R>(self: Micro<A, E, R>): Micro<void, E, R>;

exit

Added in v3.4.6 Source

Access the MicroExit of the given Micro effect.

Signature

declare function exit<A, E, R>(self: Micro<A, E, R>): Micro<MicroExit<A, E>, never, R>;

flatMap

Added in v3.4.0 Source

Map the success value of this Micro effect to another Micro effect, then flatten the result.

Signature

declare const flatMap: {
  <A, B, E2, R2>(
    f: (a: A) => Micro<B, E2, R2>,
  ): <E, R>(self: Micro<A, E, R>) => Micro<B, E2 | E, R2 | R>;
  <A, E, R, B, E2, R2>(
    self: Micro<A, E, R>,
    f: (a: A) => Micro<B, E2, R2>,
  ): Micro<B, E | E2, R | R2>;
};

flatten

Added in v3.4.0 Source

Flattens any nested Micro effects, merging the error and requirement types.

Signature

declare function flatten<A, E, R, E2, R2>(
  self: Micro<Micro<A, E, R>, E2, R2>,
): Micro<A, E | E2, R | R2>;

flip

Added in v3.4.0 Source

Swap the error and success types of the Micro effect.

Signature

declare function flip<A, E, R>(self: Micro<A, E, R>): Micro<E, A, R>;

map

Added in v3.4.0 Source

Transforms the success value of the Micro effect with the specified function.

Signature

declare const map: {
  <A, B>(f: (a: A) => B): <E, R>(self: Micro<A, E, R>) => Micro<B, E, R>;
  <A, E, R, B>(self: Micro<A, E, R>, f: (a: A) => B): Micro<B, E, R>;
};

sandbox

Added in v3.4.0 Source

Replace the error type of the given Micro with the full MicroCause object.

Signature

declare function sandbox<A, E, R>(self: Micro<A, E, R>): Micro<A, MicroCause<E>, R>;

tap

Added in v3.4.0 Source

Execute a side effect from the success value of the Micro effect.

It is similar to the andThen api, but the success value is ignored.

Signature

declare const tap: {
  <A, X>(
    f: (a: NoInfer<A>) => X,
  ): <E, R>(
    self: Micro<A, E, R>,
  ) => [X] extends [Micro<_A1, E1, R1>] ? Micro<A, E | E1, R | R1> : Micro<A, E, R>;
  <X>(
    f: NotFunction<X>,
  ): <A, E, R>(
    self: Micro<A, E, R>,
  ) => [X] extends [Micro<_A1, E1, R1>] ? Micro<A, E | E1, R | R1> : Micro<A, E, R>;
  <A, E, R, X>(
    self: Micro<A, E, R>,
    f: (a: NoInfer<A>) => X,
  ): [X] extends [Micro<_A1, E1, R1>] ? Micro<A, E | E1, R | R1> : Micro<A, E, R>;
  <A, E, R, X>(
    self: Micro<A, E, R>,
    f: NotFunction<X>,
  ): [X] extends [Micro<_A1, E1, R1>] ? Micro<A, E | E1, R | R1> : Micro<A, E, R>;
};

MicroCause

causeDie

Added in v3.4.6 Source

Signature

declare function causeDie(defect: unknown, traces: readonly Array<string>): MicroCause<never>

causeFail

Added in v3.4.6 Source

Signature

declare function causeFail<E>(error: E, traces: readonly Array<string>): MicroCause<E>

Signature

declare function causeInterrupt(traces: readonly Array<string>): MicroCause<never>

causeIsDie

Added in v3.4.6 Source

Signature

declare function causeIsDie<E>(self: MicroCause<E>): self is Die;

causeIsFail

Added in v3.4.6 Source

Signature

declare function causeIsFail<E>(self: MicroCause<E>): self is Fail<E>;

Signature

declare function causeIsInterrupt<E>(self: MicroCause<E>): self is Interrupt;

causeSquash

Added in v3.4.6 Source

Signature

declare function causeSquash<E>(self: MicroCause<E>): unknown;

Signature

declare const causeWithTrace: {
  (trace: string): <E>(self: MicroCause<E>) => MicroCause<E>;
  <E>(self: MicroCause<E>, trace: string): MicroCause<E>;
};

MicroCause

Added in v3.4.6 Source

MicroCause type

Added in v3.4.6 Source

A MicroCause is a data type that represents the different ways a Micro can fail.

Details

MicroCause comes in three forms:

- Die: Indicates an unforeseen defect that wasn't planned for in the system's logic. - Fail: Covers anticipated errors that are recognized and typically handled within the application. - Interrupt: Signifies an operation that has been purposefully stopped.

Signature

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

Signature

declare const MicroCauseTypeId: typeof MicroCauseTypeId;

MicroCauseTypeId type

Added in v3.4.6 Source

Signature

type MicroCauseTypeId = typeof MicroCauseTypeId;

MicroExit

exitDie

Added in v3.4.6 Source

Signature

declare function exitDie(defect: unknown): MicroExit<never>;

exitFail

Added in v3.4.6 Source

Signature

declare function exitFail<E>(e: E): MicroExit<never, E>;

Signature

declare const exitFailCause: <E>(cause: MicroCause<E>) => MicroExit<never, E>;

Signature

declare const exitInterrupt: MicroExit<never>;

exitIsDie

Added in v3.4.6 Source

Signature

declare function exitIsDie<A, E>(
  self: MicroExit<A, E>,
): self is Failure<A, E> & {
  readonly cause: Die;
};

exitIsFail

Added in v3.4.6 Source

Signature

declare function exitIsFail<A, E>(
  self: MicroExit<A, E>,
): self is Failure<A, E> & {
  readonly cause: Fail<E>;
};

Signature

declare function exitIsFailure<A, E>(self: MicroExit<A, E>): self is Failure<A, E>;

Signature

declare function exitIsInterrupt<A, E>(
  self: MicroExit<A, E>,
): self is Failure<A, E> & {
  readonly cause: Interrupt;
};

Signature

declare function exitIsSuccess<A, E>(self: MicroExit<A, E>): self is Success<A, E>;

exitSucceed

Added in v3.4.6 Source

Signature

declare const exitSucceed: <A>(a: A) => MicroExit<A, never>;

exitVoid

Added in v3.4.6 Source

Signature

declare const exitVoid: MicroExit<void>;

exitVoidAll

Added in v3.11.0 Source

Signature

declare function exitVoidAll<I extends Iterable<MicroExit<any, any>, any, any>>(
  exits: I,
): MicroExit<void, I extends Iterable<MicroExit<_A, _E>, any, any> ? _E : never>;

isMicroExit

Added in v3.4.6 Source

Signature

declare function isMicroExit(u: unknown): u is MicroExit<unknown, unknown>;

MicroExit

Added in v3.4.6 Source

MicroExit type

Added in v3.4.6 Source

The MicroExit type is used to represent the result 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.

Signature

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

Signature

declare const MicroExitTypeId: unique symbol;

MicroExitTypeId type

Added in v3.4.0 Source

Signature

type MicroExitTypeId = typeof TypeId;

MicroFiber

fiberAwait

Added in v3.11.0 Source

Signature

declare function fiberAwait<A, E>(self: MicroFiber<A, E>): Micro<MicroExit<A, E>>;

fiberInterrupt

Added in v3.11.0 Source

Signature

declare function fiberInterrupt<A, E>(self: MicroFiber<A, E>): Micro<void>;

Signature

declare function fiberInterruptAll<A extends Iterable<MicroFiber<any, any>, any, any>>(
  fibers: A,
): Micro<void>;

fiberJoin

Added in v3.11.2 Source

Signature

declare function fiberJoin<A, E>(self: MicroFiber<A, E>): Micro<A, E>;

MicroFiber

Added in v3.11.0 Source

MicroFiber interface

Added in v3.11.0 Source

Signature

interface MicroFiber<out A, out E = never> {
  readonly [MicroFiberTypeId]: Variance<A, E>;
  readonly addObserver: (cb: (exit: MicroExit<A, E>) => void) => () => void;
  readonly context: Context<never>;
  readonly currentOpCount: number;
  readonly getRef: <I, A>(ref: Reference<I, A>) => A;
  readonly unsafeInterrupt: () => void;
  readonly unsafePoll: () => MicroExit<A, E> | undefined;
}

Signature

declare const MicroFiberTypeId: typeof MicroFiberTypeId;

MicroFiberTypeId type

Added in v3.11.0 Source

Signature

type MicroFiberTypeId = typeof MicroFiberTypeId;

Models

Micro interface

Added in v3.4.0 Source

A lightweight alternative to the Effect data type, with a subset of the functionality.

Signature

interface Micro<out A, out E = never, out R = never> extends Effect<A, E, R> {
  [ignoreSymbol]?: MicroUnifyIgnore;
  readonly [TypeId]: Variance<A, E, R>;
  [typeSymbol]?: unknown;
  [unifySymbol]?: MicroUnify<Micro<A, E, R>>;
  [iterator](): MicroIterator<Micro<A, E, R>>;
}

MicroIterator interface

Added in v3.4.0 Source

Signature

interface MicroIterator<T extends Micro<any, any, any>> {
  next(...args: readonly Array<any>): IteratorResult<YieldWrap<T>, Success<T>>;
}

MicroUnify interface

Added in v3.4.3 Source

Signature

interface MicroUnify<
  A extends {
    [typeSymbol]?: any;
  },
> extends EffectUnify<A> {
  Micro?: () => A[typeof typeSymbol] extends Micro<A0, E0, R0> | _ ? Micro<A0, E0, R0> : never;
}

MicroUnifyIgnore interface

Added in v3.4.3 Source

Signature

interface MicroUnifyIgnore extends EffectUnifyIgnore {
  Effect?: true;
}

Other

All

Added in v3.4.0 Source

Signature

declare const let: {
  <N extends string, A extends Record<string, any>, B>(
    name: N,
    f: (a: NoInfer<A>) => B,
  ): <E, R>(self: Micro<A, E, R>) => Micro<Simplify<Omit<A, N> & { [K in string]: B }>, E, R>;
  <A extends Record<string, any>, E, R, B, N extends string>(
    self: Micro<A, E, R>,
    name: N,
    f: (a: NoInfer<A>) => B,
  ): Micro<Simplify<Omit<A, N> & { [K in string]: B }>, E, R>;
};

Micro

Added in v3.4.0 Source

Signature

declare function try<A, E>(options: {
  catch: (error: unknown) => E;
  try: LazyArg<A>;
}): Micro<A, E>

Signature

declare const void: Micro<void>

Pattern Matching

match

Added in v3.4.0 Source

Signature

declare const match: {
  <E, A2, A, A3>(options: {
    readonly onFailure: (error: E) => A2;
    readonly onSuccess: (value: A) => A3;
  }): <R>(self: Micro<A, E, R>) => Micro<A2 | A3, never, R>;
  <A, E, R, A2, A3>(
    self: Micro<A, E, R>,
    options: {
      readonly onFailure: (error: E) => A2;
      readonly onSuccess: (value: A) => A3;
    },
  ): Micro<A2 | A3, never, R>;
};

matchCause

Added in v3.4.6 Source

Signature

declare const matchCause: {
  <E, A2, A, A3>(options: {
    readonly onFailure: (cause: MicroCause<E>) => A2;
    readonly onSuccess: (a: A) => A3;
  }): <R>(self: Micro<A, E, R>) => Micro<A2 | A3, never, R>;
  <A, E, R, A2, A3>(
    self: Micro<A, E, R>,
    options: {
      readonly onFailure: (cause: MicroCause<E>) => A2;
      readonly onSuccess: (a: A) => A3;
    },
  ): Micro<A2 | A3, never, R>;
};

Signature

declare const matchCauseEffect: {
  <E, A2, E2, R2, A, A3, E3, R3>(options: {
    readonly onFailure: (cause: MicroCause<E>) => Micro<A2, E2, R2>;
    readonly onSuccess: (a: A) => Micro<A3, E3, R3>;
  }): <R>(self: Micro<A, E, R>) => Micro<A2 | A3, E2 | E3, R2 | R3 | R>;
  <A, E, R, A2, E2, R2, A3, E3, R3>(
    self: Micro<A, E, R>,
    options: {
      readonly onFailure: (cause: MicroCause<E>) => Micro<A2, E2, R2>;
      readonly onSuccess: (a: A) => Micro<A3, E3, R3>;
    },
  ): Micro<A2 | A3, E2 | E3, R | R2 | R3>;
};

matchEffect

Added in v3.4.6 Source

Signature

declare const matchEffect: {
  <E, A2, E2, R2, A, A3, E3, R3>(options: {
    readonly onFailure: (e: E) => Micro<A2, E2, R2>;
    readonly onSuccess: (a: A) => Micro<A3, E3, R3>;
  }): <R>(self: Micro<A, E, R>) => Micro<A2 | A3, E2 | E3, R2 | R3 | R>;
  <A, E, R, A2, E2, R2, A3, E3, R3>(
    self: Micro<A, E, R>,
    options: {
      readonly onFailure: (e: E) => Micro<A2, E2, R2>;
      readonly onSuccess: (a: A) => Micro<A3, E3, R3>;
    },
  ): Micro<A2 | A3, E2 | E3, R | R2 | R3>;
};

References

Signature

declare class MaxOpsBeforeYield extends TagClassShape<
  "effect/Micro/currentMaxOpsBeforeYield",
  number,
  this
> {
  constructor(_: never);
}

Repetition

forever

Added in v3.4.0 Source

Repeat the given Micro effect forever, only stopping if the effect fails.

Signature

declare function forever<A, E, R>(self: Micro<A, E, R>): Micro<never, E, R>;

repeat

Added in v3.4.0 Source

Repeat the given Micro effect using the provided options. Only successful results will be repeated.

Signature

declare const repeat: {
  <A, E>(options?: {
    schedule?: MicroSchedule;
    times?: number;
    while?: Predicate<A>;
  }): <R>(self: Micro<A, E, R>) => Micro<A, E, R>;
  <A, E, R>(
    self: Micro<A, E, R>,
    options?: {
      schedule?: MicroSchedule;
      times?: number;
      while?: Predicate<A>;
    },
  ): Micro<A, E, R>;
};

repeatExit

Added in v3.4.6 Source

Repeat the given Micro using the provided options.

The while predicate will be checked after each iteration, and can use the fall MicroExit of the effect to determine if the repetition should continue.

Signature

declare const repeatExit: {
  <A, E>(options: {
    schedule?: MicroSchedule;
    times?: number;
    while: Predicate<MicroExit<A, E>>;
  }): <R>(self: Micro<A, E, R>) => Micro<A, E, R>;
  <A, E, R>(
    self: Micro<A, E, R>,
    options: {
      schedule?: MicroSchedule;
      times?: number;
      while: Predicate<MicroExit<A, E>>;
    },
  ): Micro<A, E, R>;
};

replicate

Added in v3.11.0 Source

Replicates the given effect n times.

Signature

declare const replicate: {
  (n: number): <A, E, R>(self: Micro<A, E, R>) => Array<Micro<A, E, R>>;
  <A, E, R>(self: Micro<A, E, R>, n: number): Array<Micro<A, E, R>>;
};

Performs this effect the specified number of times and collects the results.

Signature

declare const replicateEffect: {
  (
    n: number,
    options?: {
      readonly concurrency?: Concurrency;
      readonly discard?: false;
    },
  ): <A, E, R>(self: Micro<A, E, R>) => Micro<Array<A>, E, R>;
  (
    n: number,
    options: {
      readonly concurrency?: Concurrency;
      readonly discard: true;
    },
  ): <A, E, R>(self: Micro<A, E, R>) => Micro<void, E, R>;
  <A, E, R>(
    self: Micro<A, E, R>,
    n: number,
    options?: {
      readonly concurrency?: Concurrency;
      readonly discard?: false;
    },
  ): Micro<Array<A>, E, R>;
  <A, E, R>(
    self: Micro<A, E, R>,
    n: number,
    options: {
      readonly concurrency?: Concurrency;
      readonly discard: true;
    },
  ): Micro<void, E, R>;
};

Resources & Finalization

Create a resource with a cleanup Micro effect, ensuring the cleanup is executed when the MicroScope is closed.

Signature

declare function acquireRelease<A, E, R>(
  acquire: Micro<A, E, R>,
  release: (a: A, exit: MicroExit<unknown, unknown>) => Micro<void>,
): Micro<A, E, MicroScope | R>;

Acquire a resource, use it, and then release the resource when the use effect has completed.

Signature

declare function acquireUseRelease<Resource, E, R, A, E2, R2, E3, R3>(
  acquire: Micro<Resource, E, R>,
  use: (a: Resource) => Micro<A, E2, R2>,
  release: (a: Resource, exit: MicroExit<A, E2>) => Micro<void, E3, R3>,
): Micro<A, E | E2 | E3, R | R2 | R3>;

addFinalizer

Added in v3.4.0 Source

Add a finalizer to the current MicroScope.

Signature

declare function addFinalizer(
  finalizer: (exit: MicroExit<unknown, unknown>) => Micro<void>,
): Micro<void, never, MicroScope>;

ensuring

Added in v3.4.0 Source

Regardless of the result of the this Micro effect, run the finalizer effect.

Signature

declare const ensuring: {
  <XE, XR>(
    finalizer: Micro<void, XE, XR>,
  ): <A, E, R>(self: Micro<A, E, R>) => Micro<A, XE | E, XR | R>;
  <A, E, R, XE, XR>(self: Micro<A, E, R>, finalizer: Micro<void, XE, XR>): Micro<A, E | XE, R | XR>;
};

MicroScope

Added in v3.4.0 Source

Signature

declare const MicroScope: Tag<MicroScope, MicroScope>;

MicroScope

Added in v3.4.0 Source

MicroScope interface

Added in v3.4.0 Source

Signature

interface MicroScope {
  readonly [MicroScopeTypeId]: typeof MicroScopeTypeId;
  readonly addFinalizer: (
    finalizer: (exit: MicroExit<unknown, unknown>) => Micro<void>,
  ) => Micro<void>;
  readonly fork: Micro<Closeable>;
}

Signature

declare const MicroScopeTypeId: unique symbol;

MicroScopeTypeId type

Added in v3.4.0 Source

Signature

type MicroScopeTypeId = typeof MicroScopeTypeId;

onError

Added in v3.4.6 Source

When the Micro effect fails, run the given finalizer effect with the MicroCause of the executed effect.

Signature

declare const onError: {
  <A, E, XE, XR>(
    f: (cause: MicroCause<NoInfer<E>>) => Micro<void, XE, XR>,
  ): <R>(self: Micro<A, E, R>) => Micro<A, E | XE, XR | R>;
  <A, E, R, XE, XR>(
    self: Micro<A, E, R>,
    f: (cause: MicroCause<NoInfer<E>>) => Micro<void, XE, XR>,
  ): Micro<A, E | XE, R | XR>;
};

onExit

Added in v3.4.6 Source

When the Micro effect is completed, run the given finalizer effect with the MicroExit of the executed effect.

Signature

declare const onExit: {
  <A, E, XE, XR>(
    f: (exit: MicroExit<A, E>) => Micro<void, XE, XR>,
  ): <R>(self: Micro<A, E, R>) => Micro<A, E | XE, XR | R>;
  <A, E, R, XE, XR>(
    self: Micro<A, E, R>,
    f: (exit: MicroExit<A, E>) => Micro<void, XE, XR>,
  ): Micro<A, E | XE, R | XR>;
};

onExitIf

Added in v3.4.6 Source

When the Micro effect is completed, run the given finalizer effect if it matches the specified predicate.

Signature

declare const onExitIf: {
  <A, E, XE, XR, B extends MicroExit<A, E>>(
    refinement: Refinement<MicroExit<A, E>, B>,
    f: (exit: B) => Micro<void, XE, XR>,
  ): <R>(self: Micro<A, E, R>) => Micro<A, E | XE, XR | R>;
  <A, E, XE, XR>(
    predicate: Predicate<MicroExit<NoInfer<A>, NoInfer<E>>>,
    f: (exit: MicroExit<NoInfer<A>, NoInfer<E>>) => Micro<void, XE, XR>,
  ): <R>(self: Micro<A, E, R>) => Micro<A, E | XE, XR | R>;
  <A, E, R, XE, XR, B extends MicroExit<A, E>>(
    self: Micro<A, E, R>,
    refinement: Refinement<MicroExit<A, E>, B>,
    f: (exit: B) => Micro<void, XE, XR>,
  ): Micro<A, E | XE, R | XR>;
  <A, E, R, XE, XR>(
    self: Micro<A, E, R>,
    predicate: Predicate<MicroExit<NoInfer<A>, NoInfer<E>>>,
    f: (exit: MicroExit<NoInfer<A>, NoInfer<E>>) => Micro<void, XE, XR>,
  ): Micro<A, E | XE, R | XR>;
};

onInterrupt

Added in v3.4.6 Source

If this Micro effect is aborted, run the finalizer effect.

Signature

declare const onInterrupt: {
  <XE, XR>(
    finalizer: Micro<void, XE, XR>,
  ): <A, E, R>(self: Micro<A, E, R>) => Micro<A, XE | E, XR | R>;
  <A, E, R, XE, XR>(self: Micro<A, E, R>, finalizer: Micro<void, XE, XR>): Micro<A, E | XE, R | XR>;
};

provideScope

Added in v3.4.0 Source

Provide a MicroScope to an effect.

Signature

declare const provideScope: {
  (scope: MicroScope): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, Exclude<R, MicroScope>>;
  <A, E, R>(self: Micro<A, E, R>, scope: MicroScope): Micro<A, E, Exclude<R, MicroScope>>;
};

scope

Added in v3.4.0 Source

Access the current MicroScope.

Signature

declare const scope: Micro<MicroScope, never, MicroScope>;

scoped

Added in v3.4.0 Source

Provide a MicroScope to the given effect, closing it after the effect has finished executing.

Signature

declare function scoped<A, E, R>(self: Micro<A, E, R>): Micro<A, E, Exclude<R, MicroScope>>;

scopeMake

Added in v3.4.0 Source

Signature

declare const scopeMake: Micro<MicroScope.Closeable>;

Signature

declare function scopeUnsafeMake(): Closeable;

Scheduler

MicroScheduler interface

Added in v3.5.9 Source

Signature

interface MicroScheduler {
  readonly flush: () => void;
  readonly scheduleTask: (task: () => void, priority: number) => void;
  readonly shouldYield: (fiber: MicroFiber<unknown, unknown>) => boolean;
}

Signature

declare class MicroSchedulerDefault implements MicroScheduler {
  constructor();
  afterScheduled(): void;
  flush(): void;
  runTasks(): void;
  scheduleTask(task: () => void, _priority: number): void;
  shouldYield(fiber: MicroFiber<unknown, unknown>): boolean;
}

Scheduling

MicroSchedule type

Added in v3.4.6 Source

The MicroSchedule type 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.

Signature

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

Returns a new MicroSchedule with an added calculated delay to each delay returned by this schedule.

Signature

declare const scheduleAddDelay: {
  (f: () => number): (self: MicroSchedule) => MicroSchedule;
  (self: MicroSchedule, f: () => number): MicroSchedule;
};

Create a MicroSchedule that will generate a delay with an exponential backoff.

Signature

declare function scheduleExponential(baseMillis: number, factor: number): MicroSchedule;

Combines two MicroSchedules, by recurring only if both schedules want to recur, using the maximum of the two durations between recurrences.

Signature

declare const scheduleIntersect: {
  (that: MicroSchedule): (self: MicroSchedule) => MicroSchedule;
  (self: MicroSchedule, that: MicroSchedule): MicroSchedule;
};

Create a MicroSchedule that will stop repeating after the specified number of attempts.

Signature

declare function scheduleRecurs(n: number): MicroSchedule;

Create a MicroSchedule that will generate a constant delay.

Signature

declare function scheduleSpaced(millis: number): MicroSchedule;

Combines two MicroSchedules, by recurring if either schedule wants to recur, using the minimum of the two durations between recurrences.

Signature

declare const scheduleUnion: {
  (that: MicroSchedule): (self: MicroSchedule) => MicroSchedule;
  (self: MicroSchedule, that: MicroSchedule): MicroSchedule;
};

Transform a MicroSchedule to one that will have a delay that will never exceed the specified maximum.

Signature

declare const scheduleWithMaxDelay: {
  (max: number): (self: MicroSchedule) => MicroSchedule;
  (self: MicroSchedule, max: number): MicroSchedule;
};

Transform a MicroSchedule to one that will stop repeating after the specified amount of time.

Signature

declare const scheduleWithMaxElapsed: {
  (max: number): (self: MicroSchedule) => MicroSchedule;
  (self: MicroSchedule, max: number): MicroSchedule;
};

Sequencing

race

Added in v3.4.0 Source

Returns an effect that races two effects, yielding the value of the first effect to succeed. Losers of the race will be interrupted immediately.

Signature

declare const race: {
  <A2, E2, R2>(
    that: Micro<A2, E2, R2>,
  ): <A, E, R>(self: Micro<A, E, R>) => Micro<A2 | A, E2 | E, R2 | R>;
  <A, E, R, A2, E2, R2>(
    self: Micro<A, E, R>,
    that: Micro<A2, E2, R2>,
  ): Micro<A | A2, E | E2, R | R2>;
};

raceAll

Added in v3.4.0 Source

Returns an effect that races all the specified effects, yielding the value of the first effect to succeed with a value. Losers of the race will be interrupted immediately

Signature

declare function raceAll<Eff extends Micro<any, any, any>>(
  all: Iterable<Eff>,
): Micro<Success<Eff>, Error<Eff>, Context<Eff>>;

raceAllFirst

Added in v3.4.0 Source

Returns an effect that races all the specified effects, yielding the value of the first effect to succeed or fail. Losers of the race will be interrupted immediately.

Signature

declare function raceAllFirst<Eff extends Micro<any, any, any>>(
  all: Iterable<Eff>,
): Micro<Success<Eff>, Error<Eff>, Context<Eff>>;

raceFirst

Added in v3.4.0 Source

Returns an effect that races two effects, yielding the value of the first effect to succeed *or* fail. Losers of the race will be interrupted immediately.

Signature

declare const raceFirst: {
  <A2, E2, R2>(
    that: Micro<A2, E2, R2>,
  ): <A, E, R>(self: Micro<A, E, R>) => Micro<A2 | A, E2 | E, R2 | R>;
  <A, E, R, A2, E2, R2>(
    self: Micro<A, E, R>,
    that: Micro<A2, E2, R2>,
  ): Micro<A | A2, E | E2, R | R2>;
};

Type Ids

TypeId

Added in v3.4.0 Source

Signature

declare const TypeId: unique symbol;

TypeId type

Added in v3.4.0 Source

Signature

type TypeId = typeof TypeId;

Type Lambdas

MicroTypeLambda interface

Added in v3.4.1 Source

Signature

interface MicroTypeLambda extends TypeLambda {
  readonly type: Micro<unknown, unknown, unknown>;
}

Zipping

zip

Added in v3.4.0 Source

Combine two Micro effects into a single effect that produces a tuple of their results.

Signature

declare const zip: {
  <A2, E2, R2>(
    that: Micro<A2, E2, R2>,
    options?: {
      readonly concurrent?: boolean;
    },
  ): <A, E, R>(self: Micro<A, E, R>) => Micro<[A, A2], E2 | E, R2 | R>;
  <A, E, R, A2, E2, R2>(
    self: Micro<A, E, R>,
    that: Micro<A2, E2, R2>,
    options?: {
      readonly concurrent?: boolean;
    },
  ): Micro<[A, A2], E | E2, R | R2>;
};

zipWith

Added in v3.4.3 Source

The Micro.zipWith function combines two Micro effects and allows you to apply a function to the results of the combined effects, transforming them into a single value.

Signature

declare const zipWith: {
  <A2, E2, R2, A, B>(
    that: Micro<A2, E2, R2>,
    f: (a: A, b: A2) => B,
    options?: {
      readonly concurrent?: boolean;
    },
  ): <E, R>(self: Micro<A, E, R>) => Micro<B, E2 | E, R2 | R>;
  <A, E, R, A2, E2, R2, B>(
    self: Micro<A, E, R>,
    that: Micro<A2, E2, R2>,
    f: (a: A, b: A2) => B,
    options?: {
      readonly concurrent?: boolean;
    },
  ): Micro<B, E | E2, R | R2>;
};