JAVA-5736 Add bsonNamingStrategy option to support snake_case (#1627)

nhachicha · leesungbin · rozza · web-flow · commit 48fdf2a4e392 · 2025-03-19T14:16:04.000Z
Add bsonNamingStrategy option to support snake_case naming strategy

---------

Co-authored-by: leesungbin &lt;lee@sungbin.dev&gt;
Co-authored-by: Ross Lawley &lt;ross.lawley@gmail.com&gt;
diff --git a/THIRD-PARTY-NOTICES b/THIRD-PARTY-NOTICES
@@ -184,3 +184,19 @@ https://github.com/mongodb/mongo-java-driver.
     See the License for the specific language governing permissions and
     limitations under the License.
 
+9) The following files: BsonCodecUtils.kt
+
+     Copyright 2008-present MongoDB, Inc.
+     Copyright 2017-2021 JetBrains s.r.o.
+
+     Licensed under the Apache License, Version 2.0 (the "License");
+     you may not use this file except in compliance with the License.
+     You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+     Unless required by applicable law or agreed to in writing, software
+     distributed under the License is distributed on an "AS IS" BASIS,
+     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+     See the License for the specific language governing permissions and
+     limitations under the License.
diff --git a/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/BsonConfiguration.kt b/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/BsonConfiguration.kt
@@ -31,4 +31,19 @@ public data class BsonConfiguration(
     val encodeDefaults: Boolean = true,
     val explicitNulls: Boolean = false,
     val classDiscriminator: String = "_t",
+    val bsonNamingStrategy: BsonNamingStrategy? = null
 )
+
+/**
+ * Optional BSON naming strategy for a field.
+ *
+ * @since 5.4
+ */
+public enum class BsonNamingStrategy {
+
+    /**
+     * A strategy that transforms serial names from camel case to snake case — lowercase characters with words separated
+     * by underscores.
+     */
+    SNAKE_CASE,
+}
diff --git a/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/BsonDecoder.kt b/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/BsonDecoder.kt
@@ -37,11 +37,13 @@ import org.bson.BsonType
 import org.bson.BsonValue
 import org.bson.codecs.BsonValueCodec
 import org.bson.codecs.DecoderContext
+import org.bson.codecs.kotlinx.utils.BsonCodecUtils.cacheElementNamesByDescriptor
 import org.bson.codecs.kotlinx.utils.BsonCodecUtils.createBsonArrayDecoder
 import org.bson.codecs.kotlinx.utils.BsonCodecUtils.createBsonDecoder
 import org.bson.codecs.kotlinx.utils.BsonCodecUtils.createBsonDocumentDecoder
 import org.bson.codecs.kotlinx.utils.BsonCodecUtils.createBsonMapDecoder
 import org.bson.codecs.kotlinx.utils.BsonCodecUtils.createBsonPolymorphicDecoder
+import org.bson.codecs.kotlinx.utils.BsonCodecUtils.getCachedElementNamesByDescriptor
 import org.bson.internal.NumberCodecHelper
 import org.bson.internal.StringCodecHelper
 import org.bson.types.ObjectId
@@ -102,6 +104,7 @@ internal sealed class AbstractBsonDecoder(
                     elementDescriptor.serialName, elementDescriptor.isNullable && !descriptor.isElementOptional(it))
             }
         this.elementsMetadata = elementsMetadata
