Skip to content

STM

132 exports Added in v2.0.0 Source

Constructors

Treats the specified acquire transaction as the acquisition of a resource. The acquire transaction will be executed interruptibly. If it is a success and is committed the specified release workflow will be executed uninterruptibly as soon as the use workflow completes execution.

Signature

declare const acquireUseRelease: {
  <A, A2, E2, R2, A3, E3, R3>(
    use: (resource: A) => STM<A2, E2, R2>,
    release: (resource: A) => STM<A3, E3, R3>,
  ): <E, R>(acquire: STM<A, E, R>) => Effect<A2, E2 | E3 | E, R2 | R3 | R>;
  <A, E, R, A2, E2, R2, A3, E3, R3>(
    acquire: STM<A, E, R>,
    use: (resource: A) => STM<A2, E2, R2>,
    release: (resource: A) => STM<A3, E3, R3>,
  ): Effect<A2, E | E2 | E3, R | R2 | R3>;
};

all

Added in v2.0.0 Source

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

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

Signature

declare const all: All.Signature;

attempt

Added in v2.0.0 Source

Creates an STM value from a partial (but pure) function.

Signature

declare const attempt: <A>(evaluate: LazyArg<A>) => STM<A, unknown>;

check

Added in v2.0.0 Source

Checks the condition, and if it's true, returns unit, otherwise, retries.

Signature

declare const check: (predicate: LazyArg<boolean>) => STM<void>;

cond

Added in v2.0.0 Source

Similar to Either.cond, evaluate the predicate, return the given A as success if predicate returns true, and the given E as error otherwise

Signature

declare const cond: <A, E>(
  predicate: LazyArg<boolean>,
  error: LazyArg<E>,
  result: LazyArg<A>,
) => STM<A, E>;

context

Added in v2.0.0 Source

Retrieves the environment inside an stm.

Signature

declare const context: <R>() => STM<Context.Context<R>, never, R>;

contextWith

Added in v2.0.0 Source

Accesses the environment of the transaction to perform a transaction.

Signature

declare const contextWith: <R0, R>(f: (environment: Context.Context<R0>) => R) => STM<R, never, R0>;

Accesses the environment of the transaction to perform a transaction.

Signature

declare const contextWithSTM: <R0, A, E, R>(
  f: (environment: Context.Context<R0>) => STM<A, E, R>,
) => STM<A, E, R0 | R>;

die

Added in v2.0.0 Source

Fails the transactional effect with the specified defect.

Signature

declare const die: (defect: unknown) => STM<never>;

dieMessage

Added in v2.0.0 Source

Kills the fiber running the effect with a Cause.RuntimeException that contains the specified message.

Signature

declare const dieMessage: (message: string) => STM<never>;

dieSync

Added in v2.0.0 Source

Fails the transactional effect with the specified lazily evaluated defect.

Signature

declare const dieSync: (evaluate: LazyArg<unknown>) => STM<never>;

every

Added in v2.0.0 Source

Determines whether all elements of the Iterable<A> satisfy the effectual predicate.

Signature

declare const every: {
  <A, R, E>(
    predicate: (a: NoInfer<A>) => STM<boolean, E, R>,
  ): (iterable: Iterable<A>) => STM<boolean, E, R>;
  <A, R, E>(iterable: Iterable<A>, predicate: (a: A) => STM<boolean, E, R>): STM<boolean, E, R>;
};

exists

Added in v2.0.0 Source

Determines whether any element of the Iterable[A] satisfies the effectual predicate f.

Signature

declare const exists: {
  <A, R, E>(
    predicate: (a: NoInfer<A>) => STM<boolean, E, R>,
  ): (iterable: Iterable<A>) => STM<boolean, E, R>;
  <A, R, E>(iterable: Iterable<A>, predicate: (a: A) => STM<boolean, E, R>): STM<boolean, E, R>;
};

fail

Added in v2.0.0 Source

Fails the transactional effect with the specified error.

Signature

declare const fail: <E>(error: E) => STM<never, E>;

failSync

Added in v2.0.0 Source

Fails the transactional effect with the specified lazily evaluated error.

Signature

declare const failSync: <E>(evaluate: LazyArg<E>) => STM<never, E>;

fiberId

Added in v2.0.0 Source

Returns the fiber id of the fiber committing the transaction.

Signature

declare const fiberId: STM<FiberId.FiberId>;

filter

Added in v2.0.0 Source

Filters the collection using the specified effectual predicate.

Signature

declare const filter: {
  <A, R, E>(
    predicate: (a: NoInfer<A>) => STM<boolean, E, R>,
  ): (iterable: Iterable<A>) => STM<Array<A>, E, R>;
  <A, R, E>(iterable: Iterable<A>, predicate: (a: A) => STM<boolean, E, R>): STM<Array<A>, E, R>;
};

filterNot

Added in v2.0.0 Source

Filters the collection using the specified effectual predicate, removing all elements that satisfy the predicate.

Signature

declare const filterNot: {
  <A, R, E>(
    predicate: (a: NoInfer<A>) => STM<boolean, E, R>,
  ): (iterable: Iterable<A>) => STM<Array<A>, E, R>;
  <A, R, E>(iterable: Iterable<A>, predicate: (a: A) => STM<boolean, E, R>): STM<Array<A>, E, R>;
};

fromEither

Added in v2.0.0 Source

Lifts an Either into a STM.

Signature

declare const fromEither: <A, E>(either: Either.Either<A, E>) => STM<A, E>;

fromOption

Added in v2.0.0 Source

Lifts an Option into a STM.

Signature

declare const fromOption: <A>(option: Option.Option<A>) => STM<A, Option.Option<never>>;

gen

Added in v2.0.0 Source

Signature

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

interrupt

Added in v2.0.0 Source

Interrupts the fiber running the effect.

Signature

declare const interrupt: STM<never>;

interruptAs

Added in v2.0.0 Source

Interrupts the fiber running the effect with the specified FiberId.

Signature

declare const interruptAs: (fiberId: FiberId.FiberId) => STM<never>;

iterate

Added in v2.0.0 Source

Iterates with the specified transactional function. The moral equivalent of:

```ts skip-type-checking const s = initial

while (cont(s)) { s = body(s) }

return s ```

Signature

declare const iterate: <Z, E, R>(
  initial: Z,
  options: {
    readonly body: (z: Z) => STM<Z, E, R>;
    readonly while: Predicate<Z>;
  },
) => STM<Z, E, R>;

loop

Added in v2.0.0 Source

Loops with the specified transactional function, collecting the results into a list. The moral equivalent of:

```ts skip-type-checking const as = [] let s = initial

while (cont(s)) { as.push(body(s)) s = inc(s) }

return as ```

