API and code cleanup

[hossain-khan]

Remove following API from JSON5 and replace with the new type safe parse() API

    /**
     * Parses a JSON5 string into a raw Kotlin object without type conversion.
     *
     * @param text JSON5 text to parse
     * @return The parsed value (Map, List, String, Number, Boolean, or null)
     * @throws JSON5Exception if the input is invalid JSON5
     */
    fun parseToAny(text: String): Any? {
        return JSON5Parser.parse(text)
    }

Update all unit test and usages to use the strongly typed JSON5 value class.

[hossain-khan]

JSON5 Kotlin Library Technical Diagrams

Here are Mermaid diagrams that explain the architecture and flow of the JSON5 Kotlin library. These will help engineers quickly understand how the components work together.

1. Architecture Overview

graph TD
    subgraph API [Public API]
        JSON5[JSON5]
        JSON5Value[JSON5Value]
    end
    
    subgraph CoreProcessors [Core Processors]
        Parser[JSON5Parser]
        Lexer[JSON5Lexer]
        Serializer[JSON5Serializer]
    end
    
    subgraph DataModel [Data Model]
        Token[Token]
        Token-->|types|TokenType[TokenType]
        Exception[JSON5Exception]
    end
    
    Client(Client Code)-->|parse/stringify|JSON5
    Client-->|interact with|JSON5Value
    
    JSON5-->|uses|Parser
    JSON5-->|uses|Serializer
    Parser-->|consumes tokens from|Lexer
    Parser-->|creates|JSON5Value
    Parser-->|throws|Exception
    Lexer-->|produces|Token
    Lexer-->|throws|Exception
    Serializer-->|throws|Exception
    
    classDef api fill:#f9f,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:1px;
    classDef model fill:#bfb,stroke:#333,stroke-width:1px;
    classDef client fill:#fff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    
    class JSON5,JSON5Value api;
    class Parser,Lexer,Serializer core;
    class Token,TokenType,Exception model;
    class Client client;

Loading

2. Parsing Flow

