<K, A>(self: TxHashMap<K, Option.Option<A>>): Effect.Effect<
TxHashMap<K, A>
>Removes all None values from a TxHashMap containing Option values.
Details
This function returns a new TxHashMap reference with only the Some values unwrapped. The original TxHashMap is not modified.
Example (Compacting optional values)
import { Effect, Option, TxHashMap } from "effect"
const program = Effect.gen(function*() {
// Create a map with optional user data
const userData = yield* TxHashMap.make<
string,
Option.Option<{ age: number; email?: string }>
>(
["alice", Option.some({ age: 30, email: "[email protected]" })],
["bob", Option.none()], // incomplete data
["charlie", Option.some({ age: 25 })],
["diana", Option.none()], // missing data
["eve", Option.some({ age: 28, email: "[email protected]" })]
)
// Remove all None values and unwrap Some values
const validUsers = yield* TxHashMap.compact(userData)
const size = yield* TxHashMap.size(validUsers)
console.log(size) // 3 (alice, charlie, eve)
const alice = yield* TxHashMap.get(validUsers, "alice")
console.log(alice) // Option.some({ age: 30, email: "[email protected]" })
const bob = yield* TxHashMap.get(validUsers, "bob")
console.log(bob) // Option.none() (removed from map)
// Useful for cleaning up optional data processing results
const userAges = yield* TxHashMap.map(validUsers, (user) => user.age)
const ageEntries = yield* TxHashMap.entries(userAges)
const sortedAgeEntries = ageEntries.toSorted(([left], [right]) => left.localeCompare(right))
console.log(sortedAgeEntries) // [["alice", 30], ["charlie", 25], ["eve", 28]]
})export const const compact: <K, A>(
self: TxHashMap<K, Option.Option<A>>
) => Effect.Effect<TxHashMap<K, A>>
Removes all None values from a TxHashMap containing Option values.
Details
This function returns a new TxHashMap reference with only the Some values
unwrapped. The original TxHashMap is not modified.
Example (Compacting optional values)
import { Effect, Option, TxHashMap } from "effect"
const program = Effect.gen(function*() {
// Create a map with optional user data
const userData = yield* TxHashMap.make<
string,
Option.Option<{ age: number; email?: string }>
>(
["alice", Option.some({ age: 30, email: "[email protected]" })],
["bob", Option.none()], // incomplete data
["charlie", Option.some({ age: 25 })],
["diana", Option.none()], // missing data
["eve", Option.some({ age: 28, email: "[email protected]" })]
)
// Remove all None values and unwrap Some values
const validUsers = yield* TxHashMap.compact(userData)
const size = yield* TxHashMap.size(validUsers)
console.log(size) // 3 (alice, charlie, eve)
const alice = yield* TxHashMap.get(validUsers, "alice")
console.log(alice) // Option.some({ age: 30, email: "[email protected]" })
const bob = yield* TxHashMap.get(validUsers, "bob")
console.log(bob) // Option.none() (removed from map)
// Useful for cleaning up optional data processing results
const userAges = yield* TxHashMap.map(validUsers, (user) => user.age)
const ageEntries = yield* TxHashMap.entries(userAges)
const sortedAgeEntries = ageEntries.toSorted(([left], [right]) => left.localeCompare(right))
console.log(sortedAgeEntries) // [["alice", 30], ["charlie", 25], ["eve", 28]]
})
compact = <function (type parameter) K in <K, A>(self: TxHashMap<K, Option.Option<A>>): Effect.Effect<TxHashMap<K, A>>K, function (type parameter) A in <K, A>(self: TxHashMap<K, Option.Option<A>>): Effect.Effect<TxHashMap<K, A>>A>(
self: TxHashMap<K, Option.Option<A>>(parameter) self: {
ref: TxRef.TxRef<HashMap.HashMap<K, V>>;
toString: () => string;
toJSON: () => unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
interface TxHashMap<in out K, in out V>A TxHashMap is a transactional hash map data structure that provides atomic operations
on key-value pairs within Effect transactions. It uses an immutable HashMap internally
with TxRef for transactional semantics, ensuring all operations are performed atomically.
Example (Using transactional hash maps)
import { Effect, TxHashMap } from "effect"
const program = Effect.gen(function*() {
// Create a transactional hash map
const txMap = yield* TxHashMap.make(["user1", "Alice"], ["user2", "Bob"])
// Single operations are automatically transactional
yield* TxHashMap.set(txMap, "user3", "Charlie")
const user = yield* TxHashMap.get(txMap, "user1")
console.log(user) // Option.some("Alice")
// Multi-step atomic operations
yield* Effect.tx(
Effect.gen(function*() {
const currentUser = yield* TxHashMap.get(txMap, "user1")
if (currentUser._tag === "Some") {
yield* TxHashMap.set(txMap, "user1", currentUser.value + "_updated")
yield* TxHashMap.remove(txMap, "user2")
}
})
)
const size = yield* TxHashMap.size(txMap)
console.log(size) // 2
})
The TxHashMap namespace contains type-level utilities and helper types
for working with TxHashMap instances.
Example (Reusing extracted TxHashMap types)
import { Effect, TxHashMap } from "effect"
const program = Effect.gen(function*() {
// Create a transactional inventory map
const inventory = yield* TxHashMap.make(
["laptop", { stock: 5, price: 999 }],
["mouse", { stock: 20, price: 29 }]
)
// Extract types for reuse
type ProductId = TxHashMap.TxHashMap.Key<typeof inventory> // string
type Product = TxHashMap.TxHashMap.Value<typeof inventory> // { stock: number, price: number }
type InventoryEntry = TxHashMap.TxHashMap.Entry<typeof inventory> // [string, Product]
// Use extracted types in functions
const updateStock = (id: ProductId, newStock: number) =>
TxHashMap.modify(
inventory,
id,
(product) => ({ ...product, stock: newStock })
)
yield* updateStock("laptop", 3)
})
TxHashMap<function (type parameter) K in <K, A>(self: TxHashMap<K, Option.Option<A>>): Effect.Effect<TxHashMap<K, A>>K, import OptionOption.type Option<A> = Option.None<A> | Option.Some<A>The Option data type represents optional values. An Option<A> is either
Some<A>, containing a value of type A, or None, representing absence.
When to use
Use to represent initial values that may not yet exist
- Returning from partial functions (not defined for all inputs)
- Managing optional fields in data structures
Namespace containing utility types for Option.
When to use
Use to access type-level helpers associated with Option.
Option<function (type parameter) A in <K, A>(self: TxHashMap<K, Option.Option<A>>): Effect.Effect<TxHashMap<K, A>>A>>
): import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<interface TxHashMap<in out K, in out V>A TxHashMap is a transactional hash map data structure that provides atomic operations
on key-value pairs within Effect transactions. It uses an immutable HashMap internally
with TxRef for transactional semantics, ensuring all operations are performed atomically.
Example (Using transactional hash maps)
import { Effect, TxHashMap } from "effect"
const program = Effect.gen(function*() {
// Create a transactional hash map
const txMap = yield* TxHashMap.make(["user1", "Alice"], ["user2", "Bob"])
// Single operations are automatically transactional
yield* TxHashMap.set(txMap, "user3", "Charlie")
const user = yield* TxHashMap.get(txMap, "user1")
console.log(user) // Option.some("Alice")
// Multi-step atomic operations
yield* Effect.tx(
Effect.gen(function*() {
const currentUser = yield* TxHashMap.get(txMap, "user1")
if (currentUser._tag === "Some") {
yield* TxHashMap.set(txMap, "user1", currentUser.value + "_updated")
yield* TxHashMap.remove(txMap, "user2")
}
})
)
const size = yield* TxHashMap.size(txMap)
console.log(size) // 2
})
The TxHashMap namespace contains type-level utilities and helper types
for working with TxHashMap instances.
Example (Reusing extracted TxHashMap types)
import { Effect, TxHashMap } from "effect"
const program = Effect.gen(function*() {
// Create a transactional inventory map
const inventory = yield* TxHashMap.make(
["laptop", { stock: 5, price: 999 }],
["mouse", { stock: 20, price: 29 }]
)
// Extract types for reuse
type ProductId = TxHashMap.TxHashMap.Key<typeof inventory> // string
type Product = TxHashMap.TxHashMap.Value<typeof inventory> // { stock: number, price: number }
type InventoryEntry = TxHashMap.TxHashMap.Entry<typeof inventory> // [string, Product]
// Use extracted types in functions
const updateStock = (id: ProductId, newStock: number) =>
TxHashMap.modify(
inventory,
id,
(product) => ({ ...product, stock: newStock })
)
yield* updateStock("laptop", 3)
})
TxHashMap<function (type parameter) K in <K, A>(self: TxHashMap<K, Option.Option<A>>): Effect.Effect<TxHashMap<K, A>>K, function (type parameter) A in <K, A>(self: TxHashMap<K, Option.Option<A>>): Effect.Effect<TxHashMap<K, A>>A>> =>
import EffectEffect.const gen: {
<Eff extends Effect<any, any, any>, AEff>(
f: () => Generator<Eff, AEff, never>
): Effect<
AEff,
[Eff] extends [never]
? never
: [Eff] extends [
Effect<infer _A, infer E, infer _R>
]
? E
: never,
[Eff] extends [never]
? never
: [Eff] extends [
Effect<infer _A, infer _E, infer R>
]
? R
: never
>
<Self, Eff extends Effect<any, any, any>, AEff>(
options: { readonly self: Self },
f: (this: Self) => Generator<Eff, AEff, never>
): Effect<
AEff,
[Eff] extends [never]
? never
: [Eff] extends [
Effect<infer _A, infer E, infer _R>
]
? E
: never,
[Eff] extends [never]
? never
: [Eff] extends [
Effect<infer _A, infer _E, infer R>
]
? R
: never
>
}
const currentMap: HashMap.HashMap<
K,
Option.Option<A>
>
const currentMap: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
import TxRefTxRef.const get: <A>(
self: TxRef<A>
) => Effect.Effect<A>
Reads the current value of the TxRef.
When to use
Use to read the current value of a TxRef.
Example (Reading transactional references)
import { Effect, TxRef } from "effect"
const program = Effect.gen(function*() {
const counter = yield* TxRef.make(42)
// Read the value within a transaction
const value = yield* Effect.tx(
TxRef.get(counter)
)
console.log(value) // 42
})
get(self: TxHashMap<K, Option.Option<A>>(parameter) self: {
ref: TxRef.TxRef<HashMap.HashMap<K, V>>;
toString: () => string;
toJSON: () => unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
TxHashMap<K, Option<A>>.ref: TxRef.TxRef<HashMap.HashMap<K, V>>(property) TxHashMap<K, Option<A>>.ref: {
version: number;
pending: Map<unknown, () => void>;
value: A;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
const compactedMap: HashMap.HashMap<K, A>const compactedMap: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
import HashMapHashMap.const compact: <K, A>(
self: HashMap<K, Option<A>>
) => HashMap<K, A>
Filters out None values from a HashMap of Optionss.
Example (Compacting Option values)
import { HashMap, Option } from "effect"
const map1 = HashMap.make(
["a", Option.some(1)],
["b", Option.none()],
["c", Option.some(3)]
)
const map2 = HashMap.compact(map1)
console.log(HashMap.size(map2)) // 2
console.log(HashMap.get(map2, "a")) // Option.some(1)
console.log(HashMap.has(map2, "b")) // false
compact(const currentMap: HashMap.HashMap<
K,
Option.Option<A>
>
const currentMap: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
const fromHashMap: <K, V>(
hashMap: HashMap.HashMap<K, V>
) => Effect.Effect<TxHashMap<K, V>>
Helper function to create a TxHashMap from an existing HashMap
fromHashMap(const compactedMap: HashMap.HashMap<K, A>const compactedMap: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
Pipeable.pipe<Effect.Effect<TxHashMap<K, A>, never, never>, Effect.Effect<TxHashMap<K, A>, never, never>>(this: Effect.Effect<TxHashMap<K, A>, never, never>, ab: (_: Effect.Effect<TxHashMap<K, A>, never, never>) => Effect.Effect<TxHashMap<K, A>, never, never>): Effect.Effect<TxHashMap<K, A>, never, never> (+21 overloads)pipe(import EffectEffect.const tx: <A, E, R>(
effect: Effect<A, E, R>
) => Effect<A, E, Exclude<R, Transaction>>
Defines a transaction boundary. Transactions are "all or nothing" with respect to changes
made to transactional values (i.e. TxRef) that occur within the transaction body.
Details
If called inside an active transaction, tx composes with the current transaction and reuses
its journal and retry state instead of creating a nested boundary.
Effect transactions are optimistic with retry. A transaction is retried when
its body explicitly calls Effect.txRetry and any accessed transactional
value changes, or when any accessed transactional value changes because a
different transaction commits before the current one.
The outermost tx call creates the transaction boundary and commits or rolls back the full
composed transaction.
Example (Running a transaction)
import { Effect, TxRef } from "effect"
const program = Effect.gen(function*() {
const ref1 = yield* TxRef.make(0)
const ref2 = yield* TxRef.make(0)
// Nested tx calls compose into the same transaction
yield* Effect.tx(Effect.gen(function*() {
yield* TxRef.set(ref1, 10)
yield* Effect.tx(TxRef.set(ref2, 20))
const sum = (yield* TxRef.get(ref1)) + (yield* TxRef.get(ref2))
console.log(`Transaction sum: ${sum}`)
}))
console.log(`Final ref1: ${yield* TxRef.get(ref1)}`) // 10
console.log(`Final ref2: ${yield* TxRef.get(ref2)}`) // 20
})
tx)