Package dev.toonformat.jtoon.normalizer

package dev.toonformat.jtoon.normalizer
Java object normalization to Jackson JsonNode representation.

Overview

This package handles the conversion of Java objects into a normalized JsonNode representation that can be efficiently encoded to TOON format. It bridges the gap between Java's rich type system and the simpler JSON-like structure.

Core Component

JsonNormalizer

The main normalization engine that converts any Java object to JsonNode. Uses a chain of responsibility pattern to handle different type categories:

  1. Primitives: String, Boolean, Number types
  2. Big Numbers: BigInteger, BigDecimal
  3. Temporal Types: LocalDateTime, Instant, etc.
  4. Collections: Collection, Map, arrays
  5. POJOs: Arbitrary objects via Jackson

Type Conversions

Number Normalization

  • Non-finite values (NaN, ±Infinity) → null
  • -0.0 → 0
  • Whole doubles → converted to long when possible
  • BigInteger → long if within range, otherwise string

Temporal Types

All temporal types are converted to ISO-8601 formatted strings:

  • LocalDateTime → "2025-01-15T10:30:00"
  • LocalDate → "2025-01-15"
  • LocalTime → "10:30:00"
  • ZonedDateTime → "2025-01-15T10:30:00+01:00[Europe/Paris]"
  • OffsetDateTime → "2025-01-15T10:30:00+01:00"
  • Instant → "2025-01-15T09:30:00Z"
  • java.util.Date → converted to Instant then formatted

Special Java Types

  • Optional: Unwrapped to value or null
  • Stream: Materialized to List then normalized
  • Collection: Converted to ArrayNode
  • Map: Converted to ObjectNode with string keys
  • Arrays: All primitive and object arrays handled

Design Principles

LLM-Safe Output

All normalizations produce values that are:

  • Deterministic (same input always produces same output)
  • Unambiguous (no special number representations)
  • Standard (ISO formats for dates, decimal for numbers)

Graceful Degradation

Non-serializable objects are converted to null rather than throwing exceptions. This ensures the encoder can always produce output even with problematic data.

Usage Example

JsonNormalizer normalizer = new JsonNormalizer();

// Normalize a POJO
record User(int id, String name, LocalDateTime created) {}
User user = new User(123, "Ada", LocalDateTime.now());
JsonNode normalized = JsonNormalizer.normalize(user);

// Results in:
// {
//   "id": 123,
//   "name": "Ada",
//   "created": "2025-01-15T10:30:00"
// }

Thread Safety

The JsonNormalizer uses a shared ObjectMapper instance which is thread-safe. All normalization methods are stateless and safe to call concurrently.

Since:
0.1.0
See Also:
  • JsonNode
  • ObjectMapper