sequenceDiagram
    participant C as Client
    participant J as JSON5
    participant P as JSON5Parser
    participant L as JSON5Lexer
    participant T as Token
    participant V as JSON5Value
    
    C->>J: parse(jsonText)
    J->>P: parse(jsonText)
    P->>L: new JSON5Lexer(jsonText)
    
    loop Until complete JSON5 structure is parsed
        P->>L: nextToken()
        L-->>P: Token (Punctuator/String/Number/etc)
        
        alt Token is {
            P->>P: parseObject()
            loop For each property
                P->>L: nextToken() for key
                L-->>P: Token (String/Identifier)
                P->>L: nextToken() for colon
                L-->>P: Token (:)
                P->>L: nextToken() for value
                L-->>P: Token (value)
                P->>P: parse value recursively
            end
        else Token is [
            P->>P: parseArray()
            loop For each element
                P->>L: nextToken() for element
                L-->>P: Token (element)
                P->>P: parse element recursively
            end
        else Token is other value
            P->>P: parseValue()
        end
    end
    
    P-->>J: Parsed structure (Map/List/Value)
    J->>V: JSON5Value.from(parsed)
    J-->>C: JSON5Value

Loading

3. Serialization Flow

sequenceDiagram
    participant C as Client
    participant J as JSON5
    participant S as JSON5Serializer
    participant V as SerializerVisitor
    
    C->>J: stringify(value, space)
    J->>S: stringify(value, space)
    S->>V: new SerializerVisitor(space)
    V->>V: serializeValue(value)
    
    alt value is Object/Map
        V->>V: serializeObject(value, indent)
        loop For each property
            V->>V: serializePropertyName(key)
            V->>V: serializeValue(value[key], newIndent)
        end
    else value is Array/List
        V->>V: serializeArray(value, indent)
        loop For each element
            V->>V: serializeValue(element, newIndent)
        end
    else value is String
        V->>V: serializeString(value)
    else value is Number
        V->>V: serializeNumber(value)
    else value is Boolean
        V->>V: value.toString()
    else value is null
        V->>V: "null"
    end
    
    V-->>S: JSON5 string
    S-->>J: JSON5 string
    J-->>C: JSON5 string

Loading

4. Component Responsibilities

classDiagram
    class JSON5 {
        +parse(text: String): JSON5Value
        +parse(text: String, reviver): JSON5Value
        +stringify(value: Any?, space: Any?): String
        +encodeToString(serializer, value): String
        +decodeFromString(deserializer, string): T
    }
    
    class JSON5Lexer {
        -source: String
        -pos: Int
        -line: Int
        -column: Int
        +nextToken(): Token
        -skipWhitespace()
        -skipComments()
        -readString()
        -readNumber()
        -readIdentifier()
    }
    
    class JSON5Parser {
        +parse(text: String): Any?
        +parse(text: String, reviver): Any?
        -parseObject(lexer): Map
        -parseArray(lexer): List
        -parseValue(token, lexer): Any?
    }
    
    class JSON5Serializer {
        +stringify(value: Any?, space: Any?): String
        -serializeValue(value)
        -serializeString(value)
        -serializeNumber(value)
        -serializeObject(obj, indent)
        -serializeArray(array, indent)
    }
    
    class Token {
        +type: TokenType
        +line: Int
        +column: Int
    }
    
    class JSON5Value {
        +asString(): String
        +asNumber(): Number
        +asBoolean(): Boolean
        +asObject(): Map
        +asArray(): List
        +isNull(): Boolean
    }
    
    JSON5 --> JSON5Parser: uses
    JSON5 --> JSON5Serializer: uses
    JSON5Parser --> JSON5Lexer: uses
    JSON5Parser ..> JSON5Value: creates
    JSON5Lexer ..> Token: produces

Loading

These diagrams provide a comprehensive view of the library's architecture and data flow, making it easier for engineers to understand how the components work together to parse and serialize JSON5 data.

[hossain-khan]

Here are two Mermaid diagrams for onboarding engineers to the JSON5 Kotlin library: an Architecture Overview and a Parsing Flow. You can embed these in your GitHub README.

1. Architecture Overview

graph TD
    subgraph lib [lib: JSON5 Core Library]
        JSON5
        JSON5Parser
        JSON5Lexer
        JSON5Serializer
        JSON5Value
        JSON5Exception
    end

    subgraph app [app: Application]
        AppCode
    end

    subgraph benchmark [benchmark: Performance Benchmarks]
        BenchmarkCode
    end

    AppCode -->|uses| JSON5
    BenchmarkCode -->|uses| JSON5

    JSON5 -->|parsing| JSON5Parser
    JSON5Parser -->|tokenizes| JSON5Lexer
    JSON5 -->|serializing| JSON5Serializer
    JSON5Parser -->|returns| JSON5Value
    JSON5Serializer -->|outputs| JSON5Value
    JSON5Parser -->|errors| JSON5Exception
    JSON5Lexer -->|errors| JSON5Exception
    JSON5Serializer -->|errors| JSON5Exception

Loading

2. JSON5 Parsing Flow

sequenceDiagram
    participant User as User/App
    participant JSON5 as JSON5 (API)
    participant Parser as JSON5Parser
    participant Lexer as JSON5Lexer
    participant Value as JSON5Value

    User->>JSON5: parse(text)
    JSON5->>Parser: parse(text)
    Parser->>Lexer: nextToken()
    loop Tokenize input
        Lexer-->>Parser: Token
        Parser->>Lexer: nextToken()
    end
    Parser-->>JSON5: Parsed object (Map/List/Value)
    JSON5->>Value: JSON5Value.from(parsed)
    Value-->>JSON5: JSON5Value
    JSON5-->>User: JSON5Value

Loading

These diagrams provide a high-level understanding of the library’s structure and the flow of parsing JSON5 data.