Swimmer

Common errors

• TypeError: (0 , _swimmer.poolAll) is not a function

  cause This typically occurs in CommonJS environments when `swimmer` is imported using `require()` but treated as an ES module or when bundling tools incorrectly handle the export. The library was released before widespread native ESM support in Node.js.
  fix Ensure you are using `import { poolAll } from 'swimmer'` in an ES module context or if using CommonJS, `const swimmer = require('swimmer'); const poolAll = swimmer.poolAll;` might be necessary, though inconsistent with documentation. Verify your build configuration for ESM/CJS transpilation.

• UnhandledPromiseRejectionWarning: A promise was rejected with a reason that was not handled

  cause If a task within `poolAll` or `createPool` rejects, and you haven't attached a `.catch()` handler to the `poolAll` call or registered an `onError` callback for `createPool`, the promise rejection will go unhandled.
  fix For `poolAll`, always wrap the call in a `try...catch` block: `try { await poolAll(...) } catch (err) { ... }`. For `createPool`, register an error handler: `pool.onError((err, task) => { console.error(err); });`.

• TypeError: task.then is not a function

  cause This error arises when a function passed as a task to `poolAll` or `pool.add` does not return a Promise or a thenable object.
  fix Ensure that every function you provide to Swimmer's pooling mechanism (e.g., in `urls.map(task => () => fetch(url))`) explicitly returns a Promise. The task itself should be a function that, when called, produces a Promise.

Warnings

• breaking Swimmer is no longer actively maintained. The last release (v1.4.0) was published in August 2018, and its primary author has moved on to other projects. This means there will be no new features, bug fixes, or security updates. Users should consider this carefully for long-term projects or those requiring ongoing support.
  Fix: For new projects, consider alternative, actively maintained libraries for async task management or implement custom pooling logic. For existing projects, be aware of the lack of future updates and potential security vulnerabilities.
• gotcha When using `poolAll`, any error encountered by a single task will immediately stop the entire pool and throw the error. This 'fail-fast' behavior might not be desired if you want other tasks to complete even if some fail.
  Fix: If 'fail-fast' is not desired, use `createPool` instead. The custom pool allows you to subscribe to individual `onError` events and implement custom retry logic or simply log the error and allow other tasks to continue.
• gotcha Tasks passed to `poolAll` or `pool.add` must be 'thunks' – functions that return a promise, not the promise itself. Passing an already-fired promise means Swimmer cannot manage its lifecycle.
  Fix: Always wrap your promise-returning logic in a function. Correct: `() => fetch(url)`. Incorrect: `fetch(url)`.

Install

• npm install swimmer npm
• yarn add swimmer yarn
• pnpm add swimmer pnpm

Imports

• poolAll
  wrong:

  const { poolAll } = require('swimmer')

  correct:

  import { poolAll } from 'swimmer'

  Primarily designed for ESM usage with `import`. While CommonJS `require` might work in some environments, ESM is the intended and idiomatic usage based on the documentation.
• createPool
  wrong:

  const createPool = require('swimmer').createPool

  correct:

  import { createPool } from 'swimmer'

  Use named import for `createPool` to access the custom pooling API. Similar to `poolAll`, ESM `import` is the documented approach.
• PoolInstance

  const pool = createPool(...); pool.add(...)

  The `createPool` function returns a Pool instance with methods like `add`, `start`, `stop`, `throttle`, `onError`, `onSuccess`, etc. These methods are accessed directly on the returned object.

Quickstart

This example demonstrates how to create and manage a custom task pool using `createPool`, handle successes and errors with callbacks, dynamically adjust concurrency, and add tasks, including waiting for individual task completion.

import { createPool } from 'swimmer';

const urlsToProcess = [
  'https://api.example.com/data/1',
  'https://api.example.com/data/2',
  'https://api.example.com/data/3',
  'https://api.example.com/data/4',
  'https://api.example.com/data/5',
  'https://api.example.com/data/6',
  'https://api.example.com/data/7',
  'https://api.example.com/data/8'
];

// Create a new pool with a concurrency limit of 3
const dataPool = createPool({
  concurrency: 3,
  tasks: urlsToProcess.slice(0, 3).map(url => () => fetch(url).then(res => res.json()))
});

// Subscribe to successful task completions
dataPool.onSuccess((result, taskFn) => {
  console.log(`Task successful. Result: ${JSON.stringify(result).substring(0, 50)}...`);
});

// Subscribe to errors, re-adding failed tasks for retry
dataPool.onError((err, taskFn) => {
  console.error(`Task failed: ${err.message}. Re-adding to pool for retry.`);
  dataPool.add(taskFn);
});

// Subscribe when the entire pool is settled (all tasks finished or retried)
dataPool.onSettled(() => {
  console.log('All tasks in the pool have settled.');
});

const startProcessing = async () => {
  console.log('Starting data processing with Swimmer pool...');

  // Add remaining tasks to the pool
  urlsToProcess.slice(3).forEach(url => {
    dataPool.add(() => fetch(url).then(res => res.json()));
  });

  // Dynamically adjust concurrency
  console.log('Increasing concurrency to 5.');
  dataPool.throttle(5);

  // Add a critical task and wait for its immediate completion/failure
  try {
    const singleResult = await dataPool.add(() => fetch('https://api.example.com/critical-data').then(res => res.json()));
    console.log('Critical task completed:', JSON.stringify(singleResult).substring(0, 50), '...');
  } catch (error) {
    console.error('Critical task failed:', error.message);
  }

  // The pool will continue processing until all tasks are done or explicitly cleared.
  // For demonstration, we'll let it run.
};

// Simulate API calls with a delay
const originalFetch = global.fetch;
global.fetch = async (url) => {
  const delay = Math.random() * 500 + 100; // 100ms to 600ms delay
  await new Promise(resolve => setTimeout(resolve, delay));
  if (Math.random() < 0.1) { // 10% chance of failure
    throw new Error(`Failed to fetch ${url}`);
  }
  return { json: () => Promise.resolve({ source: url, data: 'some_payload', timestamp: Date.now() }) };
};

startProcessing().finally(() => {
  // Restore original fetch after the demonstration
  global.fetch = originalFetch;
});