Signature

declare const loop: {
  <Z, A, E, R>(
    initial: Z,
    options: {
      readonly body: (z: Z) => STM<A, E, R>;
      readonly discard?: false;
      readonly step: (z: Z) => Z;
      readonly while: (z: Z) => boolean;
    },
  ): STM<Array<A>, E, R>;
  <Z, A, E, R>(
    initial: Z,
    options: {
      readonly body: (z: Z) => STM<A, E, R>;
      readonly discard: true;
      readonly step: (z: Z) => Z;
      readonly while: (z: Z) => boolean;
    },
  ): STM<void, E, R>;
};

mergeAll

Added in v2.0.0 Source

Merges an Iterable<STM> to a single STM, working sequentially.

Signature

declare const mergeAll: {
  <A2, A>(
    zero: A2,
    f: (a2: A2, a: A) => A2,
  ): <E, R>(iterable: Iterable<STM<A, E, R>>) => STM<A2, E, R>;
  <A, E, R, A2>(iterable: Iterable<STM<A, E, R>>, zero: A2, f: (a2: A2, a: A) => A2): STM<A2, E, R>;
};

reduce

Added in v2.0.0 Source

Folds an Iterable<A> using an effectual function f, working sequentially from left to right.

Signature

declare const reduce: {
  <S, A, E, R>(zero: S, f: (s: S, a: A) => STM<S, E, R>): (iterable: Iterable<A>) => STM<S, E, R>;
  <S, A, E, R>(iterable: Iterable<A>, zero: S, f: (s: S, a: A) => STM<S, E, R>): STM<S, E, R>;
};

reduceAll

Added in v2.0.0 Source

Reduces an Iterable<STM> to a single STM, working sequentially.

Signature

declare const reduceAll: {
  <A, E2, R2>(
    initial: STM<A, E2, R2>,
    f: (x: A, y: A) => A,
  ): <E, R>(iterable: Iterable<STM<A, E, R>>) => STM<A, E2 | E, R2 | R>;
  <A, E, R, E2, R2>(
    iterable: Iterable<STM<A, E, R>>,
    initial: STM<A, E2, R2>,
    f: (x: A, y: A) => A,
  ): STM<A, E | E2, R | R2>;
};

reduceRight

Added in v2.0.0 Source

Folds an Iterable<A> using an effectual function f, working sequentially from right to left.

Signature

declare const reduceRight: {
  <S, A, R, E>(zero: S, f: (s: S, a: A) => STM<S, E, R>): (iterable: Iterable<A>) => STM<S, E, R>;
  <S, A, R, E>(iterable: Iterable<A>, zero: S, f: (s: S, a: A) => STM<S, E, R>): STM<S, E, R>;
};

replicate

Added in v2.0.0 Source

Replicates the given effect n times. If 0 or negative numbers are given, an empty Chunk will be returned.

Signature

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

replicateSTM

Added in v2.0.0 Source

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

Signature

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

Performs this transaction the specified number of times, discarding the results.

Signature

declare const replicateSTMDiscard: {
  (n: number): <A, E, R>(self: STM<A, E, R>) => STM<void, E, R>;
  <A, E, R>(self: STM<A, E, R>, n: number): STM<void, E, R>;
};

succeed

Added in v2.0.0 Source

Returns an STM effect that succeeds with the specified value.

Signature

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

succeedNone

Added in v2.0.0 Source

Returns an effect with the empty value.

Signature

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

succeedSome

Added in v2.0.0 Source

Returns an effect with the optional value.

Signature

declare const succeedSome: <A>(value: A) => STM<Option.Option<A>>;

suspend

Added in v2.0.0 Source

Suspends creation of the specified transaction lazily.

Signature

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

sync

Added in v2.0.0 Source

Returns an STM effect that succeeds with the specified lazily evaluated value.

Signature

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

Context

Transforms the environment being provided to this effect with the specified function.

Signature

declare const mapInputContext: {
  <R0, R>(f: (context: Context<R0>) => Context<R>): <A, E>(self: STM<A, E, R>) => STM<A, E, R0>;
  <A, E, R0, R>(self: STM<A, E, R>, f: (context: Context<R0>) => Context<R>): STM<A, E, R0>;
};

Provides the transaction its required environment, which eliminates its dependency on R.

Signature

declare const provideContext: {
  <R>(env: Context<R>): <A, E>(self: STM<A, E, R>) => STM<A, E>;
  <A, E, R>(self: STM<A, E, R>, env: Context<R>): STM<A, E>;
};

Provides the effect with the single service it requires. If the transactional effect requires more than one service use provideEnvironment instead.

Signature

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

Provides the effect with the single service it requires. If the transactional effect requires more than one service use provideEnvironment instead.

Signature

declare const provideServiceSTM: {
  <I, S, E1, R1>(
    tag: Tag<I, S>,
    stm: STM<NoInfer<S>, E1, R1>,
  ): <A, E, R>(self: STM<A, E, R>) => STM<A, E1 | E, R1 | Exclude<R, I>>;
  <A, E, R, I, S, E1, R1>(
    self: STM<A, E, R>,
    tag: Tag<I, S>,
    stm: STM<NoInfer<S>, E1, R1>,
  ): STM<A, E | E1, R1 | Exclude<R, I>>;
};

Splits the context into two parts, providing one part using the specified layer and leaving the remainder R0.

Signature

declare const provideSomeContext: {
  <R>(context: Context<R>): <R1, E, A>(self: STM<A, E, R1>) => STM<A, E, Exclude<R1, R>>;
  <R, R1, E, A>(self: STM<A, E, R1>, context: Context<R>): STM<A, E, Exclude<R1, R>>;
};

Destructors

commit

Added in v2.0.0 Source

Commits this transaction atomically.

Signature

declare const commit: <A, E, R>(self: STM<A, E, R>) => Effect.Effect<A, E, R>;

commitEither

Added in v2.0.0 Source

Commits this transaction atomically, regardless of whether the transaction is a success or a failure.

Signature

declare const commitEither: <A, E, R>(self: STM<A, E, R>) => Effect.Effect<A, E, R>;

Do Notation

bind

Added in v2.0.0 Source

Signature

declare const bind: {
  <N extends string, K, A, E2, R2>(
    tag: Exclude<N, keyof K>,
    f: (_: NoInfer<K>) => STM<A, E2, R2>,
  ): <E, R>(self: STM<K, E, R>) => STM<MergeRecord<K, { [k in string]: A }>, E2 | E, R2 | R>;
  <K, E, R, N extends string, A, E2, R2>(
    self: STM<K, E, R>,
    tag: Exclude<N, keyof K>,
    f: (_: NoInfer<K>) => STM<A, E2, R2>,
  ): STM<MergeRecord<K, { [k in string]: A }>, E | E2, R | R2>;
};

