Simplify query cache helper usage

Author: premtsd-code

src/Database/Database.php

@@ -8633,30 +8633,25 @@ public function restoreQueryCacheDocuments(
      * Execute a callback behind a cache-aside lookup.
      *
      * The callback runs on cache miss and its value is returned to the caller.
-     * The encode callback converts fresh values into cache payloads before save.
-     * The decode callback converts cached payloads back into return values; a
-     * literal false decode result rejects the cached payload and refreshes it.
+     * Query document payloads are converted to arrays before save and restored
+     * back into Documents on cache hits. A rejected document payload refreshes
+     * the cached value.
      * A literal false value is treated as a cache miss and is not cacheable.
      *
      * @template T
-     * @template C
      * @param string $key
      * @param callable(): T $callback
      * @param string $hash
-     * @param (callable(T): C)|null $encode
-     * @param (callable(C): (T|false))|null $decode
      * @return T
+     * @throws AuthorizationException
+     * @throws Exception
      */
     public function withCache(
         string $key,
         callable $callback,
         string $hash = '',
-        ?callable $encode = null,
-        ?callable $decode = null,
     ): mixed {
         $shouldRefreshCache = false;
-        $encode ??= static fn (mixed $value): mixed => $value;
-        $decode ??= static fn (mixed $value): mixed => $value;
 
         try {
             $cached = $this->cache->load($key, self::TTL, $hash);
@@ -8669,7 +8664,7 @@ public function withCache(
             $value = \is_array($cached) && \array_key_exists('value', $cached) ? $cached['value'] : false;
 
             if ($value !== false) {
-                $decoded = $decode($value);
+                $decoded = $this->decodeCacheValue($cached, $value);
 
                 if ($decoded !== false) {
                     return $decoded;
@@ -8691,7 +8686,7 @@ public function withCache(
 
         if ($value !== false) {
             try {
-                $this->cache->save($key, ['value' => $encode($value)], $hash);
+                $this->cache->save($key, $this->encodeCacheValue($value), $hash);
             } catch (Throwable $e) {
                 Console::warning('Warning: Failed to save cache value: ' . $e->getMessage());
             }
@@ -8700,6 +8695,100 @@ public function withCache(
         return $value;
     }
 
+    /**
+     * @param array<string, mixed> $cached
+     */
+    private function decodeCacheValue(array $cached, mixed $value): mixed
+    {
+        $collection = $cached['collection'] ?? null;
+        if (!\is_string($collection) || $collection === '') {
+            return $value;
+        }
+
+        $collection = $this->silent(fn () => $this->getCollection($collection));
+        if ($collection->isEmpty()) {
+            return false;
+        }
+
+        if (($cached['type'] ?? null) === 'document') {
+            $documents = $this->restoreQueryCacheDocuments($collection, [$value]);
+            if ($documents === false) {
+                return false;
+            }
+
+            return $documents[0] ?? false;
+        }
+
+        return $this->restoreQueryCacheDocuments($collection, $value);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function encodeCacheValue(mixed $value): array
+    {
+        if ($value instanceof Document) {
+            $collection = $value->getCollection();
+            if ($collection === '') {
+                return ['value' => $value];
+            }
+
+            return [
+                'collection' => $collection,
+                'type' => 'document',
+                'value' => $value->getArrayCopy(),
+            ];
+        }
+
+        $collection = $this->getCacheValueCollection($value);
+        if ($collection === null || !\is_array($value)) {
+            return ['value' => $value];
+        }
+
+        return [
+            'collection' => $collection,
+            'type' => 'documents',
+            'value' => $this->encodeQueryCacheValue($value),
+        ];
+    }
+
+    private function getCacheValueCollection(mixed $value): ?string
+    {
+        if ($value instanceof Document) {
+            return $value->getCollection() ?: null;
+        }
+
+        if (!\is_array($value)) {
+            return null;
+        }
+
+        foreach ($value as $item) {
+            $collection = $this->getCacheValueCollection($item);
+            if ($collection !== null) {
+                return $collection;
+            }
+        }
+
+        return null;
+    }
+
+    private function encodeQueryCacheValue(mixed $value): mixed
+    {
+        if ($value instanceof Document) {
+            return $value->getArrayCopy();
+        }
+
+        if (!\is_array($value)) {
+            return $value;
+        }
+
+        foreach ($value as $key => $item) {
+            $value[$key] = $this->encodeQueryCacheValue($item);
+        }
+
+        return $value;
+    }
+
     /**
      * Helper method to iterate documents in collection using callback pattern
      * Alterative is

tests/unit/QueryCacheTest.php

@@ -54,15 +54,6 @@ private function findWithCache(
             key: $cacheKey,
             callback: fn (): array => $database->find($collection, $queries, $forPermission),
             hash: $cacheHash,
-            encode: static fn (array $documents): array => \array_map(
-                static fn (Document $document): array => $document->getArrayCopy(),
-                $documents,
-            ),
-            decode: fn (mixed $payload): array|false => $database->restoreQueryCacheDocuments(
-                collection: $collectionDocument,
-                payload: $payload,
-                forPermission: $forPermission,
-            ),
         );
     }
 
@@ -227,77 +218,79 @@ function () use (&$callbackCalls): string {
         $this->assertSame(2, $callbackCalls);
     }
 
-    public function testWithCacheEncodesSavedValueAndDecodesCachedValue(): void
+    public function testWithCacheCachesSingleDocument(): void
     {
         $cache = new HashMemoryCache();
         $database = $this->createDatabase($cache);
+        $database->createCollection('wafRules', permissions: [
+            Permission::read(Role::any()),
+            Permission::create(Role::any()),
+        ]);
+
+        $database->createDocument('wafRules', new Document([
+            '$id' => 'rule-a',
+        ]));
 
         $callbackCalls = 0;
+        $collection = $database->getCollection('wafRules');
+        $key = $database->getQueryCacheKey($collection->getId(), '_39');
+        $hash = $database->getQueryCacheField($collection, field: 'document');
 
         $first = $database->withCache(
-            key: 'key',
-            callback: function () use (&$callbackCalls): array {
+            key: $key,
+            callback: function () use ($database, &$callbackCalls): Document {
                 $callbackCalls++;
-                return ['fresh'];
+                return $database->getDocument('wafRules', 'rule-a');
             },
-            encode: static fn (array $value): array => ['encoded' => $value],
-            decode: static fn (array $value): array => $value['encoded'],
+            hash: $hash,
         );
-
         $second = $database->withCache(
-            key: 'key',
-            callback: function () use (&$callbackCalls): array {
+            key: $key,
+            callback: function () use ($database, &$callbackCalls): Document {
                 $callbackCalls++;
-                return ['miss'];
+                return $database->getDocument('wafRules', 'missing');
             },
-            encode: static fn (array $value): array => ['encoded' => $value],
-            decode: static fn (array $value): array => $value['encoded'],
+            hash: $hash,
         );
 
-        $this->assertSame(['fresh'], $first);
-        $this->assertSame(['fresh'], $second);
+        $this->assertSame('rule-a', $first->getId());
+        $this->assertSame('rule-a', $second->getId());
         $this->assertSame(1, $callbackCalls);
     }
 
-    public function testWithCacheRefreshesWhenDecodeRejectsCachedValue(): void
+    public function testWithCacheCachesStaticQueryValues(): void
     {
         $cache = new HashMemoryCache();
         $database = $this->createDatabase($cache);
+        $database->createCollection('wafRules', permissions: [
+            Permission::read(Role::any()),
+        ]);
 
         $callbackCalls = 0;
+        $collection = $database->getCollection('wafRules');
+        $key = $database->getQueryCacheKey($collection->getId(), '_39');
+        $hash = $database->getQueryCacheField($collection, field: 'count');
 
-        $database->withCache(
-            key: 'key',
-            callback: function () use (&$callbackCalls): array {
-                $callbackCalls++;
-                return ['stale'];
-            },
-            encode: static fn (array $value): array => $value,
-        );
-
-        $fresh = $database->withCache(
-            key: 'key',
-            callback: function () use (&$callbackCalls): array {
+        $first = $database->withCache(
+            key: $key,
+            callback: function () use (&$callbackCalls): int {
                 $callbackCalls++;
-                return ['fresh'];
+                return 10;
             },
-            encode: static fn (array $value): array => $value,
-            decode: static fn (array $value): array|false => $value === ['stale'] ? false : $value,
+            hash: $hash,
         );
-
-        $cachedFresh = $database->withCache(
-            key: 'key',
-            callback: function () use (&$callbackCalls): array {
+        $second = $database->withCache(
+            key: $key,
+            callback: function () use (&$callbackCalls): int {
                 $callbackCalls++;
-                return ['miss'];
+                return 20;
             },
-            encode: static fn (array $value): array => $value,
-            decode: static fn (array $value): array|false => $value === ['stale'] ? false : $value,
+            hash: $hash,
         );
 
-        $this->assertSame(['fresh'], $fresh);
-        $this->assertSame(['fresh'], $cachedFresh);
-        $this->assertSame(2, $callbackCalls);
+        $this->assertSame(10, $first);
+        $this->assertSame(10, $second);
+        $this->assertSame(1, $callbackCalls);
     }
 
     public function testQueryCacheUsesCacheUntilPurged(): void
@@ -594,6 +587,8 @@ public function testQueryCacheRehydratesNestedDocumentPayloads(): void
         $cache->save(
             $database->getQueryCacheKey($collection->getId(), '_39'),
             [
+                'collection' => $collection->getId(),
+                'type' => 'documents',
                 'value' => [
                     [
                         '$id' => 'parent-a',
@@ -648,7 +643,11 @@ public function testQueryCacheRefreshesInvalidPayload(): void
         $collection = $database->getCollection('wafRules');
         $cache->save(
             $database->getQueryCacheKey($collection->getId(), '_39'),
-            ['value' => 'invalid'],
+            [
+                'collection' => $collection->getId(),
+                'type' => 'documents',
+                'value' => 'invalid',
+            ],
             $database->getQueryCacheField($collection, $queries),
         );
 
@@ -696,6 +695,8 @@ public function testQueryCacheRefreshesInvalidPayloadEntry(): void
         $cache->save(
             $database->getQueryCacheKey($collection->getId(), '_39'),
             [
+                'collection' => $collection->getId(),
+                'type' => 'documents',
                 'value' => [
                     [
                         '$id' => 'rule-a',