Combiner

Defines reusable rules for merging two values of the same type.

A Combiner<A> contains one operation, combine(self, that), which returns the merged value. It does not define an initial value for reducing a collection; use a Reducer when you need that. This module includes the Combiner interface, a constructor for custom combining logic, and common combiners for choosing or ordering values.

9 exports Added in v4.0.0 Source

Combinators

flip

Added in v4.0.0 Source

Reverses the argument order of a combiner's combine method.

When to use

Use when you want the right-hand value to act as the accumulator, or need to reverse a non-commutative combiner such as string concatenation.

Details

Returns a new Combiner where combine(self, that) calls the original combiner as combine(that, self).

See

make

Signature

declare function flip<A>(combiner: Combiner<A>): Combiner<A>

Example

(Reversing string concatenation)

import { Combiner, String } from "effect"

const Prepend = Combiner.flip(String.ReducerConcat)

Prepend.combine("a", "b") // => "ba"

intercalate

Added in v4.0.0 Source

Wraps a Combiner so that a separator value is inserted between every pair of combined elements.

When to use

Use when you need to inject a fixed separator between accumulated values, such as when building delimited strings, paths, or CSV-like output by repeated combination.

Details

intercalate(middle)(combiner).combine(self, that) is equivalent to combiner.combine(self, combiner.combine(middle, that)). This function is curried: first provide the separator, then the base combiner.

See

make

Signature

declare function intercalate<A>(middle: A): (combiner: Combiner<A>) => Combiner<A>

Example

(Joining strings with a separator)

import { Combiner, String } from "effect"

const commaSep = Combiner.intercalate(",")(String.ReducerConcat)

commaSep.combine("a", "b") // => "a,b"

Constructors

constant

Added in v4.0.0 Source

Creates a Combiner that ignores both arguments and always returns the given constant value.

When to use

Use when you need a combiner that always returns a fixed value, including when a generic API requires a combiner but the result is predetermined.

Details

combine(self, that) returns the constant a and ignores both arguments.

See

first
last

Signature

declare function constant<A>(a: A): Combiner<A>

Example

(Always returning zero)

import { Combiner } from "effect"

const Zero = Combiner.constant(0)

Zero.combine(42, 99) // => 0

first

Added in v4.0.0 Source

Creates a Combiner that always returns the first (left) argument.

When to use

Use when you want "first write wins" semantics while merging values.

Details

combine(self, that) returns self and ignores that.

See

last

Signature

declare function first<A>(): Combiner<A>

Example

(Keeping the first value)

import { Combiner } from "effect"

const First = Combiner.first<number>()

First.combine(1, 2) // => 1

last

Added in v4.0.0 Source

Creates a Combiner that always returns the last (right) argument.

When to use

Use when you want "last write wins" semantics while merging values.

Details

combine(self, that) returns that and ignores self.

See

first

Signature

declare function last<A>(): Combiner<A>

Example

(Keeping the last value)

import { Combiner } from "effect"

const Last = Combiner.last<number>()

Last.combine(1, 2) // => 2

make

Added in v4.0.0 Source

Creates a Combiner from a binary function.

When to use

Use when you have a custom combining operation that is not covered by the built-in constructors (min, max, first, last, constant).

Details

The returned combiner's combine method delegates to the provided function. Any purity, associativity, or mutation behavior comes from that function.

See

Combiner – the interface this creates

Signature

declare function make<A>(combine: (self: A, that: A) => A): Combiner<A>

Example

(Multiplying numbers)

import { Combiner } from "effect"

const Product = Combiner.make<number>((self, that) => self * that)

Product.combine(3, 5) // => 15

max

Added in v4.0.0 Source

Creates a Combiner that returns the larger of two values according to the provided Order.

When to use

Use when you want to accumulate the maximum value across a collection or build a Reducer that tracks the running maximum.

Details

The combiner compares values using the given Order. When values are equal, it returns that (the second argument).

See

Signature

declare function max<A>(order: Order<A>): Combiner<A>

Example

(Selecting the maximum of two numbers)

import { Combiner, Number } from "effect"

const Max = Combiner.max(Number.Order)

Max.combine(3, 1) // => 3
Max.combine(1, 3) // => 3

min

Added in v4.0.0 Source

Creates a Combiner that returns the smaller of two values according to the provided Order.

When to use

Use when you want to accumulate the minimum value across a collection or build a Reducer that tracks the running minimum.

Details

The combiner compares values using the given Order. When values are equal, it returns that (the second argument).

See

Signature

declare function min<A>(order: Order<A>): Combiner<A>

Example

(Selecting the minimum of two numbers)

import { Combiner, Number } from "effect"

const Min = Combiner.min(Number.Order)

Min.combine(3, 1) // => 1
Min.combine(1, 3) // => 1

Models

Combiner interface

Added in v4.0.0 Source

Represents a strategy for combining two values of the same type A. A Combiner contains a single combine method that takes two values and returns a merged result. It does not include an identity/empty value; use Reducer when you need one.

When to use

Use when you need to describe how two values of the same type merge, pass a reusable combining strategy to library functions like Struct.makeCombiner or Option.makeCombinerFailFast, or define the combining step for a Reducer.

See

make – create a Combiner from a function

Signature

interface Combiner<A> {
  readonly combine: (self: A, that: A) => A;
}

Example

(Combining numbers with addition)

import { Combiner } from "effect"

const Sum = Combiner.make<number>((self, that) => self + that)

Sum.combine(3, 4) // => 7