Context

TOON performs best with flat, uniform JSON objects, as I have seen in this Youtube video. In cases where the input JSON is deeply nested, token counts can actually increase after conversion, which limits TOON’s efficiency for many real-world data structures.

Proposal

Add an optional utility that flattens nested JSON data before TOON encoding.
The goal is not to modify TOON’s core format, but to provide a lightweight preprocessing step that makes existing data more TOON-friendly.

Example

Input:

{
  "user": {
    "id": 1,
    "profile": { "name": "Alice", "city": "Paris" }
  }
}

Flattened:

{
  "user.id": 1,
  "user.profile.name": "Alice",
  "user.profile.city": "Paris"
}

This flatter structure can then be serialized more compactly by TOON.

Questions for maintainers

1. Would this fit within the main TOON repo (e.g., src/utils/flatten.ts) or should it be a separate companion tool like toon-flatten?
2. Any existing guidelines for extending utilities or CLI commands?

Motivation

This addition would make TOON usable in more scenarios (especially LLM workflows with nested API data) while keeping the core spec untouched.

(Note: I’m a fresher and this would be my first open-source contribution. I’m eager to start small and happy to follow your guidance on scope or approach.)