feat: add reference counting to JSON documents

README.md

@@ -6,6 +6,8 @@ A [SourceMod](http://www.sourcemod.net/) extension that provides comprehensive J
 ## Key Features
 * High-performance JSON parsing and serialization using YYJSON
 * Support for [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) operations
+* Support for [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations
+* Support for [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) operations
 * x64 support
 * Easy-to-use API for both objects and arrays
 * Pretty printing and writing support
@@ -208,7 +210,7 @@ JSON value;
 
 // Method 1: Using Array Iterator (Recommended)
 JSONArrIter iter = new JSONArrIter(arr);
-while ((value = iter.Next()) != null) {
+while ((value = iter.Next) != null) {
   PrintToServer("Index: %d", iter.Index);
   delete value;
 }

public/IJsonManager.h

@@ -1,5 +1,5 @@
-#ifndef _INCLUDE_SM_JSON_IJSONMANAGER_H_
-#define _INCLUDE_SM_JSON_IJSONMANAGER_H_
+#ifndef _INCLUDE_IJSONMANAGER_H_
+#define _INCLUDE_IJSONMANAGER_H_
 
 #include <IHandleSys.h>
 #include <variant>
@@ -15,7 +15,7 @@ class JsonArrIter;
 class JsonObjIter;
 
 #define SMINTERFACE_JSONMANAGER_NAME "IJsonManager"
-#define SMINTERFACE_JSONMANAGER_VERSION 1
+#define SMINTERFACE_JSONMANAGER_VERSION 2
 #define JSON_PACK_ERROR_SIZE 256
 #define JSON_ERROR_BUFFER_SIZE 256
 #define JSON_INT64_BUFFER_SIZE 32
@@ -116,6 +116,52 @@ class IJsonManager : public SMInterface
 	 */
 	virtual char* WriteToStringPtr(JsonValue* handle, uint32_t write_flg = 0, size_t* out_size = nullptr) = 0;
 
+	/**
+	 * Apply JSON Patch (RFC 6902) and return a new JSON value
+	 * @param target Target JSON value
+	 * @param patch JSON Patch document
+	 * @param result_mutable true to return mutable result, false for immutable
+	 * @param error Error buffer (optional)
+	 * @param error_size Error buffer size
+	 * @return Patched JSON value on success, nullptr on failure
+	 */
+	virtual JsonValue* ApplyJsonPatch(JsonValue* target, JsonValue* patch, bool result_mutable,
+		char* error = nullptr, size_t error_size = 0) = 0;
+
+	/**
+	 * Apply JSON Patch in place (target must be mutable)
+	 * @param target Target JSON value (mutable document)
+	 * @param patch JSON Patch document
+	 * @param error Error buffer (optional)
+	 * @param error_size Error buffer size
+	 * @return true on success, false on failure
+	 */
+	virtual bool JsonPatchInPlace(JsonValue* target, JsonValue* patch,
+		char* error = nullptr, size_t error_size = 0) = 0;
+
+	/**
+	 * Apply JSON Merge Patch (RFC 7396) and return a new JSON value
+	 * @param target Target JSON value
+	 * @param patch JSON Merge Patch document
+	 * @param result_mutable true to return mutable result, false for immutable
+	 * @param error Error buffer (optional)
+	 * @param error_size Error buffer size
+	 * @return Patched JSON value on success, nullptr on failure
+	 */
+	virtual JsonValue* ApplyMergePatch(JsonValue* target, JsonValue* patch, bool result_mutable,
+		char* error = nullptr, size_t error_size = 0) = 0;
+
+	/**
+	 * Apply JSON Merge Patch in place (target must be mutable)
+	 * @param target Target JSON value (mutable document)
+	 * @param patch JSON Merge Patch document
+	 * @param error Error buffer (optional)
+	 * @param error_size Error buffer size
+	 * @return true on success, false on failure
+	 */
+	virtual bool MergePatchInPlace(JsonValue* target, JsonValue* patch,
+		char* error = nullptr, size_t error_size = 0) = 0;
+
 	/**
 	 * Write JSON to file
 	 * @param handle JSON value
@@ -329,6 +375,14 @@ class IJsonManager : public SMInterface
 	 */
 	virtual size_t GetReadSize(JsonValue* handle) = 0;
 
+	/**
+	 * Get the reference count of the document
+	 * @param handle JSON value
+	 * @return Reference count of the document (number of JsonValue objects sharing this document)
+	 * @note Returns 0 if handle is null or has no document
+	 */
+	virtual size_t GetRefCount(JsonValue* handle) = 0;
+
 	/**
 	 * Create an empty mutable JSON object
 	 * @return New mutable JSON object or nullptr on failure
@@ -977,10 +1031,10 @@ class IJsonManager : public SMInterface
 	 * Remove range of elements (mutable only)
 	 * @param handle JSON array
 	 * @param start_index Start index (inclusive)
-	 * @param end_index End index (exclusive)
+	 * @param count Number of elements to remove
 	 * @return true on success
 	 */
-	virtual bool ArrayRemoveRange(JsonValue* handle, size_t start_index, size_t end_index) = 0;
+	virtual bool ArrayRemoveRange(JsonValue* handle, size_t start_index, size_t count) = 0;
 
 	/**
 	 * Remove all elements (mutable only)
@@ -1014,20 +1068,12 @@ class IJsonManager : public SMInterface
 	virtual int ArrayIndexOfInt(JsonValue* handle, int search_value) = 0;
 
 	/**
-	 * Find index of 64-bit integer value
-	 * @param handle JSON array
-	 * @param search_value 64-bit integer value to search for
-	 * @return Index of first match, or -1 if not found
-	 */
-	virtual int ArrayIndexOfInt64(JsonValue* handle, int64_t search_value) = 0;
-
-	/**
-	 * Find index of 64-bit unsigned integer value
+	 * Find index of 64-bit integer value (auto-detects signed/unsigned)
 	 * @param handle JSON array
-	 * @param search_value 64-bit unsigned integer value to search for
+	 * @param search_value 64-bit integer value to search for (std::variant<int64_t, uint64_t>)
 	 * @return Index of first match, or -1 if not found
 	 */
-	virtual int ArrayIndexOfUint64(JsonValue* handle, uint64_t search_value) = 0;
+	virtual int ArrayIndexOfInt64(JsonValue* handle, std::variant<int64_t, uint64_t> search_value) = 0;
 
 	/**
 	 * Find index of float value
@@ -1551,16 +1597,27 @@ class IJsonManager : public SMInterface
 	 * Initialize an array iterator (same as ArrIterWith but returns pointer)
 	 * @param handle JSON array value
 	 * @return New array iterator or nullptr on error
+	 * @note Caller must release the iterator using ReleaseArrIter() once finished
+	 * @note Iterators are single-pass; once ArrIterNext() returns nullptr, create a new iterator or call ArrIterReset() to iterate again
 	 */
 	virtual JsonArrIter* ArrIterInit(JsonValue* handle) = 0;
 
 	/**
 	 * Create an array iterator with an array
 	 * @param handle JSON array value
 	 * @return New array iterator or nullptr on error
+	 * @note Caller must release the iterator using ReleaseArrIter() once finished
+	 * @note Iterators are single-pass; once ArrIterNext() returns nullptr, create a new iterator or call ArrIterReset() to iterate again
 	 */
 	virtual JsonArrIter* ArrIterWith(JsonValue* handle) = 0;
 
+	/**
+	 * Reset an array iterator to the beginning
+	 * @param iter Array iterator
+	 * @return true on success, false if iterator is invalid or reset failed
+	 */
+	virtual bool ArrIterReset(JsonArrIter* iter) = 0;
+
 	/**
 	 * Get next element from array iterator
 	 * @param iter Array iterator
@@ -1593,16 +1650,27 @@ class IJsonManager : public SMInterface
 	 * Initialize an object iterator (same as ObjIterWith but returns pointer)
 	 * @param handle JSON object value
 	 * @return New object iterator or nullptr on error
+	 * @note Caller must release the iterator using ReleaseObjIter() once finished
+	 * @note Iterators are single-pass; once ObjIterNext() returns nullptr, create a new iterator or call ObjIterReset() to iterate again
 	 */
 	virtual JsonObjIter* ObjIterInit(JsonValue* handle) = 0;
 
 	/**
 	 * Create an object iterator with an object
 	 * @param handle JSON object value
 	 * @return New object iterator or nullptr on error
+	 * @note Caller must release the iterator using ReleaseObjIter() once finished
+	 * @note Iterators are single-pass; once ObjIterNext() returns nullptr, create a new iterator or call ObjIterReset() to iterate again
 	 */
 	virtual JsonObjIter* ObjIterWith(JsonValue* handle) = 0;
 
+	/**
+	 * Reset an object iterator to the beginning
+	 * @param iter Object iterator
+	 * @return true on success, false if iterator is invalid or reset failed
+	 */
+	virtual bool ObjIterReset(JsonObjIter* iter) = 0;
+
 	/**
 	 * Get next key from object iterator
 	 * @param iter Object iterator
@@ -1807,4 +1875,4 @@ class IJsonManager : public SMInterface
 		char* error = nullptr, size_t error_size = 0) = 0;
 };
 
-#endif // _INCLUDE_SM_JSON_IJSONMANAGER_H_
+#endif // _INCLUDE_IJSONMANAGER_H_