From 69a8e34003bdbc0c48e1079fb2c6a13f109011f1 Mon Sep 17 00:00:00 2001 From: Sam Roberts Date: Wed, 6 Feb 2019 15:37:40 -0800 Subject: doc: clarify effect of stream.destroy() on write() PR-URL: https://github.com/nodejs/node/pull/25973 Reviewed-By: Matteo Collina Reviewed-By: Daniel Bevenius --- doc/api/stream.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index 9e20370528..14bc50d310 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -369,12 +369,17 @@ See also: [`writable.uncork()`][]. added: v8.0.0 --> -* `error` {Error} +* `error` {Error} Optional, an error to emit with `'error'` event. * Returns: {this} -Destroy the stream, and emit the passed `'error'` and a `'close'` event. +Destroy the stream. Optionally emit an `'error'` event, and always emit +a `'close'` event. After this call, the writable stream has ended and subsequent calls to `write()` or `end()` will result in an `ERR_STREAM_DESTROYED` error. +This is a destructive and immediate way to destroy a stream. Previous calls to +`write()` may not have drained, and may trigger an `ERR_STREAM_DESTROYED` error. +Use `end()` instead of destroy if data should flush before close, or wait for +the `'drain'` event before destroying the stream. Implementors should not override this method, but instead implement [`writable._destroy()`][writable-_destroy]. -- cgit v1.2.3