Release for 2.0

content/blog/2024-10-04-arrow-2-0.md

@@ -0,0 +1,172 @@
+---
+title: Arrow 2.0 release
+category: articles
+tags: [core, articles]
+---
+
+# Arrow 2.0 release
+
+We are happy to announce the next major release of Arrow, version 2.0!
+
+This release is built with the new K2 compiler, and this gives us the ability
+to support a wider range of platforms, including WebAssembly. From now on, we shall
+provide artifacts for every platform supported by Kotlin.
+
+Apart from stabilization and general bug fixing, the theme of this release
+is improving the different DSLs provided by Arrow libraries. Our goal is to
+empower developers to write more succinct and readable code.
+
+* [Simple accumulation in Raise](#simple-accumulation-in-raise) (experimental)
+* [Additions to Fx](#additions-to-fx)
+* [Clearer retries for particular exceptions](#clearer-retries-for-particular-exceptions)
+* [Improved optics](#improved-optics) (breaking changes)
+* [Better support for kotlinx.serialization](#better-support-for-kotlinxserialization)
+
+## Upgrading to 2.0
+
+As previously announced, migrating your projects to this release should be hassle-free
+if your code compiled in 1.2.x without any deprecation warnings. Note that we talk about
+**source** compatibility here, we had to break **binary** compatibility in several places
+to implement improvements, such as in `NonEmptyList` and [`Schedule`](https://github.com/arrow-kt/arrow/pull/3504).
+
+There are two exceptions to this seamless transition. First, it was discovered that some
+functions for `Map` in `Raise` collide with those of the standard library. Furthermore,
+Arrow's variants return other `Map`, whereas the ones in the standard library return `List`.
+The decision was to [rename them](https://github.com/arrow-kt/arrow/pull/3512/files#diff-b378045af72d02f1e5d4037d411102fcdb768239abeabedf69a4520b74ad0278).
+
+The second breaking change is related to [improved optics](#improved-optics), please
+consult that section for further information.
+
+## Simple accumulation in Raise
+
+One of the core concepts when working with typed errors is the distinction
+between fail-first and [accumulation of errors](/learn/typed-errors/working-with-typed-errors/#accumulating-different-computations). Until now, the latter mode
+required using `zipOrAccumulate` and `mapOrAccumulate`, which sometimes obscure the actual
+flow of the computation.
+
+In Arrow 2.0 we have sprinkled some DSL dust over `Raise`, and now you can
+write your code in a more linear way. Inside an `accumulate` block (or in
+general, any `RaiseAccumulate`) you use `by accumulating` to execute some
+computation keeping all the errors.
+
+```kotlin
+// version with `zipOrAccumulate`
+zipOrAccumulate(
+    { checkOneThing() },
+    { checkOtherThing() }
+) { a, b -> doSomething(a, b) }
+
+// version with `accumulate`
+accumulate {
+    val a by accumulating { checkOneThing() }
+    val b by accumulating { checkOtherThing() }
+    doSomething(a, b)
+}
+```
+
+This DSL also includes shortcuts for the most common operations, like
+`bind`ing and accumulating any problem, or checking a single property
+of some data.
+
+```kotlin
+accumulate {
+    val name by Name(rawName).bindOrAccumulate()
+    ensureOrAccumulate(age >= 18) { UnderAge }
+    Person(name, age)
+}
+```
+
+Note that the API may still undergo some change. At this point you need `@OptIn(ExperimentalRaiseAccumulateApi::class)` to allow their usage in your code.
+
+## Additions to Fx
+
+Writing coroutine-heavy code may become cumbersome over time, especially if
+one intends to use as much concurrency as possible. Arrow Fx includes a `parZip`
+function, but not everybody enjoys having so many brackets.
+
+```kotlin
+parZip(
+    { downloadFile() },
+    { loadDataFromDatabase() }
+) { file, data -> Result(file, data) }
+```
+
+The new [`awaitAll` scope](/learn/coroutines/parallel/#await-all-scopes) tries to improve the situation by tweaking the
+usual `async` mechanism, ensuring that all `Deferred` values are `await`ed
+once the first one is requested. That means that the previous code behaves
+identically to the following, that is, the call `file.await()` implicitly
+awaits every `async` defined up to that point.
+
+```kotlin
+awaitAll {
+    val file = async { downloadFile() }
+    val data = async { loadDataFromDatabase() }
+    Result(file.await(), data.await())
+}
+```
+
+We've also improved the STM block by [allowing delegation](/learn/coroutines/stm/#reading-and-writing-concurrent-state) as a means to
+read or change the value of a `TVar`.
+
+```kotlin
+fun STM.deposit(accVar: TVar<Int>, amount: Int): Unit {
+    val acc by accVar       // delegation here
+    val current = acc       // implicit 'read'
+    acc = current + amount  // implicit 'write'
+}
+```
+
+## Clearer retries for particular exceptions
+
+Until now, the [`retry` operation](/learn/resilience/retry-and-repeat/) in the Resilience module would capture
+any `Throwable` exception. From version 2.0 on you can specify a subclass
+of `Throwable` to be the target for retrying, whereas the rest of
+exceptions will bubble as usual.
+
+```kotlin
+Schedule.recurs<Throwable>(2)
+        .retry<IllegalArgumentException, _> { ... }
+```
+
+The subclass of exceptions must be given as a type argument.
+Alas, Kotlin does not allow giving only a subset of those, and `retry`
+has two type parameters (the second one represents the output type of
+the `Schedule`). Fortunately, you can ask the compiler to infer the
+second one using `_`.
+
+## Improved optics
+
+The largest **breaking changes** in Arrow 2.0 relate to optics.
+First of all, the [optics hierarchy](/learn/immutable-data/intro/#many-optics-to-rule-them-all) has been greatly simplified:
+now we have traversals, optionals, lenses, prisms, and isos, and no more
+intermediate types. This smaller amount of types means that the type of
+optic compositions become easier to understand.
+
+We have also changed the generation of optics via the compiler plug-in
+(that is, the `@optics` annotation) with respect to nullable fields.
+In the 1.x series, a value of type `String?` would be presented as
+`Optional<T, String>`; this makes impossible to change the value from
+`null` to an actual `String` using only optics operations. From version
+2.0, that field is represented as `Lens<T, String?>`. To get the 1.x
+behavior you should apply `.notNull` after the optic corresponding to
+the field.
+
+A smaller breaking change is that generated optics are no longer
+[inlined by default](https://github.com/arrow-kt/arrow/pull/3505).
+This should prevent a large amount of warnings in which the compiler
+complain that inlining is not significant. Note that the previous behavior
+is still available under a flag.
+
+One pain point when building [traversals](/learn/immutable-data/traversal/) was the need to provide an
+argument to `.every`, like `.every(Every.list())`. This new version
+brings an improved variant that requires no arguments if the type
+of the `Iterable` is known. Similar improvements have been applied
+to `.at` and `.index`.
+
+## Better support for kotlinx.serialization
+
+Using Arrow Core data types as part of serialized data requires additional integration.
+In 1.2.x we started providing compile-time [support for `kotlinx.serialization`](/learn/quickstart/serialization/#kotlinxserialization).
+From 2.0 on we also provide `ArrowModule` for
+[contextual serialization](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serializers.md#contextual-serialization). This is needed, among others, when the data is processed
+by Ktor.

content/docs/learn/coroutines/parallel.md

@@ -79,6 +79,37 @@ if the amount of elements in the collection is too significant. To fight against
 problem, Arrow provides a version of `parMap` with an additional parameter that
 tells how many computations should be dispatched in parallel.
 
+### Await-all scopes
+
+Although `parZip` gives the most high-level view of the code, clearly specifying
+which tasks are independent of each other, it has the drawback of requiring a particular
+style of writing your computations. Arrow provides another tool based on `async`,
+where the code is written using the usual `async`/`.await()` idioms.
+
+<!--- INCLUDE
+import arrow.fx.coroutines.parZip
+import arrow.fx.coroutines.await.awaitAll
+typealias UserId = Int
+data class User(val name: String, val avatar: String)
+suspend fun getUserName(id: UserId): String = "$id-name"
+suspend fun getAvatar(id: UserId): String = "$id-avatar"
+-->
+```kotlin
+suspend fun getUser(id: UserId): User = awaitAll {
+  val name = async { getUserName(id) }
+  val avatar = async { getAvatar(id) }
+  User(name.await(), avatar.await())
+}
+```
+<!--- KNIT example-parallel-03.kt -->
+
+As the name suggests, within this `awaitAll` block, every time you call `.await()`
+_all_ of the `async` computations that were registered until that point are
+awaited. If any of those throws an exception, the whole block is canceled, as
+per the rules of structured concurrency. In general, writing a sequence of independent
+`async` computations within `awaitAll` is equivalent to giving those computations
+as arguments to `parZip`.
+
 ### Flows
 
 The [`parMap`](https://apidocs.arrow-kt.io/arrow-fx-coroutines/arrow.fx.coroutines/par-map.html)
@@ -113,7 +144,7 @@ suspend fun file(server1: String, server2: String) =
     { downloadFrom(server2) }
   ).merge()
 ```
-<!--- KNIT example-parallel-03.kt -->
+<!--- KNIT example-parallel-04.kt -->
 
 The example above shows a typical pattern combined with `raceN`.
 The result of the function above is `Either<A, B>`, with each type
@@ -156,7 +187,7 @@ suspend fun example() {
   println(triple)
 }
 ```
-<!--- KNIT example-parallel-04.kt -->
+<!--- KNIT example-parallel-05.kt -->
 
 ```text
 Sleeping for 500 milliseconds ...
@@ -210,7 +241,7 @@ suspend fun example() {
   println(res)
 }
 ```
-<!--- KNIT example-parallel-05.kt -->
+<!--- KNIT example-parallel-06.kt -->
 
 In the output, we can see that tasks `1` and `3` started, but `2` _raised_ an error that triggered the cancellation of the other two tasks.
 After tasks `1` and `3` are canceled, we see that the result of `raise` is returned and prints the error message.
@@ -255,7 +286,7 @@ suspend fun example() {
   println(res)
 }
 ```
-<!--- KNIT example-parallel-06.kt -->
+<!--- KNIT example-parallel-07.kt -->
 
 The example transforms, or maps, every element of an `Iterable` `[1, 2, 3, 4]` in _parallel_ using `parMap` and `failOnEven`.
 Since `failOnEven` raises an error when the `Int` is even, it fails for inputs 2 and 4, and the other two coroutines are canceled.

content/docs/learn/coroutines/stm.md

@@ -88,6 +88,35 @@ One additional guarantee of STM is that the _whole_ transaction is executed
 atomically. That means we can modify several `TVar`s in one transaction,
 and we'll never observe an intermediate state.
 
+:::tip Delegated transactional properties
+
+From version 2.0, you can use [property delegation](https://kotlinlang.org/docs/delegated-properties.html)
+to access a `TVar`. That way you don't need explicit `read` or `write`,
+they become implicit in the syntax.
+
+<!--- INCLUDE
+import arrow.fx.stm.atomically
+import arrow.fx.stm.TVar
+import arrow.fx.stm.STM
+-->
+
+```kotlin
+fun STM.deposit(accVar: TVar<Int>, amount: Int): Unit {
+  var acc by accVar       // property delegation
+  val current = acc       // implicit 'read'
+  acc = current + amount  // implicit 'write'
+  // or simply, acc = acc + amount
+}
+```
+
+<!--- INCLUDE
+suspend fun example() { }
+-->
+<!--- KNIT example-stm-02.kt -->
+<!--- TEST assert -->
+
+:::
+
 ### Other STM data structures
 
 The following types are built upon `TVar`s and provided out of the box with Arrow:
@@ -167,7 +196,7 @@ suspend fun example() = coroutineScope {
   acc2.unsafeRead() shouldBe 350
 }
 ```
-<!--- KNIT example-stm-02.kt -->
+<!--- KNIT example-stm-03.kt -->
 <!--- TEST assert -->
 
 `retry` can be used to implement a lot of complex transactions,
@@ -220,7 +249,7 @@ suspend fun example() {
   atomically { transaction(v) } shouldBe 5
 }
 ```
-<!--- KNIT example-stm-03.kt -->
+<!--- KNIT example-stm-04.kt -->
 <!--- TEST assert -->
 
 ## Exceptions

content/docs/learn/immutable-data/optional.md

@@ -57,8 +57,8 @@ val db = Db(mapOf(
 ))
 
 fun example() {
-  Db.cities.index(Index.map(), "Alejandro").country.getOrNull(db) shouldBe "Netherlands"
-  Db.cities.index(Index.map(), "Jack").country.getOrNull(db) shouldBe null
+  Db.cities.index("Alejandro").country.getOrNull(db) shouldBe "Netherlands"
+  Db.cities.index("Jack").country.getOrNull(db) shouldBe null
 }
 ```
 <!--- KNIT example-optional-01.kt -->
@@ -91,7 +91,7 @@ val db = Db(mapOf(
 
 ```kotlin
 fun example() {
-  val dbWithJack = Db.cities.index(Index.map(), "Jack").set(db, City("London", "UK"))
+  val dbWithJack = Db.cities.index("Jack").set(db, City("London", "UK"))
   // Jack was not really added to the database
   ("Jack" in dbWithJack.cities) shouldBe false
 }

content/docs/learn/immutable-data/traversal.md

@@ -75,20 +75,16 @@ and copying, and simply focuses on the path to access the values.
 
 ```kotlin
 fun Person.happyBirthdayFriendsOptics(): Person =
-  Person.friends.every(Every.list()).age.modify(this) { it + 1 }
+  Person.friends.every.age.modify(this) { it + 1 }
 ```
 <!--- KNIT example-traversal-01.kt -->
 
 :::note Every(List)
 
-You might be wondering why we need to write `Every.list()` as argument to `every`,
-given that we know that `Person.friends` focuses on a `List<Person>`.
-The reason is [type erasure](https://kotlinlang.org/docs/generics.html#type-erasure):
-the compiler cannot differentiate between `Lens<Person, List<Person>>`
-and `Lens<Person, Map<String, Person>>`, so there's no way to tell which
-is the right traversal to apply in each case. However, if we provide the
-hint ourselves by giving `Every.list()` as argument, the compiler is able
-to _check_ that our usage is correct.
+In versions prior to 2.0, `.every` required an additional argument specifying
+the type of traversal. So one would write `Person.friends.every(Every.list())`.
+This problem was related to [type erasure](https://kotlinlang.org/docs/generics.html#type-erasure),
+but fortunately, a new encoding was found without this caveat.
 
 :::
 

content/docs/learn/integrations.md

@@ -78,11 +78,21 @@ The main point of contact between Ktor and Arrow is in
 If you're using kotlinx.serialization, you need no further changes other than
 importing the serializers with `@UseSerializers`.
 
+If you want to use Arrow Core types directly as your request or response models, you will need to include the `ArrowModule` in your serializers module:
+
+```
+install(ContentNegotiation) {
+  json(Json {
+    serializersModule = ArrowModule
+  })
+}
+```
+
 If you're using Jackson, you can use the
 [custom mapper](https://github.com/arrow-kt/arrow-integrations#ktor),
 and pass it to the `ContentNegotiation` configuration.
 
-```kotlin
+```
 install(ContentNegotiation) {
   register(ContentType.Application.Json, JacksonConverter(JsonMapper.mapper))
 }