Navigateable

Updated on August 22, 2024Source codeTests

Navigateable is a class that enriches an array, allowing it to:

• Store the index-based location of an item that has been navigated to
• Retrieve the item that has been navigated to
• Store a status (ready, navigated, or navigated to <relative item position>, where <relative item position> is first, last, next, previous, or random)
• Navigate forward or backward to a different item
• Navigate to a specific item or a random item

Construct a Navigateable instance

The Navigateable constructor accepts two parameters:

Navigateable constructor options

State and methods

How Navigateable navigates

In general, whenever the setLocation, navigate, next, previous, random, first, or last methods are called, the Navigateable instance computes the new location and stores that location in its location property.

The only other thing you need to know about how your Navigateable instance navigates is what options are available for the navigate, next, and previous methods, and how those options affect the way Navigateable computes the final location.

navigate accepts an optional options object as its second argument. Here's a breakdown of the options object:

Both next and previous accept an optional options object as their only argument. Here's a breakdown of the options object:

When loops is true and the computed location is greater than array.length - 1 (the largest index-based location), your Navigateable instance calculates how much greater the computed location is, then takes that number of steps forward through the array, looping back to the beginning any time it passes array.length - 1.

See the code below for specific examples:

// The loops option is true by default
const instance = new Navigateable(['Baleada', 'Logic', 'Navigateable'])

instance.navigate(2) // The array is now located at its last item
instance.next() // The array navigated past the end of the array, so it will return to the beginning
instance.location // -> 0

instance.next({ distance: 5 }) // The array's location is 0, and its largest index is 2.
/*
 * The array starts at 0, where it left off.
 * Your instance navigates 2 steps forward and reaches the last location (3 steps remain).
 * It steps forward once more, looping around to 0 (2 steps remain).
 * It then makes its final 2 steps, landing on 2 (0 steps remain).
 */
instance.location // -> 2

When loops is true and the computed location is less than 0, your Navigateable instance does the same thing, but in reverse: it calculates how much less the computed location is, then takes that number of steps backward through the array, looping around to the end any time it passes 0.

See the code below for specific examples:

// The loops option is true by default
const instance = new Navigateable(['Baleada', 'Logic', 'Navigateable'])

instance.navigate(0) // The array is now located at its first item
instance.previous() // The array navigated past the beginning of the array, so it will loops to the end
instance.location // -> 2

instance.previous({ distance: 5 }) // The array's location is 2, and its lowest index is 0.
/*
 * The array starts at 2, where it left off.
 * Your instance navigates 2 steps backward and reaches 0 (3 steps remain).
 * It steps backward once more, looping around to 2 (2 steps remain).
 * It then makes its final two steps, landing on 0 (0 steps remain).
 */
instance.location // -> 0

Using with TypeScript

The Navigateable constructor accepts one generic type that you can use to enforce a type for the items in array. By default, TypeScript will infer the item type from the initial array you pass to the constructor, but you can specify the type manually if needed.

const withInferredTypes = new Navigateable([1, 2, 3])
withInferredTypes.array = ['a', 'b', 'c'] // Type error

const withManualTypes = new Navigateable<string | number>([1, 2, 3])
withManualTypes.array = ['a', 'b', 'c'] // No type error

API design compliance

Edit doc on GitHub