Array

Adds a single element to the end of an iterable, returning a NonEmptyArray.

When to use

Use when you need to guarantee a non-empty result after adding a required trailing value.

See

• prepend — add to the front
• appendAll — append multiple elements

Concatenates two iterables into a single array.

When to use

Use to combine two iterable inputs into a new array with the second input's elements after the first.

Details

If either input is non-empty, the result is a NonEmptyArray.

See

• append — add a single element to the end
• prependAll — add elements to the front

Computes the cartesian product of two arrays, returning all pairs as tuples.

When to use

Use when you need every [a, b] pair from two arrays as tuples.

Details

Produces every [a, b] combination of an element from self with an element from that, so the result length is self.length * that.length.

See

• cartesianWith — apply a combiner to each pair

Computes the cartesian product of two arrays, applying a combiner to each pair.

When to use

Use to compute every combination from two arrays and immediately transform each pair into a custom result.

Details

Produces every combination of an element from self with an element from that, so the result length is self.length * that.length. Iteration visits every element of that for each element of self.

See

• cartesian for returning tuples instead of applying a combiner

Adds a single element to the front of an iterable, returning a NonEmptyArray.

When to use

Use when you need to guarantee a non-empty result after adding a required leading value.

See

• append — add to the end
• prependAll — prepend multiple elements

Prepends all elements from a prefix iterable to the front of an array.

When to use

Use to prepend multiple elements from an iterable to the front of an array.

Details

If either input is non-empty, the result is a NonEmptyArray.

See

• prepend — add a single element to the front
• appendAll — add elements to the end

Creates a new Array of the specified length with all slots uninitialized.

When to use

Use when you need a pre-sized array that will be filled imperatively.

Details

Elements are typed as A | undefined because the slots are empty.

See

• makeBy — create an array by computing each element

Exposes the global array constructor.

When to use

Use to access native JavaScript array constructor methods such as isArray or from from the Effect module namespace.

Provides the starting point for the "do simulation" — an array comprehension pattern.

When to use

Use when you want array-comprehension style code with do notation.

Details

Use bind to introduce array variables and let for plain values. Each bind produces the cartesian product of all bound variables, like nested loops. Use filter and map in the pipeline to add conditions and transformations.

See

• bind — introduce an array variable into the scope
• bindTo — start a pipeline by naming the first array
• let — introduce a plain computed value

Creates an empty array.

When to use

Use to create a typed empty array without allocating placeholder elements.

See

• of — create a single-element array
• make — create from multiple values

Normalizes a value that is either a single element or an array into an array.

When to use

Use to normalize input that may be a single value or an array into a consistent array.

Details

If the input is already an array, this returns it by reference. If the input is a single value, this wraps it in a one-element array. This is useful for APIs that accept A | Array<A>.

See

• of — always wrap in a single-element array
• fromIterable — convert any iterable

Converts an Iterable to an Array.

When to use

Use to convert any Iterable (Set, Generator, etc.) into an array.

Details

If the input is already an array, this returns it by reference without copying. Otherwise, it creates a new array from the iterable. Use copy if you need a fresh array even when the input is already an array.

See

• ensure — wrap a single value or return an existing array
• copy — create a shallow copy of an array

Creates a NonEmptyArray from one or more elements.

When to use

Use when you need to create a typed non-empty array from literal values.

Details

The element type is inferred as the union of all arguments. Because at least one argument is required, this always returns a NonEmptyArray.

See

• of — create a single-element array
• fromIterable — create from any iterable

Creates a NonEmptyArray of length n where element i is computed by f(i).

When to use

Use when you need to compute each array element from its index.

Details

n is normalized to an integer greater than or equal to 1, so this function always returns at least one element. Supports both data-first and data-last usage.

See

• range — create a range of integers
• replicate — repeat a single value

Wraps a single value in a NonEmptyArray.

See

• make — create from multiple values
• empty — create an empty array

Creates a NonEmptyArray containing a range of integers, inclusive on both ends.

When to use

Use when you need a non-empty sequence of consecutive integers.

Details

If start > end, returns [start].

See

• makeBy — generate values from a function

Creates a NonEmptyArray containing a value repeated n times.

When to use

Use when you need a non-empty array containing repeated copies of one value.

Details

n is normalized to an integer greater than or equal to 1, so this function always returns at least one element. Supports both data-first and data-last usage.

See

• makeBy — vary values based on index

