circe/circe

This milestone release bumps several dependency versions, including Cats (from 1.0.1 to 1.1.0), Jawn (from 0.11.1 to 0.12.1), refined (from 0.8.7 to 0.9.0), and Monocle (from 1.5.0 to 1.5.1-cats).

It includes a few other changes, including the following:

• A fix for a bug involving optional fields and stateful decoding (#708) by Jonas Adler (#880).
• A fix for a bug involving an inconsistency in the behavior of optional decoders by Hugh Giddens (#851).
• An optimization for name transformations in circe-generic-extras by vndzzz (#860).
• Support for encodeOnly and decodeOnly for @ConfiguredJsonCodec by Espen Wiborg (#847).
• Removal of all methods deprecated in 0.9 (#888).
• A small optimization for JsonObject (#889).
• No more Scala 2.10!

The 0.10.0 release is likely also to include versions of #697, #856, and #754, and to fix #885, #855, and #792. Feedback about other features or priorities you want to see in 0.10 would be appreciated. I'm hoping to publish 0.10.0 by mid-May, but no promises.

I don't currently intend to publish other circe projects depending on this milestone release, but if there's demand (and pull requests) I'd be happy to.

This release updates the Cats version from the first to the second 1.0.0 release candidate. It also updates the Scala.js version (from 0.6.20 to 0.6.21) and several patch and plugin versions.

There's one major set of breaking API changes: the old Decoder#product (which returned a function from two cursors) has been removed, Decoder#and has been deprecated and renamed to Decoder#product, and Decoder#split has been deprecated.

This release also includes several other additions and changes:

• @haraldme added a escapeNonAscii configuration option to Printer that causes all non-ASCII characters to be escaped when printing JSON.
• @tlangs added configuration helpers for kebab-cased JSON object keys to the generic-extras module (#790).
• @howyp added Encoder and Decoder instances for Java's boxed versions of primitive types, as well as BigInteger and BigDecimal (#802).
• @s-nel added Encoder and Decoder instances for java.time.OffsetTime to circe-java8 (#810).
• @liff resolved some Serializable-related bugs (#763).
• I made some changes to circe-generic that are intended to support more reproducible builds (#791).

Thanks to all contributors and tire-kickers, and please keep an eye out for the final 0.9.0 release that will be available shortly after Cats 1.0.0 is published (probably next week).

This is the second 0.9.0 milestone release, and the first circe release for yesterday's Cats 1.0.0-RC1.

This release removes circe-streaming from this repository (see #774 and Gitter for discussion). It will shortly be resurrected into its own repository in the circe organization, and I'll publish an 0.9.0-M2 release for it once we get this issue resolved. Thanks to @aeons for taking care of this clean-up and for setting up the new repository.

This release includes a few changes not in 0.9.0-M1:

• @pjan has added derivation helpers for value classes to the generic-extras module (#661).
• @vkostyukov added some performance improvements for binary printing (#739).
• @jonas updated the project to sbt 1.0 (#761).
• @nigredo-tori changed disjunctionCodecs to use the more precise ObjectEncoder (#757).
• @lukestephenson reverted the type of a deprecated method to ease upgrades from 0.8 (#737).
• @aeons fixed some docs (#740).
• @allantl added some missing pieces to the tutorial (#755).
• There's a new Decoder#either convenience method (#759).
• We use blackbox macros in a couple of places we'd previously used whitebox (#762).
• The Scala.js version is now 0.6.20 (#741).
• Lots of other versions are updated (#750, #758, #764, #771, etc.).
• We added two adopters to the adopters list (#752, #772).

Thanks to all contributors, and also to everyone brave enough to try out these milestone releases!

This is the first milestone release for circe 0.9.0, and the first circe release for Cats 1.0.0-MF. There is likely to be one more milestone release (or possibly a release candidate) before 0.9.0 final, and it will probably include a couple of additions and possibly a few more breaking changes (most notably to BiggerDecimal in circe-numbers, which is unlikely to affect most users).

While there are a number of breaking changes in this release, most should not affect most users. One prominent exception is the dropNullKeys method on Printer, which is pretty widely used and has been renamed to dropNullValues.

I'm aiming for next weekend (27 August 2017) for the second milestone, and the first week of September for 0.9.0 final, which means that 0.9.0 may depend on Cats 1.0.0-RC1, but 1.0.0-MF is probably more likely. In the longer term, I'm hoping to publish 0.10.0 (which will include an overhaul of the way decoding is done) by mid-October, and 1.0.0 as soon as possible after Cats 1.0 is released. We use semantic versioning, which will be enforced by MiMa starting at 1.0.0 (which is one of the reasons for all the annoying renaming and shuffling in this release—I don't want to get stuck forever with an API I don't like).

Please use this milestone with caution, and report any issues you run into (either here on GitHub or on Gitter).

Performance

One focus of 0.9.0 is improving runtime performance, and in our benchmarks this milestone is quite a bit faster than 0.8.0:

Results for 0.9.0-M1

Benchmark                            Mode  Cnt      Score     Error  Units
ReadingBenchmark.readFoosCirce      thrpt   40   3610.520 ±  37.232  ops/s
ReadingBenchmark.readIntsCirce      thrpt   40  18375.199 ±  57.332  ops/s

WritingBenchmark.writeFoosCirce     thrpt   40   3745.881 ± 141.975  ops/s
WritingBenchmark.writeIntsCirce     thrpt   40  30295.139 ± 262.251  ops/s

Results for 0.8.0 (compared to 0.9.0-M1)

ReadingBenchmark.readFoosCirce      thrpt   40   2321.100 ±  14.573  ops/s (-37.5%)
ReadingBenchmark.readIntsCirce      thrpt   40  17000.038 ±  79.220  ops/s (- 7.5%)

WritingBenchmark.writeFoosCirce     thrpt   40   3104.464 ±  13.952  ops/s (-17.1%)
WritingBenchmark.writeIntsCirce     thrpt   40  19970.840 ±  69.970  ops/s (-34.1%)

Results for other Scala JSON libraries (compared to 0.9.0-M1)

Benchmark                            Mode  Cnt      Score     Error  Units
ReadingBenchmark.readFoosArgonaut   thrpt   40   1450.510 ±  10.015  ops/s (-59.8%)
ReadingBenchmark.readFoosJson4s     thrpt   40   1175.200 ±  14.908  ops/s (-67.5%)
ReadingBenchmark.readFoosPlay       thrpt   40   1251.828 ±   6.084  ops/s (-65.3%)
ReadingBenchmark.readFoosSpray      thrpt   40   2048.340 ±  28.382  ops/s (-43.3%)

ReadingBenchmark.readIntsArgonaut   thrpt   40   8762.412 ± 251.404  ops/s (-52.3%)
ReadingBenchmark.readIntsJson4s     thrpt   40   5684.703 ±  21.309  ops/s (-69.0%)
ReadingBenchmark.readIntsPlay       thrpt   40   9435.281 ± 308.286  ops/s (-48.7%)
ReadingBenchmark.readIntsSpray      thrpt   40  17369.818 ±  47.954  ops/s (- 5.5%)

Benchmark                            Mode  Cnt      Score     Error  Units
WritingBenchmark.writeFoosArgonaut  thrpt   40   2389.306 ±  75.548  ops/s (-36.2%)
WritingBenchmark.writeFoosJson4s    thrpt   40   1076.026 ±  30.364  ops/s (-71.3%)
WritingBenchmark.writeFoosPlay      thrpt   40   1402.058 ±  13.982  ops/s (-62.6%)
WritingBenchmark.writeFoosSpray     thrpt   40   3215.051 ±  72.822  ops/s (-17.1%)

WritingBenchmark.writeIntsArgonaut  thrpt   40  17469.530 ± 251.703  ops/s (-42.3%)
WritingBenchmark.writeIntsJson4s    thrpt   40   4444.495 ± 136.907  ops/s (-85.3%)
WritingBenchmark.writeIntsPlay      thrpt   40   3860.710 ± 114.302  ops/s (-87.3%)
WritingBenchmark.writeIntsSpray     thrpt   40  18030.909 ±  79.015  ops/s (-40.5%)

So for the first time circe outperforms all other Scala JSON libraries in all of our benchmarks (if only barely, in the case of some of the Spray results). The upcoming 0.9.0 release should increase the throughput a bit further, especially for the integer array reading benchmarks.

Additions

• New Json.Folder for folding Json values with fewer allocations (#656).
• New Printer#reuseWriters for ThreadLocal string builder caching (#657).
• New JsonObject.apply method (#637).
• New := syntax for object definitions (#589).
• New instances for java.time.Duration (#636).
• New circe-numbers-testing module (#652).
• New asNull and withNull methods for Json (#656).
• New Fold[JsonObject, (String, Json)] instance in circe-optics (#642).
• New AsyncParser parsing mode configuration in circe-streaming (#712).
• New transformConstructorNames configuration option in circe-generic-extras (#648).
• New number parsing benchmarks (#695).
• New JsonObject benchmarks (#698).
• New data directory with Sonatype download stats (#675).

Renaming and API changes

• Printer#dropNullKeys is now dropNullValues (#702).
• ACursor#values and keys now return Iterables instead of Vectors (#696).
• Decoder.decodeCanBuildFrom has been replaced by decodeTraversable and decodeArray (#728).
• withSnakeCaseKeys is now withSnakeCaseMemberNames (#684).
• transformKeys is now transformMemberNames (#684).
• JsonObject.from is now fromFoldable (#696).
• BiggerDecimal.fromDouble is now fromDoubleUnsafe (#667).
• Encoder.forProductN now takes a function to ProductN rather than tuples (#673).

Deprecations

• The truncateToX methods on JsonNumber are now deprecated (#706).
• ACursor#fields and fieldSet are now deprecated in favor of keys (#696).

Bug fixes

• maxDigits is respected in BiggerDecimal#toBigIntegerWithMaxDigits (#655).
• handleErrorWith in the MonadError instance for KeyDecoder now works correctly (#676).
• Generic derivation doesn't fail for nested sequences of tagged types (#659).
• Partial decoders work with -Ypartial-unification (#728).
• Fixed new issue with Scala.js tests on 2.10 (#731).
• Hygiene tests and benchmark modules are now aggregated (#670).

Other changes

• More instances are serializable (#671).
• Laws in circe-testing now use Shrink[Json] instance (#666).
• Better error messages for Decoder.decodeList (#643).
• Decoder#failedWithMessage includes history (#646).

Documentation and testing

• Improved documentation for SI-7046 workarounds (#644).
• Improved KeyEncoder documentation (#699).
• Test reorganization (#669).

Internal changes

• Performance improvements for JsonObject (#696).
• Performance improvements for Printer (#657).
• Performance improvements for KeyDecoder (#694).
• Renamed Json case class members for consistency (#653).
• Minimized internal use of Json constructors (#674).
• JsonBigDecimal now uses Java's BigDecimal rather than Scala's (#668).
• Prefer underlying when using Scala's BigDecimal and BigInt (#689).
• Prefer unaliased cats.kernel imports (#705).

Updated versions

• Cats to 1.0.0-MF (#724).
• Scala.js to 0.6.19 (#719).
• iteratee.io to 0.13.0 (#729).

New adopters and related projects

• Snowplow Analytics (#634).
• HolidayCheck (#677).
• DriveTribe (#716).
• sttp (#723).

Thanks to all contributors, including Rafał Krzewski (for tracking down a really annoying bug), Sergey Kolbasov (for new circe-streaming mode configuration options), Cyril Ponomaryov (for miscellaneous bug fixes and := syntax), Nathan Kleyn (for new circe-generic-extras configuration options), Luis Angel Vicente Sanchez (for forProductN API improvements), Sören Brunk (for new java.time instance), and Dale Wijnand (for the Cats 1.0.0-MF update).

This release (candidate) includes contributions by 25 people, which I believe is a record for the project—thanks to all of you, and especially the 15 or 16 first-time contributors.

There are a couple of reasons this is a release candidate instead of a release. The first is that I'd like to give 2.12 users a chance to kick the tires on the fix for generic derivation for case classes with tagged members (#617). I'd also like to give all users one more chance to complain about the removal of the implicit default configuration in circe-generic-extras (#597), the new, more verbose encoding for scodec's BitVector (#551), etc.

If no bugs turn up and nobody complains loudly enough, I'll publish this release as 0.8.0 next Saturday (7 May 2017).

Bug fixes

This release fixes a bug reported by @felher (#604) that resulted in generic derivation failures on Scala 2.12 for case classes with members tagged with Shapeless's @@ (and presumably other similar mechanisms). The difference in 2.12 was due to a change in the behavior of the Scala reflection API's RefinedType extractor, which is accommodated in #617.

Cyril Ponomaryov fixed a bug (reported by Giovanni Caporaletti in #578) that could result in spurious decoding failures when using custom decoders for Option that are constructed with emap.

Michael Sitko fixed a bug in circe-scodec (reported by Daniel Urban in #551) that resulted in bit vectors not being round-trippable because the encoding right-padded the bits to the next byte boundary. We considered adding a header to the encoding to indicate the length, but decided on a more verbose JSON object encoding that specifies the length in a separate field (primarily to avoid confusion that could result when accidentally attempting to decode a BitVector as a ByteVector). If you need a more concise string representation, please use ByteVector instead of BitVector.

This release also includes fixes for three number-related bugs that were backported to 0.7 for the 0.7.1 release.

Additions

Alberto Paro has added an experimental @JsonKey annotation to circe-generic-extras to help with the common use case where individual fields need to be renamed in a way that isn't necessarily systematic (e.g. camel-case to snake-case):

scala> import io.circe.generic.extras._, io.circe.generic.extras.defaults._, io.circe.syntax._
import io.circe.generic.extras._
import io.circe.generic.extras.defaults._
import io.circe.syntax._

scala> @ConfiguredJsonCodec case class Bar(@JsonKey("my-int") i: Int, s: String)
defined class Bar
defined object Bar

scala> Bar(13, "Qux").asJson.noSpaces
res0: String = {"my-int":13,"s":"Qux"}

This annotation is somewhat at odds with the circe design guidelines, but the circe-generic-extras module is explicitly intended to be a space for experimentation, and if there's evidence that @JsonKey is useful and that people want it, it could someday be promoted to circe-generic.

The circe-java8 module is now available for Scala.js, thanks to Carlos Quiroz's scala-java-time library and integration by Olli Helenius (#560). Note that this dependency is not necessary for the JVM version of the module, and that it may eventually be dropped for Scala.js (if java.time is supported more directly at some point).

Removals

The circe-generic-extras module no longer provides a default implicit configuration (#597). Users must now provide an instance anywhere they use generically derived codecs, either by defining their own or adding this (new) import:

import io.circe.generic.extras.defaults._

I personally see this change as potentially controversial, but nobody complained when it was proposed (and implemented) by Simon Hafner, and I can see the argument for more explicitness in this respect. The circe-generic-extras module should still be considered experimental, though, and the default instance may be reinstated in a future release.

Other changes

• Optimized binary printing based on findings in the Finch project by Vladimir Kostyukov (#621).
• Encoder and Decoder for java.time.Period by Kacper Gunia (#550).
• Documentation improvements by Aaron Levin (#571).
• Build updates and improvements by @n4to4 and Joe Green (#568, #573, #577, #580, #591).
• Coursier-powered build by Bruno Bieth (#606).
• Numerous version updates, including refined (0.6.2 to 0.8.0) and Scala.js (0.6.14 to 0.6.16).
• Eleven newly listed adopters!

As always thanks to all contributors, bug reporters, question askers, etc.!