+        cacheElementNamesByDescriptor(descriptor, configuration)
     }
 
     override fun decodeElementIndex(descriptor: SerialDescriptor): Int {
@@ -129,7 +132,13 @@ internal sealed class AbstractBsonDecoder(
             }
 
         return name?.let {
-            val index = descriptor.getElementIndex(it)
+            val index =
+                if (configuration.bsonNamingStrategy == BsonNamingStrategy.SNAKE_CASE) {
+                    getCachedElementNamesByDescriptor(descriptor)[it]?.let { name -> descriptor.getElementIndex(name) }
+                        ?: UNKNOWN_NAME
+                } else {
+                    descriptor.getElementIndex(it)
+                }
             return if (index == UNKNOWN_NAME) {
                 reader.skipValue()
                 decodeElementIndexImpl(descriptor)
diff --git a/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/BsonEncoder.kt b/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/BsonEncoder.kt
@@ -31,6 +31,7 @@ import org.bson.BsonValue
 import org.bson.BsonWriter
 import org.bson.codecs.BsonValueCodec
 import org.bson.codecs.EncoderContext
+import org.bson.codecs.kotlinx.utils.BsonCodecUtils.convertCamelCase
 import org.bson.types.ObjectId
 
 /**
@@ -203,7 +204,15 @@ internal open class BsonEncoderImpl(
     }
 
     internal fun encodeName(value: Any) {
-        writer.writeName(value.toString())
+        val name =
+            value.toString().let {
+                if (configuration.bsonNamingStrategy == BsonNamingStrategy.SNAKE_CASE) {
+                    convertCamelCase(it, '_')
+                } else {
+                    it
+                }
+            }
+        writer.writeName(name)
         state = STATE.VALUE
     }
 
diff --git a/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/JsonBsonDecoder.kt b/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/JsonBsonDecoder.kt
@@ -31,6 +31,7 @@ import org.bson.AbstractBsonReader
 import org.bson.BsonBinarySubType
 import org.bson.BsonType
 import org.bson.UuidRepresentation
+import org.bson.codecs.kotlinx.utils.BsonCodecUtils.toJsonNamingStrategy
 import org.bson.internal.UuidHelper
 
 @OptIn(ExperimentalSerializationApi::class)
@@ -42,6 +43,7 @@ internal interface JsonBsonDecoder : BsonDecoder, JsonDecoder {
         explicitNulls = configuration.explicitNulls
         encodeDefaults = configuration.encodeDefaults
         classDiscriminator = configuration.classDiscriminator
+        namingStrategy = configuration.bsonNamingStrategy.toJsonNamingStrategy()
         serializersModule = this@JsonBsonDecoder.serializersModule
     }
 
diff --git a/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/JsonBsonEncoder.kt b/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/JsonBsonEncoder.kt
@@ -30,6 +30,7 @@ import kotlinx.serialization.json.int
 import kotlinx.serialization.json.long
 import kotlinx.serialization.modules.SerializersModule
 import org.bson.BsonWriter
+import org.bson.codecs.kotlinx.utils.BsonCodecUtils.toJsonNamingStrategy
 import org.bson.types.Decimal128
 
 @OptIn(ExperimentalSerializationApi::class)
@@ -52,6 +53,7 @@ internal class JsonBsonEncoder(
         explicitNulls = configuration.explicitNulls
         encodeDefaults = configuration.encodeDefaults
         classDiscriminator = configuration.classDiscriminator
+        namingStrategy = configuration.bsonNamingStrategy.toJsonNamingStrategy()
         serializersModule = this@JsonBsonEncoder.serializersModule
     }
 
diff --git a/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/utils/BsonCodecUtils.kt b/bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/utils/BsonCodecUtils.kt
@@ -16,7 +16,10 @@
 package org.bson.codecs.kotlinx.utils
 
 import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.SerializationException
 import kotlinx.serialization.descriptors.SerialDescriptor
+import kotlinx.serialization.descriptors.elementNames
+import kotlinx.serialization.json.JsonNamingStrategy
 import kotlinx.serialization.modules.SerializersModule
 import org.bson.AbstractBsonReader
 import org.bson.BsonWriter
@@ -28,6 +31,7 @@ import org.bson.codecs.kotlinx.BsonDocumentDecoder
 import org.bson.codecs.kotlinx.BsonEncoder
 import org.bson.codecs.kotlinx.BsonEncoderImpl
 import org.bson.codecs.kotlinx.BsonMapDecoder
+import org.bson.codecs.kotlinx.BsonNamingStrategy
 import org.bson.codecs.kotlinx.BsonPolymorphicDecoder
 import org.bson.codecs.kotlinx.JsonBsonArrayDecoder
 import org.bson.codecs.kotlinx.JsonBsonDecoderImpl
@@ -59,6 +63,8 @@ internal object BsonCodecUtils {
         }
     }
 
+    private val cachedElementNamesByDescriptor: MutableMap<String, Map<String, String>> = mutableMapOf()
+
     internal fun createBsonEncoder(
         writer: BsonWriter,
         serializersModule: SerializersModule,
@@ -116,4 +122,73 @@ internal object BsonCodecUtils {
         return if (hasJsonDecoder) JsonBsonMapDecoder(descriptor, reader, serializersModule, configuration)
         else BsonMapDecoder(descriptor, reader, serializersModule, configuration)
     }
+
+    internal fun cacheElementNamesByDescriptor(descriptor: SerialDescriptor, configuration: BsonConfiguration) {
+        val convertedNameMap =
+            when (configuration.bsonNamingStrategy) {
+                BsonNamingStrategy.SNAKE_CASE -> {
+                    val snakeCasedNames = descriptor.elementNames.associateWith { name -> convertCamelCase(name, '_') }
+
+                    snakeCasedNames.entries
+                        .groupBy { entry -> entry.value }
+                        .filter { group -> group.value.size > 1 }
+                        .entries
+                        .fold(StringBuilder("")) { acc, group ->
+                            val keys = group.value.joinToString(", ") { entry -> entry.key }
+                            acc.append("$keys in ${descriptor.serialName} generate same name: ${group.key}.\n")
+                        }
+                        .toString()
+                        .takeIf { it.trim().isNotEmpty() }
+                        ?.let { errorMessage: String -> throw SerializationException(errorMessage) }
+
+                    snakeCasedNames.entries.associate { it.value to it.key }
+                }
+                else -> emptyMap()
+            }
+
+        cachedElementNamesByDescriptor[descriptor.serialName] = convertedNameMap
+    }
+
+    internal fun getCachedElementNamesByDescriptor(descriptor: SerialDescriptor): Map<String, String> {
+        return cachedElementNamesByDescriptor[descriptor.serialName] ?: emptyMap()
+    }
+
+    // https://github.com/Kotlin/kotlinx.serialization/blob/f9f160a680da9f92c3bb121ae3644c96e57ba42e/formats/json/commonMain/src/kotlinx/serialization/json/JsonNamingStrategy.kt#L142-L174
+    internal fun convertCamelCase(value: String, delimiter: Char) =
+        buildString(value.length * 2) {
+            var bufferedChar: Char? = null
+            var previousUpperCharsCount = 0
+
+            value.forEach { c ->
+                if (c.isUpperCase()) {
+                    if (previousUpperCharsCount == 0 && isNotEmpty() && last() != delimiter) append(delimiter)
+
+                    bufferedChar?.let(::append)
+
+                    previousUpperCharsCount++
+                    bufferedChar = c.lowercaseChar()
+                } else {
+                    if (bufferedChar != null) {
+                        if (previousUpperCharsCount > 1 && c.isLetter()) {
+                            append(delimiter)
+                        }
+                        append(bufferedChar)
+                        previousUpperCharsCount = 0
+                        bufferedChar = null
+                    }
+                    append(c)
+                }
+            }
+
+            if (bufferedChar != null) {
+                append(bufferedChar)
+            }
+        }
+
+    internal fun BsonNamingStrategy?.toJsonNamingStrategy(): JsonNamingStrategy? {
+        return when (this) {
+            BsonNamingStrategy.SNAKE_CASE -> JsonNamingStrategy.SnakeCase
+            else -> null
+        }
+    }
 }
diff --git a/bson-kotlinx/src/test/kotlin/org/bson/codecs/kotlinx/KotlinSerializerCodecTest.kt b/bson-kotlinx/src/test/kotlin/org/bson/codecs/kotlinx/KotlinSerializerCodecTest.kt
@@ -81,6 +81,7 @@ import org.bson.codecs.kotlinx.samples.DataClassWithBsonId
 import org.bson.codecs.kotlinx.samples.DataClassWithBsonIgnore
 import org.bson.codecs.kotlinx.samples.DataClassWithBsonProperty
 import org.bson.codecs.kotlinx.samples.DataClassWithBsonRepresentation
+import org.bson.codecs.kotlinx.samples.DataClassWithCamelCase
 import org.bson.codecs.kotlinx.samples.DataClassWithCollections
 import org.bson.codecs.kotlinx.samples.DataClassWithContextualDateValues
 import org.bson.codecs.kotlinx.samples.DataClassWithDataClassMapKey
@@ -94,6 +95,7 @@ import org.bson.codecs.kotlinx.samples.DataClassWithFailingInit
 import org.bson.codecs.kotlinx.samples.DataClassWithJsonElement
 import org.bson.codecs.kotlinx.samples.DataClassWithJsonElements
 import org.bson.codecs.kotlinx.samples.DataClassWithJsonElementsNullable
+import org.bson.codecs.kotlinx.samples.DataClassWithKotlinAllowedName
 import org.bson.codecs.kotlinx.samples.DataClassWithListThatLastItemDefaultsToNull
 import org.bson.codecs.kotlinx.samples.DataClassWithMutableList
 import org.bson.codecs.kotlinx.samples.DataClassWithMutableMap
@@ -105,6 +107,7 @@ import org.bson.codecs.kotlinx.samples.DataClassWithNulls
 import org.bson.codecs.kotlinx.samples.DataClassWithPair
 import org.bson.codecs.kotlinx.samples.DataClassWithParameterizedDataClass
 import org.bson.codecs.kotlinx.samples.DataClassWithRequired
+import org.bson.codecs.kotlinx.samples.DataClassWithSameSnakeCaseName
 import org.bson.codecs.kotlinx.samples.DataClassWithSequence
 import org.bson.codecs.kotlinx.samples.DataClassWithSimpleValues
 import org.bson.codecs.kotlinx.samples.DataClassWithTriple
@@ -1126,6 +1129,40 @@ class KotlinSerializerCodecTest {
         }
     }
 
+    @Test
+    fun testSnakeCaseNamingStrategy() {
+        val expected =
+            """{"two_words": "", "my_property": "", "camel_case_underscores": "", "url_mapping": "",
+            | "my_http_auth": "", "my_http2_api_key": "", "my_http2fast_api_key": ""}"""
+                .trimMargin()
+        val dataClass = DataClassWithCamelCase()
+        assertRoundTrips(expected, dataClass, BsonConfiguration(bsonNamingStrategy = BsonNamingStrategy.SNAKE_CASE))
+    }
+
+    @Test
+    fun testSameSnakeCaseName() {
+        val expected = """{"my_http_auth": "", "my_http_auth1": ""}"""
+        val dataClass = DataClassWithSameSnakeCaseName()
+        val exception =
+            assertThrows<SerializationException> {
+                assertRoundTrips(
+                    expected, dataClass, BsonConfiguration(bsonNamingStrategy = BsonNamingStrategy.SNAKE_CASE))
+            }
+        assertEquals(
+            "myHTTPAuth, myHttpAuth in org.bson.codecs.kotlinx.samples.DataClassWithSameSnakeCaseName" +
+                " generate same name: my_http_auth.\n" +
+                "myHTTPAuth1, myHttpAuth1 in org.bson.codecs.kotlinx.samples.DataClassWithSameSnakeCaseName" +
+                " generate same name: my_http_auth1.\n",
+            exception.message)
+    }
+
+    @Test
+    fun testKotlinAllowedName() {
+        val expected = """{"имя_переменной": "", "variable _name": ""}"""
+        val dataClass = DataClassWithKotlinAllowedName()
+        assertRoundTrips(expected, dataClass, BsonConfiguration(bsonNamingStrategy = BsonNamingStrategy.SNAKE_CASE))
+    }
+
     private inline fun <reified T : Any> assertRoundTrips(
         expected: String,
         value: T,
diff --git a/bson-kotlinx/src/test/kotlin/org/bson/codecs/kotlinx/samples/DataClasses.kt b/bson-kotlinx/src/test/kotlin/org/bson/codecs/kotlinx/samples/DataClasses.kt
@@ -102,6 +102,31 @@ data class DataClassWithDefaults(
     val listSimple: List<String> = listOf("a", "b", "c")
 )
 
+@Serializable
+data class DataClassWithCamelCase(
+    val twoWords: String = "",
+    @Suppress("ConstructorParameterNaming") val MyProperty: String = "",
+    @Suppress("ConstructorParameterNaming") val camel_Case_Underscores: String = "",
+    @Suppress("ConstructorParameterNaming") val URLMapping: String = "",
+    val myHTTPAuth: String = "",
+    val myHTTP2ApiKey: String = "",
+    val myHTTP2fastApiKey: String = "",
+)
+
+@Serializable
+data class DataClassWithSameSnakeCaseName(
+    val myHTTPAuth: String = "",
+    val myHttpAuth: String = "",
+    val myHTTPAuth1: String = "",
+    val myHttpAuth1: String = "",
+)
+
+@Serializable
+data class DataClassWithKotlinAllowedName(
+    @Suppress("ConstructorParameterNaming") val имяПеременной: String = "",
+    @Suppress("ConstructorParameterNaming") val `variable Name`: String = "",
+)
+
 @Serializable data class DataClassWithNulls(val boolean: Boolean?, val string: String?, val listSimple: List<String?>?)
 
 @Serializable
