JavaScript 中的 Stream API 03（可写流 WritableStream 等 API）

Stream API

可写流 API

WritableStream

WritableStream 可写流的实例创建: new WritableStream(underlyingSink, queuingStrategy)

• underlyingSink(可选): 该参数为一个包含定义可写流具体的行为的属性与方法 → 主要包含如下

  • strat(contoller):
    • 该方法会在可写流实例对象被创建时立即执行
    • 其中，方法传递进来的 controller 就为 WritableStreamDefaultController 实例对象
  • write(chunk,contoller):
    • 当一个新的数据块 chunk 准备写入底层接收器时，会执行该方法，里面具体编写什么代码逻辑由开发者决定
    • 即: 可以理解为当我们执行了 WritableStreamDefaultWriter 上的 write 写入数据块时，就会触发该方法
  • close(controller):
    • 如果应用程序发出已经完成所有分块的写入信号时，会执行该方法
    • 如完成了所有流的写入操作后执行 WritableStreamDefaultWriter 上的 close 关闭可写流时触发
  • abort(reason):
    • 如果应用程序发出希望立即关闭流且移交至错误状态的信号，将调用该方法
    • 如调用了 WritableStreamDefaultWriter 上的 abort 中止流的数据写入方法时（tip: 会立即返回一个错误状态，且丢弃所有已入队的数据）

• queuingStrategy(可选): 与上面可读流一样，略...

• + 基本创建
  // -- 可写流实例对象的创建
      const writableStream = new WritableStream({
          start(controller) {
              // 可选：流开始时的初始化逻辑  
              console.log('Stream started');
          },
          write(chunk, controller) {
              // 处理写入的数据块  
              console.log('Received chunk:', chunk);
              // 假设这里只是简单地打印出来，实际应用中可能涉及更复杂的处理  
              // 如果处理成功，不需要做任何事情；如果失败，可以调用 controller.error()  
          },
          close() {
              // 清理工作，当流被关闭时调用  
              console.log('Stream closed');
          },
          abort(reason) {
              // 错误处理，当流被异常终止时调用  
              console.error('Stream aborted:', reason);
          }
      });
  
  // -- 可写流写入器部分
      const writer = writableStream.getWriter();
  
      // 写入数据块  
      writer.write('Hello, world!').then(() => {
          console.log('Chunk written successfully');
          // 继续写入更多数据块或调用 writer.close() 来关闭流  
      }).catch(err => {
          console.error('Error writing chunk:', err);
          // 处理错误，可能需要调用 writer.abort() 来终止流  
      });
  
      // 当所有数据都写入完毕后，关闭流  
      writer.close().then(() => {
          console.log('Stream closed successfully');
      }).catch(err => {
          console.error('Error closing stream:', err);
      });
  

WritableStreamDefaultWriter

该 API 是由 WritableStream 实例对象上 getWriter 方法返回的对象，且一旦创建就会将该返回的 writer 对象锁定到 WritableStream 上

与 ReadableStreamDefaultReader 一样该 API 也可以通过对应构造函数创建对应的 writer 对象

• // 构建该实例对象时，需要传入一个 WritableStream 可写流对象 → 来创建对应的 writer 对象并锁定在该 stream 流上
  const writer = new WritableStreamDefaultWriter(stream)
  

实例属性:

• closed: 该属性返回一个 promise 对象 → 当流在正常关闭时兑现该 promise → 当流在抛出错误或者 writer 的锁被释放时拒绝

  • writer.closed.then(() => {
        // -- 流关闭时兑现
    }).catch(() => {
        // -- 流在抛出错误或 writer 锁被释放时拒绝
    })
    

• desiredSize: 属性返回填充满内部队列需要的大小值 → 如果无法成功写入流（由于流发生错误或者中止入队），则该值为null，如果流关闭，则该值为 0

• ready: 该属性返回一个 promise 对象 → 当流填充内部队列所需大小从非正数变为正数时兑现（即上面的 desiredSize 属性，表明它不需要应用背压）

实例方法:

• abort: 该方法用于中止对应的可写流，表示生产者将不能在继续向流中写入数据 → 会立即返回一个错误状态，并丢弃所有已入队的数据 → abort(reason)

• close: 该方法用于关闭对应的可写流 → 当你完成了所有数据的写入操作，并希望关闭流时，就可以使用该方法 → 关闭流是一个重要的步骤，因为它可以确保所有待处理的数据都被处理并发送到其目的地，同时也告诉流的接收方不再有任何数据会被发送

  • WritableStreamDefaultWriter.close().then(result => {  
      // 关闭操作成功完成  
    }).catch(err => {  
      // 关闭操作失败  
    });
    

  • // 假设我们有一个WritableStream实例叫做stream  
    const writer = stream.getWriter();  
      
    // 写入一些数据（这里只是示例，实际写入数据会依赖于你的具体需求）  
    writer.write("Hello, World!").then(() => {  
      // 数据写入成功，现在关闭流  
      return writer.close();  
    }).then(() => {  
      console.log('流已成功关闭');  
    }).catch(err => {  
      console.error('写入或关闭流时发生错误:', err);  
    });
    

• write: 用于将数据写入流中，返回一个 promise 用于判断是否写入成功

• releaseLock: 该方法用于是否 write 对流的锁定

WritableStreamDefaultController

该 API 用于控制 WritableStream 状态的控制器 → 与 ReadableStreamDefaultController 类似，该 API 也没有对应的构造函数 → 同理也是当 WritableStream 构造时，会给对应的配置函数提供一个对应的 WritableStreamDefaultController 实例对象

实例属性:

• signal

实例方法:

• error: 用于抛出错误并关闭一个流（这个方法很少被使用，因为通常从底层接收器的一个方法返回一个拒绝的 promise 足矣 → 但是，在响应与底层接收器交互的正常生命周期之外的事件中，使用 error() 来立即关闭一个流则会很有用） → error(message)

  • controller.error('My error is broken') 
    

该 API 具体的用法，在 WritableStream 中进行示例