chore(stream): refactor stream component

Signed-off-by: azjezz <azjezz@protonmail.com>

CHANGELOG.md

@@ -17,3 +17,4 @@
 * introduced a new `Psl\File` component.
 * refactor `Psl\Filesystem\write_file`, `Psl\Filesystem\append_file`, and `Psl\Filesystem\read_file` to use `Psl\File` component.
 * refactor `Psl\Shell\execute` to use `Psl\IO\Stream` component.
+* introduced a `Psl\IO\pipe(): (Psl\IO\CloseReadHandleInterface, Psl\IO\CloseWriteHandleInterface)` function to create a pair of handles, where writes to the WriteHandle can be read from the ReadHandle.

docs/component/io-stream.md

@@ -10,26 +10,22 @@
 
 ### `Psl\IO\Stream` Component
 
-#### `Functions`
-
-- [pipe](./../../src/Psl/IO/Stream/pipe.php#L25)
-
 #### `Classes`
 
-- [StreamCloseHandle](./../../src/Psl/IO/Stream/StreamCloseHandle.php#L13)
-- [StreamCloseReadHandle](./../../src/Psl/IO/Stream/StreamCloseReadHandle.php#L13)
-- [StreamCloseReadWriteHandle](./../../src/Psl/IO/Stream/StreamCloseReadWriteHandle.php#L13)
-- [StreamCloseSeekHandle](./../../src/Psl/IO/Stream/StreamCloseSeekHandle.php#L13)
-- [StreamCloseSeekReadHandle](./../../src/Psl/IO/Stream/StreamCloseSeekReadHandle.php#L13)
-- [StreamCloseSeekReadWriteHandle](./../../src/Psl/IO/Stream/StreamCloseSeekReadWriteHandle.php#L13)
-- [StreamCloseSeekWriteHandle](./../../src/Psl/IO/Stream/StreamCloseSeekWriteHandle.php#L13)
-- [StreamCloseWriteHandle](./../../src/Psl/IO/Stream/StreamCloseWriteHandle.php#L13)
-- [StreamReadHandle](./../../src/Psl/IO/Stream/StreamReadHandle.php#L13)
-- [StreamReadWriteHandle](./../../src/Psl/IO/Stream/StreamReadWriteHandle.php#L13)
-- [StreamSeekHandle](./../../src/Psl/IO/Stream/StreamSeekHandle.php#L13)
-- [StreamSeekReadHandle](./../../src/Psl/IO/Stream/StreamSeekReadHandle.php#L13)
-- [StreamSeekReadWriteHandle](./../../src/Psl/IO/Stream/StreamSeekReadWriteHandle.php#L13)
-- [StreamSeekWriteHandle](./../../src/Psl/IO/Stream/StreamSeekWriteHandle.php#L13)
-- [StreamWriteHandle](./../../src/Psl/IO/Stream/StreamWriteHandle.php#L13)
+- [CloseHandle](./../../src/Psl/IO/Stream/CloseHandle.php#L13)
+- [CloseReadHandle](./../../src/Psl/IO/Stream/CloseReadHandle.php#L13)
+- [CloseReadWriteHandle](./../../src/Psl/IO/Stream/CloseReadWriteHandle.php#L13)
+- [CloseSeekHandle](./../../src/Psl/IO/Stream/CloseSeekHandle.php#L13)
+- [CloseSeekReadHandle](./../../src/Psl/IO/Stream/CloseSeekReadHandle.php#L13)
+- [CloseSeekReadWriteHandle](./../../src/Psl/IO/Stream/CloseSeekReadWriteHandle.php#L13)
+- [CloseSeekWriteHandle](./../../src/Psl/IO/Stream/CloseSeekWriteHandle.php#L13)
+- [CloseWriteHandle](./../../src/Psl/IO/Stream/CloseWriteHandle.php#L13)
+- [ReadHandle](./../../src/Psl/IO/Stream/ReadHandle.php#L13)
+- [ReadWriteHandle](./../../src/Psl/IO/Stream/ReadWriteHandle.php#L13)
+- [SeekHandle](./../../src/Psl/IO/Stream/SeekHandle.php#L13)
+- [SeekReadHandle](./../../src/Psl/IO/Stream/SeekReadHandle.php#L13)
+- [SeekReadWriteHandle](./../../src/Psl/IO/Stream/SeekReadWriteHandle.php#L13)
+- [SeekWriteHandle](./../../src/Psl/IO/Stream/SeekWriteHandle.php#L13)
+- [WriteHandle](./../../src/Psl/IO/Stream/WriteHandle.php#L13)
 
 

docs/component/io.md

@@ -15,6 +15,7 @@
 - [error_handle](./../../src/Psl/IO/error_handle.php#L17)
 - [input_handle](./../../src/Psl/IO/input_handle.php#L17)
 - [output_handle](./../../src/Psl/IO/output_handle.php#L17)
+- [pipe](./../../src/Psl/IO/pipe.php#L24)
 
 #### `Interfaces`
 

src/Psl/IO/Stream/StreamCloseHandle.php → src/Psl/IO/Stream/CloseHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamCloseHandle implements IO\CloseHandleInterface
+final class CloseHandle implements IO\CloseHandleInterface
 {
     private IO\CloseHandleInterface $handle;
 

src/Psl/IO/Stream/StreamCloseReadHandle.php → src/Psl/IO/Stream/CloseReadHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamCloseReadHandle implements IO\CloseReadHandleInterface
+final class CloseReadHandle implements IO\CloseReadHandleInterface
 {
     use IO\ReadHandleConvenienceMethodsTrait;
 

src/Psl/IO/Stream/StreamCloseReadWriteHandle.php → src/Psl/IO/Stream/CloseReadWriteHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamCloseReadWriteHandle implements IO\CloseReadWriteHandleInterface
+final class CloseReadWriteHandle implements IO\CloseReadWriteHandleInterface
 {
     use IO\ReadHandleConvenienceMethodsTrait;
     use IO\WriteHandleConvenienceMethodsTrait;

src/Psl/IO/Stream/StreamCloseSeekHandle.php → src/Psl/IO/Stream/CloseSeekHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamCloseSeekHandle implements IO\CloseSeekHandleInterface
+final class CloseSeekHandle implements IO\CloseSeekHandleInterface
 {
     private IO\CloseSeekHandleInterface $handle;
 

src/Psl/IO/Stream/StreamCloseSeekReadHandle.php → src/Psl/IO/Stream/CloseSeekReadHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamCloseSeekReadHandle implements IO\CloseSeekReadHandleInterface
+final class CloseSeekReadHandle implements IO\CloseSeekReadHandleInterface
 {
     use IO\ReadHandleConvenienceMethodsTrait;
 

src/Psl/IO/Stream/StreamCloseSeekReadWriteHandle.php → src/Psl/IO/Stream/CloseSeekReadWriteHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamCloseSeekReadWriteHandle implements IO\CloseSeekReadWriteHandleInterface
+final class CloseSeekReadWriteHandle implements IO\CloseSeekReadWriteHandleInterface
 {
     use IO\ReadHandleConvenienceMethodsTrait;
     use IO\WriteHandleConvenienceMethodsTrait;

src/Psl/IO/Stream/StreamCloseSeekWriteHandle.php → src/Psl/IO/Stream/CloseSeekWriteHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamCloseSeekWriteHandle implements IO\CloseSeekWriteHandleInterface
+final class CloseSeekWriteHandle implements IO\CloseSeekWriteHandleInterface
 {
     use IO\WriteHandleConvenienceMethodsTrait;
 

src/Psl/IO/Stream/StreamCloseWriteHandle.php → src/Psl/IO/Stream/CloseWriteHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamCloseWriteHandle implements IO\CloseWriteHandleInterface
+final class CloseWriteHandle implements IO\CloseWriteHandleInterface
 {
     use IO\WriteHandleConvenienceMethodsTrait;
 

src/Psl/IO/Stream/StreamReadHandle.php → src/Psl/IO/Stream/ReadHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamReadHandle implements IO\ReadHandleInterface
+final class ReadHandle implements IO\ReadHandleInterface
 {
     use IO\ReadHandleConvenienceMethodsTrait;
 

src/Psl/IO/Stream/StreamReadWriteHandle.php → src/Psl/IO/Stream/ReadWriteHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamReadWriteHandle implements IO\ReadWriteHandleInterface
+final class ReadWriteHandle implements IO\ReadWriteHandleInterface
 {
     use IO\ReadHandleConvenienceMethodsTrait;
     use IO\WriteHandleConvenienceMethodsTrait;

src/Psl/IO/Stream/StreamSeekHandle.php → src/Psl/IO/Stream/SeekHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamSeekHandle implements IO\SeekHandleInterface
+final class SeekHandle implements IO\SeekHandleInterface
 {
     private IO\SeekHandleInterface $handle;
 

src/Psl/IO/Stream/StreamSeekReadHandle.php → src/Psl/IO/Stream/SeekReadHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamSeekReadHandle implements IO\SeekReadHandleInterface
+final class SeekReadHandle implements IO\SeekReadHandleInterface
 {
     use IO\ReadHandleConvenienceMethodsTrait;
 

src/Psl/IO/Stream/StreamSeekReadWriteHandle.php → src/Psl/IO/Stream/SeekReadWriteHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamSeekReadWriteHandle implements IO\SeekReadWriteHandleInterface
+final class SeekReadWriteHandle implements IO\SeekReadWriteHandleInterface
 {
     use IO\ReadHandleConvenienceMethodsTrait;
     use IO\WriteHandleConvenienceMethodsTrait;

src/Psl/IO/Stream/StreamSeekWriteHandle.php → src/Psl/IO/Stream/SeekWriteHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamSeekWriteHandle implements IO\SeekWriteHandleInterface
+final class SeekWriteHandle implements IO\SeekWriteHandleInterface
 {
     use IO\WriteHandleConvenienceMethodsTrait;
 

src/Psl/IO/Stream/StreamWriteHandle.php → src/Psl/IO/Stream/WriteHandle.php

@@ -10,7 +10,7 @@
 /**
  * @codeCoverageIgnore
  */
-final class StreamWriteHandle implements IO\WriteHandleInterface
+final class WriteHandle implements IO\WriteHandleInterface
 {
     use IO\WriteHandleConvenienceMethodsTrait;
 

src/Psl/IO/error_handle.php

@@ -18,7 +18,7 @@ function error_handle(): ?WriteHandleInterface
 {
     if (PHP_SAPI === "cli") {
         /** @psalm-suppress MissingThrowsDocblock */
-        return new Stream\StreamWriteHandle(
+        return new Stream\WriteHandle(
             Internal\open_resource('php://stderr', 'wb')
         );
     }

src/Psl/IO/input_handle.php

@@ -18,13 +18,13 @@ function input_handle(): ReadHandleInterface
 {
     if (PHP_SAPI === "cli") {
         /** @psalm-suppress MissingThrowsDocblock */
-        return new Stream\StreamReadHandle(
+        return new Stream\ReadHandle(
             Internal\open_resource('php://stdin', 'rb')
         );
     }
 
     /** @psalm-suppress MissingThrowsDocblock */
-    return new Stream\StreamReadHandle(
+    return new Stream\ReadHandle(
         Internal\open_resource('php://input', 'rb')
     );
 }

src/Psl/IO/output_handle.php

@@ -18,13 +18,13 @@ function output_handle(): WriteHandleInterface
 {
     if (PHP_SAPI === "cli") {
         /** @psalm-suppress MissingThrowsDocblock */
-        return new Stream\StreamWriteHandle(
+        return new Stream\WriteHandle(
             Internal\open_resource('php://stdout', 'wb')
         );
     }
 
     /** @psalm-suppress MissingThrowsDocblock */
-    return new Stream\StreamWriteHandle(
+    return new Stream\WriteHandle(
         Internal\open_resource('php://output', 'wb')
     );
 }

src/Psl/IO/Stream/pipe.php → src/Psl/IO/pipe.php

@@ -2,11 +2,10 @@
 
 declare(strict_types=1);
 
-namespace Psl\IO\Stream;
+namespace Psl\IO;
 
 use Psl;
 use Psl\Internal;
-use Psl\IO;
 
 use function error_get_last;
 use function stream_socket_pair;
@@ -18,9 +17,9 @@
 /**
  * Create a pair of handles, where writes to the WriteHandle can be read from the ReadHandle.
  *
- * @throws IO\Exception\BlockingException If unable to set one of the handles to non-blocking mode.
+ * @throws Exception\BlockingException If unable to set one of the handles to non-blocking mode.
  *
- * @return array{0: StreamCloseReadHandle, 1: StreamCloseWriteHandle}
+ * @return array{0: CloseReadHandleInterface, 1: CloseWriteHandleInterface}
  */
 function pipe(): array
 {
@@ -43,7 +42,7 @@ static function (): array {
     );
 
     return [
-        new StreamCloseReadHandle($sockets[0]),
-        new StreamCloseWriteHandle($sockets[1]),
+        new Stream\CloseReadHandle($sockets[0]),
+        new Stream\CloseWriteHandle($sockets[1]),
     ];
 }

src/Psl/Internal/Loader.php

@@ -432,7 +432,7 @@ final class Loader
         'Psl\IO\input_handle',
         'Psl\IO\output_handle',
         'Psl\IO\error_handle',
-        'Psl\IO\Stream\pipe',
+        'Psl\IO\pipe',
         'Psl\Class\exists',
         'Psl\Class\defined',
         'Psl\Class\has_constant',
@@ -607,21 +607,21 @@ final class Loader
         'Psl\Async\Awaitable',
         'Psl\Async\Deferred',
         'Psl\Async\Scheduler',
-        'Psl\IO\Stream\StreamCloseHandle',
-        'Psl\IO\Stream\StreamCloseReadHandle',
-        'Psl\IO\Stream\StreamCloseReadWriteHandle',
-        'Psl\IO\Stream\StreamCloseSeekHandle',
-        'Psl\IO\Stream\StreamCloseSeekReadHandle',
-        'Psl\IO\Stream\StreamCloseSeekReadWriteHandle',
-        'Psl\IO\Stream\StreamCloseSeekWriteHandle',
-        'Psl\IO\Stream\StreamCloseWriteHandle',
-        'Psl\IO\Stream\StreamReadHandle',
-        'Psl\IO\Stream\StreamReadWriteHandle',
-        'Psl\IO\Stream\StreamSeekHandle',
-        'Psl\IO\Stream\StreamSeekReadHandle',
-        'Psl\IO\Stream\StreamSeekReadWriteHandle',
-        'Psl\IO\Stream\StreamSeekWriteHandle',
-        'Psl\IO\Stream\StreamWriteHandle',
+        'Psl\IO\Stream\CloseHandle',
+        'Psl\IO\Stream\CloseReadHandle',
+        'Psl\IO\Stream\CloseReadWriteHandle',
+        'Psl\IO\Stream\CloseSeekHandle',
+        'Psl\IO\Stream\CloseSeekReadHandle',
+        'Psl\IO\Stream\CloseSeekReadWriteHandle',
+        'Psl\IO\Stream\CloseSeekWriteHandle',
+        'Psl\IO\Stream\CloseWriteHandle',
+        'Psl\IO\Stream\ReadHandle',
+        'Psl\IO\Stream\ReadWriteHandle',
+        'Psl\IO\Stream\SeekHandle',
+        'Psl\IO\Stream\SeekReadHandle',
+        'Psl\IO\Stream\SeekReadWriteHandle',
+        'Psl\IO\Stream\SeekWriteHandle',
+        'Psl\IO\Stream\WriteHandle',
         'Psl\IO\Internal\OptionalIncrementalTimeout',
         'Psl\File\Exception\AlreadyLockedException',
         'Psl\File\Exception\RuntimeException',

src/Psl/Shell/execute.php

@@ -85,8 +85,8 @@ function execute(
     }
     // @codeCoverageIgnoreEnd
 
-    $stdout = new Stream\StreamCloseReadHandle($pipes[1]);
-    $stderr = new Stream\StreamCloseReadHandle($pipes[2]);
+    $stdout = new Stream\CloseReadHandle($pipes[1]);
+    $stderr = new Stream\CloseReadHandle($pipes[2]);
 
     try {
         [$stdout_content, $stderr_content] = Async\concurrently([

tests/unit/IO/Stream/PipeTest.php → tests/unit/IO/PipeTest.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Psl\Tests\Unit\IO\Stream;
+namespace Psl\Tests\Unit\IO;
 
 use PHPUnit\Framework\TestCase;
 use Psl;
@@ -13,11 +13,7 @@ final class PipeTest extends TestCase
 {
     public function testReadWrite(): void
     {
-        /**
-         * @var \Psl\IO\Stream\StreamCloseReadHandle $read
-         * @var \Psl\IO\Stream\StreamCloseWriteHandle $write
-         */
-        [$read, $write] = IO\Stream\pipe();
+        [$read, $write] = IO\pipe();
 
         static::assertSame('', $read->readImmediately());
         $write->writeAll('hello');
@@ -37,11 +33,7 @@ public function testReadWrite(): void
 
     public function testReadWriteConcurrently(): void
     {
-        /**
-         * @var \Psl\IO\Stream\StreamCloseReadHandle $read
-         * @var \Psl\IO\Stream\StreamCloseWriteHandle $write
-         */
-        [$read, $write] = IO\Stream\pipe();
+        [$read, $write] = IO\pipe();
 
         $spy = new Psl\Ref('');
 
@@ -74,11 +66,7 @@ public function testReadWriteConcurrently(): void
 
     public function testReadFixedSize(): void
     {
-        /**
-         * @var \Psl\IO\Stream\StreamCloseReadHandle $read
-         * @var \Psl\IO\Stream\StreamCloseWriteHandle $write
-         */
-        [$read, $write] = IO\Stream\pipe();
+        [$read, $write] = IO\pipe();
 
         $write->writeAll('');
         $write->writeAll('hello!');
@@ -89,11 +77,7 @@ public function testReadFixedSize(): void
 
     public function testReadFixedSizeFromClosedPipe(): void
     {
-        /**
-         * @var \Psl\IO\Stream\StreamCloseReadHandle $read
-         * @var \Psl\IO\Stream\StreamCloseWriteHandle $write
-         */
-        [$read, $write] = IO\Stream\pipe();
+        [$read, $write] = IO\pipe();
 
         $write->writeAll('');
         $write->writeAll('hello!');
@@ -107,10 +91,7 @@ public function testReadFixedSizeFromClosedPipe(): void
 
     public function testReadAllTimedOut(): void
     {
-        /**
-         * @var \Psl\IO\Stream\StreamCloseReadHandle $read
-         */
-        [$read, $_write] = IO\Stream\pipe();
+        [$read, $_write] = IO\pipe();
 
         $this->expectException(IO\Exception\TimeoutException::class);
         $this->expectExceptionMessage('reached timeout while the handle is still not readable.');