Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
poolAll
✓ import { poolAll } from 'swimmer'
✗ const { poolAll } = require('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
✓ import { createPool } from 'swimmer'
✗ const createPool = require('swimmer').createPool
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.
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;
});
Errors
Common errors & fixes
TypeError: (0 , _swimmer.poolAll) is not a function
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.
fixEnsure 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
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.
fixFor `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
This error arises when a function passed as a task to `poolAll` or `pool.add` does not return a Promise or a thenable object.
fixEnsure 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.
Audit
Dependencies
No dependency data recorded yet.