{"id":13493501,"url":"https://github.com/tannerlinsley/swimmer","last_synced_at":"2025-04-05T16:04:20.649Z","repository":{"id":45779418,"uuid":"118952699","full_name":"tannerlinsley/swimmer","owner":"tannerlinsley","description":"🏊 Swimmer - An async task pooling and throttling utility for JS","archived":false,"fork":false,"pushed_at":"2020-08-29T03:14:09.000Z","size":121,"stargazers_count":209,"open_issues_count":1,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-29T15:03:37.879Z","etag":null,"topics":["async","await","concurrency","javascript","pooling","promises","task","throttling"],"latest_commit_sha":null,"homepage":"https://codesandbox.io/s/mq2j7jq39x?expanddevtools=1\u0026hidenavigation=1","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tannerlinsley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-25T18:40:12.000Z","updated_at":"2025-03-12T17:34:15.000Z","dependencies_parsed_at":"2022-09-24T12:03:35.331Z","dependency_job_id":null,"html_url":"https://github.com/tannerlinsley/swimmer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tannerlinsley%2Fswimmer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tannerlinsley%2Fswimmer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tannerlinsley%2Fswimmer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tannerlinsley%2Fswimmer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tannerlinsley","download_url":"https://codeload.github.com/tannerlinsley/swimmer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361614,"owners_count":20926642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","await","concurrency","javascript","pooling","promises","task","throttling"],"created_at":"2024-07-31T19:01:15.959Z","updated_at":"2025-04-05T16:04:20.605Z","avatar_url":"https://github.com/tannerlinsley.png","language":"JavaScript","readme":"# 🏊‍ swimmer\n\n[![David Dependancy Status](https://david-dm.org/tannerlinsley/swimmer.svg)](https://david-dm.org/tannerlinsley/swimmer)\n[![npm package v](https://img.shields.io/npm/v/swimmer.svg)](https://www.npmjs.org/package/swimmer)\n[![npm package dm](https://img.shields.io/npm/dm/swimmer.svg)](https://npmjs.com/package/swimmer)\n[![Join the community on Slack](https://img.shields.io/badge/slack-react--chat-blue.svg)](https://react-chat-signup.herokuapp.com/)\n[![Github Stars](https://img.shields.io/github/stars/tannerlinsley/swimmer.svg?style=social\u0026label=Star)](https://github.com/tannerlinsley/swimmer)\n[![Twitter Follow](https://img.shields.io/twitter/follow/nozzleio.svg?style=social\u0026label=Follow)](https://twitter.com/nozzleio)\n\n\nAn async task pooling and throttling utility for javascript.\n\n## Features\n- 🚀 3kb and zero dependencies\n- 🔥 ES6 and async/await ready\n- 😌 Simple to use!\n\n## Interactive Demo\n - [CodeSandbox](https://codesandbox.io/s/mq2j7jq39x?expanddevtools=1\u0026hidenavigation=1)\n\n## Installation\n```bash\n$ yarn add swimmer\n# or\n$ npm i swimmer --save\n```\n\n## UMD\n```\nhttps://unpkg.com/swimmer/umd/swimmer.min.js\n```\n\n## Inline Pooling\nInline Pooling is great for:\n- Throttling intensive tasks in a serial fashion\n- Usage with async/await and promises.\n- Ensuring that all tasks succeed.\n\n```javascript\nimport { poolAll } from 'swimmer'\n\nconst urls = [...]\n\nconst doIntenseTasks = async () =\u003e {\n  try {\n    const res = await poolAll(\n      urls.map(task =\u003e\n        () =\u003e fetch(url) // Return an array of functions that return a promise\n      ),\n      10 // Set the concurrency limit\n    )\n  } catch (err, task) {\n    // If an error is encountered, the entire pool stops and the error is thrown\n    console.log(`Encountered an error with task: ${task}`)\n    throw err\n  }\n\n  // If no errors are thrown, you get your results!\n  console.log(res) // [result, result, result, result]\n}\n```\n\n## Custom Pooling\nCustom pools are great for:\n- Non serial\n- Reusable pools\n- Handling errors gracefully\n- Task management and retry\n- Variable throttle speed, pausing, resuming of tasks\n\n```javascript\nimport { createPool } from 'swimmer'\n\nconst urls = [...]\nconst otherUrls = [...]\n\n// Create a new pool with a throttle speed and some default tasks\nconst pool = createPool({\n  concurrency: 5,\n  tasks: urls.map(url =\u003e () =\u003e fetch(url))\n})\n\n// Subscribe to errors\npool.onError((err, task) =\u003e {\n  console.warn(err)\n  console.log(`Encountered an error with task ${task}. Resubmitting to pool!`)\n  pool.add(task)\n})\n\n// Subscribe to successes\npool.onSuccess((res, task) =\u003e {\n  console.log(`Task Complete. Result: ${res}`)\n})\n\n// Subscribe to settle\npool.onSettled(() =\u003e console.log(\"Pool is empty. All tasks are finished!\"))\n\nconst doIntenseTasks = async () =\u003e {\n  // Add more tasks to the pool.\n  tasks.forEach(\n    url =\u003e pool.add(\n      () =\u003e fetch(url)\n    )\n  )\n\n  // Increase the concurrency to 10! This can also be done while it's running.\n  pool.throttle(10)\n\n  // Pause the pool\n  pool.stop()\n\n  // Start the pool again!\n  pool.start()\n\n  // Add a single task and WAIT for it's completion/failure\n  try {\n    const res = await pool.add(() =\u003e fetch('http://custom.com/asset.json'))\n    console.log('A custom asset!', res)\n  } catch (err) {\n    console.log('Darn! An error...')\n    throw err\n  }\n\n  // Then clear the pool. Any running tasks will attempt to finished.\n  pool.clear()\n}\n```\n\n### API\nSwimmer exports two functions:\n- `poolAll` - creates an inline async/await/promise compatible pool\n  - Arguments\n    - `Array[Function =\u003e Promise]` - An array of functions that return a promise.\n    - `Int` - The concurrency limit for this pool.\n  - Returns\n    - A `Promise` that resolves when all tasks are complete, or throws an error if one of them fails.\n  - Example:\n- `createPool` - creates an custom pool\n  - Arguments\n    - `Object{}` - An optional configuration object for this pool\n      - `concurrency: Int (default: 5)` - The concurrency limit for this pool.\n      - `started: Boolean (default: true)` - Whether the pool should be started by default or not.\n      - `tasks: Array[Function =\u003e Promise]` - An array of functions that return a promise. These tasks will be preloaded into the pool.\n  - Returns\n    - `Object{}`\n      - `add(() =\u003e Promise, config{})` - Adds a task to the pool. Optionally pass a config object\n        - `config.priority` - Set this option to `true` to queue this task in front of all other `pending` tasks.\n        - Returns a promise that resolves/rejects with the eventual response from this task\n      - `start()` - Starts the pool.\n      - `stop()` - Stops the pool.\n      - `throttle(Int)` - Sets a new concurrency rate for the pool.\n      - `clear()` - Clears all pending tasks from the pool.\n      - `getActive()` - Returns all active tasks.\n      - `getPending()` - Returns all pending tasks.\n      - `getAll()` - Returns all tasks.\n      - `isRunning()` - Returns `true` if the pool is running.\n      - `isSettled()` - Returns `true` if the pool is settled.\n      - `onSuccess((result, task) =\u003e {})` - Registers an onSuccess callback.\n      - `onError((error, task) =\u003e {})` - Registers an onError callback.\n      - `onSettled(() =\u003e {})` - Registers an onSettled callback.\n\n## Tip of the year\nMake sure you are passing an array of `thunks`. A thunk is a function that returns your task, not your task itself. If you pass an array of tasks that have already been fired off then it's too late for Swimmer to manage them :(\n\n## Contributing\n\nWe are always looking for people to help us grow `swimmer`'s capabilities and examples. If you have an issue, feature request, or pull request, let us know!\n\n## License\n\nSwimmer uses the MIT license. For more information on this license, [click here](https://github.com/tannerlinsley/swimmer/blob/master/LICENSE).\n\n[build-badge]: https://img.shields.io/travis/tannerlinsley/swimmer/master.png?style=flat-square\n[build]: https://travis-ci.org/tannerlinsley/swimmer\n\n[npm-badge]: https://img.shields.io/npm/v/npm-package.png?style=flat-square\n[npm]: https://www.npmjs.org/package/swimmer\n\n[coveralls-badge]: https://img.shields.io/coveralls/tannerlinsley/swimmer/master.png?style=flat-square\n[coveralls]: https://coveralls.io/github/tannerlinsley/swimmer\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftannerlinsley%2Fswimmer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftannerlinsley%2Fswimmer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftannerlinsley%2Fswimmer/lists"}