Merge pull request #97 from clue-labs/custom-events

Explicitly allow custom events and exclude any semantics

README.md

@@ -53,6 +53,15 @@ read-only streams and the readable side of duplex streams.
 Besides defining a few methods, this interface also implements the
 `EventEmitterInterface` which allows you to react to certain events.
 
+Every implementation of this interface MUST follow these event semantics in
+order to be considered a well-behaving stream.
+
+> Note that higher-level implementations of this interface may choose to
+  define additional events with dedicated semantics not defined as part of
+  this low-level stream specification. Conformance with these event semantics
+  is out of scope for this interface, so you may also have to refer to the
+  documentation of such a higher-level implementation.
+
 #### data event
 
 The `data` event will be emitted whenever some data was read/received
@@ -383,6 +392,15 @@ write-only streams and the writable side of duplex streams.
 Besides defining a few methods, this interface also implements the
 `EventEmitterInterface` which allows you to react to certain events.
 
+Every implementation of this interface MUST follow these event semantics in
+order to be considered a well-behaving stream.
+
+> Note that higher-level implementations of this interface may choose to
+  define additional events with dedicated semantics not defined as part of
+  this low-level stream specification. Conformance with these event semantics
+  is out of scope for this interface, so you may also have to refer to the
+  documentation of such a higher-level implementation.
+
 #### drain event
 
 The `drain` event will be emitted whenever the write buffer became full
@@ -703,6 +721,15 @@ Besides defining a few methods, this interface also implements the
 `EventEmitterInterface` which allows you to react to the same events defined
 on the `ReadbleStreamInterface` and `WritableStreamInterface`.
 
+Every implementation of this interface MUST follow these event semantics in
+order to be considered a well-behaving stream.
+
+> Note that higher-level implementations of this interface may choose to
+  define additional events with dedicated semantics not defined as part of
+  this low-level stream specification. Conformance with these event semantics
+  is out of scope for this interface, so you may also have to refer to the
+  documentation of such a higher-level implementation.
+
 See also [`ReadableStreamInterface`](#readablestreaminterface) and
 [`WritableStreamInterface`](#writablestreaminterface) for more details.
 

src/DuplexStreamInterface.php

@@ -15,6 +15,15 @@
  * `EventEmitterInterface` which allows you to react to the same events defined
  * on the `ReadbleStreamInterface` and `WritableStreamInterface`.
  *
+ * Every implementation of this interface MUST follow these event semantics in
+ * order to be considered a well-behaving stream.
+ *
+ * > Note that higher-level implementations of this interface may choose to
+ *   define additional events with dedicated semantics not defined as part of
+ *   this low-level stream specification. Conformance with these event semantics
+ *   is out of scope for this interface, so you may also have to refer to the
+ *   documentation of such a higher-level implementation.
+ *
  * @see ReadableStreamInterface
  * @see WritableStreamInterface
  */

src/ReadableStreamInterface.php

@@ -144,6 +144,15 @@
  *     non-writable AND non-readable mode, see also `isWritable()`.
  *     Note that this event should not be confused with the `end` event.
  *
+ * Every implementation of this interface MUST follow these event semantics in
+ * order to be considered a well-behaving stream.
+ *
+ * > Note that higher-level implementations of this interface may choose to
+ *   define additional events with dedicated semantics not defined as part of
+ *   this low-level stream specification. Conformance with these event semantics
+ *   is out of scope for this interface, so you may also have to refer to the
+ *   documentation of such a higher-level implementation.
+ *
  * @see EventEmitterInterface
  */
 interface ReadableStreamInterface extends EventEmitterInterface

src/WritableStreamInterface.php

@@ -120,6 +120,15 @@
  *     non-writable AND non-readable mode, see also `isReadable()`.
  *     Note that this event should not be confused with the `end` event.
  *
+ * Every implementation of this interface MUST follow these event semantics in
+ * order to be considered a well-behaving stream.
+ *
+ * > Note that higher-level implementations of this interface may choose to
+ *   define additional events with dedicated semantics not defined as part of
+ *   this low-level stream specification. Conformance with these event semantics
+ *   is out of scope for this interface, so you may also have to refer to the
+ *   documentation of such a higher-level implementation.
+ *
  * @see EventEmitterInterface
  * @see DuplexStreamInterface
  */