Chunk

A Chunk<A> represents an ordered, immutable collection of values of type A. While similar to an array, Chunk provides a functional interface, optimizing certain operations that can be costly with regular arrays, like repeated concatenation.

Why Use Chunk?

• Immutability: Unlike standard JavaScript arrays, which are mutable, Chunk provides a truly immutable collection, preventing data from being modified after creation. This is especially useful in concurrent programming contexts where immutability can enhance data consistency.

• High Performance: Chunk supports specialized operations for efficient array manipulation, such as appending single elements or concatenating chunks, making these operations faster than their regular JavaScript array equivalents.

Creating a Chunk

empty

Create an empty Chunk with Chunk.empty.

Example (Creating an Empty Chunk)

1
import { Chunk } from "effect"
2

3
//      ┌─── Chunk<number>
4
//      ▼
5
const chunk = Chunk.empty<number>()

make

To create a Chunk with specific values, use Chunk.make(...values). Note that the resulting chunk is typed as non-empty.

Example (Creating a Non-Empty Chunk)

1
import { Chunk } from "effect"
2

3
//      ┌─── NonEmptyChunk<number>
4
//      ▼
5
const chunk = Chunk.make(1, 2, 3)

fromIterable

You can create a Chunk by providing a collection, either from an iterable or directly from an array.

Example (Creating a Chunk from an Iterable)

1
import { Chunk, List } from "effect"
2

3
const fromArray = Chunk.fromIterable([1, 2, 3])
4

5
const fromList = Chunk.fromIterable(List.make(1, 2, 3))

unsafeFromArray

Chunk.unsafeFromArray creates a Chunk directly from an array without cloning. This approach can improve performance by avoiding the overhead of copying data but requires caution, as it bypasses the usual immutability guarantees.

Example (Directly Creating a Chunk from an Array)

1
import { Chunk } from "effect"
2

3
const chunk = Chunk.unsafeFromArray([1, 2, 3])

Concatenating

To combine two Chunk instances into one, use Chunk.appendAll.

Example (Combining Two Chunks into One)

1
import { Chunk } from "effect"
2

3
// Concatenate two chunks with different types of elements
4
//
5
//      ┌─── NonEmptyChunk<string | number>
6
//      ▼
7
const chunk = Chunk.appendAll(Chunk.make(1, 2), Chunk.make("a", "b"))
8

9
console.log(chunk)
10
/*
11
Output:
12
{ _id: 'Chunk', values: [ 1, 2, 'a', 'b' ] }
13
*/

Dropping

To remove elements from the beginning of a Chunk, use Chunk.drop, specifying the number of elements to discard.

Example (Dropping Elements from the Start)

1
import { Chunk } from "effect"
2

3
// Drops the first 2 elements from the Chunk
4
const chunk = Chunk.drop(Chunk.make(1, 2, 3, 4), 2)

Comparing

To check if two Chunk instances are equal, use Equal.equals. This function compares the contents of each Chunk for structural equality.

Example (Comparing Two Chunks)

1
import { Chunk, Equal } from "effect"
2

3
const chunk1 = Chunk.make(1, 2)
4
const chunk2 = Chunk.make(1, 2, 3)
5

6
console.log(Equal.equals(chunk1, chunk1))
7
// Output: true
8

9
console.log(Equal.equals(chunk1, chunk2))
10
// Output: false
11

12
console.log(Equal.equals(chunk1, Chunk.make(1, 2)))
13
// Output: true

Converting

Convert a Chunk to a ReadonlyArray using Chunk.toReadonlyArray. The resulting type varies based on the Chunk’s contents, distinguishing between empty, non-empty, and generic chunks.

Example (Converting a Chunk to a ReadonlyArray)

1
import { Chunk } from "effect"
2

3
//      ┌─── readonly [number, ...number[]]
4
//      ▼
5
const nonEmptyArray = Chunk.toReadonlyArray(Chunk.make(1, 2, 3))
6

7
//      ┌─── readonly never[]
8
//      ▼
9
const emptyArray = Chunk.toReadonlyArray(Chunk.empty())
10

11
declare const chunk: Chunk.Chunk<number>
12

13
//      ┌─── readonly number[]
14
//      ▼
15
const array = Chunk.toReadonlyArray(chunk)