refactor: rename PackedIntegerType to IntPacking and update references across the codebase

Author: rasros

README.md

@@ -51,8 +51,8 @@ Minimal example using the default `EncodedFormat` (Base62 + PackedFormat):
 ```kotlin
 @Serializable
 data class Payload(
-    @PackedType(PackedIntegerType.DEFAULT) val id: ULong, // low numbers are compacted
-    @PackedType(PackedIntegerType.SIGNED)  val delta: Int, // zigzagged to compact small negatives
+    @PackedType(IntPacking.VARINT) val id: ULong, // low numbers are compacted
+    @PackedType(IntPacking.ZIGZAG)  val delta: Int, // zigzagged to compact small negatives
     val urgent: Boolean,    // Packed into bitset
     val handled: Instant?,  // Nullability tracked via bitset
     val type: PayloadType
@@ -76,8 +76,8 @@ payloads for Kotlin classes by moving structural metadata into a compact header.
 
 * Bit-Packing: Booleans and nullability markers are stored in a single
   bit-header (about 1 bit per field).
-* VarInts: Int/Long fields can be optimized using `@PackedType(PackedIntegerType.DEFAULT)`
-  (unsigned varint) or `@PackedType(PackedIntegerType.SIGNED)` (ZigZag) annotations.
+* VarInts: Int/Long fields can be optimized using `@PackedType(IntPacking.VARINT)`
+  (unsigned varint) or `@PackedType(IntPacking.ZIGZAG)` (ZigZag) annotations.
   If you already use `kotlinx-serialization-protobuf`, `@ProtoType` annotations are
   recognized automatically as a fallback.
 * Full Graph Support: Handles nested objects, lists, maps, and polymorphism
@@ -87,7 +87,7 @@ payloads for Kotlin classes by moving structural metadata into a compact header.
 
 ```kotlin
 val compactFormat = PackedFormat {
-    defaultEncoding = PackedIntegerType.SIGNED
+    defaultEncoding = IntPacking.ZIGZAG
     serializersModule = myCustomModule
 }
 val bytes = compactFormat.encodeToByteArray(payload)

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

@@ -8,63 +8,38 @@ import kotlinx.serialization.protobuf.ProtoIntegerType as KxProtoIntegerType
 import kotlinx.serialization.protobuf.ProtoType as KxProtoType
 
 /**
- * Specifies the integer encoding strategy for `Int` and `Long` fields in [PackedFormat].
+ * Integer encoding strategy for `Int` and `Long` fields in [PackedFormat].
  *
- * Mirrors [kotlinx.serialization.protobuf.ProtoIntegerType].
+ * Compatible with [kotlinx.serialization.protobuf.ProtoIntegerType] as a fallback (see [PackedType]).
  */
