Skip to main content Link Search Menu Expand Document (external link)

STM overview

Added in v2.0.0


Table of contents


constructors

acquireUseRelease

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

export 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.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.Effect<A2, E | E2 | E3, R | R2 | R3>
}

Added in v2.0.0

all

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

export declare const all: All.Signature

Added in v2.0.0

attempt

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

Signature

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

Added in v2.0.0

check

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

Signature

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

Added in v2.0.0

cond

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

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

Added in v2.0.0

context

Retrieves the environment inside an stm.

Signature

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

Added in v2.0.0

contextWith

Accesses the environment of the transaction to perform a transaction.

Signature

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

Added in v2.0.0

contextWithSTM

Accesses the environment of the transaction to perform a transaction.

Signature

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

Added in v2.0.0

die

Fails the transactional effect with the specified defect.

Signature

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

Added in v2.0.0

dieMessage

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

Signature

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

Added in v2.0.0

dieSync

Fails the transactional effect with the specified lazily evaluated defect.

Signature

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

Added in v2.0.0

every

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

Signature

export 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>
}

Added in v2.0.0

exists

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

Signature

export 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>
}

Added in v2.0.0

fail

Fails the transactional effect with the specified error.

Signature

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

Added in v2.0.0

failSync

Fails the transactional effect with the specified lazily evaluated error.

Signature

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

Added in v2.0.0

fiberId

Returns the fiber id of the fiber committing the transaction.

Signature

export declare const fiberId: STM<FiberId.FiberId, never, never>

Added in v2.0.0

filter

Filters the collection using the specified effectual predicate.

Signature

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

Added in v2.0.0

filterNot

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

Signature

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

Added in v2.0.0

fromEither

Lifts an Either into a STM.

Signature

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

Added in v2.0.0

fromOption

Lifts an Option into a STM.

Signature

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

Added in v2.0.0

gen

Signature

export declare const gen: <Eff extends YieldWrap<STM<any, any, any>>, AEff>(
  f: (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
>

Added in v2.0.0

interrupt

Interrupts the fiber running the effect.

Signature

export declare const interrupt: STM<never, never, never>

Added in v2.0.0

interruptAs

Interrupts the fiber running the effect with the specified FiberId.

Signature

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

Added in v2.0.0

iterate

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

const s = initial

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

return s

Signature

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

Added in v2.0.0

loop

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

const as = []
let s = initial

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

return as

Signature

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

Added in v2.0.0

mergeAll

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

Signature

export 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>
}

Added in v2.0.0

reduce

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

Signature

export 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>
}

Added in v2.0.0

reduceAll

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

Signature

export 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>
}

Added in v2.0.0

reduceRight

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

Signature

export 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>
}

Added in v2.0.0

replicate

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

Signature

export declare const replicate: {
  (n: number): <A, E, R>(self: STM<A, E, R>) => STM<A, E, R>[]
  <A, E, R>(self: STM<A, E, R>, n: number): STM<A, E, R>[]
}

Added in v2.0.0

replicateSTM

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

Signature

export declare const replicateSTM: {
  (n: number): <A, E, R>(self: STM<A, E, R>) => STM<A[], E, R>
  <A, E, R>(self: STM<A, E, R>, n: number): STM<A[], E, R>
}

Added in v2.0.0

replicateSTMDiscard

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

Signature

export 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>
}

Added in v2.0.0

succeed

Returns an STM effect that succeeds with the specified value.

Signature

export declare const succeed: <A>(value: A) => STM<A, never, never>

Added in v2.0.0

succeedNone

Returns an effect with the empty value.

Signature

export declare const succeedNone: STM<Option.Option<never>, never, never>

Added in v2.0.0

succeedSome

Returns an effect with the optional value.

Signature

export declare const succeedSome: <A>(value: A) => STM<Option.Option<A>, never, never>

Added in v2.0.0

suspend

Suspends creation of the specified transaction lazily.

Signature

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

Added in v2.0.0

sync

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

Signature

export declare const sync: <A>(evaluate: () => A) => STM<A, never, never>

Added in v2.0.0

try

Imports a synchronous side-effect into a pure value, translating any thrown exceptions into typed failed effects.

Signature

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

Added in v2.0.0

void

Returns an STM effect that succeeds with void.

Signature

export declare const void: STM<void, never, never>

Added in v2.0.0

context

mapInputContext

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

Signature

