Add chainable JSON access with JsonMap to documentation, including examples in README, API reference, and usage guides for Java and Kotlin. Update contact email for corporate sponsorship.

guptavishal-xm1 · guptavishal-xm1 · commit 9ff9b9865bcc · 2025-10-15T20:32:59.000+05:30
diff --git a/README.md b/README.md
@@ -122,6 +122,17 @@ fun main() {
 }
 ```
 
+**Chainable JSON Access:**
+```java
+import io.mochaapi.client.*;
+
+// Clean nested JSON access without casting
+String city = Api.get("https://api.example.com/user/123")
+    .execute()
+    .toJsonMap()
+    .get("data").get("location").get("city").toString();
+```
+
 ## Core Capabilities
 
 **Production-Ready Features:**
@@ -208,7 +219,7 @@ MochaJSON is open source and free to use. If it helps your project, consider spo
 ### 🏢 Corporate Sponsorship
 
 For enterprise support, custom features, or bulk licensing, contact us at:
-- 📧 Email: sponsors@mochaapi.org
+- 📧 Email: kashvi0712@proton.me
 - 💼 GitHub: [Enterprise Contact](https://github.com/MochaAPI)
 
 ## Comparison with Alternatives
diff --git a/docs/docs/api/api-reference.md b/docs/docs/api/api-reference.md
@@ -251,6 +251,7 @@ Container for HTTP response data with JSON parsing capabilities.
 | `json()` | Get JSON mapper instance | None | `JsonMapper` |
 | `to(Class&lt;T&gt; type)` | Parse JSON to specified type | `type` - Target class | `T` |
 | `toMap()` | Parse JSON to Map | None | `Map<String, Object>` |
+| `toJsonMap()` | Parse JSON to chainable JsonMap | None | `JsonMap` |
 | `toList()` | Parse JSON to List | None | `List&lt;Object&gt;` |
 | `isSuccess()` | Check if status is 200-299 | None | `boolean` |
 | `isError()` | Check if status is 400+ | None | `boolean` |
@@ -268,6 +269,7 @@ Map<String, String> headers = response.headers();
 // JSON parsing
 User user = response.to(User.class);
 Map<String, Object> data = response.toMap();
+JsonMap json = response.toJsonMap();
 List&lt;Object&gt; items = response.toList();
 
 // Status checking
@@ -278,6 +280,37 @@ if (response.isSuccess()) {
 }
 ```
 
+### `JsonMap` Class
+
+Chainable wrapper for JSON data that eliminates casting boilerplate when accessing nested objects.
+
+#### Constructors
+
+| Constructor | Description | Parameters |
+|-------------|-------------|------------|
+| `JsonMap(Map<String, Object> map)` | Create JsonMap from Map | `map` - Map to wrap |
+
+#### Methods
+
+| Method | Description | Parameters | Returns |
+|--------|-------------|------------|---------|
+| `get(String key)` | Get value with chainable access | `key` - Key to retrieve | `JsonMap` |
+| `toString()` | Get string representation | None | `String` |
+
+#### Example Usage
+
+```java
+JsonMap json = response.toJsonMap();
+
+// Chainable nested access
+String city = json.get("data").get("location").get("city").toString();
+String latitude = json.get("data").get("location").get("coordinates").get("latitude").toString();
+
+// Intermediate access
+JsonMap user = json.get("data").get("user");
+String name = user.get("name").get("first").toString();
+```
+
 ## JSON Mapping
 
 ### `JsonMapper` Interface
diff --git a/docs/docs/usage/java-examples.md b/docs/docs/usage/java-examples.md
@@ -139,6 +139,70 @@ public class SecurityExample {
 }
 ```
 
+### Nested JSON Access with JsonMap
+
+When working with deeply nested API responses, JsonMap eliminates the need for verbose casting and provides a clean, chainable API.
+
+```java
+import io.mochaapi.client.*;
+
+public class JsonMapExample {
+    public static void main(String[] args) {
+        try {
+            // Example: User profile API with nested data
+            JsonMap response = Api.get("https://api.example.com/user/123")
+                .execute()
+                .toJsonMap();
+            
+            // Traditional approach (verbose with casting)
+            Map<String, Object> data = response.toMap();
+            Map<String, Object> user = (Map<String, Object>) data.get("data");
+            Map<String, Object> name = (Map<String, Object>) user.get("name");
+            Map<String, Object> location = (Map<String, Object>) user.get("location");
+            Map<String, Object> street = (Map<String, Object>) location.get("street");
+            Map<String, Object> coordinates = (Map<String, Object>) location.get("coordinates");
+            
+            String traditionalName = name.get("first") + " " + name.get("last");
+            String traditionalAddress = street.get("number") + " " + street.get("name") + ", " + location.get("city");
+            String traditionalLat = coordinates.get("latitude").toString();
+            
+            // JsonMap approach (clean chaining)
+            String cleanName = response.get("data").get("name").get("first") + " " + 
+                              response.get("data").get("name").get("last");
+            String cleanAddress = response.get("data").get("location").get("street").get("number") + " " + 
+                                 response.get("data").get("location").get("street").get("name") + ", " + 
+                                 response.get("data").get("location").get("city");
+            String cleanLat = response.get("data").get("location").get("coordinates").get("latitude").toString();
+            
+            System.out.println("Name: " + cleanName);
+            System.out.println("Address: " + cleanAddress);
+            System.out.println("Latitude: " + cleanLat);
+            
+            // Intermediate access for complex operations
+            JsonMap userData = response.get("data");
+            JsonMap locationData = userData.get("location");
+            
+            String email = userData.get("email").toString();
+            String city = locationData.get("city").toString();
+            String state = locationData.get("state").toString();
+            
+            System.out.println("Email: " + email);
+            System.out.println("Location: " + city + ", " + state);
+            
+        } catch (ApiException | JsonException e) {
+            e.printStackTrace();
+        }
+    }
+}
+```
+
+**Benefits of JsonMap:**
+
+- **No casting boilerplate**: Eliminates `(Map<String, Object>)` casts
+- **Type safety**: Prevents ClassCastException errors
+- **Readable code**: Chainable syntax reads naturally
+- **Flexible access**: Supports both direct chaining and intermediate variables
+
 ### Multiple Clients Pattern
 
 ```java
