feat(str): implement jsonDecode

Author: xHeaven

packages/support/src/Str/ManipulatesString.php

@@ -10,10 +10,12 @@
 use Stringable;
 use Tempest\Intl;
 use Tempest\Support\Arr\ImmutableArray;
+use Tempest\Support\Arr\MutableArray;
 use Tempest\Support\Random;
 use Tempest\Support\Regex;
 
 use function Tempest\Support\arr;
+use function Tempest\Support\Json\decode;
 use function Tempest\Support\tap;
 
 /**
@@ -865,6 +867,16 @@ public function dump(mixed ...$dumps): self
         return $this;
     }
 
+    /**
+     * Decodes the JSON string and returns an array helper instance.
+     */
+    public function jsonDecode(bool $mutable = false): ImmutableArray|MutableArray
+    {
+        $decoded = decode($this->value);
+
+        return $mutable ? new MutableArray($decoded) : new ImmutableArray($decoded);
+    }
+
     /**
      * Converts to a scalar string.
      */

packages/support/tests/Str/ManipulatesStringTest.php

@@ -750,4 +750,44 @@ public function test_uuid(): void
     {
         $this->assertTrue(str()->uuid()->isUuid());
     }
+
+    public function test_json_decode(): void
+    {
+        $json = '{"name": "tempest", "version": "1.0", "tags": ["php", "framework"]}';
+        $result = str($json)->jsonDecode();
+
+        $this->assertInstanceOf(\Tempest\Support\Arr\ImmutableArray::class, $result);
+        $this->assertSame('tempest', $result->get('name'));
+        $this->assertSame('1.0', $result->get('version'));
+        $this->assertInstanceOf(\Tempest\Support\Arr\ImmutableArray::class, $result->get('tags'));
+        $this->assertSame(['php', 'framework'], $result->get('tags')->toArray());
+    }
+
+    public function test_json_decode_mutable(): void
+    {
+        $json = '{"name": "tempest", "version": "1.0"}';
+        $result = str($json)->jsonDecode(mutable: true);
+
+        $this->assertInstanceOf(\Tempest\Support\Arr\MutableArray::class, $result);
+        $this->assertSame('tempest', $result->get('name'));
+        $this->assertSame('1.0', $result->get('version'));
+    }
+
+    public function test_json_decode_array(): void
+    {
+        $json = '["php", "framework", "tempest"]';
+        $result = str($json)->jsonDecode();
+
+        $this->assertInstanceOf(\Tempest\Support\Arr\ImmutableArray::class, $result);
+        $this->assertSame('php', $result->get(0));
+        $this->assertSame('framework', $result->get(1));
+        $this->assertSame('tempest', $result->get(2));
+    }
+
+    public function test_json_decode_invalid_json(): void
+    {
+        $this->expectException(\Tempest\Support\Json\Exception\JsonCouldNotBeDecoded::class);
+
+        str('invalid json')->jsonDecode();
+    }
 }