bindTo

Added in v2.0.0 Source

Signature

declare const bindTo: {
  <N extends string>(tag: N): <A, E, R>(self: STM<A, E, R>) => STM<Record<N, A>, E, R>;
  <A, E, R, N extends string>(self: STM<A, E, R>, tag: N): STM<Record<N, A>, E, R>;
};

Do

Added in v2.0.0 Source

Signature

declare const Do: STM<{}>;

Elements

This function takes an iterable of STM values and returns a new STM value that represents the first STM value in the iterable that succeeds. If all of the Effect values in the iterable fail, then the resulting STM value will fail as well.

This function is sequential, meaning that the STM values in the iterable will be executed in sequence, and the first one that succeeds will determine the outcome of the resulting STM value.

Returns a new STM value that represents the first successful STM value in the iterable, or a failed STM value if all of the STM values in the iterable fail.

Signature

declare function firstSuccessOf<A, E, R>(effects: Iterable<STM<A, E, R>>): STM<A, E, R>;

Error Handling

catchAll

Added in v2.0.0 Source

Recovers from all errors.

Signature

declare const catchAll: {
  <E, B, E1, R1>(f: (e: E) => STM<B, E1, R1>): <A, R>(self: STM<A, E, R>) => STM<B | A, E1, R1 | R>;
  <A, E, R, B, E1, R1>(self: STM<A, E, R>, f: (e: E) => STM<B, E1, R1>): STM<A | B, E1, R | R1>;
};

catchSome

Added in v2.0.0 Source

Recovers from some or all of the error cases.

Signature

declare const catchSome: {
  <E, A2, E2, R2>(
    pf: (error: E) => Option<STM<A2, E2, R2>>,
  ): <A, R>(self: STM<A, E, R>) => STM<A2 | A, E | E2, R2 | R>;
  <A, E, R, A2, E2, R2>(
    self: STM<A, E, R>,
    pf: (error: E) => Option<STM<A2, E2, R2>>,
  ): STM<A | A2, E | E2, R | R2>;
};

catchTag

Added in v2.0.0 Source

Recovers from the specified tagged error.

Signature

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

catchTags

Added in v2.0.0 Source

Recovers from multiple tagged errors.

Signature

declare const catchTags: {
  <
    E extends {
      _tag: string;
    },
    Cases extends {
      [K in string]: (
        error: Extract<
          E,
          {
            _tag: K;
          }
        >,
      ) => STM<any, any, any>;
    },
  >(
    cases: Cases,
  ): <A, R>(
    self: STM<A, E, R>,
  ) => STM<
    | A
    | {
        [K in string | number | symbol]: Cases[K] extends (...args: Array<any>) => STM<A, any, any>
          ? A
          : never;
      }[keyof Cases],
    | Exclude<
        E,
        {
          _tag: keyof Cases;
        }
      >
    | {
        [K in string | number | symbol]: Cases[K] extends (...args: Array<any>) => STM<any, E, any>
          ? E
          : never;
      }[keyof Cases],
    | R
    | {
        [K in string | number | symbol]: Cases[K] extends (...args: Array<any>) => STM<any, any, R>
          ? R
          : never;
      }[keyof Cases]
  >;
  <
    R,
    E extends {
      _tag: string;
    },
    A,
    Cases extends {
      [K in string]: (
        error: Extract<
          E,
          {
            _tag: K;
          }
        >,
      ) => STM<any, any, any>;
    },
  >(
    self: STM<A, E, R>,
    cases: Cases,
  ): STM<
    | A
    | {
        [K in string | number | symbol]: Cases[K] extends (...args: Array<any>) => STM<A, any, any>
          ? A
          : never;
      }[keyof Cases],
    | Exclude<
        E,
        {
          _tag: keyof Cases;
        }
      >
    | {
        [K in string | number | symbol]: Cases[K] extends (...args: Array<any>) => STM<any, E, any>
          ? E
          : never;
      }[keyof Cases],
    | R
    | {
        [K in string | number | symbol]: Cases[K] extends (...args: Array<any>) => STM<any, any, R>
          ? R
          : never;
      }[keyof Cases]
  >;
};

orDie

Added in v2.0.0 Source

Translates STM effect failure into death of the fiber, making all failures unchecked and not a part of the type of the effect.

Signature

declare const orDie: <A, E, R>(self: STM<A, E, R>) => STM<A, never, R>;

orDieWith

Added in v2.0.0 Source

Keeps none of the errors, and terminates the fiber running the STM effect with them, using the specified function to convert the E into a defect.

Signature

declare const orDieWith: {
  <E>(f: (error: E) => unknown): <A, R>(self: STM<A, E, R>) => STM<A, never, R>;
  <A, E, R>(self: STM<A, E, R>, f: (error: E) => unknown): STM<A, never, R>;
};

orElse

Added in v2.0.0 Source

Tries this effect first, and if it fails or retries, tries the other effect.

Signature

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

orElseEither

Added in v2.0.0 Source

Returns a transactional effect that will produce the value of this effect in left side, unless it fails or retries, in which case, it will produce the value of the specified effect in right side.

Signature

declare const orElseEither: {
  <A2, E2, R2>(
    that: LazyArg<STM<A2, E2, R2>>,
  ): <A, E, R>(self: STM<A, E, R>) => STM<Either<A2, A>, E2, R2 | R>;
  <A, E, R, A2, E2, R2>(
    self: STM<A, E, R>,
    that: LazyArg<STM<A2, E2, R2>>,
  ): STM<Either<A2, A>, E2, R | R2>;
};

orElseFail

Added in v2.0.0 Source

Tries this effect first, and if it fails or retries, fails with the specified error.

Signature

declare const orElseFail: {
  <E2>(error: LazyArg<E2>): <A, E, R>(self: STM<A, E, R>) => STM<A, E2, R>;
  <A, E, R, E2>(self: STM<A, E, R>, error: LazyArg<E2>): STM<A, E2, R>;
};

Returns an effect that will produce the value of this effect, unless it fails with the None value, in which case it will produce the value of the specified effect.

Signature

declare const orElseOptional: {
  <A2, E2, R2>(
    that: LazyArg<STM<A2, Option<E2>, R2>>,
  ): <A, E, R>(self: STM<A, Option<E>, R>) => STM<A2 | A, Option<E2 | E>, R2 | R>;
  <A, E, R, A2, E2, R2>(
    self: STM<A, Option<E>, R>,
    that: LazyArg<STM<A2, Option<E2>, R2>>,
  ): STM<A | A2, Option<E | E2>, R | R2>;
};

