Skip to content
Effect Days 2026 Get your ticket

TxChunk

Stores a Chunk inside transactional state.

A TxChunk<A> keeps its current Chunk<A> in a TxRef, so reads and updates can be committed atomically with other transactional operations. This module offers a transactional version of common chunk workflows, including creating collections, reading or replacing the current chunk, adding or removing values, checking size, slicing, mapping, filtering, and combining chunks.

22 exports Added in v4.0.0 Source

Combinators

append

Added in v4.0.0 Source

Appends an element to the end of the TxChunk.

Details

This function mutates the original TxChunk by adding the element to the end. It does not return a new TxChunk reference.

Signature

declare const append: {
  <A>(element: A): (self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, element: A): Effect<void>;
}

Example

(Appending an element)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3])


  // Add element to the end atomically
  yield* TxChunk.append(txChunk, 4)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [1, 2, 3, 4]

appendAll

Added in v4.0.0 Source

Concatenates another chunk to the end of the TxChunk.

Details

This function mutates the original TxChunk by appending all elements from the other chunk. It does not return a new TxChunk reference.

Signature

declare const appendAll: {
  <A>(other: Chunk<A>): (self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, other: Chunk<A>): Effect<void>;
}

Example

(Appending another chunk)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3])
  const otherChunk = Chunk.fromIterable([4, 5, 6])


  // Append all elements from another chunk atomically
  yield* TxChunk.appendAll(txChunk, otherChunk)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [1, 2, 3, 4, 5, 6]

concat

Added in v4.0.0 Source

Concatenates another TxChunk to the end of this TxChunk.

Details

This function mutates the original TxChunk by appending all elements from the other TxChunk. It does not return a new TxChunk reference.

Signature

declare const concat: {
  <A>(other: TxChunk<A>): (self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, other: TxChunk<A>): Effect<void>;
}

Example

(Concatenating TxChunks)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk1 = yield* TxChunk.fromIterable([1, 2, 3])
  const txChunk2 = yield* TxChunk.fromIterable([4, 5, 6])


  // Concatenate atomically within a transaction
  yield* TxChunk.concat(txChunk1, txChunk2)


  const result = yield* TxChunk.get(txChunk1)


  // Original txChunk2 is unchanged
  const original = yield* TxChunk.get(txChunk2)
  return [Chunk.toArray(result), Chunk.toArray(original)]
})


await Effect.runPromise(program) // => [[1, 2, 3, 4, 5, 6], [4, 5, 6]]

drop

Added in v4.0.0 Source

Drops the first n elements from the TxChunk.

Details

This function mutates the original TxChunk by removing the first n elements. It does not return a new TxChunk reference.

Signature

declare const drop: {
  (n: number): <A>(self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, n: number): Effect<void>;
}

Example

(Dropping leading elements)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5])


  // Drop the first 2 elements - automatically transactional
  yield* TxChunk.drop(txChunk, 2)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [3, 4, 5]

filter

Added in v4.0.0 Source

Filters the TxChunk keeping only elements that satisfy the predicate.

Details

This function mutates the original TxChunk by removing elements that don't match the predicate. It does not return a new TxChunk reference.

Signature

declare const filter: {
  <A, B>(refinement: (a: A) => a is B): (self: TxChunk<A>) => Effect<void>;
  <A>(predicate: (a: A) => boolean): (self: TxChunk<A>) => Effect<void>;
  <A, B>(self: TxChunk<A>, refinement: (a: A) => a is B): Effect<void>;
  <A>(self: TxChunk<A>, predicate: (a: A) => boolean): Effect<void>;
}

Example

(Filtering elements)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5, 6])


  // Keep only even numbers atomically
  yield* TxChunk.filter(txChunk, (n) => n % 2 === 0)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [2, 4, 6]

get

Added in v4.0.0 Source

Reads the current chunk from the TxChunk.

Signature

declare function get<A>(self: TxChunk<A>): Effect<Chunk<A>>

Example

