finished documentation types

Author: transistive

src/Contracts/HasPropertiesInterface.php

@@ -20,28 +20,30 @@
  * Defines how an object with properties should behave.
  *
  * @psalm-immutable
+ *
+ * @template T
  */
 interface HasPropertiesInterface
 {
     /**
      * Returns the properties a map.
      *
-     * @return CypherMap<mixed>
+     * @return CypherMap<T>
      */
     public function getProperties(): CypherMap;
 
     /**
      * @param string $name
      *
-     * @return mixed
+     * @return T
      */
     public function __get($name);
 
     /**
      * Always throws an exception as cypher objects are immutable.
      *
      * @param string $name
-     * @param mixed  $value
+     * @param T      $value
      *
      * @throws BadMethodCallException
      */

src/Contracts/PointInterface.php

@@ -17,6 +17,8 @@
  * Defines a basic Point type in neo4j.
  *
  * @psalm-immutable
+ *
+ * @psalm-type Crs = 'wgs-84'|'wgs-84-3d'|'cartesian'|'cartesian-3d';
  */
 interface PointInterface
 {
@@ -35,7 +37,7 @@ public function getY(): float;
      *
      * @see https://en.wikipedia.org/wiki/Spatial_reference_system
      *
-     * @return 'wgs-84'|'wgs-84-3d'|'cartesian'|'cartesian-3d'
+     * @return Crs
      */
     public function getCrs(): string;
 

src/Formatter/OGMFormatter.php

@@ -34,7 +34,7 @@
  *
  * @see https://neo4j.com/docs/driver-manual/current/cypher-workflow/#driver-type-mapping
  *
- * @psalm-type OGMTypes = string|\Laudis\Neo4j\Types\Date|\Laudis\Neo4j\Types\DateTime|\Laudis\Neo4j\Types\Duration|\Laudis\Neo4j\Types\LocalDateTime|\Laudis\Neo4j\Types\LocalTime|\Laudis\Neo4j\Types\Time|int|float|bool|null|\Laudis\Neo4j\Types\CypherList|\Laudis\Neo4j\Types\CypherMap|\Laudis\Neo4j\Types\Node|\Laudis\Neo4j\Types\Relationship|\Laudis\Neo4j\Types\Path|\Laudis\Neo4j\Types\Cartesian3DPoint|\Laudis\Neo4j\Types\CartesianPoint|\Laudis\Neo4j\Types\WGS84Point|\Laudis\Neo4j\Types\WGS843DPoint
+ * @psalm-type OGMTypes = string|int|float|bool|null|\Laudis\Neo4j\Types\Date|\Laudis\Neo4j\Types\DateTime|\Laudis\Neo4j\Types\Duration|\Laudis\Neo4j\Types\LocalDateTime|\Laudis\Neo4j\Types\LocalTime|\Laudis\Neo4j\Types\Time|\Laudis\Neo4j\Types\CypherList|\Laudis\Neo4j\Types\CypherMap|\Laudis\Neo4j\Types\Node|\Laudis\Neo4j\Types\Relationship|\Laudis\Neo4j\Types\Path|\Laudis\Neo4j\Types\Cartesian3DPoint|\Laudis\Neo4j\Types\CartesianPoint|\Laudis\Neo4j\Types\WGS84Point|\Laudis\Neo4j\Types\WGS843DPoint
  * @implements FormatterInterface<CypherList<CypherMap<OGMTypes>>>
  *
  * @psalm-type OGMResults = CypherList<CypherMap<OGMTypes>>

src/Types/AbstractCypherContainer.php renamed to src/Types/AbstractCypherObject.php

@@ -15,6 +15,7 @@
 
 use function array_key_exists;
 use ArrayAccess;
+use ArrayIterator;
 use BadMethodCallException;
 use function get_class;
 use InvalidArgumentException;
@@ -23,53 +24,73 @@
 use function sprintf;
 
 /**
- * @implements ArrayAccess<string, static|scalar|null>
- * @implements IteratorAggregate<string, static|scalar|null>
+ * Abstract immutable container with basic functionality to integrate easily into the driver ecosystem.
+ *
+ * @psalm-immutable
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @implements ArrayAccess<TKey, TValue>
+ * @implements IteratorAggregate<TKey, TValue>
  */
-abstract class AbstractCypherContainer implements JsonSerializable, ArrayAccess, IteratorAggregate
+abstract class AbstractCypherObject implements JsonSerializable, ArrayAccess, IteratorAggregate
 {
-    /** @var array<string, self|scalar|null>|null */
-    private ?array $cachedSerialized = null;
-
     /**
-     * @return array<string, static|scalar|null>
+     * Represents the container as an array.
+     *
+     * @return array<TKey, TValue>
      */
-    final public function jsonSerialize(): array
-    {
-        if ($this->cachedSerialized === null) {
-            $tbr = [];
+    abstract public function toArray(): array;
 
-            foreach ($this as $key => $value) {
-                $tbr[$key] = $value;
-            }
-
-            $this->cachedSerialized = $tbr;
-        }
+    public function jsonSerialize(): array
+    {
+        return $this->toArray();
+    }
 
-        return $this->cachedSerialized;
+    /**
+     * @return ArrayIterator<TKey, TValue>
+     */
+    public function getIterator(): ArrayIterator
+    {
+        return new ArrayIterator($this->toArray());
     }
 
+    /**
+     * @param TKey $offset
+     */
     final public function offsetExists($offset): bool
     {
-        return array_key_exists($offset, $this->jsonSerialize());
+        return array_key_exists($offset, $this->toArray());
     }
 
+    /**
+     * @param TKey $offset
+     *
+     * @return TValue
+     */
     final public function offsetGet($offset)
     {
-        $serialized = $this->jsonSerialize();
+        $serialized = $this->toArray();
         if (!array_key_exists($offset, $serialized)) {
             throw new InvalidArgumentException("Offset: $offset does not exists for class: ".static::class);
         }
 
-        /** @psalm-suppress InvalidReturnStatement */
         return $serialized[$offset];
     }
 
+    /**
+     * @param TKey   $offset
+     * @param TValue $value
+     */
     final public function offsetSet($offset, $value): void
     {
         throw new BadMethodCallException(sprintf('%s is immutable', get_class($this)));
     }
 
+    /**
+     * @param TKey $offset
+     */
     final public function offsetUnset($offset): void
     {
         throw new BadMethodCallException(sprintf('%s is immutable', get_class($this)));

src/Types/AbstractCypherSequence.php

@@ -16,30 +16,29 @@
 use function array_key_exists;
 use function array_search;
 use ArrayAccess;
-use ArrayIterator;
-use BadMethodCallException;
 use function count;
 use Countable;
 use function implode;
 use function in_array;
-use IteratorAggregate;
-use JsonSerializable;
 
 /**
+ * Abstract immutable sequence with basic functional methods.
+ *
  * @template TKey of array-key
  * @template TValue
  *
- * @implements ArrayAccess<TKey, TValue>
- * @implements ArrayAccess<TKey, TValue>
+ * @extends AbstractCypherObject<TKey, TValue>
  *
  * @psalm-immutable
  */
-abstract class AbstractCypherSequence implements Countable, JsonSerializable, ArrayAccess, IteratorAggregate
+abstract class AbstractCypherSequence extends AbstractCypherObject implements Countable
 {
     /** @var array<TKey, TValue> */
     protected array $sequence;
 
     /**
+     * Creates a new instance from the given iterable.
+     *
      * @template Value
      *
      * @param iterable<Value> $iterable
@@ -56,21 +55,29 @@ final public function count(): int
     }
 
     /**
+     * Copies the sequence.
+     *
      * @return static
      */
     final public function copy(): self
     {
+        // Make sure the sequence is actually copied by reassigning it.
         $map = $this->sequence;
 
         return $this::fromIterable($map);
     }
 
+    /**
+     * Returns whether or not the sequence is empty.
+     */
     final public function isEmpty(): bool
     {
         return count($this->sequence) === 0;
     }
 
     /**
+     * Returns the sequence as an array.
+     *
      * @return array<TKey, TValue>
      */
     final public function toArray(): array
@@ -79,61 +86,17 @@ final public function toArray(): array
     }
 
     /**
-     * @return ArrayIterator<TKey, TValue>
-     */
-    final public function getIterator(): ArrayIterator
-    {
-        return new ArrayIterator($this->sequence);
-    }
-
-    /**
-     * @param TKey $offset
-     */
-    final public function offsetExists($offset): bool
-    {
-        return array_key_exists($offset, $this->sequence);
-    }
-
-    /**
-     * @param TKey $offset
+     * Creates a new sequence by merging this one with the provided iterable. The provided values will override the existing items in case of a key collision.
      *
-     * @return TValue
-     */
-    final public function offsetGet($offset)
-    {
-        return $this->sequence[$offset];
-    }
-
-    /**
-     * @param TKey   $offset
-     * @param TValue $value
-     */
-    final public function offsetSet($offset, $value)
-    {
-        throw new BadMethodCallException(static::class.' is immutable');
-    }
-
-    /**
-     * @param string $offset
-     */
-    final public function offsetUnset($offset)
-    {
-        throw new BadMethodCallException(static::class.' is immutable');
-    }
-
-    final public function jsonSerialize(): array
-    {
-        return $this->sequence;
-    }
-
-    /**
      * @param iterable<array-key, TValue> $values
      *
      * @return static
      */
     abstract public function merge(iterable $values): self;
 
     /**
+     * Checks if the sequence contains the given key.
+     *
      * @param TKey $key
      */
     final public function hasKey($key): bool
@@ -142,6 +105,8 @@ final public function hasKey($key): bool
     }
 
     /**
+     * Checks if the sequence contains the given value. The equality check is strict.
+     *
      * @param TValue $value
      */
     final public function hasValue($value): bool
@@ -150,6 +115,8 @@ final public function hasValue($value): bool
     }
 
     /**
+     * Creates a filtered the sequence with the provided callback.
+     *
      * @param pure-callable(TKey, TValue):bool $callback
      *
      * @return static
@@ -167,6 +134,8 @@ final public function filter(callable $callback): self
     }
 
     /**
+     * Maps the values of this sequence to a new one with the provided callback.
+     *
      * @template U
      *
      * @param pure-callable(TKey, TValue):U $callback
@@ -184,6 +153,8 @@ final public function map(callable $callback): self
     }
 
     /**
+     * Reduces this sequence with the given callback.
+     *
      * @template TInitial
      *
      * @param pure-callable(TInitial|null, TKey, TValue):TInitial $callback
@@ -201,37 +172,47 @@ final public function reduce(callable $callback, $initial = null)
     }
 
     /**
+     * Finds the position of the value within the sequence.
+     *
      * @param TValue $value
      *
-     * @return false|TKey
+     * @return false|TKey returns the key of the value if it is found, false otherwise
      */
     final public function find($value)
     {
         return array_search($value, $this->sequence, true);
     }
 
     /**
+     * Creates a reversed sequence.
+     *
      * @return static
      */
     abstract public function reversed(): self;
 
     /**
+     * Slices a new sequence starting from the given offset with a certain length.
+     * If the length is null it will slice the entire remainder starting from the offset.
+     *
      * @return static
      */
     abstract public function slice(int $offset, int $length = null): self;
 
     /**
+     * Creates a sorted sequence. If the compoarator is null it will use natural ordering.
+     *
      * @param (pure-callable(TValue, TValue):int)|null $comparator
      *
      * @return static
      */
     abstract public function sorted(?callable $comparator = null): self;
 
-    final public function __debugInfo()
-    {
-        return $this->sequence;
-    }
-
+    /**
+     * Joins the values within the sequence together with the provided glue. If the glue is null, it will be an empty string.
+     *
+     * @param string|null $glue
+     * @return string
+     */
     public function join(?string $glue = null): string
     {
         /** @psalm-suppress MixedArgumentTypeCoercion */