Tries this effect first, and if it fails or retries, succeeds with the specified value.

Signature

declare const orElseSucceed: {
  <A2>(value: LazyArg<A2>): <A, E, R>(self: STM<A, E, R>) => STM<A2 | A, never, R>;
  <A, E, R, A2>(self: STM<A, E, R>, value: LazyArg<A2>): STM<A | A2, never, R>;
};

orTry

Added in v2.0.0 Source

Tries this effect first, and if it enters retry, then it tries the other effect. This is an equivalent of Haskell's orElse.

Signature

declare const orTry: {
  <A1, E1, R1>(
    that: LazyArg<STM<A1, E1, R1>>,
  ): <A, E, R>(self: STM<A, E, R>) => STM<A1 | A, E1 | E, R1 | R>;
  <A, E, R, A1, E1, R1>(
    self: STM<A, E, R>,
    that: LazyArg<STM<A1, E1, R1>>,
  ): STM<A | A1, E | E1, R | R1>;
};

retry

Added in v2.0.0 Source

Abort and retry the whole transaction when any of the underlying transactional variables have changed.

Signature

declare const retry: STM<never>;

Filtering

filterOrDie

Added in v2.0.0 Source

Dies with specified defect if the predicate fails.

Signature

declare const filterOrDie: {
  <A, B>(
    refinement: Refinement<NoInfer<A>, B>,
    defect: LazyArg<unknown>,
  ): <E, R>(self: STM<A, E, R>) => STM<B, E, R>;
  <A>(
    predicate: Predicate<NoInfer<A>>,
    defect: LazyArg<unknown>,
  ): <E, R>(self: STM<A, E, R>) => STM<A, E, R>;
  <A, E, R, B>(
    self: STM<A, E, R>,
    refinement: Refinement<A, B>,
    defect: LazyArg<unknown>,
  ): STM<B, E, R>;
  <A, E, R>(self: STM<A, E, R>, predicate: Predicate<A>, defect: LazyArg<unknown>): STM<A, E, R>;
};

Dies with a Cause.RuntimeException having the specified message if the predicate fails.

Signature

declare const filterOrDieMessage: {
  <A, B>(
    refinement: Refinement<NoInfer<A>, B>,
    message: string,
  ): <E, R>(self: STM<A, E, R>) => STM<B, E, R>;
  <A>(
    predicate: Predicate<NoInfer<A>>,
    message: string,
  ): <E, R>(self: STM<A, E, R>) => STM<A, E, R>;
  <A, E, R, B>(self: STM<A, E, R>, refinement: Refinement<A, B>, message: string): STM<B, E, R>;
  <A, E, R>(self: STM<A, E, R>, predicate: Predicate<A>, message: string): STM<A, E, R>;
};

filterOrElse

Added in v2.0.0 Source

Supplies orElse if the predicate fails.

Signature

declare const filterOrElse: {
  <A, B, C, E2, R2>(
    refinement: Refinement<NoInfer<A>, B>,
    orElse: (a: NoInfer<A>) => STM<C, E2, R2>,
  ): <E, R>(self: STM<A, E, R>) => STM<B | C, E2 | E, R2 | R>;
  <A, B, E2, R2>(
    predicate: Predicate<NoInfer<A>>,
    orElse: (a: NoInfer<A>) => STM<B, E2, R2>,
  ): <E, R>(self: STM<A, E, R>) => STM<A | B, E2 | E, R2 | R>;
  <A, E, R, B, C, E2, R2>(
    self: STM<A, E, R>,
    refinement: Refinement<A, B>,
    orElse: (a: A) => STM<C, E2, R2>,
  ): STM<B | C, E | E2, R | R2>;
  <A, E, R, B, E2, R2>(
    self: STM<A, E, R>,
    predicate: Predicate<A>,
    orElse: (a: A) => STM<B, E2, R2>,
  ): STM<A | B, E | E2, R | R2>;
};

filterOrFail

Added in v2.0.0 Source

Fails with the specified error if the predicate fails.

Signature

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

Finalization

ensuring

Added in v2.0.0 Source

Executes the specified finalization transaction whether or not this effect succeeds. Note that as with all STM transactions, if the full transaction fails, everything will be rolled back.

Signature

declare const ensuring: {
  <R1, B>(finalizer: STM<B, never, R1>): <A, E, R>(self: STM<A, E, R>) => STM<A, E, R1 | R>;
  <A, E, R, R1, B>(self: STM<A, E, R>, finalizer: STM<B, never, R1>): STM<A, E, R | R1>;
};

Folding

match

Added in v2.0.0 Source

Folds over the STM effect, handling both failure and success, but not retry.

Signature

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

matchSTM

Added in v2.0.0 Source

Effectfully folds over the STM effect, handling both failure and success.

Signature

declare const matchSTM: {
  <E, A1, E1, R1, A, A2, E2, R2>(options: {
    readonly onFailure: (e: E) => STM<A1, E1, R1>;
    readonly onSuccess: (a: A) => STM<A2, E2, R2>;
  }): <R>(self: STM<A, E, R>) => STM<A1 | A2, E1 | E2, R1 | R2 | R>;
  <A, E, R, A1, E1, R1, A2, E2, R2>(
    self: STM<A, E, R>,
    options: {
      readonly onFailure: (e: E) => STM<A1, E1, R1>;
      readonly onSuccess: (a: A) => STM<A2, E2, R2>;
    },
  ): STM<A1 | A2, E1 | E2, R | R1 | R2>;
};

Getters

isFailure

Added in v2.0.0 Source

Returns whether this transactional effect is a failure.

Signature

declare const isFailure: <A, E, R>(self: STM<A, E, R>) => STM<boolean, never, R>;

isSuccess

Added in v2.0.0 Source

Returns whether this transactional effect is a success.

Signature

declare const isSuccess: <A, E, R>(self: STM<A, E, R>) => STM<boolean, never, R>;

some

Added in v2.0.0 Source

Converts an option on values into an option on errors.

Signature

declare const some: <A, E, R>(self: STM<Option.Option<A>, E, R>) => STM<A, Option.Option<E>, R>;

unsome

Added in v2.0.0 Source

Converts an option on errors into an option on values.

Signature

declare const unsome: <A, E, R>(self: STM<A, Option.Option<E>, R>) => STM<Option.Option<A>, E, R>;

Mapping

as

Added in v2.0.0 Source

Maps the success value of this effect to the specified constant value.

Signature

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

asSome

Added in v2.0.0 Source

Maps the success value of this effect to an optional value.

