stream · Magic_sword2

[TOC] # 简介说明 原文链接： - [stream](https://github.com/nodejs/node/blob/main/doc/api/stream.md) ``` 版本：stream 作用：处理流式数据的抽象接口 ``` # stream # *finished() ***** 当流不再可读、可写、或遇到错误、或过早关闭事件时，则该函数会获得通知 ### 示例内容 1. 举例说明 ``` const { finished } = require('stream'); const rs = fs.createReadStream('archive.tar'); finished(rs, (err) => { if (err) { console.error('流读取失败', err); } else { console.log('流已完成读取'); } }); rs.resume(); // 排空流。 ``` # *pipeline() ***** 使用管道传送多个流，并转发错误和正确地清理，当管道完成时提供回调。 ### 示例内容 1. 举例说明 ``` const { pipeline } = require('stream'); const fs = require('fs'); const zlib = require('zlib'); // 使用 pipeline API 轻松地将一系列的流通过管道一起传送，并在管道完全地完成时获得通知。 // 使用 pipeline 可以有效地压缩一个可能很大的 tar 文件： pipeline( fs.createReadStream('archive.tar'), zlib.createGzip(), fs.createWriteStream('archive.tar.gz'), (err) => { if (err) { console.error('管道传送失败', err); } else { console.log('管道传送成功'); } } ); ``` 2. Promise 化 ``` const pipeline = util.promisify(stream.pipeline); async function run() { await pipeline( fs.createReadStream('archive.tar'), zlib.createGzip(), fs.createWriteStream('archive.tar.gz') ); console.log('管道传送成功'); } run().catch(console.error); ``` # stream.Writable # destroyed ***** 判断流是否销毁 # writable ***** 调用 write()方法是否是安全的 # writableEnded ***** 在调用了 end() 方法之后为 true。此属性不表明数据是否已刷新，对此请使用 writable.writableFinished # writableFinished ***** 在触发 'finish' 事件之前该属性被立即设置为 true # writableHighWaterMark ***** 返回构造可写流时传入的 highWaterMark 的值 # writableObjectMode ***** 获取用于给定 Writable 流的 objectMode 属性 # writableLength ***** 此属性包含准备写入的队列中的字节数（或对象）。该值提供有关 highWaterMark 状态的内省数据。 # [eve]-on() ***** 监听事件 ### 参数说明 eventName: * 类型：字符层 * 默认值：无 * 描述：事件类型 * 可选值：[ close | drain | error | finish | pipe | unpipe ] - close: 当流或其底层资源（比如文件描述符）被关闭时触发。表明不会再触发其他事件，也不会再发生操作。 - drain: 如果调用 stream.write(chunk) 返回 false，则当可以继续写入数据到流时会触发 'drain' 事件。 - error: 如果在写入或管道数据时发生错误，则会触发 'error' 事件 - finish: 调用 stream.end() 且缓冲数据都已传给底层系统之后触发。 - pipe: 当在可读流上调用 stream.pipe() 方法时会发出 'pipe' 事件，并将此可写流添加到其目标集。 - unpipe: 当可读流通过管道流向可写流发生错误时，也会触发此事件。 # cork() ***** 强制把所有写入的数据都缓冲到内存中 # uncork() ***** 将调用 stream.cork() 后缓冲的所有数据输出到目标。 # setDefaultEncoding() ***** 为可写流设置默认的 encoding。 ### 参数说明 encoding: * 类型：字符串 * 默认值：无 * 描述：默认的字符编码 * 可选值：[ ] # write() ***** 为可写流设置默认的 encoding。 ### 参数说明 chunk: * 类型：字符串 * 默认值：无 * 描述：要写入的数据 * 可选值：[ ] encoding: * 类型：字符串 * 默认值：无 * 描述：如果 chunk 是字符串，则指定字符编码 * 可选值：[ ] callback: * 类型：字符串 * 默认值：无 * 描述：当数据块被输出到目标后的回调函数 * 可选值：[ ] # end() ***** 调用 writable.end() 表明已没有数据要被写入可写流。 ### 参数说明 chunk: * 类型：对象 * 默认值：无 * 描述：要写入的数据 * 可选值：[ ] encoding: * 类型：字符串 * 默认值：无 * 描述：如果 chunk 是字符串，则指定字符编码。 * 可选值：[ ] callback: * 类型：fn * 默认值：无 * 描述：回调函数 * 可选值：[ ] # destroy() ***** 销毁流 ### 参数说明 error: * 类型：对象 * 默认值：无 * 描述：使用 'error' 事件触发的错误。 * 可选值：[ ] # stream.Readable # [Symbol.asyncIterator] ***** 异步迭代 ### 示例内容 1. 举例说明 ``` const fs = require('fs'); async function print(readable) { readable.setEncoding('utf8'); let data = ''; for await (const chunk of readable) { data += chunk; } console.log(data); console.log("======="); } print(fs.createReadStream('./index.js')).catch(console.error); ``` # readableEncoding ***** 获取用于给定可读流的 encoding 属性。可以使用 readable.setEncoding() 方法设置 encoding 属性。 # readableObjectMode ***** 获取用于给定可读流的 objectMode 属性。 # readableLength ***** 此属性包含准备读取的队列中的字节数（或对象数）。该值提供有关 highWaterMark 状态的内省数据 # readableHighWaterMark ***** 返回构造可读流时传入的 highWaterMark 的值。 # readableFlowing ***** 此属性反映“可读流”的当前状态 # readableEnded ***** 当 'end' 事件被触发时变为 true。 # readable ***** 如果可以安全地调用 readable.read()，则为 true。 # destroyed ***** 在调用 readable.destroy() 之后为 true。 # *from() ***** 从生成器中生成流对象 ### 示例内容 1. 举例说明 ``` const { Readable } = require('stream'); async function * generate() { yield 'hello'; yield 'streams'; } const readable = Readable.from(generate()); readable.on('data', (chunk) => { console.log(chunk); }); ``` # [eve]-on() ***** 监听事件 ### 参数说明 eventName: * 类型：字符层 * 默认值：无 * 描述：事件类型 * 可选值：[ close | data | end | error | pause | resume ] - close: 流或其底层资源（比如文件描述符）被关闭时触发 'close' 事件 - data: 当流将数据块传送给消费者后触发。当调用 readable.pipe()， readable.resume() 或绑定监听器到 'data' 事件时，流会转换到流动模式。 - end: 当流中没有数据可供消费时触发 - error: 'error' 事件可能随时由 Readable 实现触发 - pause: 当调用 stream.pause() 并且 readsFlowing 不为 false 时，就会触发 'pause' 事件。 - resume: 当调用 stream.resume() 并且 readsFlowing 不为 true 时，将会触发 'resume' 事件。 # isPaused() ***** 返回可读流当前的操作状态 # pause() ***** 使流动模式的流停止触发 'data' 事件，并切换出流动模式 # pipe() ***** 绑定可写流到可读流，将可读流自动切换到流动模式，并将可读流的所有数据推送到绑定的可写流 ### 参数说明 destination: * 类型：Writable * 默认值：无 * 描述：数据写入的目标。 * 可选值：[ ] options : * 类型：对象 * 默认值：无 * 描述：操作配置参数 * 可选值：[ ] # read() ***** 从内部缓冲拉取并返回数据 ### 参数说明 size : * 类型：整型 * 默认值：无 * 描述：要读取的数据的字节数 * 可选值：[ ] ### 示例内容 1. 举例说明 ``` const readable = getReadableStreamSomehow(); readable.on('readable', () => { let chunk; while (null !== (chunk = readable.read())) { console.log(`接收到 ${chunk.length} 字节的数据`); } }); ``` # resume() ***** 将被暂停的可读流恢复触发 'data' 事件，并将流切换到流动模式。 # setEncoding() ***** 为从可读流读取的数据设置字符编码。 ### 参数说明 encoding : * 类型：字符串 * 默认值：无 * 描述：字符编码 * 可选值：[ ] # unpipe() ***** 解绑之前使用 stream.pipe() 方法绑定的可写流。 ### 参数说明 destination : * 类型：字符串 * 默认值：无 * 描述：要移除管道的可写流 * 可选值：[ ] # unshift() ***** 将数据块推回内部缓冲，最好在执行读取的过程中避免调用 readable.unshift() ### 参数说明 chunk : * 类型：字符串 * 默认值：无 * 描述：要推回可读队列的数据块 * 可选值：[ ] destination : * 类型：字符串 * 默认值：无 * 描述：要移除管道的可写流 * 可选值：[ ] # wrap() ***** 可以使用 readable.wrap() 创建老版本的流作为数据源 ### 参数说明 stream: * 类型：stream * 默认值：无 * 描述：老版本的可读流 * 可选值：[ ] # destroy() ***** 销毁流。 ### 参数说明 error: * 类型：对象 * 默认值：无 * 描述：使用 'error' 事件触发的错误。 * 可选值：[ ] # stream.Duplex # [new]-Duplex() ***** 双工流是同时实现 Readable 和 Writable 接口的流 # stream.Transform # [new]-Transform() ***** 转换流是 Duplex 流，其中输出以某种方式与输入相关 ### 参数说明 options: * 类型：object * 默认值：无 * 描述：配置参数 * 可选值：[ ] - highWaterMark : 最大读取字节数量 - transform : 转换函数(buf, enc, next)