feat: add encode_json and loads helpers for better JSON null support

src/toon_format/__init__.py

@@ -23,12 +23,20 @@
 from .decoder import ToonDecodeError, decode
 from .encoder import encode
 from .types import DecodeOptions, Delimiter, DelimiterKey, EncodeOptions
-from .utils import compare_formats, count_tokens, estimate_savings
+from .utils import (
+    compare_formats,
+    count_tokens,
+    encode_json,
+    estimate_savings,
+    loads,
+)
 
 __version__ = "0.9.0-beta.1"
 __all__ = [
     "encode",
     "decode",
+    "encode_json",
+    "loads",
     "ToonDecodeError",
     "Delimiter",
     "DelimiterKey",

src/toon_format/utils.py

@@ -31,7 +31,7 @@
 # __init__.py defines encode() before importing utils, so this is safe
 from . import encode
 
-__all__ = ["count_tokens", "estimate_savings", "compare_formats"]
+__all__ = ["count_tokens", "estimate_savings", "compare_formats", "encode_json", "loads"]
 
 
 _TIKTOKEN_MISSING_MSG = (
@@ -40,6 +40,43 @@
 )
 
 
+def loads(json_string: str) -> Any:
+    """Parse JSON string into Python objects.
+
+    This is an alias for `json.loads()` provided for convenience and to ensure
+    a TOON-friendly integration flow where JSON 'null' is correctly converted
+    to Python 'None'.
+
+    Args:
+        json_string: The JSON string to parse.
+
+    Returns:
+        Any: Parsed Python data structure.
+    """
+    return json.loads(json_string)
+
+
+def encode_json(json_string: str) -> str:
+    """Encode a JSON string directly into TOON format.
+
+    Parses the JSON string (converting 'null' to 'None' automatically)
+    and then encodes the resulting Python object into TOON.
+
+    Args:
+        json_string: The JSON string to encode.
+
+    Returns:
+        str: TOON-formatted string.
+
+    Example:
+        >>> import toon_format
+        >>> toon_format.encode_json('{"abc": null}')
+        'abc: null'
+    """
+    data = loads(json_string)
+    return encode(data)
+
+
 def _require_tiktoken():
     try:
         import tiktoken  # type: ignore[import-not-found]

tests/test_json_integration.py

@@ -0,0 +1,39 @@
+import json
+from toon_format import encode_json, loads, encode
+
+def test_loads_null_to_none():
+    json_str = '{"abc": null, "xyz": 123}'
+    data = loads(json_str)
+    assert data["abc"] is None
+    assert data["xyz"] == 123
+    print("test_loads_null_to_none passed")
+
+def test_encode_json_integration():
+    json_str = '{"abc": null, "xyz": null}'
+    # This should automatically handle null -> None -> TOON null
+    toon_output = encode_json(json_str)
+    expected = "abc: null\nxyz: null"
+    assert toon_output.strip() == expected
+    print("test_encode_json_integration passed")
+
+def test_complex_json_integration():
+    json_str = '''
+    {
+        "status": "success",
+        "data": {
+            "user": null,
+            "items": [1, null, 3]
+        }
+    }
+    '''
+    toon_output = encode_json(json_str)
+    assert "user: null" in toon_output
+    # Check for null in items array (can be inline "1,null,3" or list "- null")
+    assert "null" in toon_output
+    print("test_complex_json_integration passed")
+
+if __name__ == "__main__":
+    test_loads_null_to_none()
+    test_encode_json_integration()
+    test_complex_json_integration()
+    print("All JSON integration tests passed!")