export declare const mapInputContext: {
  <R0, R>(f: (context: Context.Context<R0>) => Context.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.Context<R0>) => Context.Context<R>): STM<A, E, R0>
}

Added in v2.0.0

provideContext

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

Signature

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

Added in v2.0.0

provideService

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

Signature

export declare const provideService: {
  <T extends Context.Tag<any, any>>(
    tag: T,
    resource: Context.Tag.Service<T>
  ): <A, E, R>(self: STM<A, E, R>) => STM<A, E, Exclude<R, Context.Tag.Identifier<T>>>
  <A, E, R, T extends Context.Tag<any, any>>(
    self: STM<A, E, R>,
    tag: T,
    resource: Context.Tag.Service<T>
  ): STM<A, E, Exclude<R, Context.Tag.Identifier<T>>>
}

Added in v2.0.0

provideServiceSTM

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

Signature

export declare const provideServiceSTM: {
  <T extends Context.Tag<any, any>, E1, R1>(
    tag: T,
    stm: STM<Context.Tag.Service<T>, E1, R1>
  ): <A, E, R>(self: STM<A, E, R>) => STM<A, E1 | E, R1 | Exclude<R, Context.Tag.Identifier<T>>>
  <A, E, R, T extends Context.Tag<any, any>, E1, R1>(
    self: STM<A, E, R>,
    tag: T,
    stm: STM<Context.Tag.Service<T>, E1, R1>
  ): STM<A, E | E1, R1 | Exclude<R, Context.Tag.Identifier<T>>>
}

Added in v2.0.0

provideSomeContext

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

Signature

export declare const provideSomeContext: {
  <R>(context: 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.Context<R>): STM<A, E, Exclude<R1, R>>
}

Added in v2.0.0

destructors

commit

Commits this transaction atomically.

Signature

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

Added in v2.0.0

commitEither

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

Signature

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

Added in v2.0.0

do notation

Do

Signature

export declare const Do: STM<{}, never, never>

Added in v2.0.0

bind

Signature

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

Added in v2.0.0

bindTo

Signature

export 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>
}

Added in v2.0.0

let

Signature

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

Added in v2.0.0

elements

firstSuccessOf

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.

Signature

export declare const firstSuccessOf: <A, E, R>(effects: Iterable<STM<A, E, R>>) => STM<A, E, R>

Added in v2.0.0

error handling

catchAll

Recovers from all errors.

Signature

export 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>
}

Added in v2.0.0

catchSome

Recovers from some or all of the error cases.

Signature

export declare const catchSome: {
  <E, A2, E2, R2>(
    pf: (error: E) => Option.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.Option<STM<A2, E2, R2>>
  ): STM<A | A2, E | E2, R | R2>
}

Added in v2.0.0

catchTag

Recovers from the specified tagged error.

Signature

export declare const catchTag: {
  <K extends E["_tag"] & 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 E["_tag"] & 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>
}

Added in v2.0.0

catchTags

Recovers from multiple tagged errors.

Signature

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

Added in v2.0.0

orDie

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

Signature

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

Added in v2.0.0

orDieWith

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

export 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>
}

Added in v2.0.0

orElse

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

Signature

export 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>
}

Added in v2.0.0

orElseEither

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

export declare const orElseEither: {
  <A2, E2, R2>(that: LazyArg<STM<A2, E2, R2>>): <A, E, R>(self: STM<A, E, R>) => STM<Either.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.Either<A2, A>, E2, R | R2>
}

Added in v2.0.0

orElseFail

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

Signature

export 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>
}

Added in v2.0.0

orElseOptional

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

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

Added in v2.0.0

orElseSucceed

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

Signature

export 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>
}

Added in v2.0.0

orTry

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

Signature

export 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>
}

Added in v2.0.0

retry

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

Signature

export declare const retry: STM<never, never, never>

Added in v2.0.0

filtering

filterOrDie

Dies with specified defect if the predicate fails.

Signature

