{"id":11116,"library":"it-pipe","title":"Async Iterable Pipe Utility","description":"it-pipe is a JavaScript/TypeScript utility for composing asynchronous iterables into pipelines, simplifying stream processing in Node.js and browser environments. The library, currently at version 3.0.1, maintains an active release cadence with recent updates in early 2023. Its core `pipe` function efficiently connects sources, transforms, and sinks, automatically wrapping initial iterable sources into functions as needed. A key differentiator for `it-pipe` is its explicit support for duplex streams, enabling more complex bidirectional data flows. It leverages the `it-` ecosystem pattern for async iterables, offering a robust and type-safe solution for orchestrating sequential asynchronous operations. This package requires Node.js version 16 or newer.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/alanshaw/it-pipe","tags":["javascript","async","await","iterable","iterator","pipe","pipeline","pull","pump","typescript"],"install":[{"cmd":"npm install it-pipe","lang":"bash","label":"npm"},{"cmd":"yarn add it-pipe","lang":"bash","label":"yarn"},{"cmd":"pnpm add it-pipe","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v2.0.0, it-pipe is an ESM-only package and uses named exports. CommonJS 'require' will not work.","wrong":"const pipe = require('it-pipe')","symbol":"pipe","correct":"import { pipe } from 'it-pipe'"},{"note":"The 'pipe' function is a named export, not a default export.","wrong":"import pipe from 'it-pipe'","symbol":"pipe","correct":"import { pipe } from 'it-pipe'"},{"note":"TypeScript users can import these types to correctly type pipeline stages for better type checking.","symbol":"Source, Sink, Transform","correct":"import type { Source, Sink, Transform } from 'it-pipe'"}],"quickstart":{"code":"import { pipe } from 'it-pipe';\n\nasync function runPipelineExample() {\n  const result = await pipe(\n    // A source is just an iterable, this is shorthand for () => [1, 2, 3]\n    [1, 2, 3],\n    // A transform takes a source, and returns a source.\n    // This transform doubles each value asynchronously.\n    async function transform (source: AsyncIterable<number>): Promise<AsyncIterable<number>> {\n      return (async function * (): AsyncIterable<number> {\n        for await (const val of source) yield val * 2;\n      })();\n    },\n    // A sink, it takes a source and consumes it, optionally returning a value.\n    // This sink buffers up all the values from the source and returns them.\n    async function collect (source: AsyncIterable<number>): Promise<number[]> {\n      const vals: number[] = [];\n      for await (const val of source) {\n        vals.push(val);\n      }\n      return vals;\n    }\n  );\n\n  console.log('Pipelined Result:', result); // Expected: [2, 4, 6]\n\n  // Demonstrating piping an async generator directly\n  async function* generateStrings(): AsyncIterable<string> {\n    yield 'hello';\n    yield 'world';\n  }\n\n  const collectedStrings = await pipe(\n    generateStrings(), // An async iterable source\n    async function toUpperCase(source: AsyncIterable<string>): Promise<AsyncIterable<string>> {\n      return (async function*(): AsyncIterable<string> {\n        for await (const s of source) {\n          yield s.toUpperCase();\n        }\n      })();\n    },\n    async function collectAndJoin(source: AsyncIterable<string>): Promise<string> {\n      let finalString = '';\n      for await (const s of source) {\n        finalString += s + ' ';\n      }\n      return finalString.trim();\n    }\n  );\n  console.log('String Pipeline Result:', collectedStrings); // Expected: \"HELLO WORLD\"\n}\n\nrunPipelineExample().catch(console.error);\n","lang":"typescript","description":"This quickstart demonstrates how to use `it-pipe` to chain an iterable source, an asynchronous transform function, and an asynchronous sink function, showcasing both number and string processing pipelines."},"warnings":[{"fix":"Ensure your code correctly handles both Promise and direct return values from `pipe` when dealing with potentially synchronous pipelines. Await the result if unsure, as `await` handles both synchronously resolved values and Promises.","message":"Starting with v3.0.0, if the entire pipeline consists only of synchronous operations, the `pipe` function will return a synchronous value directly, rather than always a Promise. This change optimizes performance for fully synchronous pipelines.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update all imports from `const pipe = require('it-pipe')` to `import { pipe } from 'it-pipe'`. Ensure your project is configured to handle ES Modules (e.g., `\"type\": \"module\"` in `package.json` for Node.js, or using a bundler for browsers).","message":"Version 2.0.0 introduced significant breaking changes by switching to ES Modules (ESM) only and exclusively using named exports. CommonJS 'require' statements will no longer work, and default imports are no longer available.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Review TypeScript usage and adjust type annotations as necessary, especially for source, transform, and sink functions, which now benefit from explicit `AsyncIterable<T>` typing.","message":"Version 2.0.0 also converted the library to TypeScript. While beneficial for type safety, this might introduce minor type-related breaking changes if you were relying on specific (potentially inferred) JavaScript type behaviors or internal structures that are now more strictly defined.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Implement `try...catch` blocks within your async generator functions and async functions used as transforms and sinks to gracefully handle errors and either re-throw them or manage them appropriately to prevent pipeline stalls or unhandled promise rejections.","message":"Error propagation in async iterable pipelines can be complex. While `it-pipe` facilitates connections, individual pipeline stages (sources, transforms, sinks) must be designed to properly catch, handle, or propagate errors within their asynchronous generators or functions to ensure robust error handling throughout the pipeline.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement from `const pipe = require('it-pipe')` to `import { pipe } from 'it-pipe'`. If in a browser, ensure you are using a bundler that handles ESM, or load via a script tag (e.g., `<script src=\"https://unpkg.com/it-pipe/dist/index.min.js\"></script>`).","cause":"Attempting to use CommonJS `require()` to import `it-pipe` in an environment configured for ES Modules (Node.js with `\"type\": \"module\"` or a browser context).","error":"ReferenceError: require is not defined"},{"fix":"Ensure you are using named import syntax: `import { pipe } from 'it-pipe'`. If using CommonJS, which is not supported since v2.0.0, migrate to ESM.","cause":"Incorrectly importing `pipe` as a default export (`import pipe from 'it-pipe'`) when it is a named export, or attempting to use `require()` with named exports.","error":"TypeError: pipe is not a function"},{"fix":"Explicitly type your asynchronous generators and functions to return `AsyncIterable<T>` or `Promise<AsyncIterable<T>>` for sources and transforms, and `Promise<R>` for sinks, where `T` is the type of the yielded elements and `R` is the final return type of the sink.","cause":"A type mismatch occurs when a pipeline stage (source, transform, or sink) is not correctly typed to match the `AsyncIterable` or `Promise<AsyncIterable>` expectation of `it-pipe`.","error":"Type 'AsyncGenerator<any, void, unknown>' is not assignable to type 'Iterable<unknown> | Source<unknown>' (TypeScript)"}],"ecosystem":"npm"}