Add Cycled#peek() method (#12)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

index.d.ts

@@ -76,6 +76,13 @@ declare class Cycled<T> extends Array<T> {
 	*/
 	step(steps: number): T;
 
+	/**
+	Returns the item that is located in the given amount of `steps` through the array. For example, calling `peek(2)` would get the item 2 items after the current one. You go backward by specifying a negative number.
+
+	This method is similar to `.step()` but without changing the current item.
+	*/
+	peek(steps: number): T;
+
 	/**
 	Returns an iterable that will cycle through the array indefinitely.
 	*/

index.js

@@ -32,6 +32,10 @@ module.exports = class Cycled extends Array {
 		return this[this._index];
 	}
 
+	peek(steps) {
+		return this[(this.length + this._index + steps) % this.length];
+	}
+
 	current() {
 		return this.step(0);
 	}

index.test-d.ts

@@ -9,6 +9,7 @@ expectType<number>(cycled.current());
 expectType<number>(cycled.next());
 expectType<number>(cycled.previous());
 expectType<number>(cycled.step(10));
+expectType<number>(cycled.peek(10));
 expectType<IterableIterator<number>>(cycled.indefinitely());
 expectType<IterableIterator<number>>(cycled.indefinitelyReversed());
 expectType<number[]>([...cycled]);

readme.md

@@ -75,6 +75,12 @@ Returns the previous item.
 
 Returns the item by going the given amount of `steps` through the array. For example, calling `step(2)` is like calling `next()` twice. You go backward by specifying a negative number.
 
+#### peek(steps)
+
+Returns the item that is located in the given amount of `steps` through the array. For example, calling `peek(2)` would get the item 2 items after the current one. You go backward by specifying a negative number.
+
+This method is similar to `.step()` but without changing the current item.
+
 #### index
 
 Get or set the current index.

test.js

@@ -26,6 +26,12 @@ test('.step()', t => {
 	t.is(c.step(-2), 1);
 });
 
+test('.peek()', t => {
+	const c = new Cycled(fixture);
+	t.is(c.peek(1), 2);
+	t.is(c.peek(-2), 2);
+});
+
 test('.index', t => {
 	const c = new Cycled(fixture);
 	t.is(c.index, 0);