Merge branch 'release/v0.5.2'

CHANGELOG.md

@@ -1,3 +1,6 @@
+## v0.5.2 (2024-03-22)
+* Added full generics to Stores
+
 ## v0.5.1 (2024-03-22)
 * Added generic return type to fetch()
 

src/Stash/Context.php

@@ -36,7 +36,7 @@ class Context
     ];
 
     /**
-     * @var array<string, Store>
+     * @var array<string, Store<mixed>>
      */
     protected array $caches = [];
 
@@ -98,6 +98,8 @@ public function getDefaultPrefix(): ?string
 
     /**
      * Get cache store by name
+     *
+     * @return Store<mixed>
      */
     public function load(
         string $namespace

src/Stash/Item.php

@@ -13,19 +13,24 @@
 use Carbon\CarbonInterval;
 use DateInterval;
 use DateTimeInterface;
-
 use DecodeLabs\Coercion;
-
 use Psr\Cache\CacheItemInterface as CacheItem;
-
 use Stringable;
 
+/**
+ * @template T of mixed
+ */
 class Item implements CacheItem
 {
     public const LOCK_TTL = 30;
 
     protected string $key;
+
+    /**
+     * @var ?T
+     */
     protected mixed $value;
+
     protected bool $isHit = false;
     protected bool $fetched = false;
 
@@ -50,10 +55,16 @@ class Item implements CacheItem
     protected ?int $sleepAttempts = null;
 
     protected mixed $fallbackValue = null;
+
+    /**
+     * @var Store<T>
+     */
     protected Store $store;
 
     /**
      * Init with store and key
+     *
+     * @param Store<T> $store
      */
     public function __construct(
         Store $store,
@@ -65,6 +76,8 @@ public function __construct(
 
     /**
      * Get parent store
+     *
+     * @return Store<T>
      */
     public function getStore(): Store
     {
@@ -82,6 +95,7 @@ public function getKey(): string
     /**
      * Sets the value represented by this cache item.
      *
+     * @param T $value
      * @return $this
      */
     public function set(
@@ -95,6 +109,8 @@ public function set(
 
     /**
      * Retrieves the value of the item from the cache associated with this object's key.
+     *
+     * @return ?T
      */
     public function get(): mixed
     {
@@ -504,6 +520,8 @@ public function defer(): bool
 
     /**
      * Set value and save
+     *
+     * @param T $value
      */
     public function update(
         mixed $value,
@@ -527,7 +545,10 @@ public function extend(
             $this->setExpiration($ttl);
         }
 
-        $this->set($this->get());
+        if (null !== ($value = $this->get())) {
+            $this->set($value);
+        }
+
         return $this->save();
     }
 

src/Stash/Store.php

@@ -16,7 +16,8 @@
 use Psr\SimpleCache\CacheInterface as SimpleCache;
 
 /**
- * @extends ArrayAccess<string, mixed>
+ * @template T of mixed
+ * @extends ArrayAccess<string, T>
  */
 interface Store extends
     CacheItemPool,
@@ -36,20 +37,25 @@ public function getNamespace(): string;
     public function getDriver(): Driver;
 
     /**
-     * @template T
-     * @param Closure(Item, Store): T $generator
+     * @param Closure(Item<T>, Store<T>): T $generator
      * @return T
      */
     public function fetch(
         string $key,
         Closure $generator
     ): mixed;
 
+    /**
+     * @param T $value
+     */
     public function __set(
         string $key,
         mixed $value
     ): void;
 
+    /**
+     * @return Item<T>
+     */
     public function __get(
         string $key
     ): Item;

src/Stash/Store/Generic.php

@@ -23,12 +23,16 @@
 use Psr\Cache\InvalidArgumentException as CacheInvalidArgumentException;
 use Throwable;
 
+/**
+ * @template T of mixed
+ * @implements Store<T>
+ */
 class Generic implements Store
 {
     protected string $namespace;
 
     /**
-     * @var array<string, Item>
+     * @var array<string, Item<T>>
      */
     protected array $deferred = [];
 
@@ -84,6 +88,9 @@ public function getNamespace(): string
 
     /**
      * Fetches a value from the cache.
+     *
+     * @param ?T $default
+     * @return ?T
      */
     public function get(
         string $key,
@@ -103,6 +110,8 @@ public function get(
 
     /**
      * Retrive item object, regardless of hit or miss
+     *
+     * @return Item<T>
      */
     public function getItem(
         string $key
@@ -121,7 +130,8 @@ public function getItem(
      * Obtains multiple cache items by their unique keys.
      *
      * @param iterable<int, string> $keys
-     * @return iterable<string, mixed>
+     * @param ?T $default
+     * @return iterable<string, ?T>
      */
     public function getMultiple(
         iterable $keys,
@@ -145,7 +155,7 @@ public function getMultiple(
      * Retrieve a list of items
      *
      * @param array<string> $keys
-     * @return iterable<string, Item>
+     * @return iterable<string, Item<T>>
      */
     public function getItems(
         array $keys = []
@@ -307,12 +317,16 @@ public function fetch(
             $item->save();
         }
 
-        return $item->get();
+        /** @var T $output */
+        $output = $item->get();
+        return $output;
     }
 
 
     /**
      * Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.
+     *
+     * @param T $value
      */
     public function set(
         string $key,
@@ -331,7 +345,7 @@ public function set(
     /**
      * Persists a set of key => value pairs in the cache, with an optional TTL.
      *
-     * @param iterable<string, mixed> $values
+     * @param iterable<string, T> $values
      */
     public function setMultiple(
         iterable $values,
@@ -357,6 +371,8 @@ public function setMultiple(
 
     /**
      * Persists a cache item immediately.
+     *
+     * @param Item<T> $item
      */
     public function save(
         CacheItem $item
@@ -368,6 +384,8 @@ public function save(
 
     /**
      * Sets a cache item to be persisted later.
+     *
+     * @param Item<T> $item
      */
     public function saveDeferred(
         CacheItem $item
@@ -440,6 +458,8 @@ public function __unset(
 
     /**
      * Shortcut set()
+     *
+     * @param T $value
      */
     public function offsetSet(
         mixed $key,
@@ -450,6 +470,8 @@ public function offsetSet(
 
     /**
      * Shortcut get()
+     *
+     * @return ?T
      */
     public function offsetGet(
         mixed $key
@@ -657,6 +679,8 @@ protected function validateKey(
 
     /**
      * Check cache item
+     *
+     * @return Item<T>
      */
     protected function checkCacheItem(
         CacheItem $item
@@ -676,9 +700,9 @@ protected function checkCacheItem(
     /**
      * Wrap simple errors
      *
-     * @template T
-     * @param Closure(): T $func
-     * @return T
+     * @template E
+     * @param Closure(): E $func
+     * @return E
      */
     protected function wrapSimpleErrors(
         Closure $func