cartwheel

A circular list you never knew you needed

cartwheel takes an array (or any array-like/iterable) and gives you a circular iterator. You can ask for the next or previous value any number of times, and it will keep cycling through the list.

Install

As an npm package

npm install cartwheel

Then import it:

const cartwheel = require('cartwheel');

Or if you use ES module syntax:

import cartwheel from "cartwheel";

As a <script>

<script src="https://unpkg.com/cartwheel@1.1.0"></script>

Or if you want to host it yourself, go to releases and download cartwheel.umd.min.js. Then:

<script src="cartwheel.umd.min.js"></script>

As an ES Module (modern browsers)

import cartwheel from 'https://unpkg.com/cartwheel@1.1.0/dist/cartwheel.esm.min.js';

Or if you want to host it yourself, go to releases and download cartwheel.esm.min.js. Then:

import cartwheel from 'cartwheel.esm.min.js';

Note: This should also work with Deno, but I haven‘t tested it.

Usage

// Pass an iterable
const items = ["Ed", "Edd", "Eddy"];
const iterator = cartwheel(items);

// Start iterating
iterator.nextValue();
// Ed

iterator.nextValue();
// Edd

iterator.nextValue();
// Eddy

// It‘s circular, remember?
iterator.nextValue();
// Ed

// Standard ES iterator protocol if you like
iterator.next();
// { value: 'Edd', done: false }

// `done` will always be false though
iterator.next();
// { value: 'Eddy', done: false }

// Rewind
iterator.previousValue();
// Edd

iterator.previousValue();
// Ed

// They see me rollin‘, they hatin‘
iterator.previousValue();
// Eddy

// Iterator protocol again
iterator.previous();
// { value: 'Edd', done: false }

Documentation

cartwheel(iterable) returns an iterator object with the following methods:

next()

Returns the next item to what you last accessed. If it is the first call, returns the first item in the iterable. done is always false.

Example: { value: 42, done: false }

nextValue()

Same as next(), but returns the value directly.

previous()

Returns the previous item to what you last accessed. If it is the first call, returns the last item in the iterable. done is always false.

Example: { value: 1337, done: false }

previousValue()

Same as previous(), but returns the value directly.

FAQ

Where would I need this?

Anywhere you want to iterate a list of items in a circular “round robin” fashion. Think keyboard-navigable menus, tabs, carousels and typeahead suggestions.

Does it work with maps, sets or node lists?

Yes. It works with anything that is compatible with Array.from().

Is it like a circular doubly linked list?

Kind of. It does offer a similar API, but the implementation looks nothing like a linked list.