diff --git a/docs/docs/usage/json-handling.md b/docs/docs/usage/json-handling.md
@@ -45,6 +45,112 @@ Post post = Api.get("https://jsonplaceholder.typicode.com/posts/1")
 System.out.println("Title: " + post.title);
 ```
 
+## Chainable JSON Access with JsonMap
+
+When working with deeply nested JSON responses, the traditional approach requires multiple explicit casts to `Map<String, Object>`, which creates verbose and error-prone code. JsonMap provides a clean, chainable alternative.
+
+### The Problem: Casting Boilerplate
+
+```java
+// Traditional approach - verbose and error-prone
+Map<String, Object> response = Api.get("https://api.example.com/user").execute().toMap();
+
+// Accessing nested data requires multiple casts
+String city = ((Map<String, Object>)((Map<String, Object>)response.get("data"))
+    .get("location")).get("city").toString();
+
+String latitude = ((Map<String, Object>)((Map<String, Object>)((Map<String, Object>)response.get("data"))
+    .get("location")).get("coordinates")).get("latitude").toString();
+```
+
+### The Solution: JsonMap Chaining
+
+```java
+// JsonMap approach - clean and readable
+JsonMap json = Api.get("https://api.example.com/user").execute().toJsonMap();
+
+// Clean chaining without casting
+String city = json.get("data").get("location").get("city").toString();
+String latitude = json.get("data").get("location").get("coordinates").get("latitude").toString();
+```
+
+### Real-World Example
+
+Consider this nested JSON response from a user API:
+
+```json
+{
+  "statusCode": 200,
+  "data": {
+    "name": {
+      "title": "Ms",
+      "first": "Kitty",
+      "last": "Wallace"
+    },
+    "location": {
+      "street": {
+        "number": 1103,
+        "name": "Valley View Ln"
+      },
+      "city": "Bridgeport",
+      "state": "Minnesota",
+      "country": "United States",
+      "coordinates": {
+        "latitude": "-64.0863",
+        "longitude": "-155.0095"
+      }
+    },
+    "email": "kitty.wallace@example.com"
+  },
+  "success": true
+}
+```
+
+**Traditional approach:**
+```java
+Map<String, Object> response = Api.get("https://api.example.com/user").execute().toMap();
+Map<String, Object> data = (Map<String, Object>) response.get("data");
+Map<String, Object> name = (Map<String, Object>) data.get("name");
+Map<String, Object> location = (Map<String, Object>) data.get("location");
+Map<String, Object> street = (Map<String, Object>) location.get("street");
+Map<String, Object> coordinates = (Map<String, Object>) location.get("coordinates");
+
+String fullName = name.get("first") + " " + name.get("last");
+String address = street.get("number") + " " + street.get("name") + ", " + location.get("city");
+String lat = coordinates.get("latitude").toString();
+```
+
+**JsonMap approach:**
+```java
+JsonMap json = Api.get("https://api.example.com/user").execute().toJsonMap();
+
+String fullName = json.get("data").get("name").get("first") + " " + json.get("data").get("name").get("last");
+String address = json.get("data").get("location").get("street").get("number") + " " + 
+                 json.get("data").get("location").get("street").get("name") + ", " + 
+                 json.get("data").get("location").get("city");
+String lat = json.get("data").get("location").get("coordinates").get("latitude").toString();
+```
+
+### Benefits of JsonMap
+
+1. **Eliminates casting boilerplate** - No more explicit `(Map<String, Object>)` casts
+2. **Prevents unchecked cast warnings** - Type-safe access to nested data
+3. **Improves readability** - Clean, chainable syntax that reads naturally
+4. **Reduces errors** - No risk of ClassCastException from incorrect casting
+5. **Seamless integration** - Works alongside existing `toMap()` and `to()` methods
+
+### Kotlin Usage
+
+```kotlin
+import io.mochaapi.client.*
+
+val json = Api.get("https://api.example.com/user").execute().toJsonMap()
+
+val fullName = "${json.get("data").get("name").get("first")} ${json.get("data").get("name").get("last")}"
+val city = json.get("data").get("location").get("city").toString()
+val latitude = json.get("data").get("location").get("coordinates").get("latitude").toString()
+```
+
 ## Nested Object Parsing
 
 ### Java Example
diff --git a/docs/docs/usage/kotlin-examples.md b/docs/docs/usage/kotlin-examples.md
@@ -560,6 +560,76 @@ fun main() {
 }
 ```
 