-enum class PackedIntegerType {
+enum class IntPacking {
     /** Unsigned variable-length (LEB128). Compact for small non-negative values. */
-    DEFAULT,
+    VARINT,
     /** ZigZag variable-length. Compact for small signed values. */
-    SIGNED,
+    ZIGZAG,
     /** Fixed-width. 4 bytes for `Int`, 8 bytes for `Long`. */
     FIXED
 }
 
 /**
- * Marks an `Int` or `Long` field with an explicit encoding strategy in [PackedFormat].
- *
- * Mirrors [kotlinx.serialization.protobuf.ProtoType]:
- * - [PackedIntegerType.DEFAULT]: unsigned variable-length (LEB128)
- * - [PackedIntegerType.SIGNED]: ZigZag variable-length
- * - [PackedIntegerType.FIXED]: fixed-width (4 / 8 bytes)
- *
- * Usage:
- * ```
- * @Serializable
- * data class Example(
- *     @PackedType(PackedIntegerType.DEFAULT) val id: Long,    // compact for small positive values
- *     @PackedType(PackedIntegerType.SIGNED)  val delta: Int,  // compact for small signed values
- *     @PackedType(PackedIntegerType.FIXED)   val hash: Int    // always 4 bytes
- * )
- * ```
- *
- * Takes precedence over [kotlinx.serialization.protobuf.ProtoType] when both are present.
- * Has no effect for types outside [PackedFormat].
+ * Overrides the integer encoding strategy for an `Int` or `Long` field in [PackedFormat].
+ * Falls back to [kotlinx.serialization.protobuf.ProtoType] if present, then [PackedConfiguration.defaultEncoding].
  */
 @SerialInfo
 @Target(AnnotationTarget.PROPERTY)
 @Retention(AnnotationRetention.SOURCE)
-annotation class PackedType(val type: PackedIntegerType)
-
-internal enum class IntEncoding { FIXED, VARINT, ZIGZAG }
-
-private fun PackedIntegerType.toIntEncoding(): IntEncoding = when (this) {
-    PackedIntegerType.DEFAULT -> IntEncoding.VARINT
-    PackedIntegerType.SIGNED  -> IntEncoding.ZIGZAG
-    PackedIntegerType.FIXED   -> IntEncoding.FIXED
-}
+annotation class PackedType(val type: IntPacking)
 
-private fun KxProtoIntegerType.toIntEncoding(): IntEncoding = when (this) {
-    KxProtoIntegerType.DEFAULT -> IntEncoding.VARINT
-    KxProtoIntegerType.SIGNED  -> IntEncoding.ZIGZAG
-    KxProtoIntegerType.FIXED   -> IntEncoding.FIXED
+private fun KxProtoIntegerType.toIntPacking(): IntPacking = when (this) {
+    KxProtoIntegerType.DEFAULT -> IntPacking.VARINT
+    KxProtoIntegerType.SIGNED  -> IntPacking.ZIGZAG
+    KxProtoIntegerType.FIXED   -> IntPacking.FIXED
 }
 
-internal fun resolveIntEncoding(anns: List<Annotation>, config: PackedConfiguration): IntEncoding {
-    anns.filterIsInstance<PackedType>().firstOrNull()?.let { return it.type.toIntEncoding() }
+internal fun resolveIntEncoding(anns: List<Annotation>, config: PackedConfiguration): IntPacking {
+    anns.filterIsInstance<PackedType>().firstOrNull()?.let { return it.type }
     try {
-        anns.filterIsInstance<KxProtoType>().firstOrNull()?.let { return it.type.toIntEncoding() }
+        anns.filterIsInstance<KxProtoType>().firstOrNull()?.let { return it.type.toIntPacking() }
     } catch (_: Throwable) { }
-    return config.defaultEncoding.toIntEncoding()
+    return config.defaultEncoding
 }

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

@@ -228,16 +228,16 @@ class PackedDecoder internal constructor(
 
     override fun decodeIntElement(descriptor: SerialDescriptor, index: Int): Int =
         when (resolveIntEncoding(descriptor.getElementAnnotations(index), config)) {
-            IntEncoding.ZIGZAG -> PackedUtils.zigZagDecodeInt(readVarInt())
-            IntEncoding.VARINT -> readVarInt()
-            IntEncoding.FIXED  -> readIntPos()
+            IntPacking.ZIGZAG -> PackedUtils.zigZagDecodeInt(readVarInt())
+            IntPacking.VARINT -> readVarInt()
+            IntPacking.FIXED  -> readIntPos()
         }
 
     override fun decodeLongElement(descriptor: SerialDescriptor, index: Int): Long =
         when (resolveIntEncoding(descriptor.getElementAnnotations(index), config)) {
-            IntEncoding.ZIGZAG -> PackedUtils.zigZagDecodeLong(readVarLong())
-            IntEncoding.VARINT -> readVarLong()
-            IntEncoding.FIXED  -> readLongPos()
+            IntPacking.ZIGZAG -> PackedUtils.zigZagDecodeLong(readVarLong())
+            IntPacking.VARINT -> readVarLong()
+            IntPacking.FIXED  -> readLongPos()
         }
 
     override fun decodeFloatElement(descriptor: SerialDescriptor, index: Int): Float =

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

@@ -203,17 +203,17 @@ class PackedEncoder internal constructor(
 
     override fun encodeIntElement(descriptor: SerialDescriptor, index: Int, value: Int) {
         when (resolveIntEncoding(descriptor.getElementAnnotations(index), config)) {
-            IntEncoding.ZIGZAG -> PackedUtils.writeVarInt(PackedUtils.zigZagEncodeInt(value), dataBuffer)
-            IntEncoding.VARINT -> PackedUtils.writeVarInt(value, dataBuffer)
-            IntEncoding.FIXED  -> PackedUtils.writeInt(value, dataBuffer)
+            IntPacking.ZIGZAG -> PackedUtils.writeVarInt(PackedUtils.zigZagEncodeInt(value), dataBuffer)
+            IntPacking.VARINT -> PackedUtils.writeVarInt(value, dataBuffer)
+            IntPacking.FIXED  -> PackedUtils.writeInt(value, dataBuffer)
         }
     }
 
     override fun encodeLongElement(descriptor: SerialDescriptor, index: Int, value: Long) {
         when (resolveIntEncoding(descriptor.getElementAnnotations(index), config)) {
-            IntEncoding.ZIGZAG -> PackedUtils.writeVarLong(PackedUtils.zigZagEncodeLong(value), dataBuffer)
-            IntEncoding.VARINT -> PackedUtils.writeVarLong(value, dataBuffer)
-            IntEncoding.FIXED  -> PackedUtils.writeLong(value, dataBuffer)
+            IntPacking.ZIGZAG -> PackedUtils.writeVarLong(PackedUtils.zigZagEncodeLong(value), dataBuffer)
+            IntPacking.VARINT -> PackedUtils.writeVarLong(value, dataBuffer)
+            IntPacking.FIXED  -> PackedUtils.writeLong(value, dataBuffer)
         }
     }
 

src/commonMain/kotlin/com/eignex/kencode/PackedFormat.kt

@@ -8,10 +8,10 @@ import kotlinx.serialization.modules.SerializersModule
  * Holds the configuration for a [PackedFormat] instance.
  *
  * @property defaultEncoding The encoding applied to all `Int` and `Long` fields that carry no
- *   [PackedType] annotation. Defaults to [PackedIntegerType.FIXED] (4 / 8 raw bytes).
+ *   [PackedType] annotation. Defaults to [IntPacking.FIXED] (4 / 8 raw bytes).
  */
 data class PackedConfiguration(
-    val defaultEncoding: PackedIntegerType = PackedIntegerType.FIXED
+    val defaultEncoding: IntPacking = IntPacking.FIXED
 )
 
 /**
@@ -76,17 +76,17 @@ class PackedFormatBuilder {
 
     /**
      * The encoding applied to all `Int` and `Long` fields that carry no [PackedType] annotation.
-     * Defaults to [PackedIntegerType.FIXED].
+     * Defaults to [IntPacking.FIXED].
      */
-    var defaultEncoding: PackedIntegerType = PackedIntegerType.FIXED
+    var defaultEncoding: IntPacking = IntPacking.FIXED
 }
 
 /**
  * Creates a customized [PackedFormat] instance.
  *
  * ```
  * val format = PackedFormat {
- *     defaultEncoding = PackedIntegerType.SIGNED
+ *     defaultEncoding = Packing.ZIGZAG
  *     serializersModule = myCustomModule
  * }
  * ```

src/commonTest/kotlin/com/eignex/kencode/PackedFormatTest.kt

@@ -265,7 +265,7 @@ class PackedFormatTest {
 
         val standardFormat = PackedFormat.Default
         val optimizedFormat =
-            PackedFormat { defaultEncoding = PackedIntegerType.DEFAULT }
+            PackedFormat { defaultEncoding = IntPacking.VARINT }
 
         val standardBytes = standardFormat.encodeToByteArray(
             UnannotatedPayload.serializer(),
@@ -296,9 +296,9 @@ class PackedFormatTest {
 
         val standardFormat = PackedFormat.Default
         val varIntFormat =
-            PackedFormat { defaultEncoding = PackedIntegerType.DEFAULT }
+            PackedFormat { defaultEncoding = IntPacking.VARINT }
         val zigZagFormat =
-            PackedFormat { defaultEncoding = PackedIntegerType.SIGNED }
+            PackedFormat { defaultEncoding = IntPacking.ZIGZAG }
 
         // Standard: 12 bytes
         assertEquals(
@@ -337,7 +337,7 @@ class PackedFormatTest {
         val payload = InversePayload(5, -10L, 6u, 7uL)
 
         val optimizedFormat =
-            PackedFormat { defaultEncoding = PackedIntegerType.SIGNED }
+            PackedFormat { defaultEncoding = IntPacking.ZIGZAG }
 
         val bytes = optimizedFormat.encodeToByteArray(
             InversePayload.serializer(),

src/commonTest/kotlin/com/eignex/kencode/TestClasses.kt

@@ -75,10 +75,10 @@ data class StringHeavyPayload(
 
 @Serializable
 data class VarIntVarUIntPayload(
-    @PackedType(PackedIntegerType.SIGNED) val signedIntVar: Int,
-    @PackedType(PackedIntegerType.SIGNED) val signedLongVar: Long,
-    @PackedType(PackedIntegerType.DEFAULT) val unsignedIntVar: Int,
-    @PackedType(PackedIntegerType.DEFAULT) val unsignedLongVar: Long,
+    @PackedType(IntPacking.ZIGZAG) val signedIntVar: Int,
+    @PackedType(IntPacking.ZIGZAG) val signedLongVar: Long,
+    @PackedType(IntPacking.VARINT) val unsignedIntVar: Int,
+    @PackedType(IntPacking.VARINT) val unsignedLongVar: Long,
     val plainInt: Int,
     val plainLong: Long
 )
@@ -638,8 +638,8 @@ data class UnannotatedPayload(val x: Int, val y: Long)
 
 @Serializable
 data class InversePayload(
-    @PackedType(PackedIntegerType.FIXED) val fixedX: Int,
-    @PackedType(PackedIntegerType.FIXED) val fixedY: Long,
-    @PackedType(PackedIntegerType.FIXED) val fixedUX: UInt,
-    @PackedType(PackedIntegerType.FIXED) val fixedUY: ULong
+    @PackedType(IntPacking.FIXED) val fixedX: Int,
+    @PackedType(IntPacking.FIXED) val fixedY: Long,
+    @PackedType(IntPacking.FIXED) val fixedUX: UInt,
+    @PackedType(IntPacking.FIXED) val fixedUY: ULong
 )

src/jvmTest/kotlin/com/eignex/kencode/Examples.kt

@@ -22,10 +22,10 @@ class Examples {
     data class Payload(
 
         // only uses as many bytes as needed
-        @PackedType(PackedIntegerType.DEFAULT)
+        @PackedType(IntPacking.VARINT)
         val id: ULong,
 
-        @PackedType(PackedIntegerType.SIGNED) // zig-zag encodes small negatives efficiently
+        @PackedType(IntPacking.ZIGZAG) // zig-zag encodes small negatives efficiently
         val delta: Int,
 
         // these are packed into a bitset along with nullability flags
@@ -42,6 +42,30 @@ class Examples {
         TYPE1, TYPE2, TYPE3
     }
 
+    @Test
+    fun `blog post example`() {
+        @Serializable
+        data class JobState(
+            val clientId: Int,
+            val batchId: Int,
+            val retryCount: Int?,
+            val isPriority: Boolean
+        )
+
+        val state = JobState(119, 210, null, true)
+        val encodedFormat = EncodedFormat {
+            binaryFormat =
+                PackedFormat { defaultEncoding = IntPacking.VARINT }
+        }
+        val encodedState = encodedFormat.encodeToString(state)
+        println(encodedState)
+        // This encodes the object into the string:
+        // 02waa1a8
+
+        val decodedState =
+            encodedFormat.decodeFromString<JobState>(encodedState)
+    }
+
     @Test
     fun `example serialization`() {
         val payload = Payload(
@@ -120,10 +144,12 @@ class Examples {
         val secureFormat = EncodedFormat { transform = xteaTransform }
 
         val payload = SensitiveData(random.nextLong())
-        val token = secureFormat.encodeToString(SensitiveData.serializer(), payload)
+        val token =
+            secureFormat.encodeToString(SensitiveData.serializer(), payload)
         println(token)
 
-        val result = secureFormat.decodeFromString(SensitiveData.serializer(), token)
+        val result =
+            secureFormat.decodeFromString(SensitiveData.serializer(), token)
         println(result)
 
         assertEquals(payload, result)