get-reverse-iterating-array

A lightweight proxy function reversing an array’s default iteration direction

Usage no npm install needed!

<script type="module">
  import getReverseIteratingArray from 'https://cdn.skypack.dev/get-reverse-iterating-array';
</script>

README

get-reverse-iterating-array

This function reverses an array’s default iteration direction. By default, the iteration protocols are defined to iterate on an iterable object’s elements according to their insertion order.

The function getReverseIteratingArray returns a new Proxy object with the array as its target. The array’s [Symbol.iterator] property is trapped in order to define custom iteration behaviour. This has the advantage of not changing the implementation of Array.prototype[Symbol.iterator] directly which would cause the iteration direction of all arrays to be reversed. Using a proxy also avoids unnecessarily copying an array for reverse iteration like Array.prototype.reverse() would.

If you require to iterate over an array in both forwards and backwards direction, have a look at ReverseIterableArray.

Links:

See also:

Table of contents

Installation & usage

Browser

Download the ES module file …

curl -O https://raw.githubusercontent.com/kleinfreund/get-reverse-iterating-array/main/dist/esm/get-reverse-iterating-array.mjs

… and import it like this:

import getReverseIteratingArray from 'get-reverse-iterating-array.mjs';

const array = getReverseIteratingArray([1, 2, 3]);

Node

Install the node package as a dependency …

npm install --save get-reverse-iterating-array

… and import it like this:

  • CommonJS module

    const getReverseIteratingArray = require('get-reverse-iterating-array').default;

const array = getReverseIteratingArray([1, 2, 3]);

  • ES module

    import getReverseIteratingArray from 'get-reverse-iterating-array/dist/esm/get-reverse-iterating-array.mjs';

const array = getReverseIteratingArray([1, 2, 3]);

  • TypeScript module

    import getReverseIteratingArray from 'get-reverse-iterating-array/src/get-reverse-iterating-array';

const array = getReverseIteratingArray([1, 2, 3]);

Examples

For some live usage examples, clone the repository and run the following:

npm install && npm run examples

Then, open localhost:8080/examples in a browser.

Tests

In order to run the tests, clone the repository and run the following:

npm install && npm test

Documentation

Create a reverse-iterating array by passing any array to getReverseIteratingArray.

const reverseIteratingArray = getReverseIteratingArray([5, 4, 1, 2, 3]);

The returned object will behave like a regular built-in array with the exception of all cases involving the iteration protocols. The behaviour of the following concepts will be changed when used together with a reverse-iterating array:

  • for..of statement

    for (const element of reverseIteratingArray) {
  console.log(element)
}
//> 3
//> 2
//> 1
//> 4
//> 5

  • spread syntax

    [...reverseIteratingArray];
//> [ 3, 2, 1, 4, 5 ]

  • Array.from() method

    Array.from(reverseIteratingArray);
//> [ 3, 2, 1, 4, 5 ]

  • destructuring assignment

    const [a, b, c, d, e] = reverseIteratingArray
//> a = 3, b = 2, c = 1, d = 4, e = 5