refactor: integrate CompactZeros into PayloadTransform, remove compactZeros flag, update EncodedFormat usage and tests

Author: rasros

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

@@ -8,28 +8,26 @@ import kotlinx.serialization.modules.SerializersModule
  *
  * @property codec The ASCII-safe byte codec used to turn raw bytes into text (e.g., Base62, Base64).
  * @property transform An optional [PayloadTransform] applied after serialization and before encoding.
- *   Common uses: integrity checks via [Checksum.asTransform], encryption, or error-correcting codes.
+ *   Common uses: [CompactZeros] to strip leading zeros, integrity checks via [Checksum.asTransform],
+ *   encryption, or error-correcting codes. Use [PayloadTransform.then] to chain multiple transforms.
  * @property binaryFormat The underlying binary serialization format used before encoding to text.
- * @property compactZeros When true, leading zero bytes are stripped before encoding and restored on decode.
- *   A varint prefix encodes the count, costing 1 byte for up to 127 stripped bytes.
  */
 data class EncodedConfiguration(
     val codec: ByteEncoding = Base62,
     val transform: PayloadTransform? = null,
     val binaryFormat: BinaryFormat = PackedFormat.Default,
-    val compactZeros: Boolean = false,
 )
 
 /**
  * Text `StringFormat` that produces short, predictable string tokens by composing:
  *
  * 1. A binary format (e.g. [PackedFormat], `ProtoBuf`).
- * 2. An optional [PayloadTransform] (checksum, encryption, ECC, …).
+ * 2. An optional [PayloadTransform] ([CompactZeros], checksum, encryption, ECC, …).
  * 3. An ASCII-safe byte encoding (e.g. [Base62], [Base64], [Base36], [Base85]).
  *
  * Typical use:
- * - `encodeToString`: serialize -> transform.encode -> (optionally) compact zeros -> encode bytes to text.
- * - `decodeFromString`: decode text to bytes -> (optionally) restore zeros -> transform.decode -> deserialize.
+ * - `encodeToString`: serialize -> transform.encode -> encode bytes to text.
+ * - `decodeFromString`: decode text to bytes -> transform.decode -> deserialize.
  *
  * Use the [EncodedFormat] builder function to create a customized instance.
  *
@@ -47,16 +45,15 @@ open class EncodedFormat(
         codec: ByteEncoding = Base62,
         transform: PayloadTransform? = null,
         binaryFormat: BinaryFormat = PackedFormat,
-        compactZeros: Boolean = true,
-    ) : this(EncodedConfiguration(codec, transform, binaryFormat, compactZeros))
+    ) : this(EncodedConfiguration(codec, transform, binaryFormat))
 
     /**
      * Delegates to the underlying [BinaryFormat]'s serializers module.
      */
     override val serializersModule: SerializersModule get() = configuration.binaryFormat.serializersModule
 
     /**
-     * Default format: `PackedFormat` + `Base62` without a transform.
+     * Default format: `PackedFormat` + `Base62` + [CompactZeros].
      */
     companion object Default : EncodedFormat()
 
