feat: implement FixedInt annotation for fixed-length encoding (when changing default settings)

Author: rasros

src/main/kotlin/com/eignex/kencode/Annotations.kt

@@ -62,5 +62,28 @@ annotation class VarInt
 @Retention(AnnotationRetention.RUNTIME)
 annotation class VarUInt
 
+/**
+ * Marks an `Int` or `Long` property to be encoded using **fixed-length** encoding.
+ *
+ * Behavior:
+ * - Serialized densely using fixed bytes (4 bytes for Int, 8 bytes for Long).
+ * - **Overrides** any global `PackedConfiguration` defaults (`defaultVarInt` or `defaultZigZag`).
+ * - Applies only to `Int` and `Long` fields inside `PackedFormat` structures.
+ *
+ * Usage:
+ * ```
+ * @Serializable
+ * data class Example(
+ *     @FixedInt val hash: Int,    // always 4 bytes, even if defaultVarInt = true
+ *     @FixedInt val mask: Long    // always 8 bytes
+ * )
+ * ```
+ */
+@SerialInfo
+@Target(AnnotationTarget.PROPERTY)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class FixedInt
+
 fun List<Annotation>.hasVarInt(): Boolean = any { it is VarInt }
 fun List<Annotation>.hasVarUInt(): Boolean = any { it is VarUInt }
+fun List<Annotation>.hasFixedInt(): Boolean = any { it is FixedInt }

src/main/kotlin/com/eignex/kencode/PackedDecoder.kt

@@ -200,11 +200,21 @@ class PackedDecoder(
 
     override fun decodeIntElement(descriptor: SerialDescriptor, index: Int): Int {
         val anns = descriptor.getElementAnnotations(index)
+        val hasFixedInt = anns.hasFixedInt()
         val hasVarInt = anns.hasVarInt()
         val hasVarUInt = anns.hasVarUInt()
 
-        val zigZag = hasVarInt || (config.defaultZigZag && !hasVarUInt)
-        val isVar = hasVarUInt || zigZag || config.defaultVarInt
+        val isVar = when {
+            hasFixedInt -> false
+            hasVarInt || hasVarUInt -> true
+            else -> config.defaultVarInt || config.defaultZigZag
+        }
+
+        val zigZag = when {
+            hasVarInt -> true
+            hasVarUInt || hasFixedInt -> false
+            else -> config.defaultZigZag
+        }
 
         return if (isVar) {
             val (raw, bytesRead) = PackedUtils.decodeVarInt(input, position)
@@ -217,11 +227,21 @@ class PackedDecoder(
 
     override fun decodeLongElement(descriptor: SerialDescriptor, index: Int): Long {
         val anns = descriptor.getElementAnnotations(index)
+        val hasFixedInt = anns.hasFixedInt()
         val hasVarInt = anns.hasVarInt()
         val hasVarUInt = anns.hasVarUInt()
 
-        val zigZag = hasVarInt || (config.defaultZigZag && !hasVarUInt)
-        val isVar = hasVarUInt || zigZag || config.defaultVarInt
+        val isVar = when {
+            hasFixedInt -> false
+            hasVarInt || hasVarUInt -> true
+            else -> config.defaultVarInt || config.defaultZigZag
+        }
+
+        val zigZag = when {
+            hasVarInt -> true
+            hasVarUInt || hasFixedInt -> false
+            else -> config.defaultZigZag
+        }
 
         return if (isVar) {
             val (raw, bytesRead) = PackedUtils.decodeVarLong(input, position)

src/main/kotlin/com/eignex/kencode/PackedEncoder.kt

@@ -159,7 +159,6 @@ class PackedEncoder(
     @ExperimentalSerializationApi
     override fun encodeNotNullMark() {
         if (inStructure && isCollection) {
-            // Inline not-null marker for collections (0 = present)
             PackedUtils.writeVarLong(0L, dataBuffer)
         } else if (!inStructure) {
             PackedUtils.writeVarLong(0L, output)
@@ -204,8 +203,6 @@ class PackedEncoder(
         nullableIndices = intArrayOf()
     }
 
-    // --- Element Encoding Delegates ---
-
     private fun booleanPos(index: Int): Int {
         for (i in booleanIndices.indices) if (booleanIndices[i] == index) return i
         return -1
@@ -224,11 +221,21 @@ class PackedEncoder(
 
     override fun encodeIntElement(descriptor: SerialDescriptor, index: Int, value: Int) {
         val anns = descriptor.getElementAnnotations(index)
+        val hasFixedInt = anns.hasFixedInt()
         val hasVarInt = anns.hasVarInt()
         val hasVarUInt = anns.hasVarUInt()
 
-        val zigZag = hasVarInt || (config.defaultZigZag && !hasVarUInt)
-        val isVar = hasVarUInt || zigZag || config.defaultVarInt
+        val isVar = when {
+            hasFixedInt -> false
+            hasVarInt || hasVarUInt -> true
+            else -> config.defaultVarInt || config.defaultZigZag
+        }
+
+        val zigZag = when {
+            hasVarInt -> true
+            hasVarUInt || hasFixedInt -> false
+            else -> config.defaultZigZag
+        }
 
         if (isVar) {
             val v = if (zigZag) PackedUtils.zigZagEncodeInt(value) else value
@@ -240,11 +247,21 @@ class PackedEncoder(
 
     override fun encodeLongElement(descriptor: SerialDescriptor, index: Int, value: Long) {
         val anns = descriptor.getElementAnnotations(index)
+        val hasFixedInt = anns.hasFixedInt()
         val hasVarInt = anns.hasVarInt()
         val hasVarUInt = anns.hasVarUInt()
 
-        val zigZag = hasVarInt || (config.defaultZigZag && !hasVarUInt)
-        val isVar = hasVarUInt || zigZag || config.defaultVarInt
+        val isVar = when {
+            hasFixedInt -> false
+            hasVarInt || hasVarUInt -> true
+            else -> config.defaultVarInt || config.defaultZigZag
+        }
+
+        val zigZag = when {
+            hasVarInt -> true
+            hasVarUInt || hasFixedInt -> false
+            else -> config.defaultZigZag
+        }
 
         if (isVar) {
             val v = if (zigZag) PackedUtils.zigZagEncodeLong(value) else value