Merge branch 'develop'

* develop:
  specify next release
  update documentation
  make Stop and Failed internal classes
  use continuation pattern when pinging
  CS

Author: Baptouuuu

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 4.0.0 - 2024-03-10
+
+### Changed
+
+- When the ping callable is called it must return a `Innmind\FileWatch\Continuation`
+
+### Removed
+
+- `Innmind\FileWatch\Stop`
+- `Innmind\FileWatch\Failed`
+
 ## 3.2.0 - 2023-11-12
 
 ### Added

README.md

@@ -35,27 +35,23 @@ $watch = Factory::build(
     new Usleep,
 );
 
-$count = $watch(Path::of('/to/some/file/or/folder'))(0, function(int $count): Either {
+$count = $watch(Path::of('/to/some/file/or/folder'))(0, function(int $count, Continuation $continuation): Continuation {
     // this function is called every time the file is modified
     ++$count;
 
     if ($count === 42) {
-        // by returning a Stop instance on the left side it will instruct to
-        // stop watching for changes and the value in the Stop will be moved on
-        // the right side to the caller
-        return Either::left(Stop::of($count));
+        // This will stop watching the folder for changes and return the count
+        return $continuation->stop($count);
     }
 
-    if ($forSomeReason) {
-        // by returning a left value it will stop watching for changes and the
-        // Either will be returned as is to the caller
-        return Either::left($someReason);
-    }
-
-    // by returning a right side it will instruct to continue watching for changes
-    // and the value will be passed to this callable the next time it's called
-    return Either::right($count);
-});
+    // This will instruct to continue watching for changes and the value will be
+    // passed to this callable the next time it's called
+    return $continuation->continue($count);
+})->match(
+    static fn(int $count) => $count, // always 42 as it's the stopping value
+    static fn() => throw new \RuntimeException('Failed to watch for changes'),
+);
 ```
 
-**Note**: The function may be called multiple times for an single change due to the way `tail` and `stat` works.
+> [!WARNING]
+> The function may be called multiple times for an single change due to the way `tail` and `stat` works.

src/Continuation.php

@@ -0,0 +1,84 @@
+<?php
+declare(strict_types = 1);
+
+namespace Innmind\FileWatch;
+
+use Innmind\FileWatch\Continuation\State;
+
+/**
+ * @psalm-immutable
+ * @template T
+ */
+final class Continuation
+{
+    private State $state;
+    /** @var T */
+    private mixed $value;
+
+    /**
+     * @param T $value
+     */
+    private function __construct(State $state, mixed $value)
+    {
+        $this->state = $state;
+        $this->value = $value;
+    }
+
+    /**
+     * @psalm-pure
+     * @internal
+     * @template A
+     *
+     * @param A $value
+     *
+     * @return self<A>
+     */
+    public static function of(mixed $value): self
+    {
+        return new self(State::continue, $value);
+    }
+
+    /**
+     * @template U
+     *
+     * @param U $value
+     *
+     * @return self<U>
+     */
+    public function continue(mixed $value): self
+    {
+        return new self(State::continue, $value);
+    }
+
+    /**
+     * @template U
+     *
+     * @param U $value
+     *
+     * @return self<U>
+     */
+    public function stop(mixed $value): self
+    {
+        return new self(State::stop, $value);
+    }
+
+    /**
+     * @internal
+     * @template R
+     *
+     * @param callable(T): R $continue
+     * @param callable(T): R $stop
+     *
+     * @return R
+     */
+    public function match(
+        callable $continue,
+        callable $stop,
+    ): mixed {
+        /** @psalm-suppress ImpureFunctionCall */
+        return match ($this->state) {
+            State::continue => $continue($this->value),
+            State::stop => $stop($this->value),
+        };
+    }
+}

src/Continuation/State.php

@@ -0,0 +1,13 @@
+<?php
+declare(strict_types = 1);
+
+namespace Innmind\FileWatch\Continuation;
+
+/**
+ * @psalm-immutable
+ */
+enum State
+{
+    case continue;
+    case stop;
+}

src/Failed.php

@@ -3,18 +3,18 @@
 
 namespace Innmind\FileWatch;
 
-use Innmind\Immutable\Either;
+use Innmind\Immutable\Maybe;
 
 interface Ping
 {
     /**
      * @template C
-     * @template L
+     * @template R
      *
      * @param C $carry
-     * @param callable(C): Either<L|Stop<C>, C> $ping
+     * @param callable(R|C, Continuation<R|C>): Continuation<R> $ping
      *
-     * @return Either<Failed|L, C>
+     * @return Maybe<R|C>
      */
-    public function __invoke(mixed $carry, callable $ping): Either;
+    public function __invoke(mixed $carry, callable $ping): Maybe;
 }

src/Ping.php

@@ -0,0 +1,11 @@
+<?php
+declare(strict_types = 1);
+
+namespace Innmind\FileWatch\Ping;
+
+/**
+ * @internal
+ */
+final class Failed
+{
+}

src/Ping/Failed.php

@@ -3,12 +3,8 @@
 
 namespace Innmind\FileWatch\Ping;
 
-use Innmind\FileWatch\{
-    Ping,
-    Failed,
-    Stop,
-};
-use Innmind\Immutable\Either;
+use Innmind\FileWatch\Ping;
+use Innmind\Immutable\Maybe;
 
 final class Fallback implements Ping
 {
@@ -21,26 +17,10 @@ public function __construct(Ping $attempt, Ping $fallback)
         $this->fallback = $fallback;
     }
 
-    /**
-     * @template C
-     * @template L
-     *
-     * @param C $carry
-     * @param callable(C): Either<L|Stop<C>, C> $ping
-     *
-     * @return Either<Failed|L, C>
-     */
-    public function __invoke(mixed $carry, callable $ping): Either
+    public function __invoke(mixed $carry, callable $ping): Maybe
     {
-        /**
-         * @psalm-suppress InvalidArgument
-         * @var Either<Failed|L, C>
-         */
         return ($this->attempt)($carry, $ping)->otherwise(
-            fn($left) => match ($left instanceof Failed) {
-                true => ($this->fallback)($carry, $ping),
-                false => Either::left($left),
-            },
+            fn() => ($this->fallback)($carry, $ping),
         );
     }
 }

src/Ping/Fallback.php

@@ -4,12 +4,11 @@
 namespace Innmind\FileWatch\Ping;
 
 use Innmind\FileWatch\{
+    Continuation,
     Ping,
-    Stop,
-    Failed,
 };
 use Innmind\Url\Path;
-use Innmind\Immutable\Either;
+use Innmind\Immutable\Maybe;
 use Psr\Log\LoggerInterface;
 
 final class Logger implements Ping
@@ -30,29 +29,32 @@ private function __construct(
 
     /**
      * @template C
-     * @template L
+     * @template R
      *
      * @param C $carry
-     * @param callable(C): Either<L|Stop<C>, C> $ping
+     * @param callable(R|C, Continuation<R|C>): Continuation<R> $ping
      *
-     * @return Either<Failed|L, C>
+     * @return Maybe<R|C>
      */
-    public function __invoke(mixed $carry, callable $ping): Either
+    public function __invoke(mixed $carry, callable $ping): Maybe
     {
         $this->logger->info( // todo use debug
             'Starting to watch {path}',
             ['path' => $this->path->toString()],
         );
 
-        /** @var Either<Failed|L, C> */
-        return ($this->ping)($carry, function(mixed $carry) use ($ping): Either {
+        /**
+         * @psalm-suppress InvalidArgument
+         * @var Maybe<R|C>
+         */
+        return ($this->ping)($carry, function(mixed $carry, Continuation $continuation) use ($ping): Continuation {
             /** @var C $carry */
             $this->logger->info(
                 'Content at {path} changed',
                 ['path' => $this->path->toString()],
             );
 
-            return $ping($carry);
+            return $ping($carry, $continuation);
         });
     }