Signature

declare const asSome: <A, E, R>(self: STM<A, E, R>) => STM<Option.Option<A>, E, R>;

asSomeError

Added in v2.0.0 Source

Maps the error value of this effect to an optional value.

Signature

declare const asSomeError: <A, E, R>(self: STM<A, E, R>) => STM<A, Option.Option<E>, R>;

asVoid

Added in v2.0.0 Source

This function maps the success value of an STM to void. If the original STM succeeds, the returned STM will also succeed. If the original STM fails, the returned STM will fail with the same error.

Signature

declare const asVoid: <A, E, R>(self: STM<A, E, R>) => STM<void, E, R>;

map

Added in v2.0.0 Source

Maps the value produced by the effect.

Signature

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

mapAttempt

Added in v2.0.0 Source

Maps the value produced by the effect with the specified function that may throw exceptions but is otherwise pure, translating any thrown exceptions into typed failed effects.

Signature

declare const mapAttempt: {
  <A, B>(f: (a: A) => B): <E, R>(self: STM<A, E, R>) => STM<B, unknown, R>;
  <A, E, R, B>(self: STM<A, E, R>, f: (a: A) => B): STM<B, unknown, R>;
};

mapBoth

Added in v2.0.0 Source

Returns an STM effect whose failure and success channels have been mapped by the specified pair of functions, f and g.

Signature

declare const mapBoth: {
  <E, E2, A, A2>(options: {
    readonly onFailure: (error: E) => E2;
    readonly onSuccess: (value: A) => A2;
  }): <R>(self: STM<A, E, R>) => STM<A2, E2, R>;
  <A, E, R, E2, A2>(
    self: STM<A, E, R>,
    options: {
      readonly onFailure: (error: E) => E2;
      readonly onSuccess: (value: A) => A2;
    },
  ): STM<A2, E2, R>;
};

mapError

Added in v2.0.0 Source

Maps from one error type to another.

Signature

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

Models

Adapter interface

Added in v2.0.0 Source

Signature

interface Adapter {
  <A, E, R>(self: STM<A, E, R>): STM<A, E, R>;
  <A, _R, _E, _A>(a: A, ab: (a: A) => STM<_A, _E, _R>): STM<_A, _E, _R>;
  <A, B, _R, _E, _A>(a: A, ab: (a: A) => B, bc: (b: B) => STM<_A, _E, _R>): STM<_A, _E, _R>;
  <A, B, C, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: F) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (g: H) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, L, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => L,
    lm: (l: L) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, L, M, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => L,
    lm: (l: L) => M,
    mn: (m: M) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, L, M, N, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => L,
    lm: (l: L) => M,
    mn: (m: M) => N,
    no: (n: N) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => L,
    lm: (l: L) => M,
    mn: (m: M) => N,
    no: (n: N) => O,
    op: (o: O) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => L,
    lm: (l: L) => M,
    mn: (m: M) => N,
    no: (n: N) => O,
    op: (o: O) => P,
    pq: (p: P) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => L,
    lm: (l: L) => M,
    mn: (m: M) => N,
    no: (n: N) => O,
    op: (o: O) => P,
    pq: (p: P) => Q,
    qr: (q: Q) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => L,
    lm: (l: L) => M,
    mn: (m: M) => N,
    no: (n: N) => O,
    op: (o: O) => P,
    pq: (p: P) => Q,
    qr: (q: Q) => R,
    rs: (r: R) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => L,
    lm: (l: L) => M,
    mn: (m: M) => N,
    no: (n: N) => O,
    op: (o: O) => P,
    pq: (p: P) => Q,
    qr: (q: Q) => R,
    rs: (r: R) => S,
    st: (s: S) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
  <A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, _R, _E, _A>(
    a: A,
    ab: (a: A) => B,
    bc: (b: B) => C,
    cd: (c: C) => D,
    de: (d: D) => E,
    ef: (e: E) => F,
    fg: (f: F) => G,
    gh: (g: G) => H,
    hi: (h: H) => I,
    ij: (i: I) => J,
    jk: (j: J) => K,
    kl: (k: K) => L,
    lm: (l: L) => M,
    mn: (m: M) => N,
    no: (n: N) => O,
    op: (o: O) => P,
    pq: (p: P) => Q,
    qr: (q: Q) => R,
    rs: (r: R) => S,
    st: (s: S) => T,
    tu: (s: T) => STM<_A, _E, _R>,
  ): STM<_A, _E, _R>;
}

STM interface

Added in v2.0.0 Source

STM<A, E, R> represents an effect that can be performed transactionally, resulting in a failure E or a value A that may require an environment R to execute.

Software Transactional Memory is a technique which allows composition of arbitrary atomic operations. It is the software analog of transactions in database systems.

The API is lifted directly from the Haskell package Control.Concurrent.STM although the implementation does not resemble the Haskell one at all.

See http://hackage.haskell.org/package/stm-2.5.0.0/docs/Control-Concurrent-STM.html

STM in Haskell was introduced in:

Composable memory transactions, by Tim Harris, Simon Marlow, Simon Peyton Jones, and Maurice Herlihy, in ACM Conference on Principles and Practice of Parallel Programming 2005.

See https://www.microsoft.com/en-us/research/publication/composable-memory-transactions/

See also: Lock Free Data Structures using STMs in Haskell, by Anthony Discolo, Tim Harris, Simon Marlow, Simon Peyton Jones, Satnam Singh) FLOPS 2006: Eighth International Symposium on Functional and Logic Programming, Fuji Susono, JAPAN, April 2006

https://www.microsoft.com/en-us/research/publication/lock-free-data-structures-using-stms-in-haskell/

The implemtation is based on the ZIO STM module, while JS environments have no race conditions from multiple threads STM provides greater benefits for synchronization of Fibers and transactional data-types can be quite useful.

Signature

interface STM<out A, out E = never, out R = never>
  extends Effect<A, E, R>, Variance<A, E, R>, Pipeable {
  [ignoreSymbol]?: STMUnifyIgnore;
  [typeSymbol]?: unknown;
  [unifySymbol]?: STMUnify<STM<A, E, R>>;
  [iterator](): EffectGenerator<STM<A, E, R>>;
}

STMUnify interface

Added in v2.0.0 Source

Signature

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

STMUnifyIgnore interface

Added in v2.0.0 Source

Signature

interface STMUnifyIgnore extends EffectUnifyIgnore {
  Effect?: true;
}

Mutations

collect

Added in v2.0.0 Source

Simultaneously filters and maps the value produced by this effect.

Signature

