<S extends Iterable<any>>(
...orders: ReadonlyArray<Order.Order<ReadonlyArray.Infer<S>>>
): (
self: S
) => S extends NonEmptyReadonlyArray<infer A>
? NonEmptyArray<A>
: S extends Iterable<infer A>
? Array<A>
: neverSorts an array by multiple Orders applied in sequence: the first order is
used first; ties are broken by the second order, and so on.
When to use
Use to sort by multiple criteria where later orders break ties from earlier ones.
Details
This is data-last only and returns a function. The return type preserves
NonEmptyArray.
Example (Sorting by multiple keys)
import { Array, Order, pipe } from "effect"
const users = [
{ name: "Alice", age: 30 },
{ name: "Bob", age: 25 },
{ name: "Charlie", age: 30 }
]
const result = pipe(
users,
Array.sortBy(
Order.mapInput(Order.Number, (user: (typeof users)[number]) => user.age),
Order.mapInput(Order.String, (user: (typeof users)[number]) => user.name)
)
)
console.log(result)
// [{ name: "Bob", age: 25 }, { name: "Alice", age: 30 }, { name: "Charlie", age: 30 }]export const const sortBy: <S extends Iterable<any>>(
...orders: ReadonlyArray<
Order.Order<ReadonlyArray.Infer<S>>
>
) => (
self: S
) => S extends NonEmptyReadonlyArray<infer A>
? NonEmptyArray<A>
: S extends Iterable<infer A>
? Array<A>
: never
Sorts an array by multiple Orders applied in sequence: the first order is
used first; ties are broken by the second order, and so on.
When to use
Use to sort by multiple criteria where later orders break ties from earlier
ones.
Details
This is data-last only and returns a function. The return type preserves
NonEmptyArray.
Example (Sorting by multiple keys)
import { Array, Order, pipe } from "effect"
const users = [
{ name: "Alice", age: 30 },
{ name: "Bob", age: 25 },
{ name: "Charlie", age: 30 }
]
const result = pipe(
users,
Array.sortBy(
Order.mapInput(Order.Number, (user: (typeof users)[number]) => user.age),
Order.mapInput(Order.String, (user: (typeof users)[number]) => user.name)
)
)
console.log(result)
// [{ name: "Bob", age: 25 }, { name: "Alice", age: 30 }, { name: "Charlie", age: 30 }]
sortBy = <function (type parameter) S in <S extends Iterable<any>>(...orders: ReadonlyArray<Order.Order<ReadonlyArray.Infer<S>>>): (self: S) => S extends NonEmptyReadonlyArray<infer A> ? NonEmptyArray<A> : S extends Iterable<infer A> ? Array<A> : neverS extends interface Iterable<T, TReturn = any, TNext = any>Iterable<any>>(
...orders: ReadonlyArray<
Order.Order<ReadonlyArray.Infer<S>>
>
interface ReadonlyArray<T>ReadonlyArray<import OrderOrder.interface Order<in A>Represents a total ordering for values of type A.
When to use
Use when you need to define how values of a type are compared.
Details
An order returns -1 when the first value is less than the second, 0 when
the values are equal according to this ordering, and 1 when the first value
is greater than the second. It must satisfy total ordering laws: totality,
antisymmetry, and transitivity.
Example (Defining a custom Order)
import { Order } from "effect"
const byAge: Order.Order<{ name: string; age: number }> = (self, that) => {
if (self.age < that.age) return -1
if (self.age > that.age) return 1
return 0
}
const person1 = { name: "Alice", age: 30 }
const person2 = { name: "Bob", age: 25 }
console.log(byAge(person1, person2)) // 1
Order<ReadonlyArray.type ReadonlyArray.Infer<S extends Iterable<any>> = S extends readonly (infer A)[] ? A : S extends Iterable<infer A> ? A : neverInfers the element type of an iterable.
Example (Inferring an element type)
import type { Array } from "effect"
type StringArrayType = Array.ReadonlyArray.Infer<ReadonlyArray<string>>
// StringArrayType is string
Infer<function (type parameter) S in <S extends Iterable<any>>(...orders: ReadonlyArray<Order.Order<ReadonlyArray.Infer<S>>>): (self: S) => S extends NonEmptyReadonlyArray<infer A> ? NonEmptyArray<A> : S extends Iterable<infer A> ? Array<A> : neverS>>>
) => {
const const sortByAll: <
A extends ReadonlyArray.Infer<S>,
S extends Iterable<A>
>(
self: S
) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
const sort: {
<B>(O: Order.Order<B>): <
A extends B,
S extends Iterable<A>
>(
self: S
) => ReadonlyArray.With<
S,
ReadonlyArray.Infer<S>
>
<A extends B, B>(
self: NonEmptyReadonlyArray<A>,
O: Order.Order<B>
): NonEmptyArray<A>
<A extends B, B>(
self: Iterable<A>,
O: Order.Order<B>
): Array<A>
}
import OrderOrder.function combineAll<A>(
collection: Iterable<Order<A>>
): Order<A>
Combines all Order instances in the provided collection into a single Order.
The resulting Order compares using each Order in sequence until a non-zero result is found.
When to use
Use when you need tie-breaking across a variable number of orders.
Details
Applies orders in iteration order and short-circuits on the first non-zero
result. It returns 0 only if all orders return 0.
Example (Combining multiple Orders)
import { Order } from "effect"
const byAge = Order.mapInput(
Order.Number,
(person: { name: string; age: number }) => person.age
)
const byName = Order.mapInput(
Order.String,
(person: { name: string; age: number }) => person.name
)
const combinedOrder = Order.combineAll([byAge, byName])
const person1 = { name: "Alice", age: 30 }
const person2 = { name: "Bob", age: 30 }
console.log(combinedOrder(person1, person2)) // -1 (Same age, Alice < Bob)
combineAll(orders: ReadonlyArray<
Order.Order<ReadonlyArray.Infer<S>>
>
self: S extends Iterable<any>self: function (type parameter) S in <S extends Iterable<any>>(...orders: ReadonlyArray<Order.Order<ReadonlyArray.Infer<S>>>): (self: S) => S extends NonEmptyReadonlyArray<infer A> ? NonEmptyArray<A> : S extends Iterable<infer A> ? Array<A> : neverS
): function (type parameter) S in <S extends Iterable<any>>(...orders: ReadonlyArray<Order.Order<ReadonlyArray.Infer<S>>>): (self: S) => S extends NonEmptyReadonlyArray<infer A> ? NonEmptyArray<A> : S extends Iterable<infer A> ? Array<A> : neverS extends type NonEmptyReadonlyArray<A> = readonly [
A,
...A[]
]
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.
Example (Typing a non-empty array)
import type { Array } from "effect"
const nonEmpty: Array.NonEmptyReadonlyArray<number> = [1, 2, 3]
const head: number = nonEmpty[0] // guaranteed to exist
NonEmptyReadonlyArray<infer function (type parameter) AA> ? type NonEmptyArray<A> = [A, ...A[]]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.
Example (Typing a mutable non-empty array)
import type { Array } from "effect"
const nonEmpty: Array.NonEmptyArray<number> = [1, 2, 3]
nonEmpty.push(4)
NonEmptyArray<function (type parameter) AA> : function (type parameter) S in <S extends Iterable<any>>(...orders: ReadonlyArray<Order.Order<ReadonlyArray.Infer<S>>>): (self: S) => S extends NonEmptyReadonlyArray<infer A> ? NonEmptyArray<A> : S extends Iterable<infer A> ? Array<A> : neverS extends interface Iterable<T, TReturn = any, TNext = any>Iterable<infer function (type parameter) AA> ? interface Array<T>Array<function (type parameter) AA> : never => {
const const input: any[]input = const fromIterable: <any>(
collection: Iterable<any>
) => any[]
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.
Example (Converting a Set to an array)
import { Array } from "effect"
const result = Array.fromIterable(new Set([1, 2, 3]))
console.log(result) // [1, 2, 3]
fromIterable(self: S extends Iterable<any>self)
if (const isReadonlyArrayNonEmpty: <A>(
self: ReadonlyArray<A>
) => self is NonEmptyReadonlyArray<A>
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.
Example (Checking for a non-empty readonly array)
import { Array } from "effect"
console.log(Array.isReadonlyArrayNonEmpty([])) // false
console.log(Array.isReadonlyArrayNonEmpty([1, 2, 3])) // true
isReadonlyArrayNonEmpty(const input: any[]input)) {
return const sortByAll: <ReadonlyArray.Infer<S>, any[] & readonly [any, ...any[]]>(self: any[] & readonly [any, ...any[]]) => [any, ...any[]]sortByAll(const input: any[] &
readonly [any, ...any[]]