simplified result handling with weak references

Author: transistive

src/Bolt/BoltConnection.php

@@ -143,17 +143,18 @@ public function setTimeout(float $timeout): void
         $this->factory->getConnection()->setTimeout($timeout);
     }
 
+    /**
+     * Closes the connection.
+     *
+     * Any of the preconditioned states are: 'READY', 'STREAMING', 'TX_READY', 'TX_STREAMING', 'FAILED', 'INTERRUPTED'.
+     * Sends signal: 'DISCONNECT'
+     */
     public function close(): void
     {
-        $this->possibleStates(['READY', 'STREAMING', 'TX_READY', 'TX_STREAMING', 'FAILED', 'INTERRUPTED'], 'GOODBYE');
-
-        $this->signal('DISCONNECT');
-
         $this->consumeResults();
 
         $this->protocol()->goodbye();
 
-        $this->boltProtocol = null;
         $this->serverState = 'DEFUNCT';
         $this->subscribedResults = [];
     }
@@ -170,12 +171,14 @@ private function consumeResults(): void
         $this->subscribedResults = [];
     }
 
+    /**
+     * Resets the connection.
+     *
+     * Any of the preconditioned states are: 'READY', 'STREAMING', 'TX_READY', 'TX_STREAMING', 'FAILED', 'INTERRUPTED'.
+     * Sends signal: 'INTERRUPT'
+     */
     public function reset(): void
     {
-        $this->possibleStates(['READY', 'STREAMING', 'TX_READY', 'TX_STREAMING', 'FAILED', 'INTERRUPTED'], 'RESET');
-
-        $this->signal('INTERRUPT');
-
         $this->consumeResults();
 
         try {
@@ -191,16 +194,15 @@ public function reset(): void
     }
 
     /**
-     * @param string|null $database the database to connect to
-     * @param float|null  $timeout  timeout in seconds
+     * Begins a transaction.
+     *
+     * Any of the preconditioned states are: 'READY', 'INTERRUPTED'.
      */
     public function begin(?string $database, ?float $timeout): void
     {
-        $this->possibleStates(['READY', 'INTERRUPTED'], 'BEGIN');
-
         $this->consumeResults();
 
-        $extra = $this->buildExtra($database, $timeout);
+        $extra = $this->buildRunExtra($database, $timeout);
         try {
             $this->protocol()->begin($extra);
         } catch (IgnoredException $e) {
@@ -215,15 +217,14 @@ public function begin(?string $database, ?float $timeout): void
     }
 
     /**
-     * @param string|null $database the database to connect to
-     * @param float|null  $timeout  timeout in seconds
+     * Discards a result.
+     *
+     * Any of the preconditioned states are: 'STREAMING', 'TX_STREAMING', 'FAILED', 'INTERRUPTED'.
      */
     public function discard(?int $qid): void
     {
-        $this->possibleStates(['STREAMING', 'TX_STREAMING', 'FAILED', 'INTERRUPTED'], 'DISCARD');
-
         try {
-            $extra = $this->buildExtraParam(null, $qid);
+            $extra = $this->buildResultExtra(null, $qid);
             $bolt = $this->protocol();
 
             if ($bolt instanceof V4) {
@@ -245,18 +246,20 @@ public function discard(?int $qid): void
     }
 
     /**
+     * Runs a query/statement.
+     *
+     * Any of the preconditioned states are: 'STREAMING', 'TX_STREAMING', 'FAILED', 'INTERRUPTED'.
+     *
      * @return BoltMeta
      */
     public function run(string $text, array $parameters, ?string $database, ?float $timeout): array
     {
-        $this->possibleStates(['READY', 'TX_READY', 'TX_STREAMING', 'FAILED', 'INTERRUPTED'], 'RUN');
-
         if (!str_starts_with($this->serverState, 'TX_')) {
             $this->consumeResults();
         }
 
         try {
-            $extra = $this->buildExtra($database, $timeout);
+            $extra = $this->buildRunExtra($database, $timeout);
 
             $tbr = $this->protocol()->run($text, $parameters, $extra);
 
@@ -278,10 +281,13 @@ public function run(string $text, array $parameters, ?string $database, ?float $
         }
     }
 
+    /**
+     * Commits a transaction.
+     *
+     * Any of the preconditioned states are: 'TX_READY', 'INTERRUPTED'.
+     */
     public function commit(): void
     {
-        $this->possibleStates(['TX_READY', 'INTERRUPTED'], 'COMMIT');
-
         $this->consumeResults();
 
         try {
@@ -299,10 +305,13 @@ public function commit(): void
         $this->serverState = 'READY';
     }
 
+    /**
+     * Rolls back a transaction.
+     *
+     * Any of the preconditioned states are: 'TX_READY', 'INTERRUPTED'.
+     */
     public function rollback(): void
     {
-        $this->possibleStates(['TX_READY', 'INTERRUPTED'], 'ROLLBACK');
-
         $this->consumeResults();
 
         try {
@@ -321,12 +330,15 @@ public function rollback(): void
     }
 
     /**
+     * Pulls a result set.
+     *
+     * Any of the preconditioned states are: 'TX_READY', 'INTERRUPTED'.
+     *
      * @return non-empty-list<list>
      */
     public function pull(?int $qid, ?int $fetchSize): array
     {
-        $this->possibleStates(['STREAMING', 'TX_STREAMING', 'FAILED', 'INTERRUPTED'], 'ROLLBACK');
-        $extra = $this->buildExtraParam($fetchSize, $qid);
+        $extra = $this->buildResultExtra($fetchSize, $qid);
 
         $bolt = $this->protocol();
         try {
@@ -362,12 +374,12 @@ public function getDriverConfiguration(): DriverConfiguration
 
     public function __destruct()
     {
-        if ($this->serverState !== 'DISCONNECTED' && $this->serverState !== 'DEFUNCT' && $this->boltProtocol !== null) {
+        if ($this->serverState !== 'DISCONNECTED' && $this->serverState !== 'DEFUNCT') {
             $this->close();
         }
     }
 
-    private function buildExtra(?string $database, ?float $timeout): array
+    private function buildRunExtra(?string $database, ?float $timeout): array
     {
         $extra = [];
         if ($database) {
@@ -380,7 +392,7 @@ private function buildExtra(?string $database, ?float $timeout): array
         return $extra;
     }
 
-    public function buildExtraParam(?int $fetchSize, ?int $qid): array
+    private function buildResultExtra(?int $fetchSize, ?int $qid): array
     {
         $extra = [];
         if ($fetchSize) {
@@ -394,28 +406,14 @@ public function buildExtraParam(?int $fetchSize, ?int $qid): array
         return $extra;
     }
 
-    /**
-     * @return string
-     */
     public function getServerState(): string
     {
         return $this->serverState;
     }
 
-    /**
-     * @param callable(ServerStateTransition): void $listener
-     */
-    private function bindAfterTransitionEventListener($listener): void
-    {
-        $this->subscribedResults[] = $listener;
-    }
-
-    private function possibleStates(array $array, string $string)
-    {
-    }
-
-    private function signal(string $string)
+    private function subscribeResult(SummarizedResult $result): void
     {
+        $this->subscribedResults[] = WeakReference::create($result);
     }
 
     private function protocol(): V3

src/Bolt/BoltResult.php

@@ -143,7 +143,6 @@ public function valid(): bool
     public function rewind(): void
     {
         // Rewind is impossible
-        throw new BadMethodCallException('Cannot rewind a bolt result.');
     }
 
     public function __destruct()