@graffy/stream

中文文档
0.19.7发布于 2026/09/16Apache-2.0TypeScriptES Module零依赖构建来源已验证近 30 天下载 7070

Utility for creating AsyncIterables (streams) from any callback-based

原始使用文档
文档目录6 节
  1. Why?
  2. Usage
  3. Minimal Example
  4. Handle upstream end
  5. Handle errors
  6. Backpressure

Graffy Stream

Utility for creating AsyncIterables (streams) from any callback-based event source.

Why?

Many JS APIs provide callback-based event emitters that must be subscribed to and unsubscribed from. The async generator syntax in JS does not provide an easy mechanism to do this.

Imagine the event emitter:

websocket.addEventListener('message', callback);

We would like to feed this stream of messages into an AsyncIterable, so we can do:

for await (const message of messages) {
  // Do stuff with message.
  if (done) break;
}

and do stuff. We might also want to call removeEventListener when we break (or return or throw) out of the loop.

Usage

The default export is a factory function.

import { makeStream } from '@graffy/stream';

Minimal Example

This handles subscribing and unsubscribing from the event emitter.

const stream = makeStream((push) => {
  eventSource.on('event', push);
  return () => eventSource.off('event', push);
});

The return value, stream, is an AsyncIterable that can be used in a for-await-of loop.

Handle upstream end

This handles situations where the "upstream" event emitter has an "end" event, which should make the "downstream" for-await-of loop end as well.

const stream = makeStream((push, end) => {
  eventSource.on('event', (event) => push(event));
  eventSource.on('end', () => end());
  return () => eventSource.close();
});

Handle errors

This handles errors in both directions. The "upstream" might close with an error, which should be communicated downstream as the for-await-of loop throwing. Less often, if the code inside the loop throws, we might want to communicate that upstream.

Both are handled by the "end" functions being called with an error object as an argument.

const stream = makeStream((push, end) => {
  eventSource.on('event', (event) => push(event));
  eventSource.on('end', () => end());
  eventSource.on('error', (error) => end(error));
  return (error) => {
    if (error) {
      eventSource.closeWithError();
      return;
    }
    eventSource.close();
  };
});

Backpressure

When streams are used to pipe IO events, we might run into a situation where the downstream consumer is slower than the upstream producer. If left unchecked, we might run out of memory - we need to maintain a buffer of unconsumed events.

To handle this situation, the producer might expose methods to pause and resume the stream of events; if not, in some situations, it might also be appropriate to unsubscribe and resubscribe.

Graffy stream exposes an interface to do these, with configurable high and low water marks.

const stream = makeStream(
  (push) => {
    eventSource.on('event', (event) => {
      const wait = push(event);
      if (wait) {
        eventSource.pause();
        wait.then(() => eventSource.resume());
      }
    });

    return () => eventSource.close();
  },
  { highWatermark: 255, lowWatermark: 4 },
);

If there are more than highWatermark unconsumed events, push() will return a Promise wait. As the consumer catches up and the number of unconsumed events fall below lowWatermark, this promise will resolve.

版本与发布记录

@graffy/stream 共发布 246 个版本,首次发布于 2019/09/07;过去 12 个月发布了 21 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.19.7latest2026/09/162 个月前
0.19.62026/08/173 个月前
0.19.52026/08/033 个月前
0.19.42026/06/304 个月前
0.19.32026/05/215 个月前
0.19.22026/05/176 个月前

其他发布通道:pre → 0.19.1-alpha.3。

关于 @graffy/stream 的常见问题

@graffy/stream 是什么?

Utility for creating AsyncIterables (streams) from any callback-based

如何安装 @graffy/stream?

在项目目录运行 npm install @graffy/stream,或使用 pnpm add / yarn add / bun add。

@graffy/stream 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@graffy/stream 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@graffy/stream 可以商用吗?

@graffy/stream 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@graffy/stream 的下载量有多少?

根据 npm 官方下载统计,@graffy/stream 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,070 次,日均约 236 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@graffy/stream 还在维护吗?

最新版本 0.19.7 发布于 2026/09/16(2 个月前);至今共发布 246 个版本,其中过去 12 个月发布了 21 个;首次发布于 2019/09/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。