filehandle.writer([options])

• options <Object>
  • autoClose <boolean> 在写入器结束或失败时关闭文件句柄。默认值：false。
  • start <number> 写入开始时的字节偏移量。指定时，写入将使用明确的位置。默认值： 当前文件位置。
  • limit <number> 写入器将接受的最大字节数。超出限制的异步写入（write()、writev()）会被拒绝，并返回 ERR_OUT_OF_RANGE。同步写入（writeSync()、writevSync()）会返回 false。**默认值：**无限制。
  • chunkSize <number> 用于同步写操作的最大字节块大小。大于此阈值的写入将回退到异步 I/O。将其设置为与读取器的 chunkSize 匹配，以获得最佳 pipeTo() 性能。默认值： 131072（128 KB）。
• 返回：<Object>
  • write(chunk[, options]) <Function> 返回 Promise。 可接受 Uint8Array、Buffer或字符串（UTF-8编码）。
    • chunk <Buffer> | <TypedArray> | <DataView> | <string>
    • options <Object>
      • signal <AbortSignal> 如果信号已经被中止，写操作会直接以 AbortError 拒绝，而不会执行 I/O。
  • writev(chunks[, options]) <Function> 返回 Promise。通过单一的 writev() 系统调用使用散射/收集 I/O。支持混合的 Uint8Array/字符串数组。
    • chunks <TypedArray> | <DataView>
    • options <Object>
      • signal <AbortSignal> 如果信号已经被中止，写操作会直接以 AbortError 拒绝，而不会执行 I/O。
  • writeSync(chunk) <Function> 返回 <boolean>。尝试同步写入。如果写入成功，返回 true；如果调用者应退回到异步 write()，返回 false。在以下情况下返回 false：写入器已关闭/出错、异步操作正在进行、块超过 chunkSize，或写入会超过 limit。
    • chunk <Buffer> | <TypedArray> | <DataView> | <string>
  • writevSync(chunks) <Function> 返回 <boolean>。同步批量写入。与 writeSync() 相同的回退语义。
    • chunks <TypedArray> | <DataView>
  • end([options]) <Function> 返回 Promise 写入的总字节数。自称：如果已经关闭，返回 totalBytesWritten;如果已经关闭，返回待处理的承诺。如果作者处于错误状态，则拒绝。
    • options <Object>
      • signal <AbortSignal> 如果信号已经被中止，end() 会以 AbortError 拒绝，并且写入器保持开启状态。
  • endSync() <Function> 成功时返回写入的总字节数 <number> | <number>，如果写入器出错或有异步操作正在进行，则返回 -1。已经关闭时幂等。
  • fail(reason) <Function> 将写入器置于终端错误状态。同步。如果写入器已关闭或发生错误，则此操作无效。如果 autoClose 为真，则同步关闭文件句柄。

返回一个由此文件句柄支持的 node:stream/iter 写入器。

🌐 Return a node:stream/iter writer backed by this file handle.

作者支持 Symbol.asyncDispose 和 Symbol.dispose：

🌐 The writer supports both Symbol.asyncDispose and Symbol.dispose:

• await using w = fh.writer() — 如果写入器仍然打开（没有调用 end()），asyncDispose 会调用 fail()。如果 end() 正在等待，它会等到完成。
• using w = fh.writer() — 无条件调用 fail()。

writeSync() 和 writevSync() 方法启用了 stream/iter pipeTo() 使用的 try-sync 快路径。当读者的块大小与写者的 chunkSize 匹配时，pipeTo() 管道中的所有写入都会同步完成，且无任何 promise 开销。

🌐 The writeSync() and writevSync() methods enable the try-sync fast path used by stream/iter pipeTo(). When the reader's chunk size matches the writer's chunkSize, all writes in a pipeTo() pipeline complete synchronously with zero promise overhead.

此功能仅在启用 --experimental-stream-iter 标志时可用。

🌐 This function is only available when the --experimental-stream-iter flag is enabled.

import { open } from 'node:fs/promises';
import { from, pipeTo } from 'node:stream/iter';
import { compressGzip } from 'node:zlib/iter';

// Async pipeline
const fh = await open('output.gz', 'w');
await pipeTo(from('Hello!'), compressGzip(), fh.writer({ autoClose: true }));

// Sync pipeline with limit
const src = await open('input.txt', 'r');
const dst = await open('output.txt', 'w');
const w = dst.writer({ limit: 1024 * 1024 }); // Max 1 MB
await pipeTo(src.pull({ autoClose: true }), w);
await w.end();
await dst.close();const { open } = require('node:fs/promises');
const { from, pipeTo } = require('node:stream/iter');
const { compressGzip } = require('node:zlib/iter');

async function run() {
  // Async pipeline
  const fh = await open('output.gz', 'w');
  await pipeTo(from('Hello!'), compressGzip(), fh.writer({ autoClose: true }));

  // Sync pipeline with limit
  const src = await open('input.txt', 'r');
  const dst = await open('output.txt', 'w');
  const w = dst.writer({ limit: 1024 * 1024 }); // Max 1 MB
  await pipeTo(src.pull({ autoClose: true }), w);
  await w.end();
  await dst.close();
}

run().catch(console.error);拷贝