declare const collect: {
  <A, A2>(pf: (a: A) => Option<A2>): <E, R>(self: STM<A, E, R>) => STM<A2, E, R>;
  <A, E, R, A2>(self: STM<A, E, R>, pf: (a: A) => Option<A2>): STM<A2, E, R>;
};

collectSTM

Added in v2.0.0 Source

Simultaneously filters and maps the value produced by this effect.

Signature

declare const collectSTM: {
  <A, A2, E2, R2>(
    pf: (a: A) => Option<STM<A2, E2, R2>>,
  ): <E, R>(self: STM<A, E, R>) => STM<A2, E2 | E, R2 | R>;
  <A, E, R, A2, E2, R2>(
    self: STM<A, E, R>,
    pf: (a: A) => Option<STM<A2, E2, R2>>,
  ): STM<A2, E | E2, R | R2>;
};

either

Added in v2.0.0 Source

Converts the failure channel into an Either.

Signature

declare const either: <A, E, R>(self: STM<A, E, R>) => STM<Either.Either<A, E>, never, R>;

eventually

Added in v2.0.0 Source

Returns an effect that ignores errors and runs repeatedly until it eventually succeeds.

Signature

declare const eventually: <A, E, R>(self: STM<A, E, R>) => STM<A, E, R>;

flip

Added in v2.0.0 Source

Flips the success and failure channels of this transactional effect. This allows you to use all methods on the error channel, possibly before flipping back.

Signature

declare const flip: <A, E, R>(self: STM<A, E, R>) => STM<E, A, R>;

flipWith

Added in v2.0.0 Source

Swaps the error/value parameters, applies the function f and flips the parameters back

Signature

declare const flipWith: {
  <E, A, R, E2, A2, R2>(
    f: (stm: STM<E, A, R>) => STM<E2, A2, R2>,
  ): (self: STM<A, E, R>) => STM<A | A2, E | E2, R | R2>;
  <A, E, R, E2, A2, R2>(
    self: STM<A, E, R>,
    f: (stm: STM<E, A, R>) => STM<E2, A2, R2>,
  ): STM<A | A2, E | E2, R | R2>;
};

ignore

Added in v2.0.0 Source

Returns a new effect that ignores the success or failure of this effect.

Signature

declare const ignore: <A, E, R>(self: STM<A, E, R>) => STM<void, never, R>;

merge

Added in v2.0.0 Source

Returns a new effect where the error channel has been merged into the success channel to their common combined type.

Signature

declare const merge: <A, E, R>(self: STM<A, E, R>) => STM<E | A, never, R>;

negate

Added in v2.0.0 Source

Returns a new effect where boolean value of this effect is negated.

Signature

declare const negate: <E, R>(self: STM<boolean, E, R>) => STM<boolean, E, R>;

none

Added in v2.0.0 Source

Requires the option produced by this value to be None.

Signature

declare const none: <A, E, R>(self: STM<Option.Option<A>, E, R>) => STM<void, Option.Option<E>, R>;

option

Added in v2.0.0 Source

Converts the failure channel into an Option.

Signature

declare const option: <A, E, R>(self: STM<A, E, R>) => STM<Option.Option<A>, never, R>;

refineOrDie

Added in v2.0.0 Source

Keeps some of the errors, and terminates the fiber with the rest.

Signature

declare const refineOrDie: {
  <E, E2>(pf: (error: E) => Option<E2>): <A, R>(self: STM<A, E, R>) => STM<A, E2, R>;
  <A, E, R, E2>(self: STM<A, E, R>, pf: (error: E) => Option<E2>): STM<A, E2, R>;
};

Keeps some of the errors, and terminates the fiber with the rest, using the specified function to convert the E into a Throwable.

Signature

declare const refineOrDieWith: {
  <E, E2>(
    pf: (error: E) => Option<E2>,
    f: (error: E) => unknown,
  ): <A, R>(self: STM<A, E, R>) => STM<A, E2, R>;
  <A, E, R, E2>(
    self: STM<A, E, R>,
    pf: (error: E) => Option<E2>,
    f: (error: E) => unknown,
  ): STM<A, E2, R>;
};

reject

Added in v2.0.0 Source

Fail with the returned value if the PartialFunction matches, otherwise continue with our held value.

Signature

declare const reject: {
  <A, E2>(pf: (a: A) => Option<E2>): <E, R>(self: STM<A, E, R>) => STM<A, E2 | E, R>;
  <A, E, R, E2>(self: STM<A, E, R>, pf: (a: A) => Option<E2>): STM<A, E | E2, R>;
};

rejectSTM

Added in v2.0.0 Source

Continue with the returned computation if the specified partial function matches, translating the successful match into a failure, otherwise continue with our held value.

Signature

declare const rejectSTM: {
  <A, E2, R2>(
    pf: (a: A) => Option<STM<E2, E2, R2>>,
  ): <E, R>(self: STM<A, E, R>) => STM<A, E2 | E, R2 | R>;
  <A, E, R, E2, R2>(
    self: STM<A, E, R>,
    pf: (a: A) => Option<STM<E2, E2, R2>>,
  ): STM<A, E | E2, R | R2>;
};

repeatUntil

Added in v2.0.0 Source

Repeats this STM effect until its result satisfies the specified predicate.

WARNING: repeatUntil uses a busy loop to repeat the effect and will consume a thread until it completes (it cannot yield). This is because STM describes a single atomic transaction which must either complete, retry or fail a transaction before yielding back to the Effect runtime. - Use retryUntil instead if you don't need to maintain transaction state for repeats. - Ensure repeating the STM effect will eventually satisfy the predicate.

Signature

declare const repeatUntil: {
  <A>(predicate: Predicate<A>): <E, R>(self: STM<A, E, R>) => STM<A, E, R>;
  <A, E, R>(self: STM<A, E, R>, predicate: Predicate<A>): STM<A, E, R>;
};

repeatWhile

Added in v2.0.0 Source

Repeats this STM effect while its result satisfies the specified predicate.

WARNING: repeatWhile uses a busy loop to repeat the effect and will consume a thread until it completes (it cannot yield). This is because STM describes a single atomic transaction which must either complete, retry or fail a transaction before yielding back to the Effect runtime. - Use retryWhile instead if you don't need to maintain transaction state for repeats. - Ensure repeating the STM effect will eventually not satisfy the predicate.

Signature

declare const repeatWhile: {
  <A>(predicate: Predicate<A>): <E, R>(self: STM<A, E, R>) => STM<A, E, R>;
  <A, E, R>(self: STM<A, E, R>, predicate: Predicate<A>): STM<A, E, R>;
};

retryUntil

Added in v2.0.0 Source

Filters the value produced by this effect, retrying the transaction until the predicate returns true for the value.