@@ -66,8 +63,7 @@ open class EncodedFormat(
      */
     override fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String {
         val bytes = configuration.binaryFormat.encodeToByteArray(serializer, value)
-        val transformed = configuration.transform?.encode(bytes) ?: bytes
-        val payload = if (configuration.compactZeros) compactZerosEncode(transformed) else transformed
+        val payload = configuration.transform?.encode(bytes) ?: bytes
         return configuration.codec.encode(payload)
     }
 
@@ -79,47 +75,18 @@ open class EncodedFormat(
      */
     override fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T {
         val input = configuration.codec.decode(string)
-        val raw = if (configuration.compactZeros) compactZerosDecode(input) else input
-        val bytes = configuration.transform?.decode(raw) ?: raw
+        val bytes = configuration.transform?.decode(input) ?: input
         return configuration.binaryFormat.decodeFromByteArray(deserializer, bytes)
     }
-
-    private fun compactZerosEncode(bytes: ByteArray): ByteArray {
-        var k = 0
-        while (k < bytes.size && bytes[k] == 0.toByte()) k++
-        val prefix = varintEncode(k)
-        val result = ByteArray(prefix.size + bytes.size - k)
-        prefix.copyInto(result)
-        bytes.copyInto(result, destinationOffset = prefix.size, startIndex = k)
-        return result
-    }
-
-    private fun compactZerosDecode(bytes: ByteArray): ByteArray {
-        require(bytes.isNotEmpty()) { "Compact payload cannot be empty." }
-        val (k, prefixLen) = varintDecode(bytes)
-        val result = ByteArray(k + bytes.size - prefixLen)
-        bytes.copyInto(result, destinationOffset = k, startIndex = prefixLen)
-        return result
-    }
-
-    private fun varintEncode(value: Int): ByteArray {
-        val out = ByteOutput(5)
-        PackedUtils.writeVarInt(value, out)
-        return out.toByteArray()
-    }
-
-    private fun varintDecode(bytes: ByteArray): Pair<Int, Int> =
-        PackedUtils.decodeVarInt(bytes, 0)
 }
 
 /**
  * Builder for configuring [EncodedFormat] instances.
  */
 class EncodedFormatBuilder {
     var codec: ByteEncoding = Base62
-    var transform: PayloadTransform? = null
+    var transform: PayloadTransform? = CompactZeros
     var binaryFormat: BinaryFormat = PackedFormat.Default
-    var compactZeros: Boolean = true
 
     var checksum: Checksum?
         get() = null
@@ -132,7 +99,7 @@ class EncodedFormatBuilder {
  * ```
  * val format = EncodedFormat {
  *     codec = Base36
- *     transform = Crc16.asTransform()
+ *     transform = CompactZeros.then(Crc16.asTransform())
  * }
  * ```
  *
@@ -147,13 +114,11 @@ fun EncodedFormat(
         codec = from.configuration.codec
         transform = from.configuration.transform
         binaryFormat = from.configuration.binaryFormat
-        compactZeros = from.configuration.compactZeros
     }
     builder.builderAction()
     return EncodedFormat(EncodedConfiguration(
         builder.codec,
         builder.transform,
         builder.binaryFormat,
-        builder.compactZeros,
     ))
 }

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

@@ -13,6 +13,59 @@ interface PayloadTransform {
     fun decode(data: ByteArray): ByteArray
 }
 
+/**
+ * Chains two transforms into a pipeline.
+ *
+ * On encode: `this` is applied first, then [next].
+ * On decode: [next] is reversed first, then `this`.
+ *
+ * Example: `CompactZeros.then(Crc16.asTransform())` compacts bytes, then appends a checksum.
+ */
+fun PayloadTransform.then(next: PayloadTransform): PayloadTransform = object : PayloadTransform {
+    override fun encode(data: ByteArray): ByteArray = next.encode(this@then.encode(data))
+    override fun decode(data: ByteArray): ByteArray = this@then.decode(next.decode(data))
+}
+
+/**
+ * Strips leading zero bytes before encoding and restores them on decode.
+ *
+ * When the payload starts with a non-zero byte (k=0), the data is returned unchanged.
+ * Otherwise a sentinel `0x00` byte followed by a varint count is prepended to the
+ * stripped payload. Net overhead: 0 bytes for k=0, +1 byte for k=2, −(k−2) bytes for k≥3.
+ */
+object CompactZeros : PayloadTransform {
+
+    override fun encode(data: ByteArray): ByteArray {
+        var k = 0
+        while (k < data.size && data[k] == 0.toByte()) k++
+        if (k == 0) return data
+        // Sentinel byte 0x00 signals that a compact prefix follows.
+        // Safe because the stripped data always starts with a non-zero byte.
+        val count = varintEncode(k)
+        val result = ByteArray(1 + count.size + data.size - k)
+        result[0] = 0x00
+        count.copyInto(result, destinationOffset = 1)
+        data.copyInto(result, destinationOffset = 1 + count.size, startIndex = k)
+        return result
+    }
+
+    override fun decode(data: ByteArray): ByteArray {
+        require(data.isNotEmpty()) { "Compact payload cannot be empty." }
+        if (data[0] != 0.toByte()) return data  // k=0, no prefix was written
+        val (k, prefixLen) = PackedUtils.decodeVarInt(data, 1)
+        val dataStart = 1 + prefixLen
+        val result = ByteArray(k + data.size - dataStart)
+        data.copyInto(result, destinationOffset = k, startIndex = dataStart)
+        return result
+    }
+
+    private fun varintEncode(value: Int): ByteArray {
+        val out = ByteOutput(5)
+        PackedUtils.writeVarInt(value, out)
+        return out.toByteArray()
+    }
+}
+
 /**
  * Wraps this [Checksum] as a [PayloadTransform] that appends the digest on encode
  * and strips and verifies it on decode.

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

@@ -9,53 +9,47 @@ class EncodedFormatTest {
     @Serializable
     data class Payload(val x: Int, val s: String)
 
-    private val formatNoChecksum: StringFormat = EncodedFormat(Base62, null)
-    private val formatWithChecksum: StringFormat = EncodedFormat(Base62, Crc16.asTransform())
+    private val formatBare: StringFormat = EncodedFormat(Base62, null)
+    private val formatChecksum: StringFormat = EncodedFormat(Base62, Crc16.asTransform())
+    private val formatCompact: StringFormat = EncodedFormat(Base62, CompactZeros)
+    private val formatCompactChecksum: StringFormat = EncodedFormat(Base62, CompactZeros.then(Crc16.asTransform()))
 
     @Test
-    fun `roundtrip without checksum`() {
+    fun `roundtrip without transform`() {
         val value = Payload(42, "hello")
-        val encoded =
-            formatNoChecksum.encodeToString(Payload.serializer(), value)
-        val decoded =
-            formatNoChecksum.decodeFromString(Payload.serializer(), encoded)
+        val encoded = formatBare.encodeToString(Payload.serializer(), value)
+        val decoded = formatBare.decodeFromString(Payload.serializer(), encoded)
         assertEquals(value, decoded)
     }
 
     @Test
     fun `roundtrip with checksum`() {
         val value = Payload(-5, "world")
-        val encoded =
-            formatWithChecksum.encodeToString(Payload.serializer(), value)
-        val decoded =
-            formatWithChecksum.decodeFromString(Payload.serializer(), encoded)
+        val encoded = formatChecksum.encodeToString(Payload.serializer(), value)
+        val decoded = formatChecksum.decodeFromString(Payload.serializer(), encoded)
         assertEquals(value, decoded)
     }
 
     @Test
     fun `checksum mismatch throws`() {
         val value = Payload(7, "x")
-        val encoded =
-            formatWithChecksum.encodeToString(Payload.serializer(), value)
+        val encoded = formatChecksum.encodeToString(Payload.serializer(), value)
         val tampered = encoded.dropLast(1) + when (encoded.last()) {
             'A' -> 'B'
             else -> 'A'
         }
         assertFailsWith<IllegalArgumentException> {
-            formatWithChecksum.decodeFromString(Payload.serializer(), tampered)
+            formatChecksum.decodeFromString(Payload.serializer(), tampered)
         }
     }
 
     @Test
-    fun `compactZeros roundtrip without checksum`() {
+    fun `compactZeros roundtrip`() {
         val value = Payload(1, "hi")
-        val encoded =
-            formatNoChecksum.encodeToString(Payload.serializer(), value)
-        val decoded =
-            formatNoChecksum.decodeFromString(Payload.serializer(), encoded)
+        val encoded = formatCompact.encodeToString(Payload.serializer(), value)
+        val decoded = formatCompact.decodeFromString(Payload.serializer(), encoded)
         assertEquals(value, decoded)
-        val uncompressed = EncodedFormat(Base62, compactZeros = false)
-            .encodeToString(Payload.serializer(), value)
+        val uncompressed = formatBare.encodeToString(Payload.serializer(), value)
         assertTrue(
             encoded.length <= uncompressed.length,
             "compactZeros ($encoded) should be <= uncompressed ($uncompressed)"
@@ -65,10 +59,8 @@ class EncodedFormatTest {
     @Test
     fun `compactZeros roundtrip with checksum`() {
         val value = Payload(0, "zero")
-        val encoded =
-            formatWithChecksum.encodeToString(Payload.serializer(), value)
-        val decoded =
-            formatWithChecksum.decodeFromString(Payload.serializer(), encoded)
+        val encoded = formatCompactChecksum.encodeToString(Payload.serializer(), value)
+        val decoded = formatCompactChecksum.decodeFromString(Payload.serializer(), encoded)
         assertEquals(value, decoded)
     }
 
@@ -78,25 +70,32 @@ class EncodedFormatTest {
         data class Z(val a: Int, val b: Int)
 
         val value = Z(0, 0)
-        val encoded = formatNoChecksum.encodeToString(Z.serializer(), value)
-        val decoded = formatNoChecksum.decodeFromString(Z.serializer(), encoded)
+        val encoded = formatCompact.encodeToString(Z.serializer(), value)
+        val decoded = formatCompact.decodeFromString(Z.serializer(), encoded)
         assertEquals(value, decoded)
     }
 
     @Test
     fun `compactZeros checksum mismatch throws`() {
         val value = Payload(7, "x")
-        val encoded =
-            formatWithChecksum.encodeToString(Payload.serializer(), value)
+        val encoded = formatCompactChecksum.encodeToString(Payload.serializer(), value)
         val tampered = encoded.dropLast(1) + when (encoded.last()) {
             'A' -> 'B'
             else -> 'A'
         }
         assertFailsWith<IllegalArgumentException> {
-            formatWithChecksum.decodeFromString(Payload.serializer(), tampered)
+            formatCompactChecksum.decodeFromString(Payload.serializer(), tampered)
         }
     }
 
+    @Test
+    fun `compactZeros no overhead when no leading zeros`() {
+        val value = Payload(-1, "a")
+        val compact = formatCompact.encodeToString(Payload.serializer(), value)
+        val bare = formatBare.encodeToString(Payload.serializer(), value)
+        assertEquals(bare, compact)
+    }
+
     @Test
     fun `builder configures custom properties successfully`() {
         val value = Payload(99, "builder validation")
@@ -110,14 +109,25 @@ class EncodedFormatTest {
         val encoded = customFormat.encodeToString(Payload.serializer(), value)
 
         assertTrue(encoded.isNotEmpty())
-        val decoded =
-            customFormat.decodeFromString(Payload.serializer(), encoded)
+        val decoded = customFormat.decodeFromString(Payload.serializer(), encoded)
         assertEquals(value, decoded)
 
-        val tampered =
-            encoded.dropLast(1) + if (encoded.last() == 'u') "t" else "u"
+        val tampered = encoded.dropLast(1) + if (encoded.last() == 'u') "t" else "u"
         assertFailsWith<IllegalArgumentException> {
             customFormat.decodeFromString(Payload.serializer(), tampered)
         }
     }
+
+    @Test
+    fun `builder then composition roundtrip`() {
+        val value = Payload(0, "composed")
+
+        val format = EncodedFormat {
+            transform = CompactZeros.then(Crc16.asTransform())
+        }
+
+        val encoded = format.encodeToString(Payload.serializer(), value)
+        val decoded = format.decodeFromString(Payload.serializer(), encoded)
+        assertEquals(value, decoded)
+    }
 }