Builds an array by repeatedly applying a function to a seed value. The function returns Option.some([element, nextSeed]) to continue, or Option.none() to stop.

See

• makeBy — generate from index
• range — generate a numeric range

Converts a nullable value to an array: null/undefined becomes [], anything else becomes [value].

When to use

Use to treat a nullable single value as zero or one array element.

See

• liftNullishOr — lift a nullable-returning function
• fromOption — convert from Option

Converts an Option to an array: Some(a) becomes [a], None becomes [].

When to use

Use to convert a single Option into an array for downstream array operations.

See

• getSomes — extract Some values from an array of Options

Converts a record into an array of [key, value] tuples.

When to use

Use to convert a record into an array of key-value tuples for iteration or transformation.

Details

Key order follows Object.entries semantics. Empty records produce an empty array.

See

• Record.toEntries the equivalent function from the Record module
• Record.fromEntries to build a record from an array of tuples

Removes duplicates using Equal.equivalence(), preserving the order of the first occurrence.

When to use

Use to remove repeated values from an iterable when Effect's default equality is the right comparison, preserving the first occurrence.

See

• dedupeWith — use custom equality
• dedupeAdjacent — only dedupes consecutive elements

Removes consecutive duplicate elements using Equal.equivalence().

When to use

Use when you need to collapse consecutive duplicates while preserving later non-consecutive repeats, and the default equality is sufficient.

See

• dedupeAdjacentWith — use custom equality
• dedupe — remove all duplicates

Removes consecutive duplicate elements using a custom equivalence.

When to use

Use when consecutive duplicates should be collapsed using a custom equivalence, while equivalent values that appear later should remain in the result.

Details

Non-adjacent duplicates are preserved.

See

• dedupeAdjacent — uses default equality
• dedupeWith — dedupes all duplicates, not just adjacent

Removes duplicates using a custom equivalence, preserving the order of the first occurrence.

When to use

Use to remove all duplicate elements with a custom equivalence when default equality is not appropriate.

See

• dedupe — uses default equality
• dedupeAdjacentWith — only dedupes consecutive elements

Keeps only elements satisfying a predicate (or refinement).

When to use

Use to filter an iterable into a new array of original elements that satisfy a boolean predicate or refinement.

Details

The predicate receives (element, index). Refinements are supported for type narrowing.

See

• partition — split into matching and non-matching
• filterMap for transforming while filtering

Keeps transformed values for elements where a Filter succeeds.

When to use

Use to filter an iterable with a Result-returning transformation while discarding failures.

Details

The filter receives (element, index). Failures are discarded.

See

• filter — keep original elements matching a predicate
• partition for keeping both failures and successes

Extracts all failure values from an iterable of Results, discarding successes.

When to use

Use when you can drop the success channel and only need the failure payloads, not the original result wrappers.

See

• getSuccesses — extract success values
• separate — split into failures and successes

Extracts all Some values from an iterable of Options, discarding Nones.

When to use

Use to collect only present values from an iterable of Option values while discarding None values.

See

• fromOption — convert a single Option
• getSuccesses — extract successes from Results

Extracts all success values from an iterable of Results, discarding failures.

When to use

Use when you can drop the failure channel and only need the success payloads, not the original result wrappers.

See

• getFailures — extract failure values
• separate — split into failures and successes

Splits an iterable using a Filter into failures and successes.

When to use

Use to partition an iterable by evaluating each element with a Result-returning filter and keeping both failure and success values.

Details

Returns [excluded, satisfying]. The filter receives (element, index).

See

• filter — keep only matching elements
• filterMap for discarding failures
• separate — split an iterable of Result values

Separates an iterable of Results into failure values and success values.

When to use

Use to split an iterable of Result values into failure and success arrays.

Details

Returns [failures, successes]. This is equivalent to partition(identity).

See

• getFailures — extract only failures
• getSuccesses — extract only successes
• partition for computing Result values while splitting

Computes the number of elements in an iterable that satisfy a predicate.

When to use

Use when you need to count how many elements of an iterable satisfy a predicate.

Details

The predicate receives both the element and its index. Empty iterables return 0.

See

• filter — when you need the matching elements, not just the count

Returns a Reducer that combines ReadonlyArray values by concatenation.

See

• makeReducerConcat — mutable Array variant

Joins string elements with a separator.

See

• intersperse — insert separator elements without joining

Returns a Reducer that combines Array values by concatenation.

See

• getReadonlyReducerConcat — readonly variant

Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.

When to use

