ION

ION - Isomorphic Object Notation

Purpose

ION is a JSON like object serialization format. If given the following code:

function isomorphicSerialize(obj: any) {
    const serialized = ION.stringify(obj);
    const deserialized = ION.parse(obj);
}

It guarantees that either:

• ION.stringify throws an error
• deserialized and obj are identical objects

JSON fails in various circumstances at this:

• Dates become strings
• undefined becomes null
• Symbols are omitted
• NaN, Infinity, and -Infinity become null
• Sets and maps become {}

In cases where something can't be perfectly recreated from parsing, ION will throw an error.

Performance

ION is optimized for performance while maintaining type safety guarantees:

Stringify Performance:

• Small objects: ~3.2x slower than JSON
• Medium objects: ~3.5x slower than JSON
• Large arrays (100 items): ~1.8x slower than JSON
• String-heavy data: ~2.1x slower than JSON

Parse Performance:

• Small objects: ~8.6x slower than JSON
• Medium objects: ~5.6x slower than JSON
• Large arrays (100 items): ~5.5x slower than JSON
• String-heavy data: ~2.4x slower than JSON

Average: ION stringify is ~2.2x slower and parse is ~5.7x slower than JSON, while providing complete type preservation and safety guarantees that JSON cannot offer.

Syntax

ION is a superset of JSON. Any valid JSON is valid ION, although not all objects are translated exactly the same.

{
    "string": "hello",
    "number": 123,
    "array": [
        {
            "name": null,
            "boolean": true,
        }
    ]
}

JSON has support for several types: boolean, number, string, object, and array. ION adds a couple more:

• Infinity
• -Infinity
• NaN
• Date
• Map
• Set

Note: WeakMap and WeakSet cannot be serialized and will throw an error if encountered.

If an object has any undefined properties, they are simply omitted. These advanced properties look like:

{
    "date": date:2026-01-27T15:30:00Z,
    "not-a-number": NaN,
    "infinity": Infinity,
    "negativeInf": -Infinity,
    "someMap": map {
        "property": 1,
        "another": 2
    },
    "someSet": set {
        "a",
        "b"
    }
}