(Reading the current chunk)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3])


  // Read the current value within a transaction
  const chunk = yield* TxChunk.get(txChunk)
  return [Chunk.toArray(chunk), Chunk.size(chunk)]
})


await Effect.runPromise(program) // => [[1, 2, 3], 3]

map

Added in v4.0.0 Source

Maps each element of the TxChunk using a function that returns the same element type.

Details

This function mutates the original TxChunk by transforming each element in place. It does not return a new TxChunk reference.

Signature

declare const map: {
  <A>(f: (a: NoInfer<A>) => A): (self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, f: (a: A) => A): Effect<void>;
}

Example

(Mapping elements)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4])


  // Transform each element atomically (must maintain same type)
  yield* TxChunk.map(txChunk, (n) => n * 2)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [2, 4, 6, 8]

modify

Added in v4.0.0 Source

Modifies the value of the TxChunk using the provided function.

Details

This function mutates the original TxChunk by updating its internal state. It does not return a new TxChunk reference.

Signature

declare const modify: {
  <A, R>(f: (current: Chunk<NoInfer<A>>) => [returnValue: R, newValue: Chunk<A>]): (self: TxChunk<A>) => Effect<R>;
  <A, R>(self: TxChunk<A>, f: (current: Chunk<A>) => [returnValue: R, newValue: Chunk<A>]): Effect<R>;
}

Example

(Modifying while returning a value)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3])


  // Modify and return both old size and new chunk
  const oldSize = yield* TxChunk.modify(txChunk, (chunk) => [
    Chunk.size(chunk), // return value (old size)
    Chunk.append(chunk, 4) // new value
  ])


  const newChunk = yield* TxChunk.get(txChunk)
  return [oldSize, Chunk.toArray(newChunk)]
})


await Effect.runPromise(program) // => [3, [1, 2, 3, 4]]

prepend

Added in v4.0.0 Source

Prepends an element to the beginning of the TxChunk.

Details

This function mutates the original TxChunk by adding the element to the beginning. It does not return a new TxChunk reference.

Signature

declare const prepend: {
  <A>(element: A): (self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, element: A): Effect<void>;
}

Example

(Prepending an element)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([2, 3, 4])


  // Add element to the beginning atomically
  yield* TxChunk.prepend(txChunk, 1)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [1, 2, 3, 4]

prependAll

Added in v4.0.0 Source

Concatenates another chunk to the beginning of the TxChunk.

Details

This function mutates the original TxChunk by prepending all elements from the other chunk. It does not return a new TxChunk reference.

Signature

declare const prependAll: {
  <A>(other: Chunk<A>): (self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, other: Chunk<A>): Effect<void>;
}

Example

(Prepending another chunk)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([4, 5, 6])
  const otherChunk = Chunk.fromIterable([1, 2, 3])


  // Prepend all elements from another chunk atomically
  yield* TxChunk.prependAll(txChunk, otherChunk)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [1, 2, 3, 4, 5, 6]

set

Added in v4.0.0 Source

Sets the value of the TxChunk.

Details

This function mutates the original TxChunk by replacing its internal state with the provided chunk. It does not return a new TxChunk reference.

Signature

declare const set: {
  <A>(chunk: Chunk<A>): (self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, chunk: Chunk<A>): Effect<void>;
}

Example

(Replacing the stored chunk)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3])


  // Replace the entire chunk content
  const newChunk = Chunk.fromIterable([10, 20, 30, 40])
  yield* TxChunk.set(txChunk, newChunk)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [10, 20, 30, 40]

size

Added in v4.0.0 Source

Gets the size of the TxChunk.

Signature

declare function size<A>(self: TxChunk<A>): Effect<number>

Example

(Getting the size)

import { Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5])


  // Get the current size - automatically transactional
  const currentSize = yield* TxChunk.size(txChunk)


  // Size is tracked for conflict detection
  yield* TxChunk.append(txChunk, 6)
  const newSize = yield* TxChunk.size(txChunk)
  return [currentSize, newSize]
})


await Effect.runPromise(program) // => [5, 6]