+### Nested JSON Access with JsonMap
+
+JsonMap provides a clean, chainable API for accessing nested JSON data without casting boilerplate.
+
+```kotlin
+import io.mochaapi.client.*
+
+fun main() {
+    try {
+        // Example: User profile API with nested data
+        val json = Api.get("https://api.example.com/user/123")
+            .execute()
+            .toJsonMap()
+        
+        // Traditional approach (verbose with casting)
+        val data = json.toMap()
+        val user = data["data"] as Map<String, Any>
+        val name = user["name"] as Map<String, Any>
+        val location = user["location"] as Map<String, Any>
+        val street = location["street"] as Map<String, Any>
+        val coordinates = location["coordinates"] as Map<String, Any>
+        
+        val traditionalName = "${name["first"]} ${name["last"]}"
+        val traditionalAddress = "${street["number"]} ${street["name"]}, ${location["city"]}"
+        val traditionalLat = coordinates["latitude"].toString()
+        
+        // JsonMap approach (clean chaining)
+        val cleanName = "${json.get("data").get("name").get("first")} ${json.get("data").get("name").get("last")}"
+        val cleanAddress = "${json.get("data").get("location").get("street").get("number")} " +
+                          "${json.get("data").get("location").get("street").get("name")}, " +
+                          "${json.get("data").get("location").get("city")}"
+        val cleanLat = json.get("data").get("location").get("coordinates").get("latitude").toString()
+        
+        println("Name: $cleanName")
+        println("Address: $cleanAddress")
+        println("Latitude: $cleanLat")
+        
+        // Intermediate access for complex operations
+        val userData = json.get("data")
+        val locationData = userData.get("location")
+        
+        val email = userData.get("email").toString()
+        val city = locationData.get("city").toString()
+        val state = locationData.get("state").toString()
+        
+        println("Email: $email")
+        println("Location: $city, $state")
+        
+        // Kotlin extension functions for even cleaner syntax
+        fun JsonMap.safeGet(key: String): String = get(key).toString()
+        
+        val firstName = json.get("data").get("name").safeGet("first")
+        val lastName = json.get("data").get("name").safeGet("last")
+        val fullName = "$firstName $lastName"
+        
+        println("Full name: $fullName")
+        
+    } catch (e: Exception) {
+        println("Error: ${e.message}")
+    }
+}
+```
+
+**Benefits for Kotlin developers:**
+
+- **No casting**: Eliminates `as Map<String, Any>` casts
+- **Null safety**: Works well with Kotlin's null safety features
+- **Extension functions**: Can create custom extension functions for cleaner syntax
+- **Coroutines friendly**: Works seamlessly with async operations
+
 ## Functional Style with Extension Functions
 
 ```kotlin
diff --git a/src/main/java/io/mochaapi/client/ApiResponse.java b/src/main/java/io/mochaapi/client/ApiResponse.java
@@ -89,6 +89,30 @@ public <T> T to(Class<T> type) {
     public Map<String, Object> toMap() {
         return jsonMapper.toMap(body);
     }
+
+    // Returns a new JsonMap representation of the response body for convenient dot-style access.
+    // Example: response.toJsonMap().get("user").get("name").get("first");
+    // See: src/main/java/io/mochaapi/client/JsonMap
+    /**
+     * Converts the response body to a {@link JsonMap} for convenient dot-style property access.
+     * <p>
+     * Example usage:
+     * <pre>
+     * JsonMap user = response.toJsonMap().get("user");
+     * String firstName = user.get("name").get("first").toString();
+     * </pre>
+     * <p>
+     * The {@code JsonMap} wrapper allows chainable {@code get()} calls that automatically
+     * wrap nested {@code Map}s without unchecked casts.
+     * <p>
+     * See {@link io.mochaapi.client.JsonMap} for usage semantics.
+     *
+     * @return a JsonMap representing the response body
+     * @throws JsonException if parsing fails or the body is not valid JSON
+     */
+    public JsonMap toJsonMap() {
+    return new JsonMap(jsonMapper.toMap(body));
+    }
     
     /**
      * Converts the response body to a List.
diff --git a/src/main/java/io/mochaapi/client/JsonMap b/src/main/java/io/mochaapi/client/JsonMap
