<const A, Input = unknown>(value: A): Filter<
Input,
A,
EqualsWith<Input, A, A, Exclude<Input, A>>
>Creates a filter that only passes values equal to the specified value using structural equality.
When to use
Use to accept inputs that are structurally equal to a known expected value
while staying in a composable Filter / Result pipeline.
Details
Delegates to Equal.equals. On success it returns Result.succeed(value);
on failure it returns Result.fail(input).
export const const equals: <A, Input = unknown>(
value: A
) => Filter<
Input,
A,
EqualsWith<Input, A, A, Exclude<Input, A>>
>
Creates a filter that only passes values equal to the specified value using structural equality.
When to use
Use to accept inputs that are structurally equal to a known expected value
while staying in a composable Filter / Result pipeline.
Details
Delegates to Equal.equals. On success it returns Result.succeed(value);
on failure it returns Result.fail(input).
equals =
<const function (type parameter) A in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>A, function (type parameter) Input in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>Input = unknown>(value: const Avalue: function (type parameter) A in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>A): interface Filter<in Input, out Pass = Input, out Fail = Input>Represents a filter function that can transform inputs to outputs or filter them out.
Details
A filter takes an input value and either returns a boxed pass value or the
special fail type to indicate the value should be filtered out.
Example (Defining a positive number filter)
import { Filter, Result } from "effect"
// A filter that only passes positive numbers
const positiveFilter: Filter.Filter<number> = (n) => n > 0 ? Result.succeed(n) : Result.fail(n)
console.log(positiveFilter(5)) // Result.succeed(5)
console.log(positiveFilter(-3)) // Result.fail(-3)
Filter<function (type parameter) Input in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>Input, function (type parameter) A in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>A, type EqualsWith<A, B, Y, N> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? Y : NDetermines if two types are equal, returning custom types for each case.
When to use
Use when you need a type-level if/else based on type equality.
Details
Returns Y when A and B are equal, N otherwise.
Example (Choosing a conditional type based on equality)
import type { Types } from "effect"
type R1 = Types.EqualsWith<string, string, "same", "diff"> // "same"
type R2 = Types.EqualsWith<string, number, "same", "diff"> // "diff"
EqualsWith<function (type parameter) Input in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>Input, function (type parameter) A in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>A, function (type parameter) A in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>A, type Exclude<T, U> = T extends U
? never
: T
Exclude from T those types that are assignable to U
Exclude<function (type parameter) Input in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>Input, function (type parameter) A in <const A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>A>>> => (u: Input = unknownu) =>
import EqualEqual.function equals<Input, A>(self: Input, that: A): boolean (+1 overload)Checks whether two values are deeply structurally equal.
When to use
Use when you need Effect's default structural equality check.
Details
Returns a boolean and never throws. Primitives are compared by value, and
NaN equals NaN. Objects implementing Equal delegate to their
[Equal.symbol] method; if only one operand implements Equal, the result
is false.
Dates compare by ISO string, RegExps compare by string representation,
arrays compare element-by-element, Maps and Sets compare entries
order-independently, and plain objects compare enumerable keys recursively.
Functions without an Equal implementation compare by reference. Circular
references are handled when both structures are circular at the same depth.
Hash values are checked first as a fast-path rejection. The function also
supports dual data-last usage: call it with one argument to get a curried
predicate.
Gotchas
- Results are cached per object pair in a WeakMap. Objects must not be
mutated after their first comparison.
- Map and Set comparisons are O(n²) in size.
Example (Comparing values)
import { Equal } from "effect"
// Primitives
console.log(Equal.equals(1, 1)) // true
console.log(Equal.equals(NaN, NaN)) // true
console.log(Equal.equals("a", "b")) // false
// Objects and arrays
console.log(Equal.equals({ a: 1, b: 2 }, { a: 1, b: 2 })) // true
console.log(Equal.equals([1, [2, 3]], [1, [2, 3]])) // true
// Dates
console.log(Equal.equals(new Date("2024-01-01"), new Date("2024-01-01"))) // true
// Maps (order-independent)
const m1 = new Map([["a", 1], ["b", 2]])
const m2 = new Map([["b", 2], ["a", 1]])
console.log(Equal.equals(m1, m2)) // true
// Curried form
const is5 = Equal.equals(5)
console.log(is5(5)) // true
console.log(is5(3)) // false
equals(u: Input = unknownu, value: const Avalue) ? import ResultResult.const succeed: <A>(right: A) => Result<A>Creates a Result holding a Success value.
Details
- Use when you have a value and want to lift it into the
Result type
- The error type
E defaults to never
Example (Wrapping a value)
import { Result } from "effect"
const result = Result.succeed(42)
console.log(Result.isSuccess(result))
// Output: true
succeed(value: const Avalue) : import ResultResult.const fail: <E>(
left: E
) => Result<never, E>
Creates a Result holding a Failure value.
When to use
Use to represent a failed Result with a typed failure value.
Details
- The success type
A defaults to never
Example (Creating a failure)
import { Result } from "effect"
const result = Result.fail("Something went wrong")
console.log(Result.isFailure(result))
// Output: true
fail(u: Input = unknownu as any)