slice

Added in v4.0.0 Source

Takes a slice of the TxChunk from start to end (exclusive).

Details

This function mutates the original TxChunk by keeping only the elements in the specified range. It does not return a new TxChunk reference.

Signature

declare const slice: {
  (start: number, end: number): <A>(self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, start: number, end: number): Effect<void>;
}

Example

(Taking a slice)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5, 6, 7])


  // Take elements from index 2 to 5 (exclusive) - automatically transactional
  yield* TxChunk.slice(txChunk, 2, 5)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [3, 4, 5]

take

Added in v4.0.0 Source

Takes the first n elements from the TxChunk.

Details

This function mutates the original TxChunk by keeping only the first n elements. It does not return a new TxChunk reference.

Signature

declare const take: {
  (n: number): <A>(self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, n: number): Effect<void>;
}

Example

(Taking leading elements)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5])


  // Take only the first 3 elements - automatically transactional
  yield* TxChunk.take(txChunk, 3)


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [1, 2, 3]

update

Added in v4.0.0 Source

Updates the value of the TxChunk using the provided function.

Details

This function mutates the original TxChunk by updating its internal state. It does not return a new TxChunk reference.

Signature

declare const update: {
  <A>(f: (current: Chunk<NoInfer<A>>) => Chunk<A>): (self: TxChunk<A>) => Effect<void>;
  <A>(self: TxChunk<A>, f: (current: Chunk<A>) => Chunk<A>): Effect<void>;
}

Example

(Updating the stored chunk)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3])


  // Update the chunk by reversing it atomically
  yield* TxChunk.update(txChunk, (chunk) => Chunk.reverse(chunk))


  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [3, 2, 1]

Constructors

empty

Added in v4.0.0 Source

Creates a new empty TxChunk.

Details

This function returns a new TxChunk reference that is initially empty. No existing TxChunk instances are modified.

Signature

declare function empty<A = never>(): Effect<TxChunk<A>>

Example

(Creating an empty TxChunk)

import { Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  // Create an empty TxChunk
  const txChunk = yield* TxChunk.empty<number>()


  // Check if it's empty - automatically transactional
  const isEmpty = yield* TxChunk.isEmpty(txChunk)


  // Add elements - automatically transactional
  yield* TxChunk.append(txChunk, 42)


  const isStillEmpty = yield* TxChunk.isEmpty(txChunk)
  return [isEmpty, isStillEmpty]
})


await Effect.runPromise(program) // => [true, false]

fromIterable

Added in v4.0.0 Source

Creates a new TxChunk from an iterable.

Details

This function returns a new TxChunk reference containing elements from the provided iterable. No existing TxChunk instances are modified.

Signature

declare function fromIterable<A>(iterable: Iterable<A>): Effect<TxChunk<A>>

Example

(Creating from an iterable)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  // Create TxChunk from array
  const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5])


  // Read the contents - automatically transactional
  const chunk = yield* TxChunk.get(txChunk)


  // Multi-step atomic modification - use explicit transaction
  yield* Effect.tx(
    Effect.gen(function*() {
      yield* TxChunk.append(txChunk, 6)
      yield* TxChunk.prepend(txChunk, 0)
    })
  )


  const updated = yield* TxChunk.get(txChunk)
  return [Chunk.toArray(chunk), Chunk.toArray(updated)]
})


await Effect.runPromise(program) // => [[1, 2, 3, 4, 5], [0, 1, 2, 3, 4, 5, 6]]

make

Added in v4.0.0 Source

Creates a new TxChunk with the specified initial chunk.

Details

This function returns a new TxChunk reference containing the provided initial chunk. No existing TxChunk instances are modified.

Signature

declare function make<A>(initial: Chunk<A>): Effect<TxChunk<A>>

Example

(Creating a TxChunk from a chunk)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  // Create a TxChunk with initial values
  const initialChunk = Chunk.fromIterable([1, 2, 3])
  const txChunk = yield* TxChunk.make(initialChunk)


  // Read the value - automatically transactional
  const result = yield* TxChunk.get(txChunk)
  return Chunk.toArray(result)
})