export declare const filterOrDie: {
  <A, B extends A>(
    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 extends A>(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>
}

Added in v2.0.0

filterOrDieMessage

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

Signature

export declare const filterOrDieMessage: {
  <A, B extends A>(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 extends A>(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>
}

Added in v2.0.0

filterOrElse

Supplies orElse if the predicate fails.

Signature

export declare const filterOrElse: {
  <A, B extends A, 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 extends A, 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>
}

Added in v2.0.0

filterOrFail

Fails with the specified error if the predicate fails.

Signature

export declare const filterOrFail: {
  <A, B extends A, 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 extends A, 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>
}

Added in v2.0.0

finalization

ensuring

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

export 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>
}

Added in v2.0.0

folding

match

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

Signature

export 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>
}

Added in v2.0.0

matchSTM

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

Signature

export 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>
}

Added in v2.0.0

getters

Returns a successful effect with the head of the list if the list is non-empty or fails with the error None if the list is empty.

Signature

export declare const head: <A, E, R>(self: STM<Iterable<A>, E, R>) => STM<A, Option.Option<E>, R>

Added in v2.0.0

isFailure

Returns whether this transactional effect is a failure.

Signature

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

Added in v2.0.0

isSuccess

Returns whether this transactional effect is a success.

Signature

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

Added in v2.0.0

some

Converts an option on values into an option on errors.

Signature

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

Added in v2.0.0

unsome

Converts an option on errors into an option on values.

Signature

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

Added in v2.0.0

mapping

as

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

Signature

export 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>
}

Added in v2.0.0

asSome

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

Signature

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

Added in v2.0.0

asSomeError

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

Signature

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

Added in v2.0.0

asVoid

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

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

Added in v2.0.0

map

Maps the value produced by the effect.

Signature

export 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>
}

Added in v2.0.0

mapAttempt

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

export 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>
}

Added in v2.0.0

mapBoth

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

Signature

export 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>
}

Added in v2.0.0

mapError

Maps from one error type to another.

Signature

export 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>
}

Added in v2.0.0

models

Adapter (interface)

Signature

export 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>
}

Added in v2.0.0

STM (interface)

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

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

Added in v2.0.0

STMUnify (interface)

Signature

export interface STMUnify<A extends { [Unify.typeSymbol]?: any }> extends Effect.EffectUnify<A> {
  STM?: () => A[Unify.typeSymbol] extends STM<infer A0, infer E0, infer R0> | infer _ ? STM<R0, E0, A0> : never
}

Added in v2.0.0

STMUnifyIgnore (interface)

Signature

export interface STMUnifyIgnore extends Effect.EffectUnifyIgnore {
  Effect?: true
}

Added in v2.0.0

mutations

collect

Simultaneously filters and maps the value produced by this effect.

Signature

export declare const collect: {
  <A, A2>(pf: (a: A) => Option.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.Option<A2>): STM<A2, E, R>
}

Added in v2.0.0

collectSTM

Simultaneously filters and maps the value produced by this effect.

Signature

export declare const collectSTM: {
  <A, A2, E2, R2>(pf: (a: A) => Option.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.Option<STM<A2, E2, R2>>): STM<A2, E | E2, R | R2>
}

Added in v2.0.0

either

Converts the failure channel into an Either.

Signature

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

Added in v2.0.0

eventually

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

Signature

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

Added in v2.0.0

flip

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

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

Added in v2.0.0

flipWith

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

Signature

export 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>
}

Added in v2.0.0

if

Runs onTrue if the result of b is true and onFalse otherwise.

Signature

export declare const if: { <A, E1, R1, A2, E2, R2>(options: { readonly onTrue: STM<A, E1, R1>; readonly onFalse: STM<A2, E2, R2>; }): <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 onTrue: STM<A, E1, R1>; readonly onFalse: STM<A2, E2, R2>; }): STM<A | A2, E1 | E2 | E, R1 | R2 | R>; <E, R, A, E1, R1, A2, E2, R2>(self: STM<boolean, E, R>, options: { readonly onTrue: STM<A, E1, R1>; readonly onFalse: STM<A2, E2, R2>; }): STM<A | A2, E | E1 | E2, R | R1 | R2>; }

Added in v2.0.0

ignore

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

Signature

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

Added in v2.0.0

merge

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

Signature

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

Added in v2.0.0

negate

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

Signature

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

Added in v2.0.0

none

Requires the option produced by this value to be None.

Signature

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

Added in v2.0.0

option

Converts the failure channel into an Option.

Signature

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

Added in v2.0.0

refineOrDie

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

Signature

export declare const refineOrDie: {
  <E, E2>(pf: (error: E) => Option.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.Option<E2>): STM<A, E2, R>
}

Added in v2.0.0

refineOrDieWith

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

Signature

