git.iko.soy/typeable/aeson
on 0.10.0.0 help sign in
typeable/aeson/changelog.md
258 lines 8.8 kB history raw
1# 0.10.0.0
3## Performance improvements
5* Direct encoding via the new `toEncoding` method is over 2x faster
6 than `toJSON`. (You must write or code-gen a `toEncoding`
7 implementation to unlock this speedup. See below for details.)
9* Improved string decoding gives a 12% speed win in parsing
10 string-heavy JSON payloads (very common).
12* Encoding and decoding of time-related types are 10x faster (!!) as a
13 result of bypassing `Data.Time.Format` and the arbitrary-precision
14 `Integer` type.
16* When using `toEncoding`, `[Char]` can be encoded without a conversion to
17 `Text`. This is fast and efficient.
19* Parsing into an `Object` is now 5% faster and more
20 allocation-efficient.
22## SUBTLE API CHANGES, READ CAREFULLY
24With the exception of long-deprecated code, the API changes below
25**should be upwards compatible** from older versions of `aeson`. If you run
26into upgrade problems, please file an issue with details.
28* The `ToJSON` class has a new method, `toEncoding`, that allows
29 direct encoding from a Haskell value to a lazy bytestring without
30 construction of an intermediate `Value`.
32 The performance benefits of direct encoding are significant: more
33 than 2x faster than before, with less than 1/3 the memory usage.
35 To preserve API compatibility across upgrades from older versions of
36 this library, the default implementation of `toEncoding` uses
37 `toJSON`. You will *not* see any performance improvement unless you
38 write an implementation of `toEncoding`, which can be very simple:
40 ```haskell
41 instance ToJSON Coord where
42 toEncoding = genericToEncoding defaultOptions
43 ```
45 (Behind the scenes, the `encode` function uses `toEncoding` now, so
46 if you implement `toEncoding` for your types, you should see a
47 speedup immediately.)
49 If you use Template Haskell or GHC Generics to auto-generate your
50 `ToJSON` instances, you'll benefit from fast toEncoding
51 implementations for free!
53* When converting from a `Value` to a target Haskell type, `FromJSON`
54 instances now provide much better error messages, including a
55 complete JSON path from the root of the object to the offending
56 element. This greatly eases debugging.
58* It is now possible to use Template Haskell to generate `FromJSON`
59 and `ToJSON` instances for types in data families.
61* If you use Template Haskell or generics, and used to use the
62 `camelTo` function to rename fields, the new `camelTo2` function is
63 smarter. For example, `camelTo` will rename `CamelAPICase` to
64 `camelapi_case` (ugh!), while `camelTo2` will map it to
65 `camel_api_case` (yay!).
67* New `ToJSON` and `FromJSON` instances for the following time-related
68 types: `Day`, `LocalTime`.
70* The `Result` type is now an instance of `Foldable` and `Traversable`.
72* The `Data.Aeson.Generic` module has been removed. It was deprecated in
73 late 2013.
75* GHC 7.2 and older are no longer supported.
77* The instance of `Monad` for the `Result` type lacked an implementation
78 of `fail` (oops). This has been corrected.
82# 0.9.0.1
84* A stray export of `encodeToBuilder` got away!
86# 0.9.0.0
88* The `json` and `json'` parsers are now synonyms for `value` and
89 `value'`, in conformance with the looser semantics of RFC 7159.
91* Renamed `encodeToByteStringBuilder` to the more compact
92 `encodeToBuilder`.
94# 0.8.1.1
96* The dependency on the `unordered-containers` package was too lax,
97 and has been corrected.
99# 0.8.1.0
101* Encoding a `Scientific` value with a huge exponent is now handled
102 efficiently. (This would previously allocate a huge
103 arbitrary-precision integer, potentially leading to a denial of
104 service.)
106* Handling of strings that contain backslash escape sequences is
107 greatly improved. For a pathological string containing almost a
108 megabyte of consecutive backslashes, the new implementation is 27x
109 faster and uses 42x less memory.
111* The `ToJSON` instance for `UTCTime` is rendered with higher
112 (picosecond) resolution.
114* The `value` parser now correctly handles leading whitespace.
116* New instances of `ToJSON` and `FromJSON` for `Data.Sequence` and
117 `Data.Functor.Identity`. The `Value` type now has a `Read` instance.
119* `ZonedTime` parser ordering now favours the standard `JSON` format,
120 increasing efficiency in the common case.
122* Encoding to a `Text.Builder` now escapes `'<'` and `'>'` characters,
123 to reduce XSS risk.
125# 0.8.0.2
127* Fix `ToJSON` instance for 15-tuples (see #223).
129# 0.8.0.1
131* Support `time-1.5`.
133# 0.8.0.0
135* Add `ToJSON` and `FromJSON` instances for tuples of up to 15
136 elements.
138# 0.7.1.0
140* Major compiler and library compatibility changes: we have dropped
141 support for GHC older than 7.4, `text` older than 1.1, and
142 `bytestring` older than 0.10.4.0. Supporting the older versions had
143 become increasingly difficult, to the point where it was no longer
144 worth it.
146# 0.7.0.0
148* The performance of encoding to and decoding of bytestrings have both
149 improved by up to 2x, while also using less memory.
151* New dependency: the `scientific` package lets us parse floating point
152 numbers more quickly and accurately.
154* `eitherDecode`, `decodeStrictWith`: fixed bugs.
156* Added `FromJSON` and `ToJSON` instances for `Tree` and `Scientific`.
158* Fixed the `ToJSON` instances for `UTCTime` and `ZonedTime`.
160# 0.6 series
162* Much improved documentation.
164* Angle brackets are now escaped in JSON strings, to help avoid XSS
165 attacks.
167* Fixed up handling of nullary constructors when using generic
168 encoding.
170* Added `ToJSON`/`FromJSON` instances for:
172 * The `Fixed` class
173 * ISO-8601 dates: `UTCTime`, `ZonedTime`, and `TimeZone`
175* Added accessor functions for inspecting `Value`s.
177* Added `eitherDecode` function that returns an error message if
178 decoding fails.
180# 0.5 to 0.6
182* This release introduces a slightly obscure, but
183 backwards-incompatible, change.
185 In the generic APIs of versions 0.4 and 0.5, fields whose names
186 began with a `"_"` character would have this character removed. This
187 no longer occurs, as it was both buggy and surprising
188 (https://github.com/bos/aeson/issues/53).
190* Fixed a bug in generic decoding of nullary constructors
191 (https://github.com/bos/aeson/issues/62).
193# 0.4 to 0.5
195* When used with the UTF-8 encoding performance improvements
196 introduced in version 0.11.1.12 of the `text` package, this release
197 improves `aeson`'s JSON encoding performance by 33% relative to
198 `aeson` 0.4.
200 As part of achieving this improvement, an API change was necessary.
201 The `fromValue` function in the `Data.Aeson.Encode` module now uses
202 the `text` package's `Builder` type instead of the `blaze-builder`
203 package's `Builder` type.
205# 0.3 to 0.4
207* The new `decode` function complements the longstanding `encode`
208 function, and makes the API simpler.
210* New examples make it easier to learn to use the package
211 (https://github.com/bos/aeson/tree/master/examples).
213* Generics support
215 `aeson`'s support for data-type generic programming makes it
216 possible to use JSON encodings of most data types without writing
217 any boilerplate instances.
219 Thanks to Bas Van Dijk, `aeson` now supports the two major schemes
220 for doing datatype-generic programming:
222 * the modern mechanism, built into GHC itself
223 (http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html)
225 * the older mechanism, based on SYB (aka "scrap your
226 boilerplate")
228 The modern GHC-based generic mechanism is fast and terse: in fact,
229 its performance is generally comparable in performance to
230 hand-written and TH-derived `ToJSON` and `FromJSON` instances. To
231 see how to use GHC generics, refer to `examples/Generic.hs`.
233 The SYB-based generics support lives in `Data.Aeson.Generic` and is
234 provided mainly for users of GHC older than 7.2. SYB is far slower
235 (by about 10x) than the more modern generic mechanism. To see how
236 to use SYB generics, refer to `examples/GenericSYB.hs`.
238* We switched the intermediate representation of JSON objects from
239 `Data.Map` to `Data.HashMap` which has improved type conversion
240 performance.
242* Instances of `ToJSON` and `FromJSON` for tuples are between 45% and 70%
243 faster than in 0.3.
245* Evaluation control
247 This version of aeson makes explicit the decoupling between
248 *identifying* an element of a JSON document and *converting* it to
249 Haskell. See the `Data.Aeson.Parser` documentation for details.
251 The normal `aeson` `decode` function performs identification
252 strictly, but defers conversion until needed. This can result in
253 improved performance (e.g. if the results of some conversions are
254 never needed), but at a cost in increased memory consumption.
256 The new `decode'` function performs identification and conversion
257 immediately. This incurs an up-front cost in CPU cycles, but
258 reduces reduce memory consumption.