TxChunk unstable

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.

23 exports Since v4.0.0 Source

Combinators

append

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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]

Guards

isTxChunk

unstable

Since v4.0.0

Checks whether u is a TxChunk<unknown>.

Signature

declare function isTxChunk(u: unknown): u is TxChunk<unknown>

Example Checking for transactional chunks

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

const txChunk = TxChunk.makeUnsafe(TxRef.makeUnsafe(Chunk.empty<number>()))

TxChunk.isTxChunk(txChunk) // => true
TxChunk.isTxChunk(Chunk.empty()) // => false

Models

TxChunk

interface unstable

Since v4.0.0

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/TxChunk": "~effect/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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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]