export declare const refineOrDieWith: {
  <E, E2>(pf: (error: E) => Option.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.Option<E2>, f: (error: E) => unknown): STM<A, E2, R>
}

Added in v2.0.0

reject

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

Signature

export declare const reject: {
  <A, E2>(pf: (a: A) => Option.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.Option<E2>): STM<A, E | E2, R>
}

Added in v2.0.0

rejectSTM

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

export declare const rejectSTM: {
  <A, E2, R2>(pf: (a: A) => Option.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.Option<STM<E2, E2, R2>>): STM<A, E | E2, R | R2>
}

Added in v2.0.0

repeatUntil

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

export 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>
}

Added in v2.0.0

repeatWhile

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

export 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>
}

Added in v2.0.0

retryUntil

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

Signature

export declare const retryUntil: {
  <A, B extends A>(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 extends A>(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>
}

Added in v2.0.0

retryWhile

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

Signature

export 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>
}

Added in v2.0.0

summarized

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

export 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>
}

Added in v2.0.0

unless

The moral equivalent of if (!p) exp

Signature

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

Added in v2.0.0

unlessSTM

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

Signature

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

Added in v2.0.0

validateAll

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

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

Added in v2.0.0

validateFirst

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

Signature

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

Added in v2.0.0

when

The moral equivalent of if (p) exp.

Signature

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

Added in v2.0.0

whenSTM

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

Signature

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

Added in v2.0.0

refinements

isSTM

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

Signature

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

Added in v2.0.0

sequencing

flatMap

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

Signature

export 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>
}

Added in v2.0.0

flatten

Flattens out a nested STM effect.

Signature

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

Added in v2.0.0

tap

“Peeks” at the success of transactional effect.

Signature

export 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>
}

Added in v2.0.0

tapBoth

“Peeks” at both sides of an transactional effect.

Signature

export declare const tapBoth: {
  <XE extends E, A2, E2, R2, XA extends A, 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 extends E, A2, E2, R2, XA extends A, 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>
}

Added in v2.0.0

tapError

“Peeks” at the error of the transactional effect.

Signature

export 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>
}

Added in v2.0.0

symbols

STMTypeId

Signature

export declare const STMTypeId: typeof STMTypeId

Added in v2.0.0

STMTypeId (type alias)

Signature

export type STMTypeId = typeof STMTypeId

Added in v2.0.0

traversing

forEach

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

Signature

export declare const forEach: {
  <A, A2, E, R>(
    f: (a: A) => STM<A2, E, R>,
    options?: { readonly discard?: false | undefined } | undefined
  ): (elements: Iterable<A>) => STM<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 | undefined } | undefined
  ): STM<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>
}

Added in v2.0.0

partition

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

Signature

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

Added in v2.0.0

type lambdas

STMTypeLambda (interface)

Signature

export interface STMTypeLambda extends TypeLambda {
  readonly type: STM<this["Target"], this["Out1"], this["Out2"]>
}

Added in v2.0.0

utils

All (namespace)

Added in v2.0.0

Signature (interface)

Signature

export interface Signature {
  <Arg extends ReadonlyArray<STMAny> | Iterable<STMAny> | Record<string, STMAny>, O extends Options>(
    arg: Narrow<Arg>,
    options?: O
  ): [Arg] extends [ReadonlyArray<STMAny>]
    ? ReturnTuple<Arg, IsDiscard<O>>
    : [Arg] extends [Iterable<STMAny>]
      ? ReturnIterable<Arg, IsDiscard<O>>
      : [Arg] extends [Record<string, STMAny>]
        ? ReturnObject<Arg, IsDiscard<O>>
        : never
}

Added in v2.0.0

Options (type alias)

Signature

export type Options = {
  readonly discard?: boolean | undefined
}

Added in v2.0.0

STM (namespace)

Added in v2.0.0

Variance (interface)

Signature

export interface Variance<out A, out E, out R> {
  readonly [STMTypeId]: {
    readonly _A: Covariant<A>
    readonly _E: Covariant<E>
    readonly _R: Covariant<R>
  }
}

Added in v2.0.0

zipping

zip

Sequentially zips this value with the specified one.

Signature

export 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>
}

Added in v2.0.0

zipLeft

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

Signature

export 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>
}

Added in v2.0.0

zipRight

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

Signature

export 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>
}

Added in v2.0.0

zipWith

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

Signature

export 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>
}

Added in v2.0.0