aeson v0.10.0.0 Release Notes

  • ๐ŸŽ Performance improvements

    • Direct encoding via the new toEncoding method is over 2x faster than toJSON. (You must write or code-gen a toEncoding implementation to unlock this speedup. See below for details.)

    • ๐Ÿ‘Œ Improved string decoding gives a 12% speed win in parsing string-heavy JSON payloads (very common).

    • Encoding and decoding of time-related types are 10x faster (!!) as a result of bypassing Data.Time.Format and the arbitrary-precision Integer type.

    • When using toEncoding, [Char] can be encoded without a conversion to Text. This is fast and efficient.

    • ๐Ÿ“œ Parsing into an Object is now 5% faster and more allocation-efficient.

    SUBTLE API CHANGES, READ CAREFULLY

    ๐Ÿ—„ With the exception of long-deprecated code, the API changes below should be upwards compatible from older versions of aeson. If you run โฌ†๏ธ into upgrade problems, please file an issue with details.

    • The ToJSON class has a new method, toEncoding, that allows direct encoding from a Haskell value to a lazy bytestring without construction of an intermediate Value.

    The performance benefits of direct encoding are significant: more than 2x faster than before, with less than 1/3 the memory usage.

    To preserve API compatibility across upgrades from older versions of this library, the default implementation of toEncoding uses toJSON. You will not see any performance improvement unless you write an implementation of toEncoding, which can be very simple:

      instance ToJSON Coord where
        toEncoding = genericToEncoding defaultOptions
    

    (Behind the scenes, the encode function uses toEncoding now, so if you implement toEncoding for your types, you should see a speedup immediately.)

    If you use Template Haskell or GHC Generics to auto-generate your ToJSON instances, you'll benefit from fast toEncoding implementations for free!

    • When converting from a Value to a target Haskell type, FromJSON instances now provide much better error messages, including a complete JSON path from the root of the object to the offending element. This greatly eases debugging.

    • It is now possible to use Template Haskell to generate FromJSON and ToJSON instances for types in data families.

    • If you use Template Haskell or generics, and used to use the camelTo function to rename fields, the new camelTo2 function is smarter. For example, camelTo will rename CamelAPICase to camelapi_case (ugh!), while camelTo2 will map it to camel_api_case (yay!).

    • ๐Ÿ†• New ToJSON and FromJSON instances for the following time-related types: Day, LocalTime.

    • ๐Ÿ“œ FromJSON UTCTime parser accepts the same values as for ZonedTime, but converts any time zone offset into a UTC time.

    • The Result type is now an instance of Foldable and Traversable.

    • ๐Ÿšš The Data.Aeson.Generic module has been removed. It was deprecated in late 2013.

    • ๐Ÿ‘ GHC 7.2 and older are no longer supported.

    • The instance of Monad for the Result type lacked an implementation of fail (oops). This has been corrected.

    • Semantics of (.:?) operator are changed. It's doesn't anymore accept present Null value.

    • โž• Added (Foldable t, ToJSON a) => ToJSON (t a) overlappable instance. You might see No instance for (Foldable YourPolymorphicType) arising from a use of โ€˜.=โ€™ -errors due this change.