Signature

declare const retryUntil: {
  <A, B>(refinement: Refinement<NoInfer<A>, B>): <E, R>(self: STM<A, E, R>) => STM<B, E, R>;
  <A>(predicate: Predicate<A>): <E, R>(self: STM<A, E, R>) => STM<A, E, R>;
  <A, E, R, B>(self: STM<A, E, R>, refinement: Refinement<A, B>): STM<B, E, R>;
  <A, E, R>(self: STM<A, E, R>, predicate: Predicate<A>): STM<A, E, R>;
};

retryWhile

Added in v2.0.0 Source

Filters the value produced by this effect, retrying the transaction while the predicate returns true for the value.

Signature

declare const retryWhile: {
  <A>(predicate: Predicate<A>): <E, R>(self: STM<A, E, R>) => STM<A, E, R>;
  <A, E, R>(self: STM<A, E, R>, predicate: Predicate<A>): STM<A, E, R>;
};

summarized

Added in v2.0.0 Source

Summarizes a STM effect by computing a provided value before and after execution, and then combining the values to produce a summary, together with the result of execution.

Signature

declare const summarized: {
  <A2, E2, R2, A3>(
    summary: STM<A2, E2, R2>,
    f: (before: A2, after: A2) => A3,
  ): <A, E, R>(self: STM<A, E, R>) => STM<[A3, A], E2 | E, R2 | R>;
  <A, E, R, A2, E2, R2, A3>(
    self: STM<A, E, R>,
    summary: STM<A2, E2, R2>,
    f: (before: A2, after: A2) => A3,
  ): STM<[A3, A], E | E2, R | R2>;
};

unless

Added in v2.0.0 Source

The moral equivalent of if (!p) exp

Signature

declare const unless: {
  (predicate: LazyArg<boolean>): <A, E, R>(self: STM<A, E, R>) => STM<Option<A>, E, R>;
  <A, E, R>(self: STM<A, E, R>, predicate: LazyArg<boolean>): STM<Option<A>, E, R>;
};

unlessSTM

Added in v2.0.0 Source

The moral equivalent of if (!p) exp when p has side-effects

Signature

declare const unlessSTM: {
  <E2, R2>(
    predicate: STM<boolean, E2, R2>,
  ): <A, E, R>(self: STM<A, E, R>) => STM<Option<A>, E2 | E, R2 | R>;
  <A, E, R, E2, R2>(
    self: STM<A, E, R>,
    predicate: STM<boolean, E2, R2>,
  ): STM<Option<A>, E | E2, R | R2>;
};

validateAll

Added in v2.0.0 Source

Feeds elements of type A to f and accumulates all errors in error channel or successes in success channel.

This combinator is lossy meaning that if there are errors all successes will be lost. To retain all information please use STM.partition.

Signature

declare const validateAll: {
  <A, B, E, R>(
    f: (a: A) => STM<B, E, R>,
  ): (elements: Iterable<A>) => STM<Array<B>, [E, ...Array<E>], R>;
  <A, B, E, R>(
    elements: Iterable<A>,
    f: (a: A) => STM<B, E, R>,
  ): STM<Array<B>, [E, ...Array<E>], R>;
};

Feeds elements of type A to f until it succeeds. Returns first success or the accumulation of all errors.

Signature

declare const validateFirst: {
  <A, B, E, R>(f: (a: A) => STM<B, E, R>): (elements: Iterable<A>) => STM<B, Array<E>, R>;
  <A, B, E, R>(elements: Iterable<A>, f: (a: A) => STM<B, E, R>): STM<B, Array<E>, R>;
};

when

Added in v2.0.0 Source

The moral equivalent of if (p) exp.

Signature

declare const when: {
  (predicate: LazyArg<boolean>): <A, E, R>(self: STM<A, E, R>) => STM<Option<A>, E, R>;
  <A, E, R>(self: STM<A, E, R>, predicate: LazyArg<boolean>): STM<Option<A>, E, R>;
};

whenSTM

Added in v2.0.0 Source

The moral equivalent of if (p) exp when p has side-effects.

Signature

declare const whenSTM: {
  <E2, R2>(
    predicate: STM<boolean, E2, R2>,
  ): <A, E, R>(self: STM<A, E, R>) => STM<Option<A>, E2 | E, R2 | R>;
  <A, E, R, E2, R2>(
    self: STM<A, E, R>,
    predicate: STM<boolean, E2, R2>,
  ): STM<Option<A>, E | E2, R | R2>;
};

Other

Signature

declare const if: {
  <A, E1, R1, A2, E2, R2>(options: {
    readonly onFalse: STM<A2, E2, R2>;
    readonly onTrue: STM<A, E1, R1>;
  }): <E = never, R = never>(self: boolean | STM<boolean, E, R>) => STM<A | A2, E1 | E2 | E, R1 | R2 | R>;
  <A, E1, R1, A2, E2, R2, E = never, R = never>(self: boolean, options: {
    readonly onFalse: STM<A2, E2, R2>;
    readonly onTrue: STM<A, E1, R1>;
  }): STM<A | A2, E1 | E2 | E, R1 | R2 | R>;
  <E, R, A, E1, R1, A2, E2, R2>(self: STM<boolean, E, R>, options: {
    readonly onFalse: STM<A2, E2, R2>;
    readonly onTrue: STM<A, E1, R1>;
  }): STM<A | A2, E | E1 | E2, R | R1 | R2>;
}

Signature

declare const let: {
  <N extends string, K, A>(
    tag: Exclude<N, keyof K>,
    f: (_: NoInfer<K>) => A,
  ): <E, R>(self: STM<K, E, R>) => STM<MergeRecord<K, { [k in string]: A }>, E, R>;
  <K, E, R, N extends string, A>(
    self: STM<K, E, R>,
    tag: Exclude<N, keyof K>,
    f: (_: NoInfer<K>) => A,
  ): STM<MergeRecord<K, { [k in string]: A }>, E, R>;
};

STM

Added in v2.0.0 Source

Signature

declare const try: {
  <A, E>(options: {
    readonly catch: (u: unknown) => E;
    readonly try: LazyArg<A>;
  }): STM<A, E>;
  <A>(try_: LazyArg<A>): STM<A, unknown>;
}

Signature

declare const void: STM<void>

Refinements

isSTM

Added in v2.0.0 Source

Returns true if the provided value is an STM, false otherwise.

Signature

declare const isSTM: (u: unknown) => u is STM<unknown, unknown, unknown>;

Sequencing

flatMap

Added in v2.0.0 Source

Feeds the value produced by this effect to the specified function, and then runs the returned effect as well to produce its results.