Use when you need to map while threading state through each element and keep the final state.

Details

Combines map and reduce in a single pass. The callback receives the current state, element, and index, and returns [nextState, mappedValue]. The result is [finalState, mappedArray]. This can be used in both data-first and data-last style.

See

• scan — when you only need the accumulated results (not the final state)
• reduce — when you only need the final accumulated value

Folds an iterable from left to right into a single value.

When to use

Use to combine all elements into one accumulated value from left to right.

Details

The function receives (accumulator, element, index).

See

• reduceRight — fold from right to left
• scan — fold keeping intermediate values

Folds an iterable from right to left into a single value.

When to use

Use when you need to fold values from right to left.

Details

The function receives (accumulator, element, index).

See

• reduce — fold from left to right
• scanRight — fold keeping intermediate values

Folds left-to-right while keeping every intermediate accumulator value.

When to use

Use to compute a running accumulator where each intermediate value is needed.

Details

The output length is input.length + 1 because it starts with the initial value. The result is always a NonEmptyArray. Use reduce if you only need the final accumulated value.

See

• scanRight — right-to-left scan
• reduce — fold without intermediate values

Folds right-to-left while keeping every intermediate accumulator value.

When to use

Use to compute a running accumulator from right to left where each intermediate value is needed.

Details

The output length is input.length + 1 because it ends with the initial value. The result is always a NonEmptyArray.

See

• scan — left-to-right scan
• reduceRight — fold without intermediate values

Removes the first n elements, creating a new array.

When to use

Use to keep the suffix of an iterable after skipping a fixed number of leading elements.

Details

n is clamped to [0, length]. When n <= 0, this returns a copy of the full array.

See

• dropRight for removing a fixed number of elements from the end
• dropWhile for removing a prefix based on a predicate instead of a fixed count
• take for keeping a fixed number of elements from the start

Removes the last n elements, creating a new array.

When to use

Use to remove the last n elements from an iterable.

Details

n is clamped to [0, length].

See

• drop — remove from the start
• takeRight — keep from the end

Drops elements from the start while the predicate holds, returning the rest.

When to use

Use to remove a leading prefix of elements that satisfy a predicate.

Details

The predicate receives (element, index).

See

• takeWhile — keep the matching prefix instead
• drop — drop a fixed count

Drops elements from the start while a Filter succeeds.

When to use

Use when you need to drop a prefix from an iterable by computing a Result per element instead of using a simple boolean predicate.

Details

The filter receives (element, index). The result contains the remaining original elements after the first filter failure.

See

• dropWhile for dropping a prefix with a simple boolean predicate
• takeWhileFilter for keeping only the matching prefix

Reads an element at the given index safely, returning Option.some or Option.none if the index is out of bounds.

When to use

Use when you need to read an array element by index and handle an out-of-bounds index as Option.none.

Details

The index is floored to an integer. This never throws.

See

• getUnsafe for indexed access that throws when the index is out of bounds
• head for reading the first element as an Option
• last for reading the last element as an Option

Returns the first element of an array safely wrapped in Option.some, or Option.none if the array is empty.

When to use

Use to safely get the first element of an array that may be empty.

See

• headNonEmpty — direct access when array is known non-empty
• last — get the last element

Returns the first element of a NonEmptyReadonlyArray directly (no Option wrapper).

When to use

Use to get the first element without Option wrapping when the array is known to be non-empty.

See

• head — safe version for possibly-empty arrays

Returns all elements except the last safely, wrapped in an Option.

When to use

Use to safely get all elements before the last when the iterable may be empty.

Details

Allocates a new array via slice(0, -1). Empty inputs return Option.none().

See

• initNonEmpty — when the array is known non-empty
• tail — all elements except the first

Returns all elements except the last of a NonEmptyReadonlyArray.

When to use

Use to get all elements before the last when the array is known to be non-empty.

See

• init — safe version for possibly-empty arrays
• tailNonEmpty — all elements except the first

Returns the last element of an array safely wrapped in Option.some, or Option.none if the array is empty.

When to use

Use to safely get the last element of an array that may be empty.

See

• lastNonEmpty — direct access when array is known non-empty
• head — get the first element

Returns the last element of a NonEmptyReadonlyArray directly (no Option wrapper).

When to use

Use to get the last element without Option wrapping when the array is known to be non-empty.

See

• last — safe version for possibly-empty arrays

Returns the number of elements in a ReadonlyArray.

When to use

Use when you need length as a composable function rather than a property access.

