Array Ordering

ordered() is the check the library was born from: assert that a collection came back sorted — without copying it, sorting a fixture, or comparing only two records.

should().array(students).ordered({ by: (e) => e?.age });

On failure the chain throws Elements aren't ordered.

Settings

ordered(settings?) takes an optional ArrayOrderedSettings<T>:

Field	Type	Default	Meaning
`by`	`(e?: T \\| null) => any`	`x => x`	extracts the comparable value from each element
`dir`	`'asc' \\| 'desc'`	`'asc'`	expected direction

With no settings the check compares elements as-is, ascending:

should().array([1, 2, 3]).ordered();                    // ok
should().array([1, 3, 2]).ordered();                    // throws
should().array(['a', 'b', 'c']).ordered();              // ok — lexicographic

Ordering by a field

interface Student { name: string; age: number; }
const students: Student[] = studentService.getAll();

should().array(students).ordered({ by: (e) => e?.age });             // ascending by age
should().array(students).ordered({ by: (e) => e?.age, dir: 'desc' }); // descending
should().array(students).ordered({ by: (e) => e?.name });            // by any comparable field

Comparison semantics

Adjacency rules, applied to the by values of neighboring elements:

equal neighbors are fine in both directions (1, 1, 2 is ascending);
dir: 'asc' requires each value to be <= the next; desc requires >=;
values are compared with JavaScript's >/< operators — numbers and strings work naturally, mixed or non-comparable values behave as those operators do.

should().array([1, 1, 2]).ordered(); // ok — equal neighbors allowed
should().array([2, 1]).ordered({ dir: 'desc' }); // ok

Negation

should().array([3, 1, 2]).not.ordered(); // ok — the array is not sorted
should().array([1, 2, 3]).not.ordered(); // throws 'Elements are ordered.'

Note that not.ordered() asserts some disorder, not a specific inverse ordering — if the point of the test is a concrete order, assert ordered({ dir: 'desc' }) positively instead.

Signatures

See API reference — Array verifier and the ArrayOrderedSettings fields in the API reference.

02 сентября 2026