ZLib.kotlin

---

ZLib.kotlin is a clean-room, RFC-based implementation of the zlib format (RFC 1950) and DEFLATE (RFC 1951) in pure Kotlin Multiplatform. It is not a direct port of zlib or any C# project. The original zlib and certain .NET ports served as useful references; see Credits.

---

Table of Contents

• About
• Features
• Installation
• Usage
• Documentation
• Compatibility
• Testing
• Credits & References
• License
• Contributing
• Contact

---

About

ZLib.kotlin is part of The Solace Project special libraries, designed to offer reliable, efficient compression for Kotlin Native targets. It is a complete rewrite in pure Kotlin, ensuring safety, maintainability, and native performance—without JNI, C interop, or external dependencies.

This library is a clean-room rewrite from the RFCs (RFC 1950 and RFC 1951). It is not a direct port of zlib or any C# project. The .NET implementations (zlib.net and zlib.managed) served as useful references.

---

Features

• Pure Kotlin implementation: No C/C++ code or JNI required.
• Comprehensive multiplatform support:
  • Native targets: macOS (ARM64), Linux (x64, ARM64), Windows (x64), iOS (ARM64, x64, Simulator)
  • JavaScript: Node.js runtime support
  • Future targets: WebAssembly and Android Native planned
• Familiar API: Designed to be comfortable for users familiar with zlib; .NET ports (zlib.net, zlib.managed) served as useful references.
• Fast and lightweight: Efficient, battle-tested algorithms for compression and decompression.
• Zero dependencies: No need for external libraries or system zlib installs.
• Actively maintained: Open to improvements and contributions.

---

Installation

Add ZLib.kotlin to your project with Gradle:

dependencies {
    implementation("com.solaceharmony:zlib.kotlin:<latest-version>")
}

Or, for multiplatform projects:

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("com.solaceharmony:zlib.kotlin:<latest-version>")
            }
        }
    }
}

Note: Replace <latest-version> with the latest published version on Maven Central or your chosen repository.

---

Usage

Here's a simple example of compressing and decompressing a ByteArray:

val data: ByteArray = "Hello, ZLib.kotlin!".encodeToByteArray()

// Compress
val compressed: ByteArray = ZLib.compress(data)

// Decompress
val decompressed: ByteArray = ZLib.decompress(compressed)

println(decompressed.decodeToString()) // Output: Hello, ZLib.kotlin!

For more advanced usage, streaming, or custom options, see the detailed API documentation and practical examples.

---

Documentation

📚 API Reference

Comprehensive API documentation covering:

• Core classes (ZStream, ZInputStream, ZStreamException)
• Compression and decompression methods
• Configuration options and constants
• Advanced usage patterns
• Error handling and performance tips

💡 Examples

Practical examples demonstrating:

• Basic compression/decompression - Simple operations with error handling
• Advanced techniques - Performance comparison, streaming, custom parameters
• Best practices - Memory management, buffer sizing, optimization tips

---

Compatibility

Supported Platforms

• Native Targets:

  • macOS: ARM64 (Apple Silicon)
  • Linux: x64, ARM64
  • Windows: x64 (via mingw)
  • iOS: ARM64, x64, Simulator ARM64
  • watchOS: ARM32, ARM64, x64, Simulator ARM64
  • tvOS: ARM64, x64, Simulator ARM64

• JavaScript: Node.js runtime

• Planned: WebAssembly, Android Native

All targets are tested and fully functional. For platform-specific build requirements, see the Testing section below.

---

Testing

Run multiplatform tests using Gradle with the -PwithTests=true flag. Tests are disabled by default to speed up normal builds.

Platform-Specific Tests

# Native targets  
./gradlew -PwithTests=true macosArm64Test        # macOS ARM64
./gradlew -PwithTests=true linuxX64Test          # Linux x64
./gradlew -PwithTests=true linuxArm64Test        # Linux ARM64
./gradlew -PwithTests=true mingwX64Test          # Windows x64

# iOS targets
./gradlew -PwithTests=true iosX64Test            # iOS x64
./gradlew -PwithTests=true iosSimulatorArm64Test # iOS Simulator ARM64

# watchOS targets  
./gradlew -PwithTests=true watchosX64Test            # watchOS x64
./gradlew -PwithTests=true watchosSimulatorArm64Test # watchOS Simulator ARM64

# tvOS targets
./gradlew -PwithTests=true tvosX64Test            # tvOS x64
./gradlew -PwithTests=true tvosSimulatorArm64Test # tvOS Simulator ARM64

# JavaScript
./gradlew -PwithTests=true jsTest                # Node.js

# Run all available tests
./gradlew -PwithTests=true allTests              # All platforms

Note: Some platform tests may only run on compatible host systems (e.g., iOS tests typically require macOS).

---

Credits & References

• zlib (C) Jean-loup Gailly and Mark Adler — Original C implementation inspiring the format and algorithms
• .NET implementations used as references: zlib.net, zlib.managed
• This project: Kotlin Multiplatform implementation by Sydney Bach / The Solace Project

Special thanks to all contributors and maintainers of the original and derivative implementations.

---

License

This project is licensed under the Apache License 2.0. See NOTICE for attribution and third-party notices.

Attribution

This library is an original Kotlin Multiplatform implementation maintained by Sydney Bach / The Solace Project. It is inspired by and acknowledges the original zlib work by Jean‑loup Gailly and Mark Adler. Any remaining references to legacy code paths were removed during the rewrite; the streaming inflate presented here is a clean, Kotlin‑native implementation that adheres to the zlib format (RFC 1950) and DEFLATE specification (RFC 1951).

---

Contributing

Contributions, bug reports, and pull requests are welcome!

• Fork the repo and create your branch.
• Submit a PR with a clear description.

---

Contact

Maintained by The Solace Project.

For questions or support, please open an issue or contact us at [email protected].

---

Acknowledgment: We recognize the original zlib by Jean‑loup Gailly and Mark Adler, and note that .NET implementations (zlib.net, zlib.managed) were consulted as references during development.