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

Closed
wants to merge 2 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
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
12 changes: 11 additions & 1 deletion content/docs/learn/integrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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))
}
Expand Down
27 changes: 25 additions & 2 deletions content/docs/learn/quickstart/serialization.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,6 @@ include a `UseSerializers` annotation at the very top.
@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.

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

or by merging with another serializers module

```
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:

```
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 All @@ -57,7 +80,7 @@ If you're using Jackson for serialization, [this module](https://github.com/arro
adds support for Arrow types. You just need to call an additional method when
creating the mapper.

```kotlin
```
val mapper = ObjectMapper()
.registerKotlinModule()
.registerArrowModule() // <- this is the one
Expand Down