Returns the maximum element of a non-empty array according to the given Order.

See

• min — find the minimum
• sort — sort the entire array

Returns the minimum element of a non-empty array according to the given Order.

See

• max — find the maximum
• sort — sort the entire array

Returns all elements except the first safely, wrapped in an Option.

When to use

Use to safely get all elements after the first when the iterable may be empty.

Details

Allocates a new array via slice(1). Empty inputs return Option.none().

See

• tailNonEmpty — when the array is known non-empty
• init — all elements except the last

Returns all elements except the first of a NonEmptyReadonlyArray.

When to use

Use to get all elements after the first when the array is known to be non-empty.

See

• tail — safe version for possibly-empty arrays
• initNonEmpty — all elements except the last

Keeps the first n elements, creating a new array.

When to use

Use to keep up to the first n elements from an iterable as a new array.

Details

n is clamped to [0, length]. Returns an empty array when n <= 0.

See

• takeRight for keeping elements from the end
• takeWhile for keeping an initial prefix while a predicate holds
• drop for removing elements from the start

Keeps the last n elements, creating a new array.

When to use

Use to keep the last n elements of an iterable.

Details

n is clamped to [0, length]. Returns an empty array when n <= 0.

See

• take — keep from the start
• dropRight — remove from the end

Takes elements from the start while the predicate holds, stopping at the first element that fails.

When to use

Use to keep the leading elements of an iterable while each element satisfies a predicate, returning the retained prefix as an array.

Details

Supports refinements for type narrowing. The predicate receives (element, index).

See

• take for keeping a fixed number of leading elements
• dropWhile for removing the matching prefix and keeping the rest
• span for splitting the matching prefix from the remaining elements

Takes elements from the start while a Filter succeeds, collecting transformed values.

When to use

Use when you need to take a prefix from an iterable while a function can successfully extract or transform elements, stopping at the first element that produces a failure result.

Details

The filter receives (element, index) and processing stops at the first filter failure.

See

• takeWhile for taking a prefix based on a boolean predicate

Groups consecutive equal elements using Equal.equivalence().

When to use

Use when you already have adjacent equal values and Effect's default equality is the right comparison.

Details

Only adjacent elements are grouped.

See

• groupWith — use custom equality
• groupBy — group by a key function into a record

Groups elements into a record by a key-returning function. Each key maps to a NonEmptyArray of elements that produced that key.

When to use

Use to build buckets of elements indexed by a computed string or symbol key.

Details

Unlike group and groupWith, elements do not need to be adjacent to be grouped together. The key function must return a string or symbol.

See

• group — group adjacent equal elements
• groupWith — group adjacent elements by custom equality

Groups consecutive equal elements using a custom equivalence function.

When to use

Use when you already have a non-empty array arranged so matching elements are adjacent and need a custom equivalence function.

Details

Only adjacent elements are grouped. Non-adjacent duplicates stay separate. Requires a NonEmptyReadonlyArray.

See

• group for grouping adjacent elements with Equal.equivalence()
• groupBy for grouping all elements into a record by key, regardless of adjacency

Checks whether all elements satisfy the predicate. Supports refinements for type narrowing.

When to use

Use to check whether every array element satisfies a predicate, including refinement-based type narrowing.

See

• some — test if any element matches

Checks whether a value is an Array.

When to use

Use to verify a value is a mutable array, narrowing its type to Array<unknown>.

Details

Acts as a type guard narrowing the input to Array<unknown> and delegates to globalThis.Array.isArray.

See

• isArrayEmpty — check for an empty array
• isArrayNonEmpty — check for a non-empty array

Checks whether a mutable Array is empty, narrowing the type to [].

See

• isReadonlyArrayEmpty — readonly variant
• isArrayNonEmpty — opposite check

Checks whether a mutable Array is non-empty, narrowing the type to NonEmptyArray.

When to use

Use when you need the narrowed value to remain a mutable Array after proving it has at least one element.

See

• isReadonlyArrayNonEmpty — readonly variant
• isArrayEmpty — opposite check

Checks whether a ReadonlyArray is empty, narrowing the type to readonly [].

See

• isArrayEmpty — mutable variant
• isReadonlyArrayNonEmpty — opposite check

Checks whether a ReadonlyArray is non-empty, narrowing the type to NonEmptyReadonlyArray.

When to use

Use when you need to prove a readonly array has at least one element without requiring mutable array methods afterward.

See

