STM overview
Added in v2.0.0
Table of contents
- constructors
- acquireUseRelease
- all
- attempt
- check
- cond
- context
- contextWith
- contextWithSTM
- die
- dieMessage
- dieSync
- every
- exists
- fail
- failSync
- fiberId
- filter
- filterNot
- fromEither
- fromOption
- gen
- interrupt
- interruptAs
- iterate
- loop
- mergeAll
- reduce
- reduceAll
- reduceRight
- replicate
- replicateSTM
- replicateSTMDiscard
- succeed
- succeedNone
- succeedSome
- suspend
- sync
- try
- void
- context
- destructors
- do notation
- elements
- error handling
- filtering
- finalization
- folding
- getters
- mapping
- models
- mutations
- refinements
- sequencing
- symbols
- traversing
- type lambdas
- utils
- zipping
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>
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>
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>
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>
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<Array<A>, E, R>
<A, R, E>(iterable: Iterable<A>, predicate: (a: A) => STM<boolean, E, R>): STM<Array<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<Array<A>, E, R>
<A, R, E>(iterable: Iterable<A>, predicate: (a: A) => STM<boolean, E, R>): STM<Array<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>
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>>
Added in v2.0.0
gen
Signature
export 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
>
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<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>
}
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>) => Array<STM<A, E, R>>
<A, E, R>(self: STM<A, E, R>, n: number): Array<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<Array<A>, E, R>
<A, E, R>(self: STM<A, E, R>, n: number): STM<Array<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>
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>>
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>
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>; <A>(try_: LazyArg<A>): STM<A, unknown>; }
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>
<A, E, R>(self: STM<A, E, R>, env: Context.Context<R>): STM<A, E>
}
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: (_: 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>
}
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: (_: 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>
}
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> }
>(
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]
>
}
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
head
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<E | A, 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<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>
}
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, Array<E>, R>
<A, B, E, R>(elements: Iterable<A>, f: (a: A) => STM<B, E, R>): STM<B, Array<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, 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>
}
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<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>
}
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: 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>
}
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