Chunk

A Chunk<A> represents a chunk of values of type A. Chunks are usually backed by arrays, but expose a purely functional, safe interface to the underlying elements, and they become lazy on operations that would be costly with arrays, such as repeated concatenation. Like lists and arrays, Chunk is an ordered collection.

Use Chunk Only for Repeated Concatenation

Chunk is purpose-built to amoritize the cost of repeated concatenation of arrays. Therefore, for use-cases that do not involve repeated concatenation of arrays, the overhead of Chunk will result in reduced performance.

Why Chunk?

Let’s explore the reasons behind using Chunk:

• Immutability: In JavaScript, there is no built-in immutable data type that can efficiently represent an array. While the Array type exists, it provides a mutable interface, which means it can be modified after creation. Chunk, on the other hand, is an immutable array-like data structure that ensures the data remains unchanged. Immutability is beneficial in various scenarios, especially when dealing with concurrent programming.

• High Performance: Chunk not only offers immutability but also delivers high performance. It provides specialized operations for common array manipulations, such as appending a single element or concatenating two chunks together. These specialized operations are significantly faster than performing the same operations on regular JavaScript arrays.

Creating

empty

To create an empty Chunk, you can use the following code:

import { Chunk } from "effect"

const emptyChunk = Chunk.empty()

make

If you want to create a Chunk with specific values, you can use the Chunk.make(...values) function:

import { Chunk } from "effect"

const nonEmptyChunk = Chunk.make(1, 2, 3)

fromIterable / unsafeFromArray

You can create a Chunk by providing a collection of values.

Creating a chunk from a generic Iterable:

import { Chunk, List } from "effect"

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

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

Chunk.fromIterable makes a chunk by cloning the iterable, which can be an expensive process for large iterables or when making many chunks.

Creating a chunk from an Array:

import { Chunk } from "effect"

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

Chunk.unsafeFromArray doesn’t do any cloning which can have performance benefits, but this breaks the assumption that chunk is immutable.

Potential Risks

It is important to note that using Chunk.unsafeFromArray can potentially lead to unsafe or unexpected behavior if the input array is mutated after conversion. If you want to ensure safety, it is recommended to use fromIterable.

Concatenating

You can concatenate two Chunks using the appendAll function:

import { Chunk } from "effect"

const concatenatedChunk = Chunk.appendAll(
  Chunk.make(1, 2),
  Chunk.make("a", "b")
)

console.log(concatenatedChunk)
/*
Output:
{
  _id: "Chunk",
  values: [ 1, 2, "a", "b" ]
}
*/

Dropping

To drop elements from the beginning of a Chunk, you can use the drop function:

import { Chunk } from "effect"

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

Comparing

You can compare two Chunks for equality using the Equal.equals function:

import { Chunk, Equal } from "effect"

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

const areEqual = Equal.equals(chunk1, chunk2)

Converting

To convert a Chunk to a ReadonlyArray, you can use the toReadonlyArray function:

import { Chunk } from "effect"

const readonlyArray = Chunk.toReadonlyArray(Chunk.make(1, 2, 3))