Signature

declare const flatMap: {
  <A, A2, E1, R1>(
    f: (a: A) => STM<A2, E1, R1>,
  ): <E, R>(self: STM<A, E, R>) => STM<A2, E1 | E, R1 | R>;
  <A, E, R, A2, E1, R1>(self: STM<A, E, R>, f: (a: A) => STM<A2, E1, R1>): STM<A2, E | E1, R | R1>;
};

flatten

Added in v2.0.0 Source

Flattens out a nested STM effect.

Signature

declare const flatten: <A, E2, R2, E, R>(self: STM<STM<A, E2, R2>, E, R>) => STM<A, E2 | E, R2 | R>;

tap

Added in v2.0.0 Source

"Peeks" at the success of transactional effect.

Signature

declare const tap: {
  <A, X, E2, R2>(f: (a: A) => STM<X, E2, R2>): <E, R>(self: STM<A, E, R>) => STM<A, E2 | E, R2 | R>;
  <A, E, R, X, E2, R2>(self: STM<A, E, R>, f: (a: A) => STM<X, E2, R2>): STM<A, E | E2, R | R2>;
};

tapBoth

Added in v2.0.0 Source

"Peeks" at both sides of an transactional effect.

Signature

declare const tapBoth: {
  <XE, A2, E2, R2, XA, A3, E3, R3, A, E>(options: {
    readonly onFailure: (error: XE) => STM<A2, E2, R2>;
    readonly onSuccess: (value: XA) => STM<A3, E3, R3>;
  }): <R>(self: STM<A, E, R>) => STM<A, E2 | E3 | E, R2 | R3 | R>;
  <A, E, R, XE, A2, E2, R2, XA, A3, E3, R3>(
    self: STM<A, E, R>,
    options: {
      readonly onFailure: (error: XE) => STM<A2, E2, R2>;
      readonly onSuccess: (value: XA) => STM<A3, E3, R3>;
    },
  ): STM<A, E | E2 | E3, R | R2 | R3>;
};

tapError

Added in v2.0.0 Source

"Peeks" at the error of the transactional effect.

Signature

declare const tapError: {
  <E, X, E2, R2>(
    f: (error: NoInfer<E>) => STM<X, E2, R2>,
  ): <A, R>(self: STM<A, E, R>) => STM<A, E | E2, R2 | R>;
  <A, E, R, X, E2, R2>(self: STM<A, E, R>, f: (error: E) => STM<X, E2, R2>): STM<A, E | E2, R | R2>;
};

Symbols

STMTypeId

Added in v2.0.0 Source

Signature

declare const STMTypeId: unique symbol;

STMTypeId type

Added in v2.0.0 Source

Signature

type STMTypeId = typeof STMTypeId;

Traversing

forEach

Added in v2.0.0 Source

Applies the function f to each element of the Iterable<A> and returns a transactional effect that produces a new Chunk<A2>.

Signature

declare const forEach: {
  <A, A2, E, R>(
    f: (a: A) => STM<A2, E, R>,
    options?: {
      readonly discard?: false;
    },
  ): (elements: Iterable<A>) => STM<Array<A2>, E, R>;
  <A, A2, E, R>(
    f: (a: A) => STM<A2, E, R>,
    options: {
      readonly discard: true;
    },
  ): (elements: Iterable<A>) => STM<void, E, R>;
  <A, A2, E, R>(
    elements: Iterable<A>,
    f: (a: A) => STM<A2, E, R>,
    options?: {
      readonly discard?: false;
    },
  ): STM<Array<A2>, E, R>;
  <A, A2, E, R>(
    elements: Iterable<A>,
    f: (a: A) => STM<A2, E, R>,
    options: {
      readonly discard: true;
    },
  ): STM<void, E, R>;
};

partition

Added in v2.0.0 Source

Feeds elements of type A to a function f that returns an effect. Collects all successes and failures in a tupled fashion.

Signature

declare const partition: {
  <A, A2, E, R>(
    f: (a: A) => STM<A2, E, R>,
  ): (elements: Iterable<A>) => STM<[excluded: Array<E>, satisfying: Array<A2>], never, R>;
  <A, A2, E, R>(
    elements: Iterable<A>,
    f: (a: A) => STM<A2, E, R>,
  ): STM<[excluded: Array<E>, satisfying: Array<A2>], never, R>;
};

Type Lambdas

STMTypeLambda interface

Added in v2.0.0 Source

Signature

interface STMTypeLambda extends TypeLambda {
  readonly type: STM<unknown, unknown, unknown>;
}

Utils

All

Added in v2.0.0 Source

Zipping

zip

Added in v2.0.0 Source

Sequentially zips this value with the specified one.

Signature

declare const zip: {
  <A1, E1, R1>(
    that: STM<A1, E1, R1>,
  ): <A, E, R>(self: STM<A, E, R>) => STM<[A, A1], E1 | E, R1 | R>;
  <A, E, R, A1, E1, R1>(self: STM<A, E, R>, that: STM<A1, E1, R1>): STM<[A, A1], E | E1, R | R1>;
};

zipLeft

Added in v2.0.0 Source

Sequentially zips this value with the specified one, discarding the second element of the tuple.

Signature

declare const zipLeft: {
  <A1, E1, R1>(that: STM<A1, E1, R1>): <A, E, R>(self: STM<A, E, R>) => STM<A, E1 | E, R1 | R>;
  <A, E, R, A1, E1, R1>(self: STM<A, E, R>, that: STM<A1, E1, R1>): STM<A, E | E1, R | R1>;
};

zipRight

Added in v2.0.0 Source

Sequentially zips this value with the specified one, discarding the first element of the tuple.

Signature

declare const zipRight: {
  <A1, E1, R1>(that: STM<A1, E1, R1>): <A, E, R>(self: STM<A, E, R>) => STM<A1, E1 | E, R1 | R>;
  <A, E, R, A1, E1, R1>(self: STM<A, E, R>, that: STM<A1, E1, R1>): STM<A1, E | E1, R | R1>;
};

zipWith

Added in v2.0.0 Source

Sequentially zips this value with the specified one, combining the values using the specified combiner function.

Signature

declare const zipWith: {
  <A1, E1, R1, A, A2>(
    that: STM<A1, E1, R1>,
    f: (a: A, b: A1) => A2,
  ): <E, R>(self: STM<A, E, R>) => STM<A2, E1 | E, R1 | R>;
  <A, E, R, A1, E1, R1, A2>(
    self: STM<A, E, R>,
    that: STM<A1, E1, R1>,
    f: (a: A, b: A1) => A2,
  ): STM<A2, E | E1, R | R1>;
};