chore: miscellaneous changes

docs/component/class.md

@@ -18,5 +18,6 @@
 - [has_method](./../../src/Psl/Class/has_method.php#L14)
 - [is_abstract](./../../src/Psl/Class/is_abstract.php#L14)
 - [is_final](./../../src/Psl/Class/is_final.php#L14)
+- [is_readonly](./../../src/Psl/Class/is_readonly.php#L14)
 
 

docs/component/env.md

@@ -17,11 +17,11 @@
 - [current_exec](./../../src/Psl/Env/current_exec.php#L12)
 - [get_var](./../../src/Psl/Env/get_var.php#L19)
 - [get_vars](./../../src/Psl/Env/get_vars.php#L14)
-- [join_paths](./../../src/Psl/Env/join_paths.php#L18)
+- [join_paths](./../../src/Psl/Env/join_paths.php#L20)
 - [remove_var](./../../src/Psl/Env/remove_var.php#L19)
 - [set_current_dir](./../../src/Psl/Env/set_current_dir.php#L16)
 - [set_var](./../../src/Psl/Env/set_var.php#L20)
-- [split_paths](./../../src/Psl/Env/split_paths.php#L16)
+- [split_paths](./../../src/Psl/Env/split_paths.php#L18)
 - [temp_dir](./../../src/Psl/Env/temp_dir.php#L21)
 
 

docs/component/network.md

@@ -19,7 +19,7 @@
 
 #### `Classes`
 
-- [Address](./../../src/Psl/Network/Address.php#L7)
+- [Address](./../../src/Psl/Network/Address.php#L10)
 - [SocketOptions](./../../src/Psl/Network/SocketOptions.php#L14)
 
 #### `Enums`

docs/component/option.md

@@ -12,9 +12,9 @@
 
 #### `Functions`
 
-- [from_nullable](./../../src/Psl/Option/from_nullable.php#L16)
-- [none](./../../src/Psl/Option/none.php#L12)
-- [some](./../../src/Psl/Option/some.php#L16)
+- [from_nullable](./../../src/Psl/Option/from_nullable.php#L18)
+- [none](./../../src/Psl/Option/none.php#L14)
+- [some](./../../src/Psl/Option/some.php#L18)
 
 #### `Classes`
 

docs/component/random-sequence.md

@@ -18,6 +18,6 @@
 
 - [MersenneTwisterPHPVariantSequence](./../../src/Psl/RandomSequence/MersenneTwisterPHPVariantSequence.php#L10)
 - [MersenneTwisterSequence](./../../src/Psl/RandomSequence/MersenneTwisterSequence.php#L10)
-- [SecureSequence](./../../src/Psl/RandomSequence/SecureSequence.php#L15)
+- [SecureSequence](./../../src/Psl/RandomSequence/SecureSequence.php#L13)
 
 

src/Psl/Async/Awaitable.php

@@ -27,7 +27,7 @@
  *
  * @implements PromiseInterface<T>
  */
-final class Awaitable implements PromiseInterface
+final readonly class Awaitable implements PromiseInterface
 {
     private State $state;
 
@@ -117,6 +117,8 @@ public static function error(Throwable $throwable): self
 
     /**
      * @return bool True if the operation has completed.
+     *
+     * @psalm-mutation-free
      */
     public function isComplete(): bool
     {

src/Psl/Async/Deferred.php

@@ -18,7 +18,7 @@
  *
  * @template T
  */
-final class Deferred
+final readonly class Deferred
 {
     /**
      * @var Internal\State<T>
@@ -62,6 +62,8 @@ public function error(Throwable $throwable): void
 
     /**
      * @return bool True if the operation has completed.
+     *
+     * @psalm-mutation-free
      */
     public function isComplete(): bool
     {
@@ -70,6 +72,8 @@ public function isComplete(): bool
 
     /**
      * @return Awaitable<T> The awaitable associated with this Deferred.
+     *
+     * @psalm-mutation-free
      */
     public function getAwaitable(): Awaitable
     {

src/Psl/Async/Internal/State.php

@@ -133,6 +133,8 @@ public function error(Throwable $throwable): void
 
     /**
      * Suppress the `Throwable`s thrown to the loop error handler if and operation error is not handled by a callback.
+     *
+     * @psalm-external-mutation-free
      */
     public function ignore(): void
     {
@@ -141,6 +143,8 @@ public function ignore(): void
 
     /**
      * @return bool True if the operation has completed.
+     *
+     * @psalm-mutation-free
      */
     public function isComplete(): bool
     {

src/Psl/Async/OptionalIncrementalTimeout.php

@@ -46,8 +46,6 @@ public function __construct(?float $timeout, Closure $handler)
      * If the timeout has already been exceeded, the handler is invoked, and its return value is provided.
      *
      * @return float|null The remaining time in seconds, null if no timeout is set, or the handler's return value if the timeout is exceeded.
-     *
-     * @external-mutation-free
      */
     public function getRemaining(): ?float
     {

src/Psl/Async/Scheduler.php

@@ -18,7 +18,7 @@
  *
  * @codeCoverageIgnore
  */
-final class Scheduler
+final readonly class Scheduler
 {
     private function __construct()
     {

src/Psl/Channel/ChannelInterface.php

@@ -16,7 +16,7 @@ interface ChannelInterface extends Countable
      *
      * @return null|positive-int
      *
-     * @mutation-free
+     * @psalm-mutation-free
      */
     public function getCapacity(): ?int;
 
@@ -30,7 +30,7 @@ public function close(): void;
     /**
      * Returns true if the channel is closed.
      *
-     * @mutation-free
+     * @psalm-mutation-free
      */
     public function isClosed(): bool;
 
@@ -39,7 +39,7 @@ public function isClosed(): bool;
      *
      * @return int<0, max>
      *
-     * @mutation-free
+     * @psalm-mutation-free
      */
     public function count(): int;
 
@@ -48,14 +48,14 @@ public function count(): int;
      *
      * Unbounded channels are never full.
      *
-     * @mutation-free
+     * @psalm-mutation-free
      */
     public function isFull(): bool;
 
     /**
      * Returns true if the channel is empty.
      *
-     * @mutation-free
+     * @psalm-mutation-free
      */
     public function isEmpty(): bool;
 }

src/Psl/Channel/Internal/BoundedChannelState.php

@@ -37,16 +37,24 @@ final class BoundedChannelState implements ChannelInterface
      */
     private array $messages = [];
 
+    /**
+     * @var int<0, max>
+     */
     private int $size = 0;
 
     public bool $closed = false;
 
+    /**
+     * @var positive-int
+     */
+    private readonly int $capacity;
+
     /**
      * @param positive-int $capacity
      */
-    public function __construct(
-        private int $capacity
-    ) {
+    public function __construct(int $capacity)
+    {
+        $this->capacity = $capacity;
     }
 
     public function __destruct()
@@ -71,7 +79,9 @@ public function waitForMessage(Suspension $suspension): void
     }
 
     /**
-     * {@inheritDoc}
+     * @return positive-int
+     *
+     * @psalm-mutation-free
      */
     public function getCapacity(): int
     {
@@ -99,31 +109,33 @@ public function close(): void
     }
 
     /**
-     * {@inheritDoc}
+     * @psalm-mutation-free
      */
     public function isClosed(): bool
     {
         return $this->closed;
     }
 
     /**
-     * {@inheritDoc}
+     * @return int<0, max>
+     *
+     * @psalm-mutation-free
      */
     public function count(): int
     {
         return $this->size;
     }
 
     /**
-     * {@inheritDoc}
+     * @psalm-mutation-free
      */
     public function isFull(): bool
     {
         return $this->capacity === $this->size;
     }
 
     /**
-     * {@inheritDoc}
+     * @psalm-mutation-free
      */
     public function isEmpty(): bool
     {
@@ -171,6 +183,7 @@ public function receive(): mixed
         }
 
         $item = array_shift($this->messages);
+        /** @psalm-suppress InvalidPropertyAssignmentValue - The size is always in sync with messages */
         $this->size--;
 
         if ($suspension = array_shift($this->waitingForSpace)) {

src/Psl/Channel/Internal/ChannelSideTrait.php

@@ -15,7 +15,11 @@ trait ChannelSideTrait
     protected UnboundedChannelState|BoundedChannelState $state;
 
     /**
-     * @return int<1, max>|null
+     * Returns the channel capacity if it’s bounded.
+     *
+     * @return null|positive-int
+     *
+     * @psalm-mutation-free
      */
     public function getCapacity(): ?int
     {
@@ -28,25 +32,36 @@ public function close(): void
         $this->state->close();
     }
 
+    /**
+     * @psalm-mutation-free
+     */
     public function isClosed(): bool
     {
         return $this->state->isClosed();
     }
 
     /**
      * @return int<0, max>
+     *
+     * @psalm-mutation-free
      */
     public function count(): int
     {
         /** @var int<0, max> */
         return $this->state->count();
     }
 
+    /**
+     * @psalm-mutation-free
+     */
     public function isFull(): bool
     {
         return $this->state->isFull();
     }
 
+    /**
+     * @psalm-mutation-free
+     */
     public function isEmpty(): bool
     {
         return $this->state->isEmpty();

src/Psl/Channel/Internal/UnboundedChannelState.php

@@ -44,9 +44,11 @@ public function waitForMessage(Suspension $suspension): void
     }
 
     /**
-     * {@inheritDoc}
+     * @return null
+     *
+     * @psalm-mutation-free
      */
-    public function getCapacity(): ?int
+    public function getCapacity(): null
     {
         return null;
     }
@@ -66,31 +68,33 @@ public function close(): void
     }
 
     /**
-     * {@inheritDoc}
+     * @psalm-mutation-free
      */
     public function isClosed(): bool
     {
         return $this->closed;
     }
 
     /**
-     * {@inheritDoc}
+     * @return int<0, max>
+     *
+     * @psalm-mutation-free
      */
     public function count(): int
     {
         return count($this->messages);
     }
 
     /**
-     * {@inheritDoc}
+     * @psalm-mutation-free
      */
     public function isFull(): bool
     {
         return false;
     }
 
     /**
-     * {@inheritDoc}
+     * @psalm-mutation-free
      */
     public function isEmpty(): bool
     {

src/Psl/Class/is_readonly.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Class;
+
+use ReflectionClass;
+
+/**
+ * Checks if class is read only.
+ *
+ * @param class-string $class_name
+ */
+function is_readonly(string $class_name): bool
+{
+    /** @psalm-suppress MissingThrowsDocblock */
+    return (new ReflectionClass($class_name))->isReadOnly();
+}

src/Psl/Collection/Exception/OutOfBoundsException.php

@@ -9,6 +9,9 @@
 
 final class OutOfBoundsException extends Exception\OutOfBoundsException implements ExceptionInterface
 {
+    /**
+     * @psalm-mutation-free
+     */
     public static function for(string|int $offset): OutOfBoundsException
     {
         return new self(Str\format('Key (%s) was out-of-bounds.', $offset));