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

STM.ts overview

Since v2.0.0


Exports Grouped by Category


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

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

Source

Since 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

declare const all: All.Signature

Source

Since v2.0.0

attempt

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

Signature

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

Source

Since v2.0.0

check

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

Signature

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

Source

Since 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

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

Source

Since v2.0.0

context

Retrieves the environment inside an stm.

Signature

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

Source

Since v2.0.0

contextWith

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>

Source

Since v2.0.0

contextWithSTM

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>

Source

Since v2.0.0

die

Fails the transactional effect with the specified defect.

Signature

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

Source

Since v2.0.0

dieMessage

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

Signature

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

Source

Since v2.0.0

dieSync

Fails the transactional effect with the specified lazily evaluated defect.

Signature

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

Source

Since v2.0.0

every

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

Source

Since v2.0.0

exists

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

Source

Since v2.0.0

fail

Fails the transactional effect with the specified error.

Signature

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

Source

Since v2.0.0

failSync

Fails the transactional effect with the specified lazily evaluated error.

Signature

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

Source

Since v2.0.0

fiberId

Returns the fiber id of the fiber committing the transaction.

Signature

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

Source

Since v2.0.0

filter

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

Source

Since v2.0.0

filterNot

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

Source

Since v2.0.0

fromEither

Lifts an Either into a STM.

Signature

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

Source

Since v2.0.0

fromOption

Lifts an Option into a STM.

Signature

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

Source

Since v2.0.0

gen

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
>

Source

Since v2.0.0

interrupt

Interrupts the fiber running the effect.

Signature

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

Source

Since v2.0.0

interruptAs

Interrupts the fiber running the effect with the specified FiberId.

Signature

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

Source

Since 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

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>

Source

Since 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

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

Source

Since v2.0.0

mergeAll

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

Source

Since v2.0.0

reduce

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

Source

Since v2.0.0

reduceAll

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

Source

Since v2.0.0

reduceRight

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

Source

Since v2.0.0

replicate

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

Source

Since v2.0.0

replicateSTM

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

Source

Since v2.0.0

replicateSTMDiscard

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

Source

Since v2.0.0

succeed

Returns an STM effect that succeeds with the specified value.

Signature

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

Source

Since v2.0.0

succeedNone

Returns an effect with the empty value.

Signature

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

Source

Since v2.0.0

succeedSome

Returns an effect with the optional value.

Signature

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

Source

Since v2.0.0

suspend

Suspends creation of the specified transaction lazily.

Signature

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

Source

Since v2.0.0

sync

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

Signature

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

Source

Since v2.0.0

try

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

Signature

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

Source

Since v2.0.0

void

Returns an STM effect that succeeds with void.

Signature

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

Source

Since v2.0.0

context

mapInputContext

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

Signature

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

Source

Since v2.0.0

provideContext

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

Signature

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

Source

Since 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

declare const provideService: {
  <I, S>(tag: Context.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: Context.Tag<I, S>, resource: NoInfer<S>): STM<A, E, Exclude<R, I>>
}

Source

Since 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

declare const provideServiceSTM: {
  <I, S, E1, R1>(
    tag: Context.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: Context.Tag<I, S>,
    stm: STM<NoInfer<S>, E1, R1>
  ): STM<A, E1 | E, R1 | Exclude<R, I>>
}

Source

Since v2.0.0

provideSomeContext

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

Source

Since v2.0.0

destructors

commit

Commits this transaction atomically.

Signature

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

Source

Since v2.0.0

commitEither

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>

Source

Since v2.0.0

do notation

Do

Signature

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

Source

Since v2.0.0

bind

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 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: (_: NoInfer<K>) => STM<A, E2, R2>
  ): STM<MergeRecord<K, { [k in N]: A }>, E | E2, R | R2>
}

Source

Since v2.0.0

bindTo

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

Source

Since v2.0.0

let

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 N]: 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 N]: A }>, E, R>
}

Source

Since 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.

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 const firstSuccessOf: <A, E, R>(effects: Iterable<STM<A, E, R>>) => STM<A, E, R>

Source

Since v2.0.0

error handling

catchAll

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

Source

Since v2.0.0

catchSome

Recovers from some or all of the error cases.

Signature

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

Source

Since v2.0.0

catchTag

Recovers from the specified tagged error.

Signature

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

Source

Since v2.0.0

catchTags

Recovers from multiple tagged errors.

Signature

declare const catchTags: {
  <
    E extends { _tag: string },
    Cases extends { [K in E["_tag"]]+?: (error: Extract<E, { _tag: K }>) => STM<any, any, any> }
  >(
    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> }
  >(
    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]
  >
}

