# @ion-bot/flow

> A stream.

Latest version **0.3.0** (published 2018-10-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install @ion-bot/flow
pnpm add @ion-bot/flow
yarn add @ion-bot/flow
bun add @ion-bot/flow
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2018-10-20 |
| First published | 2018-10-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 26 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | trustgit |
| Maintainers | ion-bot |

## Links

- npm: https://www.npmjs.com/package/@ion-bot/flow
- Repository: https://github.com/ion-bot/flow
- Issues: https://github.com/ion-bot/flow/issues
- npm.io page: https://npm.io/package/@ion-bot/flow

## Dependencies (2)

- [debug](https://npm.io/package/debug.md) ^4.0.1
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.0.0-beta.51

## Recent versions

- 0.3.0 (latest) — 2018-10-20
- 0.2.0 — 2018-10-14
- 0.1.2 — 2018-10-13
- 0.1.1 — 2018-10-12

## README

# @ion-bot/flow
![@ion-bot/flow logo](https://raw.githubusercontent.com/ion-bot/flow/master/doc/static/logo.jpg)

[![GitHub Org](https://img.shields.io/badge/part%20of-ion--bot-orange.svg)](https://github.com/ion-bot)
[![GitHub](https://img.shields.io/github/license/ion-bot/flow.svg)](https://github.com/ion-bot/flow/blob/master/LICENSE)
[![Build status](https://ci.appveyor.com/api/projects/status/edugm063oxsas06e?svg=true)](https://ci.appveyor.com/project/trustgit/flow)
[![codecov](https://codecov.io/gh/ion-bot/flow/branch/master/graph/badge.svg)](https://codecov.io/gh/ion-bot/flow)
[![CodeFactor](https://www.codefactor.io/repository/github/ion-bot/flow/badge)](https://www.codefactor.io/repository/github/ion-bot/flow)
[![npm (scoped)](https://img.shields.io/npm/v/@ion-bot/flow.svg)](https://npmjs.org/package/@ion-bot/flow)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/ion-bot/flow.svg)

@ion-bot/flow 是一个使程序流在运行过程中可以便利地通过异步函数获取传入的消息的类。

## Introduction
@ion-bot/flow 是一个类库，因此你可以这样将其包含进你的项目中：
```js
import IonFlow from '@ion-bot/flow'
// 创建 Ion 实例，传入一组 behavior（下文以 behaviors 指代，基本指一组程序流）
// 同时传进的 timeout 指在多少毫秒后强制结束一次 behavior
const ion = new IonFlow(behaviors: Array, timeout = 60000: number) 
ion.push(msg) // 传入一条消息，IonFlow 实例将自动分发给各 behaviors 处理
```

## Behavior
Behavior 是这样的对象：
```js
const someBehavior = {
    match(msg): boolean, // 触发条件
    id(msg): PrimitiveValue, // 消息标识
    async flow(stream: IonFlowMessageStream) // 行为主体（程序流）
}
```

`id(msg)` 是一个函数，如果你想让两个 msg 交由同一次 flow 处理，则应确保对于这两个 msg 返回同一个 value。

`match(msg)` 是一个函数，它接受传入的消息并判断是否要开始这个 behavior；

一旦 `match(msg)` 返回一个 truthy value，`flow(stream)` 将被调用。

`flow(stream)` 的参数 `stream` 是一个 `IonFlowMessageStream` 实例，它有如下方法：

> 注意：虽然它是一个 `stream.Transform` 流，但不推荐使用以下标明的 API 以外的方法！

```js
class IonFlowMessageStream extends stream.Transform {
    get(): Promise // 获取下一条消息，用法： await stream.get() 将返回下一条消息
    end() // 结束接受消息，关闭消息流。这将用于你确定不再需要新消息时。
    timeout // 赋值将重置消息流关闭的计时器。消息流将在这时间（ms）过后关闭，之后不能再读取新消息。
    waste() // 将流转换为 flowing（“浪费”）状态，收到的消息将不会持久储存
    keep() // 将流转换为 paused（“存储”）状态，收到的消息将会储存并在队列中等待读取
}
```

例如，获取一条（已经收到或即将到达的）消息，你只需要：

```js
msg = await stream.get()
```

这样，获取消息就像同步函数一样简洁明了。

## Under the Hood
在底层，@ion-bot/flow 使用了 `stream.Transform` 流来传递消息。

每当调用 `msgGetter()` 时，都将判断流内是否有信息可读；

若有则直接返回，若没有则监听 `readable` 事件直到有信息可读为止。

对于每个 `id(msg)` 对应的消息，我们使用一个流来传递，并存储在一个 `Map<symbol, Map<any, IonFlowMessageStream>>`内。

---
_Source: https://npm.io/package/@ion-bot/flow · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._