ArrayX overview
Generic, framework-agnostic extensions to Effect’s Array module.
Added in v0.0.0
Table of contents
combinators
insertUniq
Inserts or moves an item before another item, removing existing copies of the item first. Use it to reorder a list of string or number identifiers without mutating the original array.
The item is inserted before the first matching destination remaining after removal. A null or missing destination appends it to the end. When the destination equals the item, removal leaves no destination, so it also appends. Comparisons use strict equality (===): strings and numbers are distinct, signed zeros are equal, and NaN never matches or gets removed.
Signature
export declare const insertUniq: (<A extends string | number>(config: {
item: A
insertToBeLeftOf: A | null
}) => (array: readonly A[] | A[]) => A[]) &
(<A extends string | number>(array: readonly A[] | A[], config: { item: A; insertToBeLeftOf: A | null }) => A[])
Example
import { ArrayX } from "@nunofyobiz/effect-extras"
const shopping = ["bread", "milk", "apples", "coffee"]
// Move bread just before apples; the original shopping list stays unchanged.
assert.deepStrictEqual(ArrayX.insertUniq(shopping, { item: "bread", insertToBeLeftOf: "apples" }), [
"milk",
"bread",
"apples",
"coffee"
])
// Add eggs at the end when no destination is requested.
assert.deepStrictEqual(ArrayX.insertUniq(shopping, { item: "eggs", insertToBeLeftOf: null }), [
"bread",
"milk",
"apples",
"coffee",
"eggs"
])
Added in v0.0.0
filtering
compactNullable
Removes all null and undefined elements from a list. Use it to turn a list of optional values into a list of present values, with type NonNullable<A>.
Falsy-but-present values such as 0 and "" are kept — only nullish values are dropped. Use it to clean up an array of optionals into a dense array of known-present values.
Signature
export declare const compactNullable: <A>(array: A[]) => NonNullable<A>[]
Example
import { ArrayX } from "@nunofyobiz/effect-extras"
const invitees = ["Amira", null, "Ben", undefined, "Chloe"]
// Remove missing names before printing the invitation list.
assert.deepStrictEqual(ArrayX.compactNullable(invitees), ["Amira", "Ben", "Chloe"])
Added in v0.0.0
filterHead
Drops the leading elements of array until predicate first holds, keeping everything from the first match onward. Use it to trim an unusable prefix while preserving the rest of a list.
The first matching element and all subsequent elements are retained regardless of whether they match — only the prefix before the first match is trimmed. If nothing matches, returns an empty array.
Signature
export declare const filterHead: (<A>(predicate: Predicate.Predicate<A>) => (array: A[]) => A[]) &
(<A>(array: A[], predicate: Predicate.Predicate<A>) => A[])
Example
import { ArrayX } from "@nunofyobiz/effect-extras"
const readingList = [
{ title: "Dune", available: false },
{ title: "The Hobbit", available: true },
{ title: "Foundation", available: false }
]
// Start at the first available book, retaining later books even if unavailable.
assert.deepStrictEqual(
ArrayX.filterHead(readingList, (book) => book.available),
[
{ title: "The Hobbit", available: true },
{ title: "Foundation", available: false }
]
)
Added in v0.0.0
filterMapNullable
Transforms each element and drops results that are null or undefined. Use Effect’s Array.flatMapNullishOr for new code that maps optional results; the result type is narrowed to NonNullable<B>.
A nullable-friendly Array.filterMap: where filterMap expects f to return an Option, this accepts a function returning B | null (or undefined) and treats nullish results as “skip this element”. Falsy-but- present values such as 0 and "" are kept.
Signature
export declare const filterMapNullable: (<A, B>(f: (a: A) => B | null) => (array: A[]) => NonNullable<B>[]) &
(<A, B>(array: A[], f: (a: A) => B | null) => NonNullable<B>[])
Example
import { Array } from "effect"
// Keep only the even numbers, mapped to their halves
assert.deepStrictEqual(
Array.flatMapNullishOr([1, 2, 3, 4], (n) => (n % 2 === 0 ? n / 2 : null)),
[1, 2]
)
Added in v0.0.0
filterTail
Drops the trailing elements of array after predicate last holds, keeping everything up to and including the last match. Use it to trim an unusable suffix while preserving the earlier list.
The mirror of {@link filterHead}: the last matching element and all preceding elements are retained regardless of whether they match — only the suffix after the last match is trimmed. If nothing matches, returns an empty array.
Signature
export declare const filterTail: (<A>(predicate: Predicate.Predicate<A>) => (array: A[]) => A[]) &
(<A>(array: A[], predicate: Predicate.Predicate<A>) => A[])
Example
import { ArrayX } from "@nunofyobiz/effect-extras"
const readingList = [
{ title: "Dune", available: false },
{ title: "The Hobbit", available: true },
{ title: "Foundation", available: false }
]
// End at the last available book, retaining earlier books even if unavailable.
assert.deepStrictEqual(
ArrayX.filterTail(readingList, (book) => book.available),
[
{ title: "Dune", available: false },
{ title: "The Hobbit", available: true }
]
)
Added in v0.0.0
folding
categorize
Collects items into arrays under their category names, preserving their order within each category. Use Effect’s Array.groupBy for new category-based grouping code.
Each item is appended to the array under its category, preserving input order. The result is Partial<Record<C, A[]>> because not every possible category C is guaranteed to appear — only categories that received at least one item are present.
Signature
export declare function categorize<A, C extends string>(
items: Iterable<A>,
categorize: (a: A) => C
): Partial<Record<C, A[]>>
Example
import { Array } from "effect"
const parity = (n: number) => (n % 2 === 0 ? "even" : "odd")
assert.deepStrictEqual(Array.groupBy([1, 2, 3, 4], parity), {
odd: [1, 3],
even: [2, 4]
})
Added in v0.0.0
chunkBy
Splits array into runs of consecutive elements that share the same group value. Use it to segment a list while keeping separate runs with the same key separate. The group is derived by chunk and compared with the provided Equivalence.
Only adjacent elements are grouped: a new run starts every time the group value differs from the first group value of the current run. The comparator receives (firstGroup, currentGroup), and chunk is called once per element in input order. Each entry in the result carries the group value and the non-empty array of values that produced it, preserving input order. An empty input yields an empty array. Use it for run-length-style segmentation; reach for Array.groupBy instead when you want all elements with the same key collapsed regardless of position.
Signature
export declare const chunkBy: (<A, B>(
chunk: (a: A) => B,
GroupEquivalence: Equivalence.Equivalence<B>
) => (array: A[]) => { group: B; values: Array.NonEmptyArray<A> }[]) &
(<A, B>(
array: A[],
chunk: (a: A) => B,
GroupEquivalence: Equivalence.Equivalence<B>
) => { group: B; values: Array.NonEmptyArray<A> }[])
Example
import { Equivalence } from "effect"
import { ArrayX } from "@nunofyobiz/effect-extras"
const calendar = [
{ day: "Monday", title: "Dentist" },
{ day: "Monday", title: "Lunch" },
{ day: "Tuesday", title: "Book club" },
{ day: "Monday", title: "Call Mum" }
]
// Group consecutive entries by day; the later Monday entry starts a separate run.
assert.deepStrictEqual(
ArrayX.chunkBy(calendar, (entry) => entry.day, Equivalence.String),
[
{
group: "Monday",
values: [
{ day: "Monday", title: "Dentist" },
{ day: "Monday", title: "Lunch" }
]
},
{ group: "Tuesday", values: [{ day: "Tuesday", title: "Book club" }] },
{ group: "Monday", values: [{ day: "Monday", title: "Call Mum" }] }
]
)
Added in v0.0.0
mapRightAccum
Maps over array while threading an accumulator, iterating from right to left instead of left to right.
Identical to Array.mapAccum, except the traversal order is reversed: f is called on the last element first, and the resulting array is returned in the original (left-to-right) order. Use it when each element’s mapped value depends on state accumulated from the elements that follow it. Callback indices count traversal steps: the last input element receives index zero, the next-to-last receives one, and so on.
Signature
export declare const mapRightAccum: (<A, B, C>(
initialAccumulator: C,
f: (accumulator: C, a: A, index: number) => [C, B]
) => (array: A[]) => [C, B[]]) &
(<A, B, C>(array: A[], initialAccumulator: C, f: (accumulator: C, a: A, index: number) => [C, B]) => [C, B[]])
Example
import { ArrayX } from "@nunofyobiz/effect-extras"
const playlist = [
{ title: "Morning Walk", minutes: 3 },
{ title: "Sea Breeze", minutes: 4 },
{ title: "Home Again", minutes: 2 }
]
// Each track shows the minutes left from its start through the end of the playlist.
assert.deepStrictEqual(
ArrayX.mapRightAccum(playlist, 0, (remaining, track) => [
remaining + track.minutes,
{ title: track.title, remaining: remaining + track.minutes }
]),
[
9,
[
{ title: "Morning Walk", remaining: 9 },
{ title: "Sea Breeze", remaining: 6 },
{ title: "Home Again", remaining: 2 }
]
]
)
Added in v0.0.0
getters
findFirstWithIndex2d
Finds the first element of a 2-dimensional array (row-major order) matching predicate, returning it alongside its row and column indices. Use it to locate a value in nested lists without flattening away its position.
Scans rows top-to-bottom and, within each row, left-to-right. On a match returns Option.some([value, rowIndex, columnIndex]); if no element matches (or the grid is empty), returns Option.none().
Signature
export declare const findFirstWithIndex2d: (<A>(
predicate: Predicate.Predicate<A>
) => (array: A[][]) => Option.Option<[A, number, number]>) &
(<A>(array: A[][], predicate: Predicate.Predicate<A>) => Option.Option<[A, number, number]>)
Example
import { Option } from "effect"
import { ArrayX } from "@nunofyobiz/effect-extras"
const shelves = [
["Dune", "Foundation"],
["The Hobbit", "Piranesi", "Earthsea"]
]
// Piranesi is on the second shelf in the second slot (indices start at zero).
assert.deepStrictEqual(
ArrayX.findFirstWithIndex2d(shelves, (book) => book === "Piranesi"),
Option.some(["Piranesi", 1, 1])
)
Added in v0.0.0
maxOption
Returns the maximum element of array according to order, wrapped in an Option so that empty arrays are handled safely.
Effect’s Array.max throws on an empty array; this returns Option.none() instead, and Option.some(max) otherwise. Reach for it whenever the input array might be empty.
Signature
export declare const maxOption: (<A>(order: Order.Order<A>) => (array: A[]) => Option.Option<A>) &
(<A>(array: A[], order: Order.Order<A>) => Option.Option<A>)
Example
import { Option, Order } from "effect"
import { ArrayX } from "@nunofyobiz/effect-extras"
const cart = [
{ name: "Tea", price: 4 },
{ name: "Coffee", price: 9 }
]
const byPrice = Order.mapInput(Order.Number, (product: { price: number }) => product.price)
// Pick the most expensive product; an empty cart has no maximum.
assert.deepStrictEqual(ArrayX.maxOption(cart, byPrice), Option.some(cart[1]))
assert.deepStrictEqual(ArrayX.maxOption([], byPrice), Option.none())
Added in v0.0.0
slice
Returns a shallow copy of array between start (inclusive) and end (exclusive). Use it to select a portion of a list inside an Effect pipeline.
Array.prototype.slice is already non-mutating (it returns a shallow copy), but it isn’t pipeable. This helper makes it composable inside pipe(...) chains alongside the rest of the codebase’s Effect-style utilities.
Signature
export declare const slice: (<A>(start: number, end: number) => (array: readonly A[]) => A[]) &
(<A>(array: readonly A[], start: number, end: number) => A[])
Example
import { pipe } from "effect"
import { ArrayX } from "@nunofyobiz/effect-extras"
const guests = ["Amira", "Ben", "Chloe", "Diego"]
// Select the middle two guests without changing the invitation list.
assert.deepStrictEqual(ArrayX.slice(guests, 1, 3), ["Ben", "Chloe"])
assert.deepStrictEqual(pipe(guests, ArrayX.slice(1, 3)), ["Ben", "Chloe"])
Added in v0.0.0
takeFirstWhere
Picks the smallest matching element according to order, or returns Option.none() if nothing matches. Use it to find the lowest-ranked eligible item, regardless of its position in the list.
Combines a refinement filter with Array.min: only elements satisfying predicate are considered, and the minimum of those (by order) is returned. The refinement narrows the element type, so the resulting Option carries the more specific B.
Signature
export declare const takeFirstWhere: (<A, B extends A>(
predicate: Predicate.Refinement<A, B>,
order: Order.Order<B>
) => (array: A[]) => Option.Option<B>) &
(<A, B extends A>(array: A[], predicate: Predicate.Refinement<A, B>, order: Order.Order<B>) => Option.Option<B>)
Example
import { Option, Order } from "effect"
import { ArrayX } from "@nunofyobiz/effect-extras"
type Product = { name: string; price: number; available: boolean }
const cart: Product[] = [
{ name: "Tea", price: 4, available: false },
{ name: "Coffee", price: 9, available: true },
{ name: "Bread", price: 5, available: true }
]
const isAvailable = (product: Product): product is Product => product.available
const byPrice = Order.mapInput(Order.Number, (product: Product) => product.price)
// Ignore unavailable tea and choose the cheapest available product.
assert.deepStrictEqual(
ArrayX.takeFirstWhere(cart, isAvailable, byPrice),
Option.some({ name: "Bread", price: 5, available: true })
)
assert.deepStrictEqual(ArrayX.takeFirstWhere([], isAvailable, byPrice), Option.none())
Added in v0.0.0
takeLastWhere
Picks the largest matching element according to order, or returns Option.none() if nothing matches. Use it to find the highest-ranked eligible item, regardless of its position in the list.
The mirror of {@link takeFirstWhere}: only elements satisfying predicate are considered, and the maximum of those (by order) is returned. The refinement narrows the element type, so the resulting Option carries the more specific B.
Signature
export declare const takeLastWhere: (<A, B extends A>(
predicate: Predicate.Refinement<A, B>,
order: Order.Order<B>
) => (array: A[]) => Option.Option<B>) &
(<A, B extends A>(array: A[], predicate: Predicate.Refinement<A, B>, order: Order.Order<B>) => Option.Option<B>)
Example
import { Option, Order } from "effect"
import { ArrayX } from "@nunofyobiz/effect-extras"
type Product = { name: string; price: number; available: boolean }
const cart: Product[] = [
{ name: "Tea", price: 4, available: true },
{ name: "Coffee", price: 9, available: false },
{ name: "Bread", price: 5, available: true }
]
const isAvailable = (product: Product): product is Product => product.available
const byPrice = Order.mapInput(Order.Number, (product: Product) => product.price)
// Ignore unavailable coffee and choose the most expensive available product.
assert.deepStrictEqual(
ArrayX.takeLastWhere(cart, isAvailable, byPrice),
Option.some({ name: "Bread", price: 5, available: true })
)
assert.deepStrictEqual(ArrayX.takeLastWhere([], isAvailable, byPrice), Option.none())
Added in v0.0.0