• isArrayNonEmpty — mutable variant
• isReadonlyArrayEmpty — opposite check

Checks whether at least one element satisfies the predicate. Narrows the type to NonEmptyReadonlyArray on success.

See

• every — test if all elements match
• contains — test for a specific value

Creates an Equivalence for arrays based on an element Equivalence. Two arrays are equivalent when they have the same length and all elements are pairwise equivalent.

See

• makeOrder — create an ordering for arrays

Creates an Order for arrays based on an element Order. Arrays are compared element-wise; if all compared elements are equal, shorter arrays come first.

See

• makeEquivalence — create an equivalence for arrays

Lifts a nullable-returning function into one that returns an array: null/undefined becomes [], anything else becomes [value].

See

• fromNullishOr — convert a single nullable value
• liftOption — lift an Option-returning function

Lifts an Option-returning function into one that returns an array: Some(a) becomes [a], None becomes [].

When to use

Use when an optional parser or lookup should participate in array pipelines as zero-or-one results.

See

• liftPredicate — lift a boolean predicate
• liftResult — lift a Result-returning function

Lifts a predicate into an array: returns [value] if the predicate holds, [] otherwise.

See

• liftOption — lift an Option-returning function

Lifts a Result-returning function into one that returns an array: failures produce [], successes produce [value].

When to use

Use when a fallible parser or lookup should participate in array pipelines as zero-or-one results and the failure value should be discarded.

See

• liftOption — lift an Option-returning function
• liftPredicate — lift a boolean predicate

Wraps each array element in an object with the given key, starting a do-notation scope.

When to use

Use when you already have an array and want to start a do-notation pipeline by naming each element.

Details

Equivalent to Array.map(self, (a) => ({ [tag]: a })). This is an alternative to starting with Do plus bind when you already have an array.

See

• Do — start with an empty scope
• bind — add another array variable to the scope

Applies a function to each suffix of the array (starting from each index), collecting the results.

When to use

Use when you need to compute a result from every suffix of an array, such as cumulative aggregations from each position.

Details

For index i, the function receives self.slice(i).

See

• scan for keeping intermediate accumulator values during a fold

Transforms each element using a function, returning a new array.

When to use

Use to transform each element independently while preserving the array shape.

Details

The function receives (element, index). The return type preserves NonEmptyArray.

See

• flatMap — map and flatten

A mutable array guaranteed to have at least one element.

When to use

Use when mutation is acceptable and non-emptiness must be tracked at the type level.

Details

This is the mutable counterpart of NonEmptyReadonlyArray. Most Array module functions return NonEmptyArray when the result is guaranteed non-empty.

See

• NonEmptyReadonlyArray — readonly counterpart
• isArrayNonEmpty — narrow an Array to this type

A readonly array guaranteed to have at least one element.

When to use

Use when non-emptiness must be tracked at the type level while preventing mutation. Many Array module functions accept or return this type.

See

• NonEmptyArray — mutable counterpart
• isReadonlyArrayNonEmpty — narrow a ReadonlyArray to this type

Utility types for working with ReadonlyArray at the type level. Use these to infer element types, preserve non-emptiness, and flatten nested arrays.

Pattern-matches on an array, handling empty and non-empty cases separately.

When to use

Use when you need to branch on whether an array is empty.

Details

onNonEmpty receives a NonEmptyReadonlyArray. Supports both data-first and data-last usage.

See

• matchLeft — destructures into head + tail
• matchRight — destructures into init + last

Pattern-matches on an array from the left, providing the first element and the remaining elements separately.

When to use

Use when you need to branch on an array and handle the non-empty case as the first element plus the remaining elements.

Details

onNonEmpty receives (head, tail) where tail is the rest of the array.

See

• match — receives the full non-empty array
• matchRight — destructures into init + last

Pattern-matches on an array from the right, providing all elements except the last and the last element separately.

When to use

Use when you need to branch on an array and handle the non-empty case as the elements before the last plus the last element.

Details

onNonEmpty receives (init, last) where init is everything but the last element.

See

• match — receives the full non-empty array
• matchLeft — destructures into head + tail

Checks whether an array contains a value, using Equal.equivalence() for comparison.

When to use

Use to check whether an iterable contains a value using Effect's default equality instead of providing a comparison function.

See

• containsWith — use custom equality

Returns a membership-test function using a custom equivalence.

When to use

Use when checking membership with caller-provided equality instead of Equal.equivalence().

See

• contains for the Equal.equivalence() variant