Chunk
Stores many values in an immutable ordered collection.
A Chunk<A> is useful when you need to build or transform collections without changing the original collection. It is designed for efficient append, prepend, and concatenation. This module includes helpers for creating, reading, slicing, mapping, filtering, sorting, zipping, combining, and converting chunks to and from arrays and iterables.
Combinators
Combining
Appends the specified element to the end of the Chunk.
When to use
Use to add one element after the existing chunk elements and return a NonEmptyChunk.
See
Signature
declare const append: {
<A2>(a: A2): <A>(self: Chunk<A>) => NonEmptyChunk<A2 | A>;
<A, A2>(self: Chunk<A>, a: A2): NonEmptyChunk<A | A2>;
};Concatenates two chunks, combining their elements. If either chunk is non-empty, the result is also a non-empty chunk.
When to use
Use to concatenate two chunks when the second chunk's elements should come after the first.
See
prependAllfor concatenating chunks in the opposite orderappendfor adding a single element to the end
Signature
declare const appendAll: {
<S extends Chunk<any>, T extends Chunk<any>>(
that: T,
): (self: S) => OrNonEmpty<S, T, Infer<S> | Infer<T>>;
<A, B>(self: Chunk<A>, that: NonEmptyChunk<B>): NonEmptyChunk<A | B>;
<A, B>(self: NonEmptyChunk<A>, that: Chunk<B>): NonEmptyChunk<A | B>;
<A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<A | B>;
};Prepends an element to the front of a Chunk, creating a new NonEmptyChunk.
Signature
declare const prepend: {
<B>(elem: B): <A>(self: Chunk<A>) => NonEmptyChunk<B | A>;
<A, B>(self: Chunk<A>, elem: B): NonEmptyChunk<A | B>;
};prependAll
Prepends the specified prefix chunk to the beginning of the specified chunk. If either chunk is non-empty, the result is also a non-empty chunk.
Signature
declare const prependAll: {
<S extends Chunk<any>, T extends Chunk<any>>(
that: T,
): (self: S) => OrNonEmpty<S, T, Infer<S> | Infer<T>>;
<A, B>(self: Chunk<A>, that: NonEmptyChunk<B>): NonEmptyChunk<A | B>;
<A, B>(self: NonEmptyChunk<A>, that: Chunk<B>): NonEmptyChunk<A | B>;
<A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<A | B>;
};Constructors
Creates an empty Chunk.
Signature
declare const empty: <A = never>() => Chunk<A>;fromIterable
Creates a new Chunk from an iterable collection of values.
Signature
declare function fromIterable<A>(self: Iterable<A>): Chunk<A>;Builds a NonEmptyChunk from an non-empty collection of elements.
Signature
declare function make<As extends readonly [any, any]>(...as: As): NonEmptyChunk<As[number]>;Returns a non-empty Chunk of length n with element i initialized by f(i).
Details
n is normalized to an integer greater than or equal to 1.
Signature
declare const makeBy: {
<A>(f: (i: number) => A): (n: number) => NonEmptyChunk<A>;
<A>(n: number, f: (i: number) => A): NonEmptyChunk<A>;
};Builds a NonEmptyChunk from a single element.
Signature
declare function of<A>(a: A): NonEmptyChunk<A>;Creates a non-empty Chunk of consecutive integers from start through end, inclusive.
Details
If start is greater than end, returns a single-element chunk containing start.
Signature
declare function range(start: number, end: number): NonEmptyChunk<number>;Converting
Converts a Chunk into an Array. If the provided Chunk is non-empty (NonEmptyChunk), the function will return a NonEmptyArray, ensuring the non-empty property is preserved.
Signature
declare const toArray: <S extends Chunk<any>>(
self: S,
) => S extends NonEmptyChunk<any> ? RA.NonEmptyArray<Chunk.Infer<S>> : Array<Chunk.Infer<S>>;toReadonlyArray
Converts a Chunk into a ReadonlyArray. If the provided Chunk is non-empty (NonEmptyChunk), the function will return a NonEmptyReadonlyArray, ensuring the non-empty property is preserved.
Signature
declare const toReadonlyArray: <S extends Chunk<any>>(
self: S,
) => S extends NonEmptyChunk<any>
? RA.NonEmptyReadonlyArray<Chunk.Infer<S>>
: ReadonlyArray<Chunk.Infer<S>>;Deduplication
Filtering
Filters out optional values
Signature
declare function compact<A>(self: Chunk<Option<A>>): Chunk<A>;dedupeAdjacent
Deduplicates adjacent elements that are identical.
Signature
declare function dedupeAdjacent<A>(self: Chunk<A>): Chunk<A>;difference
Creates a Chunk of values not included in the other given Chunk. The order and references of result values are determined by the first Chunk.
Signature
declare const difference: {
<A>(that: Chunk<A>): (self: Chunk<A>) => Chunk<A>;
<A>(self: Chunk<A>, that: Chunk<A>): Chunk<A>;
};differenceWith
Creates a Chunk of values not included in the other given Chunk using the provided isEquivalent function. The order and references of result values are determined by the first Chunk.
Signature
declare function differenceWith<A>(isEquivalent: (self: A, that: A) => boolean): {
(that: Chunk<A>): (self: Chunk<A>) => Chunk<A>;
(self: Chunk<A>, that: Chunk<A>): Chunk<A>;
};Drops the first up to n elements from the chunk.
Signature
declare const drop: {
(n: number): <A>(self: Chunk<A>) => Chunk<A>;
<A>(self: Chunk<A>, n: number): Chunk<A>;
};Drops the last n elements.
Signature
declare const dropRight: {
(n: number): <A>(self: Chunk<A>) => Chunk<A>;
<A>(self: Chunk<A>, n: number): Chunk<A>;
};Drops all elements so long as the predicate returns true.
Signature
declare const dropWhile: {
<A>(predicate: Predicate<NoInfer<A>>): (self: Chunk<A>) => Chunk<A>;
<A>(self: Chunk<A>, predicate: Predicate<A>): Chunk<A>;
};Returns a filtered subset of the elements.
Signature
declare const filter: {
<A, B>(refinement: Refinement<NoInfer<A>, B>): (self: Chunk<A>) => Chunk<B>;
<A>(predicate: Predicate<NoInfer<A>>): (self: Chunk<A>) => Chunk<A>;
<A, B>(self: Chunk<A>, refinement: Refinement<A, B>): Chunk<B>;
<A>(self: Chunk<A>, predicate: Predicate<A>): Chunk<A>;
};Returns a filtered and mapped subset of the elements.
Signature
declare const filterMap: {
<A, B, X>(f: (input: A, i: number) => Result<B, X>): (self: Chunk<A>) => Chunk<B>;
<A, B, X>(self: Chunk<A>, f: (input: A, i: number) => Result<B, X>): Chunk<B>;
};filterMapWhile
Transforms all elements of the chunk for as long as the specified function succeeds.
Signature
declare const filterMapWhile: {
<A, B, X>(f: Filter<A, B, X>): (self: Chunk<A>) => Chunk<B>;
<A, B, X>(self: Chunk<A>, f: Filter<A, B, X>): Chunk<B>;
};Splits a chunk using a Filter into failures and successes.
Details
Returns [excluded, satisfying]. The filter receives (element, index).
Signature
declare const partition: {
<A, Pass, Fail>(
f: (input: NoInfer<A>, i: number) => Result<Pass, Fail>,
): (self: Chunk<A>) => [excluded: Chunk<Fail>, satisfying: Chunk<Pass>];
<A, Pass, Fail>(
self: Chunk<A>,
f: (input: A, i: number) => Result<Pass, Fail>,
): [excluded: Chunk<Fail>, satisfying: Chunk<Pass>];
};Separates a chunk of Result values into a chunk of failures and a chunk of successes.
Details
The returned tuple is [failures, successes], preserving the original order within each side.
Signature
declare function separate<A, B>(self: Chunk<Result<B, A>>): [Chunk<A>, Chunk<B>];Takes the first up to n elements from the chunk.
Signature
declare const take: {
(n: number): <A>(self: Chunk<A>) => Chunk<A>;
<A>(self: Chunk<A>, n: number): Chunk<A>;
};Takes the last n elements.
Signature
declare const takeRight: {
(n: number): <A>(self: Chunk<A>) => Chunk<A>;
<A>(self: Chunk<A>, n: number): Chunk<A>;
};Takes all elements so long as the predicate returns true.
Signature
declare const takeWhile: {
<A, B>(refinement: Refinement<NoInfer<A>, B>): (self: Chunk<A>) => Chunk<B>;
<A>(predicate: Predicate<NoInfer<A>>): (self: Chunk<A>) => Chunk<A>;
<A, B>(self: Chunk<A>, refinement: Refinement<A, B>): Chunk<B>;
<A>(self: Chunk<A>, predicate: Predicate<A>): Chunk<A>;
};Folding
Joins the elements together with "sep" in the middle.
Signature
declare const join: {
(sep: string): (self: Chunk<string>) => string;
(self: Chunk<string>, sep: string): string;
};Maps over the chunk statefully, producing new elements of type B.
Signature
declare const mapAccum: {
<S, A, B>(s: S, f: (s: S, a: A) => readonly [S, B]): (self: Chunk<A>) => [S, Chunk<B>];
<S, A, B>(self: Chunk<A>, s: S, f: (s: S, a: A) => readonly [S, B]): [S, Chunk<B>];
};Reduces the elements of a chunk from left to right.
Signature
declare const reduce: {
<B, A>(b: B, f: (b: B, a: A, i: number) => B): (self: Chunk<A>) => B;
<A, B>(self: Chunk<A>, b: B, f: (b: B, a: A, i: number) => B): B;
};reduceRight
Reduces the elements of a chunk from right to left.
Signature
declare const reduceRight: {
<B, A>(b: B, f: (b: B, a: A, i: number) => B): (self: Chunk<A>) => B;
<A, B>(self: Chunk<A>, b: B, f: (b: B, a: A, i: number) => B): B;
};Getters
Gets the value at an index in a Chunk safely, returning None when the index is out of bounds.
Signature
declare const get: {
(index: number): <A>(self: Chunk<A>) => Option<A>;
<A>(self: Chunk<A>, index: number): Option<A>;
};Returns the first element of this chunk safely if it exists.
Signature
declare const head: <A>(self: Chunk<A>) => Option<A>;headNonEmpty
Returns the first element of this non empty chunk.
Signature
declare const headNonEmpty: <A>(self: NonEmptyChunk<A>) => A;Returns the last element of this chunk safely if it exists.
Signature
declare function last<A>(self: Chunk<A>): Option<A>;lastNonEmpty
Returns the last element of this non empty chunk.
Signature
declare const lastNonEmpty: <A>(self: NonEmptyChunk<A>) => A;Retrieves the size of the chunk.
Signature
declare function size<A>(self: Chunk<A>): number;Returns every element after the first safely, or None when the chunk is empty.
Signature
declare function tail<A>(self: Chunk<A>): Option<Chunk<A>>;tailNonEmpty
Returns every element after the first from a non-empty chunk.
Signature
declare function tailNonEmpty<A>(self: NonEmptyChunk<A>): Chunk<A>;Guards
Checks whether a predicate holds true for every Chunk element.
Signature
declare const every: {
<A, B>(refinement: Refinement<NoInfer<A>, B>): (self: Chunk<A>) => self is Chunk<B>;
<A>(predicate: Predicate<A>): (self: Chunk<A>) => boolean;
<A, B>(self: Chunk<A>, refinement: Refinement<A, B>): self is Chunk<B>;
<A>(self: Chunk<A>, predicate: Predicate<A>): boolean;
};Checks whether u is a Chunk<unknown>
Signature
declare const isChunk: {
<A>(u: Iterable<A>): u is Chunk<A>;
(u: unknown): u is Chunk<unknown>;
};isNonEmpty
Determines if the chunk is not empty.
Signature
declare function isNonEmpty<A>(self: Chunk<A>): self is NonEmptyChunk<A>;Checks whether a predicate holds true for some Chunk element.
Signature
declare const some: {
<A>(predicate: Predicate<NoInfer<A>>): (self: Chunk<A>) => self is NonEmptyChunk<A>;
<A>(self: Chunk<A>, predicate: Predicate<A>): self is NonEmptyChunk<A>;
};Instances
makeEquivalence
Creates an Equivalence for chunks that compares chunk lengths and then compares corresponding elements with the provided element equivalence.
Signature
declare function makeEquivalence<A>(isEquivalent: Equivalence<A>): Equivalence<Chunk<A>>;Mapping
Transforms the elements of a chunk using the specified mapping function. If the input chunk is non-empty, the resulting chunk will also be non-empty.
Signature
declare const map: {
<S extends Chunk<any>, B>(f: (a: Infer<S>, i: number) => B): (self: S) => With<S, B>;
<A, B>(self: NonEmptyChunk<A>, f: (a: A, i: number) => B): NonEmptyChunk<B>;
<A, B>(self: Chunk<A>, f: (a: A, i: number) => B): Chunk<B>;
};Models
A Chunk is an immutable, ordered collection optimized for efficient concatenation and access patterns.
Signature
interface Chunk<out A> extends Iterable<A>, Equal, Pipeable, Inspectable {
readonly "~effect/collections/Chunk": {
readonly _A: Covariant<A>;
};
backing: Backing<A>;
depth: number;
left: Chunk<A>;
readonly length: number;
right: Chunk<A>;
}NonEmptyChunk interface
A non-empty Chunk guaranteed to contain at least one element.
Signature
interface NonEmptyChunk<out A> extends Chunk<A>, NonEmptyIterable<A> {}Other
Predicates
Returns a function that checks if a Chunk contains a given value using the default Equivalence.
Signature
declare const contains: {
<A>(a: A): (self: Chunk<A>) => boolean;
<A>(self: Chunk<A>, a: A): boolean;
};containsWith
Returns a function that checks if a Chunk contains a given value using a provided isEquivalent function.
Signature
declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boolean) => {
(a: A): (self: Chunk<A>) => boolean;
(self: Chunk<A>, a: A): boolean;
};Determines if the chunk is empty.
Signature
declare function isEmpty<A>(self: Chunk<A>): boolean;Searching
Returns the first element that satisfies the specified predicate, or None if no such element exists.
Signature
declare const findFirst: {
<A, B>(refinement: Refinement<NoInfer<A>, B>): (self: Chunk<A>) => Option<B>;
<A>(predicate: Predicate<NoInfer<A>>): (self: Chunk<A>) => Option<A>;
<A, B>(self: Chunk<A>, refinement: Refinement<A, B>): Option<B>;
<A>(self: Chunk<A>, predicate: Predicate<A>): Option<A>;
};findFirstIndex
Returns the first index for which a predicate holds.
Signature
declare const findFirstIndex: {
<A>(predicate: Predicate<A>): (self: Chunk<A>) => Option<number>;
<A>(self: Chunk<A>, predicate: Predicate<A>): Option<number>;
};Finds the last element for which a predicate holds.
Signature
declare const findLast: {
<A, B>(refinement: Refinement<NoInfer<A>, B>): (self: Chunk<A>) => Option<B>;
<A>(predicate: Predicate<NoInfer<A>>): (self: Chunk<A>) => Option<A>;
<A, B>(self: Chunk<A>, refinement: Refinement<A, B>): Option<B>;
<A>(self: Chunk<A>, predicate: Predicate<A>): Option<A>;
};findLastIndex
Returns the last index for which a predicate holds.
Signature
declare const findLastIndex: {
<A>(predicate: Predicate<A>): (self: Chunk<A>) => Option<number>;
<A>(self: Chunk<A>, predicate: Predicate<A>): Option<number>;
};Sequencing
Applies a function to each element in a chunk and returns a new chunk containing the concatenated mapped elements.
Signature
declare const flatMap: {
<S extends Chunk<any>, T extends Chunk<any>>(
f: (a: Infer<S>, i: number) => T,
): (self: S) => AndNonEmpty<S, T, Infer<T>>;
<A, B>(self: NonEmptyChunk<A>, f: (a: A, i: number) => NonEmptyChunk<B>): NonEmptyChunk<B>;
<A, B>(self: Chunk<A>, f: (a: A, i: number) => Chunk<B>): Chunk<B>;
};Flattens a chunk of chunks into a single chunk by concatenating all chunks.
Signature
declare const flatten: <S extends Chunk<Chunk<any>>>(self: S) => Chunk.Flatten<S>;Set Operations
intersection
Creates a Chunk of values that are included in both chunks.
Details
The order and references of result values are determined by the first chunk.
Signature
declare const intersection: {
<A>(that: Chunk<A>): <B>(self: Chunk<B>) => Chunk<A & B>;
<A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<A & B>;
};Creates a Chunks of unique values, in order, from all given Chunks.
Signature
declare const union: {
<A>(that: Chunk<A>): <B>(self: Chunk<B>) => Chunk<A | B>;
<A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<A | B>;
};Sorting
Sorts the elements of a Chunk in increasing order, creating a new Chunk.
Signature
declare const sort: {
<B>(O: Order<B>): <A>(self: Chunk<A>) => Chunk<A>;
<A, B>(self: Chunk<A>, O: Order<B>): Chunk<A>;
};Sorts the elements of a Chunk based on a projection function.
Signature
declare const sortWith: {
<A, B>(f: (a: A) => B, order: Order<B>): (self: Chunk<A>) => Chunk<A>;
<A, B>(self: Chunk<A>, f: (a: A) => B, order: Order<B>): Chunk<A>;
};Splitting
Groups elements in chunks of up to n elements.
When to use
Use to divide a chunk into ordered, non-overlapping chunks with at most n elements each.
Details
The final chunk may contain fewer than n elements. Empty input produces an empty chunk of chunks.
Gotchas
Values of n less than or equal to zero produce singleton chunks.
See
splitfor splitting into a target number of chunks instead of a fixed chunk size
Signature
declare const chunksOf: {
(n: number): <A>(self: Chunk<A>) => Chunk<Chunk<A>>;
<A>(self: Chunk<A>, n: number): Chunk<Chunk<A>>;
};Splits a chunk into up to n chunks, distributing elements in order.
Details
The chunk size is derived from the input length and n; the final chunk may contain fewer elements than the others.
Signature
declare const split: {
(n: number): <A>(self: Chunk<A>) => Chunk<Chunk<A>>;
<A>(self: Chunk<A>, n: number): Chunk<Chunk<A>>;
};Returns two splits of this chunk at the specified index.
Signature
declare const splitAt: {
(n: number): <A>(self: Chunk<A>) => [beforeIndex: Chunk<A>, fromIndex: Chunk<A>];
<A>(self: Chunk<A>, n: number): [beforeIndex: Chunk<A>, fromIndex: Chunk<A>];
};splitNonEmptyAt
Splits a NonEmptyChunk at n, returning a non-empty prefix and the remaining suffix.
Details
n is floored and normalized to at least 1. If n is greater than or equal to the chunk length, the first result is the original chunk and the second result is empty.
Signature
declare const splitNonEmptyAt: {
(n: number): <A>(self: NonEmptyChunk<A>) => [beforeIndex: NonEmptyChunk<A>, fromIndex: Chunk<A>];
<A>(self: NonEmptyChunk<A>, n: number): [beforeIndex: NonEmptyChunk<A>, fromIndex: Chunk<A>];
};splitWhere
Splits this chunk on the first element that matches this predicate. Returns a tuple containing two chunks: the first one is before the match, and the second one is from the match onward.
Signature
declare const splitWhere: {
<A>(
predicate: Predicate<NoInfer<A>>,
): (self: Chunk<A>) => [beforeMatch: Chunk<A>, fromMatch: Chunk<A>];
<A>(self: Chunk<A>, predicate: Predicate<A>): [beforeMatch: Chunk<A>, fromMatch: Chunk<A>];
};Takes a Chunk of pairs and returns two corresponding Chunks.
Details
This function is the reverse of zip.
Signature
declare function unzip<A, B>(self: Chunk<readonly [A, B]>): [Chunk<A>, Chunk<B>];Transforming
Applies a function to the element at the specified index safely, creating a new Chunk, or returns None if the index is out of bounds.
Signature
declare const modify: {
<A, B>(i: number, f: (a: A) => B): (self: Chunk<A>) => Option<Chunk<A | B>>;
<A, B>(self: Chunk<A>, i: number, f: (a: A) => B): Option<Chunk<A | B>>;
};Deletes the element at the specified index, creating a new Chunk.
Signature
declare const remove: {
(i: number): <A>(self: Chunk<A>) => Chunk<A>;
<A>(self: Chunk<A>, i: number): Chunk<A>;
};Changes the element at the specified index safely, creating a new Chunk, or returns None if the index is out of bounds.
Signature
declare const replace: {
<B>(i: number, b: B): <A>(self: Chunk<A>) => Option<Chunk<B | A>>;
<A, B>(self: Chunk<A>, i: number, b: B): Option<Chunk<A | B>>;
};Reverses the order of elements in a Chunk.
When to use
Use to read or process chunk elements in reverse order.
Details
If the input chunk is a NonEmptyChunk, the reversed chunk is also a NonEmptyChunk.
Signature
declare const reverse: <S extends Chunk<any>>(self: S) => Chunk.With<S, Chunk.Infer<S>>;Unsafe
fromArrayUnsafe
Wraps an array into a chunk without copying.
When to use
Use when the input array can be shared with the resulting Chunk and avoiding a copy matters.
Gotchas
Mutating the source array after wrapping can mutate the resulting Chunk.
Signature
declare function fromArrayUnsafe<A>(self: readonly Array<A>): Chunk<A>fromNonEmptyArrayUnsafe
Wraps a non-empty array into a non-empty chunk without copying.
When to use
Use when the input array is already known to be non-empty, can be shared with the resulting Chunk, and avoiding a copy matters.
Gotchas
Mutating the source array after wrapping can mutate the resulting Chunk.
Signature
declare function fromNonEmptyArrayUnsafe<A>(self: readonly [A, A]): NonEmptyChunk<A>;Gets an element at the specified index without returning an Option.
When to use
Use when reading from a Chunk at an index known to be in bounds and direct element access is preferred over handling Option.none.
Gotchas
Throws if the index is out of bounds.
Signature
declare const getUnsafe: {
(index: number): <A>(self: Chunk<A>) => A;
<A>(self: Chunk<A>, index: number): A;
};headUnsafe
Returns the first element of this chunk.
When to use
Use when you know the chunk is non-empty and need the first element directly without handling Option.none.
Gotchas
Throws an error if the chunk is empty.
Signature
declare function headUnsafe<A>(self: Chunk<A>): A;lastUnsafe
Returns the last element of this chunk.
When to use
Use when you know the chunk is non-empty and need the last element directly without handling Option.none.
Gotchas
Throws an error if the chunk is empty.
Signature
declare function lastUnsafe<A>(self: Chunk<A>): A;Utility Types
ChunkTypeLambda interface
Type lambda for Chunk, used for higher-kinded type operations.
Signature
interface ChunkTypeLambda extends TypeLambda {
readonly type: Chunk<unknown>;
}Zipping
Zips this chunk pointwise with the specified chunk.
Signature
declare const zip: {
<B>(that: Chunk<B>): <A>(self: Chunk<A>) => Chunk<[A, B]>;
<A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<[A, B]>;
};Zips this chunk pointwise with the specified chunk using the specified combiner.
Signature
declare const zipWith: {
<A, B, C>(that: Chunk<B>, f: (a: A, b: B) => C): (self: Chunk<A>) => Chunk<C>;
<A, B, C>(self: Chunk<A>, that: Chunk<B>, f: (a: A, b: B) => C): Chunk<C>;
};
Iterates over each element of a
Chunkand applies a function to it.Details
This function processes every element of the given
Chunk, calling the provided functionfon each element. It does not return a new value; instead, it is primarily used for side effects, such as logging or accumulating data in an external variable.