Arrow 1.2.0

We are thrilled to finally announce Arrow 1.2.0, the stable release that follows the 1.2.0-RC released in April. In the 1.2.0 version, we have introduced a brand new module for typed errors and additional options for resilience.

With the 1.2.0 release, we have finalized the APIs for version 2.0. To ensure community involvement, we marked every function and type we intend to remove as @Deprecated during the RC release cycle. Gathering input from the community is one of our primary goals with the 1.2.x series, and we are delighted to hear about the impact of these changes on your projects.

This release also celebrates Arrow’s 10th birthday, marking the first commit from one half of Arrow’s origin libraries! Simon Vergauwen gave a brief overview of the past 10-year journey at KotlinConf, which you can watch here.

Changes from RC

We received overwhelmingly positive feedback during the release candidate phase. The changes from the 1.2.0-RC release to the stable release are relatively minimal and involve no breaking changes. In particular, we have addressed one issue related to kapt and introduced three small features. Let’s review each of them in detail.

Improvements to Raise

Several teams have started porting their codebases to the new typed error mechanism based on Raise. We’ve added a new utility function to the library in response to their feedback.

withError

When working with typed errors using Raise or Either in Arrow, it is common to encounter different typed errors from various layers or modules. We have introduced a new DSL called withError to enhance convenience in such scenarios. This DSL enables the installation of a transformation (Error) -> OtherError within the DSL.

data class Error(val message: String)
data class OtherError(val message: String)

fun Error.toOtherError(): OtherError =
  OtherError(message)

fun one(): Either<Error, Int> = Error("BOOM!").left()
fun two(): Either<OtherError, Int> = 2.right()

val res: Either<OtherError, Int> = either {
  withError(Error::toOtherError) {
    one().bind() + two().bind()
  }
} shouldBeLeft OtherError("Boom!")

merge happy and error paths

The merge function in Arrow’s Either type allows you to "flatten" an Either when both the Left and Right sides have the same type. In the latest release, the Raise type now also provides the same functionality within its DSL.

val res: String = merge {
  if(Random.nextBoolean()) raise("failed")
  else "success"
} shouldBe "failed"

New NonEmptyCollection interface

In Arrow 1.2.0, we are introducing a common parent for NonEmptyList and NonEmptySet based on a Slack discussion. This enhancement brings a new parent type for non-empty collections. Additionally, the non-empty collections now overload more methods and provide non-null return types, in contrast to the nullable return types provided by regular Kotlin collections.

Complete API Docs

With the release of 1.2.0-RC, we launched a new website that includes a comprehensive documentation overhaul. This revamp focuses on real-world use cases and practical examples of Arrow usage. Consequently, the KDoc documentation may have seemed sparse, especially for new APIs. In Arrow 1.2.0, we have addressed this by ensuring all APIs are fully documented in the KDocs.

If you have any feedback regarding the website, please submit an issue in the Arrow Website repository. Similarly, if you have any feedback concerning the API Docs, please file an issue in the Arrow repository.

Arrow Optics KSP

Previously, the Arrow Optics KSP plugin had issues when combined with kapt. We are delighted to inform you that we have resolved this issue in Arrow 1.2.0. Once again, you can utilize the Arrow Optics KSP plugin with kapt-based projects.

Additionally, Arrow 1.2.0 introduces support for disabling inline code in the KSP generated. In particular, the use of inline in the plug-in made it difficult to use @optics with private or internal fields. By default, this feature remains enabled (given the important performance benefits of inline in this case), allowing for seamless integration with your projects.

ksp {
    arg("inline", "true")
    ...
}

Serialization Module

A new library, arrow-core-serialization, is included in this release. This library exports the serializers required for using Arrow Core types with kotlinx.serialization, one of the most used libraries in the Kotlin ecosystem. Previously, we only supported Jackson.

As a curiosity, this closes one of the longest-standing issues in our repository. We’ve made an additional bug-fixing round during this development cycle, ensuring our tracker is up-to-date.

Plans for Arrow 2.0

Aligning the release of Kotlin 2.0 and Arrow 2.0 makes the most sense for binary compatibility. While we anticipate this alignment to have only minor implications from the Kotlin perspective, it will make it easier for the entire community to transition to both major versions simultaneously, ensuring that nobody misses out on the benefits of the 2.0 API today.

We anticipate the K2 compiler to be released towards the end of the year or early 2024. Stay tuned for any announcements regarding its release! In the meantime, this gives Arrow 1.x an opportunity to mature further, incorporating additional feedback and improvements from the community as we approach the 2.0 release. Together, we are strongest!

Thanks

A special shout-out to all those who have supported and contributed to Arrow over the years. Your invaluable feedback and support have been critical to the development and growth of Arrow.

You can find the complete changelog on GitHub.

Xebia 💙 Kotlin

We, the functional team at Xebia, are great fans of Kotlin, exploring the many possibilities it brings to the back-end scene. We’re proud maintainers of Arrow, a set of companion libraries to Kotlin’s standard library, coroutines, and compiler; and provide Kotlin training to become an expert Kotliner. If you’re interested in talking to us, you can use our contact form, or join us on the Kotlin Slack.