Async Iterators

A TypeScript library of asynchronous array functions with Promise compatibility.

Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
3. Usage
4. Feature Requests & Bug Reports
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Native JavaScript array loops such as Array.prototype.map() are incompatible with Promises. Writing asynchronous within a map, even if wrapped in Promise.all will result in inconsistent behavior.

For example, if we want to fetch three dad jokes by ID from the icanhazdadjoke web API then we unfortunately cannot maintain the order of the IDs in our response. Using map from async-iterators will maintain order.

await Promise.all(
  ["0ga2EdN7prc", "4EBsPZvP7h", "xHQucUvszd"].map(async (jokeId, index) => {
    await fetch(`https://icanhazdadjoke.com/j/${jokeId}`, {
      headers: { Accept: "application/json" },
    })
      .then((response) => response.json())
      .then((json) => console.log(`Joke #${index}: ${json.joke}`));
  })
);
// Order of the logs is not guaranteed.
// Joke #1: Some people eat light bulbs. They say it's a nice light snack.
// Joke #2: To the guy who invented zero... thanks for nothing.
// Joke #0: How come the stadium got hot after the game? Because all of the fans left.

import { map } from "async-iterators";

await map(
  ["0ga2EdN7prc", "4EBsPZvP7h", "xHQucUvszd"],
  async (jokeId, index) => {
    await fetch(`https://icanhazdadjoke.com/j/${jokeId}`, {
      headers: { Accept: "application/json" },
    })
      .then((response) => response.json())
      .then((json) => console.log(`Joke #${index}: ${json.joke}`));
  }
);
// Order is guaranteed.
// Joke #0: How come the stadium got hot after the game? Because all of the fans left.
// Joke #1: Some people eat light bulbs. They say it's a nice light snack.
// Joke #2: To the guy who invented zero... thanks for nothing.

Built With

Getting Started

Installation

This package has no dependencies and never will. Simply install the NPM package and you're ready to use it!

Clone the repo

git clone https://github.com/GuthrieW/async-iterators.git

Install NPM packages

NPM

npm install async-iteraors

Yarn

yarn add async-iterators

Usage

For more examples, please refer to the documentation

Feature Requests & Bug Reports

See the open issues for a full list of proposed features (and known issues).

Please consider contributing to the project if you open an issue!

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors:

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Wesley Guthrie - @twitter_handle - wesleyeguthrie@gmail.com

Project Link: https://github.com/GuthrieW/async-iterators

Acknowledgments

• Gregory Spicer and Joshua Sarna for both introducing me to this issue and working on solutions together