Improve JSON5 parser API with strongly-typed JSON5Value sealed class

[Copilot]

This PR introduces a new strongly-typed API for JSON5 parsing while maintaining backward compatibility with the existing API.

Changes

New JSON5Value Sealed Class

Added a comprehensive JSON5Value sealed class hierarchy that represents all possible JSON5 values according to the JSON5 specification:

• JSON5Value.Object - JSON5 objects (key-value maps)
• JSON5Value.Array - JSON5 arrays (ordered lists)
• JSON5Value.String - String values
• JSON5Value.Number hierarchy:
  • Integer - Whole numbers
  • Decimal - Floating-point numbers
  • Hexadecimal - Hexadecimal numbers (0x prefix)
  • PositiveInfinity - Positive infinity
  • NegativeInfinity - Negative infinity
  • NaN - Not a Number
• JSON5Value.Boolean - Boolean values
• JSON5Value.Null - Null values

Updated API Methods

New strongly-typed parse method:

fun parse(text: String): JSON5Value

Backward compatibility method:

fun parseToAny(text: String): Any? // Original behavior

Both methods also support reviver functions.

Helper Methods

Added JSON5Value.from(value: Any?) companion method to convert existing Kotlin objects to strongly-typed JSON5 values.

Usage Examples

New Strongly-Typed API

val result: JSON5Value = JSON5.parse("""
{
    // Comments are supported
    name: 'My App',
    version: 1.0,
    enabled: true
}
""")

when (result) {
    is JSON5Value.Object -> {
        val name = result.value["name"] as JSON5Value.String
        println("App: ${name.value}")
    }
}

Backward Compatibility

// Existing code can use parseToAny()
val result: Any? = JSON5.parseToAny("""{"key": "value"}""")
val map = result as Map<String, Any?>

Breaking Changes

⚠️ Breaking Change: The parse() method now returns JSON5Value instead of Any?.

Migration: Replace JSON5.parse() with JSON5.parseToAny() to preserve existing behavior.

Testing

• Added comprehensive test coverage for the new API (12 new tests)
• Updated existing tests to use parseToAny() for compatibility
• All 139 tests pass, ensuring no regressions

Fixes #38.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[hossain-khan]

Well done 👍🏽