pull-stream - npm Package Compare versions

Comparing version 2.28.2 to 2.28.3

package.json

 {
   "name": "pull-stream",
   "description": "minimal pull stream",
-  "version": "2.28.2",
+  "version": "2.28.3",
   "homepage": "https://github.com/dominictarr/pull-stream",
@@ -6,0 +6,0 @@ "repository": {

README.md

@@ -264,4 +264,50 @@ # pull-stream
 
+### handling end, error, and abort.
+
+in pull streams, any part of the stream (source, sink, or through)
+may terminate the stream. (this is the case with node streams too,
+but it's not handled well).
+
+#### source: end, error
+
+A source may end (`cb(true)` after read) or error (`cb(error)` after read)
+After ending, the source *must* never `cb(null, data)`
+
+#### sink: abort
+
+Sinks do not normally end the stream, but if they decide they do
+not need any more data they may "abort" the source by calling `read(true, cb)`.
+A abort (`read(true, cb)`) may be called before a preceding read call
+has called back.
+
+### handling end/abort/error in through streams
+
+Rules for implementing `read` in a through stream:
+1) Sink wants to stop. sink aborts the through
+
+    just forward the exact read() call to your source,
+    any future read calls should cb(true).
+
+2) We want to stop. (abort from the middle of the stream)
+
+    abort your source, and then cb(true) to tell the sink we have ended.
+    If the source errored during abort, end the sink by cb read with `cb(err)`.
+    (this will be an ordinary end/error for the sink)
+
+3) Source wants to stop. (`read(null, cb) -> cb(err||true)`)
+
+    forward that exact callback towards the sink chain,
+    we must respond to any future read calls with `cb(err||true)`.
+
+In none of the above cases data is flowing!
+4) If data is flowing (normal operation:   `read(null, cb) -> cb(null, data)`
+
+    forward data downstream (towards the Sink)
+    do none of the above!
+
+There either is data flowing (4) OR you have the error/abort cases (1-3), never both.
+
+
 ## License
 
 MIT

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

54688

increased by3%

Number of lines in readme file

313

increased by17.23%

No dependency changes