Source

Since 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

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

Source

Since 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

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

Source

Since v2.0.0

orElse

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

Source

Since 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

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

Source

Since v2.0.0

orElseFail

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

Source

Since 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

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

Source

Since v2.0.0

orElseSucceed

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

Source

Since 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

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

Source

Since v2.0.0

retry

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

Signature

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

Source

Since v2.0.0

filtering

filterOrDie

Dies with specified defect if the predicate fails.

Signature

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

Source

Since v2.0.0

filterOrDieMessage

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

Signature

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

Source

Since v2.0.0

filterOrElse

Supplies orElse if the predicate fails.

Signature

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

Source

Since v2.0.0

filterOrFail

Fails with the specified error if the predicate fails.

Signature

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

Source

Since 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

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

Source

Since v2.0.0

folding

match

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

Source

Since v2.0.0

matchSTM

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

Source

Since 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

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

Source

Since v2.0.0

isFailure

Returns whether this transactional effect is a failure.

Signature

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

Source

Since v2.0.0

isSuccess

Returns whether this transactional effect is a success.

Signature

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

Source

Since v2.0.0

some

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>

Source

Since v2.0.0

unsome

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>

Source

Since v2.0.0

mapping

as

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

Source

Since v2.0.0

asSome

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>

Source

Since v2.0.0

asSomeError

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>

Source

Since 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

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

Source

Since v2.0.0

map

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

Source

Since 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

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

Source

Since 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

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

Source

Since v2.0.0

mapError

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

Source

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

Source

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

Source

Since 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<A0, E0, R0> : never
}

Source

Since v2.0.0

STMUnifyIgnore (interface)

Signature

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

Source

Since v2.0.0

mutations

collect

Simultaneously filters and maps the value produced by this effect.

Signature

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

Source

Since v2.0.0

collectSTM

Simultaneously filters and maps the value produced by this effect.

Signature

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

Source

Since v2.0.0

either

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>

Source

Since v2.0.0

eventually

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>

Source

Since 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

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

Source

Since v2.0.0

flipWith

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

Source

Since v2.0.0

if

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

Signature

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

Source

Since v2.0.0

ignore

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>

Source

Since 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

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

Source

Since v2.0.0

negate

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>

Source

Since v2.0.0

none

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>

Source

Since v2.0.0

option

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>

Source

Since v2.0.0

refineOrDie

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

Signature

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

Source

Since 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

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

Source

Since v2.0.0

reject

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

Source

Since 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

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

Source

Since 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

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

Source

Since 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

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

Source

Since v2.0.0

retryUntil

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

Signature

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

Source

Since v2.0.0

retryWhile

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

Source

Since 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

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

Source

Since v2.0.0

unless

The moral equivalent of if (!p) exp

Signature

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

Source

Since v2.0.0

unlessSTM

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

Source

Since 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

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

Source

Since v2.0.0

validateFirst

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

Source

Since v2.0.0

when

The moral equivalent of if (p) exp.

Signature

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

Source

Since v2.0.0

whenSTM

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

Source

Since v2.0.0

refinements

isSTM

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

Signature

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

Source

Since 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

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

Source

Since v2.0.0

flatten

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>

Source

Since v2.0.0

tap

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

Source

Since v2.0.0

tapBoth

“Peeks” at both sides of an transactional effect.

Signature

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, E | E2 | E3, 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>
}

Source

Since v2.0.0

tapError

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

Source

Since v2.0.0

symbols

STMTypeId

Signature

declare const STMTypeId: unique symbol

Source

Since v2.0.0

STMTypeId (type alias)

Signature

type STMTypeId = typeof STMTypeId

Source

Since 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

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

Source

Since 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

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

Source

Since v2.0.0

type lambdas

STMTypeLambda (interface)

Signature

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

Source

Since v2.0.0

utils

All (namespace)

Source

Since v2.0.0

Signature (interface)

Signature

export interface Signature {
  <
    Arg extends ReadonlyArray<STMAny> | Iterable<STMAny> | Record<string, STMAny>,
    O extends NoExcessProperties<Options, O>
  >(
    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
}

Source

Since v2.0.0

Options (type alias)

Signature

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

Source

Since v2.0.0

STM (namespace)

Source

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

Source

Since v2.0.0

zipping

zip

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

Source

Since v2.0.0

zipLeft

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

Source

Since v2.0.0

zipRight

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

Source

Since v2.0.0

zipWith

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

Source

Since v2.0.0