From 3a1f3e57e96e80b2dfedf7cac937426de70c249f Mon Sep 17 00:00:00 2001 From: Paul Toffoloni Date: Thu, 12 Nov 2026 16:19:32 +0100 Subject: [PATCH] Add simple README --- Package.swift | 10 +- README.md | 93 +++++++++++++++++++ .../Compression+Data.swift | 0 3 files changed, 98 insertions(+), 5 deletions(-) create mode 100644 README.md rename Sources/{CompressionFoundation => CompressionFoundationCompat}/Compression+Data.swift (100%) diff --git a/Package.swift b/Package.swift index a1f93d5..61af2c8 100644 --- a/Package.swift +++ b/Package.swift @@ -11,10 +11,6 @@ let package = Package( .visionOS(.v26), ], products: [ - .library( - name: "Compression", - targets: ["CompressionCore", "CompressionDeflate", "CompressionFoundation", "CompressionZstd"] - ), .library( name: "CompressionDeflate", targets: ["CompressionDeflate"] @@ -23,6 +19,10 @@ let package = Package( name: "CompressionZstd", targets: ["CompressionZstd"] ), + .library( + name: "CompressionFoundationCompat", + targets: ["CompressionCore", "CompressionFoundationCompat"] + ), ], targets: [ .target( @@ -30,7 +30,7 @@ let package = Package( swiftSettings: swiftSettings ), .target( - name: "CompressionFoundation", + name: "CompressionFoundationCompat", dependencies: [ .target(name: "CompressionCore") ], diff --git a/README.md b/README.md new file mode 100644 index 0000000..b44aa2e --- /dev/null +++ b/README.md @@ -0,0 +1,93 @@ +# Compression + +[![Swift 6.3](https://img.shields.io/badge/Swift-6.3-F05138?logo=swift&logoColor=white)](https://www.swift.org) + +This is a compression package for Swift which supports multiple algorithms and is aimed to be used on any Swift-compatible platform. + +> [!Important] +> This package is still under development and the API may change in future releases. +> Use at your own risk. + + +## Getting Started + +To use the package, add the following to your `Package.swift` file: + +```swift +.package(url: "https://github.com/brokenhandsio/compression.git", branch: "main") +``` + +Then, in your target, you can add whatever product fits your needs: + +Product | Description +--- | --- +`CompressionCore` | Core compression and decompression functionality +`CompressionDeflate` | Gzip and Deflate codecs via zlib +`CompressionZstd` | Zstandard codec via zstd +`CompressionFoundationCompat` | Compression functionality compatibility layer for Foundation APIs + +## Usage + +Start with importing the product with whatever algorithm you intend to use, for example: + +```swift +import CompressionZstd +``` + +### One-shot Compression + +A number of APIs are provided for different use cases. For simplicity, you can start with the `[UInt8]` returning API: + +```swift +let data = Array("The quick brown fox jumps over the lazy dog.".utf8) +let compressor = Deflate.Compressor(configuration: .default) +let compressed = try compressor.compress(data) +``` + +This API is based on `OutputSpan` APIs which you can drop down to as well if performance is a concern: + +```swift +let data = Array("The quick brown fox jumps over the lazy dog.".utf8) +let compressor = Deflate.Compressor() +let capacity = compressor.upperBound(forInputSize: data.count) +let compressed = try [UInt8](capacity: capacity) { output in + try compressor.compress(data, into: &output) +} +``` + +### Streaming Compression + +Streaming compression allows you to compress data in chunks, which is useful for large data streams or when you don't have all the data available at once, for example when reading from a file or network stream. + +```swift +let data = Array("The quick brown fox jumps over the lazy dog.".utf8) +let compressor = Zstd.StreamingCompressor(configuration: .default) +var output: OutputSpan = ... +var result = try compressor.compress(data.span, into: &output) +switch result.status { + case .awaitingInput: break // The compressor is waiting for more input data + case .needsOutput: break // The compressor needs more output space to continue + case .finished: break // Compression has finished successfully +} +try compressor.finish(into: &output) +``` + +> [!Important] +> Remember to always call `finish()` after compressing all input data to ensure that the compression is properly finalized. To re-use the compressor for a new stream, call `reset()` first. + +### Async Sequences + +The package also provide de/compression `AsyncSequence`s based on the streaming APIs, allowing you to process data asynchronously in a sequence of chunks. + +```swift +let data: AsyncStream<[UInt8]> = ... +let decompressed = data.decompressed(using: .zstd(maxDecompressedSize: 10 * 1024)) +var output: [UInt8] = [] + +for try await chunk in decompressed { + output.append(contentsOf: chunk) +} +``` + +> [!Note] +> The AsyncSequence APIs are currently not available on Embedded platforms. diff --git a/Sources/CompressionFoundation/Compression+Data.swift b/Sources/CompressionFoundationCompat/Compression+Data.swift similarity index 100% rename from Sources/CompressionFoundation/Compression+Data.swift rename to Sources/CompressionFoundationCompat/Compression+Data.swift