Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Mention ArrowModule in serialization and ktor sections #306

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions content/docs/learn/integrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,16 @@ 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:

```kotlin
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please, do not use ```kotlin here (or in the rest of the file), as it would trigger Knit, but these blocks are not complete Kotlin code.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've removed the kotlin tags from the code blocks, and also from the pre-existing blocks for consistency.

They weren't being picked up by knit in the build (at least a ./gradlew knit build passed) as there were no knit patterns in either file, but should one be added at a later it's better to avoid surprises.

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.
Expand Down
29 changes: 26 additions & 3 deletions content/docs/learn/quickstart/serialization.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,19 +20,18 @@ If you're using kotlinx.serialization, you need to depend on the
Declare your serializable types as usual. However, when one of the fields
mentions a type from Arrow Core,

```
```kotlin
@Serializable
data class Book(val title: String, val authors: NonEmptyList<String>)
```

you need to "import" the serializer into the file. The easiest way is to
include a `UseSerializers` annotation at the very top.

```
```kotlin
@file:UseSerializers(
EitherSerializer::class,
IorSerializer::class,
ValidatedSerializer::class,
OptionSerializer::class,
NonEmptyListSerializer::class,
NonEmptySetSerializer::class
Expand All @@ -43,6 +42,30 @@ The list above mentions all the serializers, but you only need to add those
which are used in your fields. Don't worry too much: if you miss one, the
kotlinx.serialization plug-in gives you an error.

Additionally, you can use `arrow.core.serialization.ArrowModule` to register run-time [contextual serialization](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serializers.md#contextual-serialization) support of the Arrow Core types.

```kotlin
val format = Json { serializersModule = ArrowModule }
```

or by merging with another serializers module

```kotlin
val format = Json { serializersModule = myModule + ArrowModule }
```

This will allow for use of the Arrow Core types as the value to be serialized without specifying the serializer explicitly:

```kotlin
val payload = format.encodeToString(nonEmptyListOf("hello", "world"))
```

:::note

Using `@UseSerializers` to provide static _compile-time_ serialization of fields containing Arrow Core types is usually preferable to annotating fields with `@Contextual` and relying on _run-time_ resolution, wherever possible.

:::

:::info Additional reading

[_Marshalling Arrow Types in Ktor_](https://garthgilmour.medium.com/marshalling-arrow-types-in-ktor-bc471aa3650)
Expand Down