await Effect.runPromise(program) // => [1, 2, 3]

makeUnsafe

Added in v4.0.0 Source

Creates a new TxChunk with the specified TxRef.

Details

This function returns a new TxChunk reference wrapping the provided TxRef. No existing TxChunk instances are modified.

Signature

declare function makeUnsafe<A>(ref: TxRef<Chunk<A>>): TxChunk<A>

Example

(Wrapping an existing TxRef)

import { Chunk, Effect, TxChunk, TxRef } from "effect"


// Create a TxChunk from an existing TxRef (advanced usage)
const ref = TxRef.makeUnsafe(Chunk.fromIterable([1, 2, 3]))
const txChunk = TxChunk.makeUnsafe(ref)
Chunk.toArray(await Effect.runPromise(TxChunk.get(txChunk))) // => [1, 2, 3]

Models

TxChunk interface

Added in v4.0.0 Source

TxChunk is a transactional chunk data structure that provides Software Transactional Memory (STM) semantics for chunk operations.

Details

Accessed values are tracked by the transaction in order to detect conflicts and to track changes. A transaction will retry whenever a conflict is detected or whenever the transaction explicitly calls Effect.txRetry and any of the accessed TxChunk values change.

Signature

interface TxChunk<in out A> extends Inspectable, Pipeable {
  readonly "~effect/transactions/TxChunk": "~effect/transactions/TxChunk";
  readonly ref: TxRef<Chunk<A>>;
}

Example

(Using a transactional chunk)

import { Chunk, Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  // Create a transactional chunk
  const txChunk: TxChunk.TxChunk<number> = yield* TxChunk.fromIterable([
    1,
    2,
    3
  ])


  // Single operations - no explicit transaction needed
  yield* TxChunk.append(txChunk, 4)
  const result = yield* TxChunk.get(txChunk)


  // Multi-step atomic operation - use explicit transaction
  yield* Effect.tx(
    Effect.gen(function*() {
      yield* TxChunk.prepend(txChunk, 0)
      yield* TxChunk.append(txChunk, 5)
    })
  )


  const finalResult = yield* TxChunk.get(txChunk)
  return [Chunk.toArray(result), Chunk.toArray(finalResult)]
})


await Effect.runPromise(program) // => [[1, 2, 3, 4], [0, 1, 2, 3, 4, 5]]

Predicates

isEmpty

Added in v4.0.0 Source

Checks whether the TxChunk is empty.

Signature

declare function isEmpty<A>(self: TxChunk<A>): Effect<boolean>

Example

(Checking for an empty chunk)

import { Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const emptyChunk = yield* TxChunk.empty<number>()
  const nonEmptyChunk = yield* TxChunk.fromIterable([1, 2, 3])


  // Check if chunks are empty - automatically transactional
  const isEmpty1 = yield* TxChunk.isEmpty(emptyChunk)
  const isEmpty2 = yield* TxChunk.isEmpty(nonEmptyChunk)


  return [isEmpty1, isEmpty2]
})


await Effect.runPromise(program) // => [true, false]

isNonEmpty

Added in v4.0.0 Source

Checks whether the TxChunk is non-empty.

Signature

declare function isNonEmpty<A>(self: TxChunk<A>): Effect<boolean>

Example

(Checking for a non-empty chunk)

import { Effect, TxChunk } from "effect"


const program = Effect.gen(function*() {
  const emptyChunk = yield* TxChunk.empty<number>()
  const nonEmptyChunk = yield* TxChunk.fromIterable([1, 2, 3])


  // Check if chunks are non-empty - automatically transactional
  const isNonEmpty1 = yield* TxChunk.isNonEmpty(emptyChunk)
  const isNonEmpty2 = yield* TxChunk.isNonEmpty(nonEmptyChunk)


  return [isNonEmpty1, isNonEmpty2]
})


await Effect.runPromise(program) // => [false, true]