feat: adicionar suporte a constantes públicas para configuração e testes no JsonBufferPool

Author: CAFernandes

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Automatic Integration**: `Response::json()` now uses pooling transparently for optimal performance
   - **Smart Detection**: Automatically activates pooling for arrays 10+ elements, objects 5+ properties, strings >1KB
   - **Graceful Fallback**: Small datasets use traditional `json_encode()` for best performance
+  - **Public Constants**: All size estimation and threshold constants are now publicly accessible for advanced usage and testing
 
 - **Performance Monitoring & Statistics**:
   - Real-time pool statistics with reuse rates and efficiency metrics
@@ -28,6 +29,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Transparent Optimization**: Automatic activation based on data characteristics
   - **Manual Control**: Direct pool access via `JsonBufferPool::encodeWithPool()` when needed
   - **Configuration API**: Production tuning via `JsonBufferPool::configure()`
+  - **Enhanced Error Handling**: Precise validation messages separating type vs range errors
+  - **Type Safety**: `encodeWithPool()` now always returns string, simplifying error handling
 
 #### Performance Improvements
 - **Sustained Throughput**: 101,000+ JSON operations per second in continuous load tests
@@ -37,9 +40,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### Technical Details
 - **PSR-12 Compliant**: All new code follows project coding standards
-- **Comprehensive Testing**: 20 new tests with 60 assertions covering all functionality
+- **Comprehensive Testing**: 84 JSON tests with 329+ assertions covering all functionality
 - **Backward Compatible**: No changes required to existing applications
 - **Production Ready**: Tested with various data sizes and load patterns
+- **Centralized Constants**: All thresholds and size constants are unified to avoid duplication
+- **Test Maintainability**: Tests now use constants instead of hardcoded values for better maintainability
 
 #### Files Added
 - `src/Json/Pool/JsonBuffer.php`: Core buffer implementation
@@ -52,6 +57,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `src/Http/Response.php`: Integrated automatic pooling in `json()` method
 - Enhanced with smart detection and fallback mechanisms
 
+#### Post-Release Improvements (July 2025)
+- **Enhanced Configuration Validation**: Separated type checking from range validation for more precise error messages
+- **Improved Type Safety**: `encodeWithPool()` method now has tightened return type (always returns string)
+- **Public Constants Exposure**: Made all size estimation and threshold constants public for advanced usage and testing
+- **Centralized Thresholds**: Unified pooling decision thresholds across Response.php and JsonBufferPool to eliminate duplication
+- **Test Maintainability**: Updated all tests to use constants instead of hardcoded values
+- **Documentation Updates**: 
+  - Added comprehensive [Constants Reference Guide](docs/technical/json/CONSTANTS_REFERENCE.md)
+  - Updated performance guide with recent improvements
+  - Enhanced error handling documentation
+
 ## [1.1.0] - 2025-07-09
 
 ### 🚀 **High-Performance Edition**

docs/releases/v1.1.1/RELEASE_NOTES.md

@@ -28,18 +28,43 @@ $response->json($data); // Now uses pooling when beneficial
 ```
 
 **Smart Detection Criteria:**
-- Arrays with 10+ elements
-- Objects with 5+ properties  
-- Strings larger than 1KB
+- Arrays with 10+ elements (JsonBufferPool::POOLING_ARRAY_THRESHOLD)
+- Objects with 5+ properties (JsonBufferPool::POOLING_OBJECT_THRESHOLD)
+- Strings larger than 1KB (JsonBufferPool::POOLING_STRING_THRESHOLD)
 
-### Manual Pool Control
+### Enhanced Error Handling & Type Safety
+
+**Precise Validation Messages:**
+```php
+// Type errors are clearly separated from range errors
+try {
+    JsonBufferPool::configure(['max_pool_size' => 'invalid']);
+} catch (InvalidArgumentException $e) {
+    echo $e->getMessage(); // "'max_pool_size' must be an integer"
+}
+
+try {
+    JsonBufferPool::configure(['max_pool_size' => -1]);
+} catch (InvalidArgumentException $e) {
+    echo $e->getMessage(); // "'max_pool_size' must be a positive integer"
+}
+```
+
+**Always-String Return Type:**
+```php
+// encodeWithPool() now always returns string, never false
+$json = JsonBufferPool::encodeWithPool($data); // Always string
+// No need to check for false - error handling is internal
+```
+
+### Manual Pool Control & Public Constants
 
 For advanced use cases, direct pool access is available:
 
 ```php
 use PivotPHP\Core\Json\Pool\JsonBufferPool;
 
-// Direct encoding with pooling
+// Direct encoding with pooling (always returns string)
 $json = JsonBufferPool::encodeWithPool($data);
 
 // Manual buffer management
@@ -49,6 +74,27 @@ $result = $buffer->finalize();
 JsonBufferPool::returnBuffer($buffer);
 ```
 
+**Public Constants for Advanced Usage:**
+```php
+// Size estimation constants
+JsonBufferPool::EMPTY_ARRAY_SIZE;           // 2
+JsonBufferPool::SMALL_ARRAY_SIZE;           // 512
+JsonBufferPool::MEDIUM_ARRAY_SIZE;          // 2048
+JsonBufferPool::LARGE_ARRAY_SIZE;           // 8192
+JsonBufferPool::XLARGE_ARRAY_SIZE;          // 32768
+
+// Pooling thresholds
+JsonBufferPool::POOLING_ARRAY_THRESHOLD;    // 10
+JsonBufferPool::POOLING_OBJECT_THRESHOLD;   // 5
+JsonBufferPool::POOLING_STRING_THRESHOLD;   // 1024
+
+// Type-specific constants
+JsonBufferPool::STRING_OVERHEAD;            // 20
+JsonBufferPool::OBJECT_PROPERTY_OVERHEAD;   // 50
+JsonBufferPool::OBJECT_BASE_SIZE;           // 100
+JsonBufferPool::MIN_LARGE_BUFFER_SIZE;      // 65536
+```
+
 ### Real-time Monitoring
 
 Comprehensive statistics for production monitoring:
@@ -180,17 +226,20 @@ For maximum performance, consider these enhancements:
 
 ### Test Coverage
 
-- **20 new tests** covering all JSON pooling functionality
-- **60 additional assertions** validating behavior
+- **84 JSON tests** covering all pooling functionality
+- **329+ total assertions** validating behavior
 - **All existing tests** continue to pass (335+ tests total)
 - **PSR-12 compliance** maintained throughout
+- **Enhanced test maintainability** with constant-based assertions
 
 ### Validation
 
 - **Memory leak testing** - No buffer leaks detected
 - **Stress testing** - 60+ seconds sustained load
 - **Compatibility testing** - All existing functionality preserved
 - **Performance regression testing** - No slowdowns for any use case
+- **Type safety validation** - Precise error message testing
+- **Configuration validation** - Comprehensive parameter checking
 
 ## 🎯 Use Cases