philiprehberger-gzip_kit 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fac216e7083cff42b7ae1ff40bc14622a65090bc176fdeeb142c1528e9e7df1
-  data.tar.gz: 962f299e080f1338f585eac96a61739bfea7a989bbc4b9ac370c1a2f0e6c7db4
+  metadata.gz: fc38727681cc1557d80be3bdf12969c479c53bdf2b67d48b88c35286ed2bfed2
+  data.tar.gz: 723760091ce30d192a0bc0fe8a921dc2c5da331b3c068c7d3e5bc70edcd71c76
 SHA512:
-  metadata.gz: d54f8f5bc6419a4e7b03c5609a05b01ee87d16577b1cc0c448b0573b184fb1e5a710d0b746959f7a8244aeba58fd2e65cc10d7246279714b82594bcf92b72d65
-  data.tar.gz: 04134126507453cc6648e4f901e025f61b549e7a8cbe07d02181cc27121eb11df271ae4fcb34f89fcd7f60a491b1220140d5fafa5336c58194985a47ccd36bc0
+  metadata.gz: 4db3b719e3188b6c0011eecf3e26ea2e4f2386fb76d0ed0a2aac0f82d43a383107e2acdec7cc8adeee288aa5716ce9114678b0d468afadf991741e29a9a13f11
+  data.tar.gz: 363c8fdd0ca90ace3235e6c27e3f8b014391709d8208f2d5bb64a881832dfd8159159412ae2abe848a1175b46f324df183f52383f1838990262a7b40fbf05800

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-23
+
+### Added
+- Optional `chunk_size:` keyword on `compress_stream`, `decompress_stream`, `compress_file`, `decompress_file` (defaults to 64 KB).
+- Optional `stats:` keyword on `decompress` — returns `{ data:, ratio: }` when true.
+- Module-level YARD overview and `@example` blocks on primary methods.
+
+## [0.3.0] - 2026-04-16
+
+### Added
+- `GzipKit.equivalent?(blob_a, blob_b)` — returns true iff both gzip-compressed inputs decompress to equal byte strings; raises `GzipKit::Error` if either input is not valid gzip
+
 ## [0.2.1] - 2026-03-31
 
 ### Changed

data/README.md

@@ -108,6 +108,41 @@ File.open("output.gz", "rb") do |input|
 end
 ```
 
+### Custom chunk size
+
+Streaming and file methods read in 64 KB chunks by default. Override with `chunk_size:` to tune for memory constraints or throughput:
+
+```ruby
+require "philiprehberger/gzip_kit"
+
+# Smaller chunks for memory-constrained environments
+File.open("input.txt", "rb") do |input|
+  File.open("output.gz", "wb") do |output|
+    Philiprehberger::GzipKit.compress_stream(input, output, chunk_size: 4 * 1024)
+  end
+end
+
+# Larger chunks for bulk throughput
+Philiprehberger::GzipKit.compress_file("input.bin", "output.gz", chunk_size: 1 * 1024 * 1024)
+Philiprehberger::GzipKit.decompress_file("output.gz", "restored.bin", chunk_size: 1 * 1024 * 1024)
+```
+
+`chunk_size:` must be a positive `Integer`; any other value raises `ArgumentError`.
+
+### Decompress with stats
+
+Mirror of `compress(..., stats: true)` — returns a hash with the decompressed payload and the compressed-to-decompressed size ratio:
+
+```ruby
+require "philiprehberger/gzip_kit"
+
+compressed = Philiprehberger::GzipKit.compress("a" * 10_000)
+result = Philiprehberger::GzipKit.decompress(compressed, stats: true)
+# => { data: "aaaa...", ratio: 0.0041 }
+```
+
+The ratio is `compressed_size / decompressed_size` (inverse of compression ratio). For zero-length output, ratio is `0.0`.
+
 ### Stream Concatenation
 
 ```ruby
@@ -120,6 +155,20 @@ combined = Philiprehberger::GzipKit.concat(part_a, part_b)
 Philiprehberger::GzipKit.decompress(combined) # => "Hello, world!"
 ```
 
+### Equivalence Check
+
+Compare two gzip blobs by their decompressed payload — useful when the same source is recompressed at different levels or with different metadata:
+
+```ruby
+require "philiprehberger/gzip_kit"
+
+fast = Philiprehberger::GzipKit.compress("hello", level: Zlib::BEST_SPEED)
+best = Philiprehberger::GzipKit.compress("hello", level: Zlib::BEST_COMPRESSION)
+
+Philiprehberger::GzipKit.equivalent?(fast, best) # => true
+Philiprehberger::GzipKit.equivalent?(fast, Philiprehberger::GzipKit.compress("world")) # => false
+```
+
 ### Header Inspection
 
 ```ruby
@@ -134,13 +183,14 @@ header = Philiprehberger::GzipKit.inspect_header(gzip_data)
 | Method | Description |
 |--------|-------------|
 | `GzipKit.compress(string, level:, stats:)` | Compress a string to gzip bytes; returns stats hash when `stats: true` |
-| `GzipKit.decompress(data)` | Decompress gzip bytes to a string |
+| `GzipKit.decompress(data, stats:)` | Decompress gzip bytes to a string; returns `{ data:, ratio: }` when `stats: true` |
 | `GzipKit.compressed?(data)` | Check if data is gzip-compressed via magic bytes |
-| `GzipKit.compress_file(src, dest, level:, &block)` | Compress a file to a gzip file with optional progress callback |
-| `GzipKit.decompress_file(src, dest, &block)` | Decompress a gzip file with optional progress callback |
-| `GzipKit.compress_stream(io_in, io_out, level:)` | Streaming compression in 64KB chunks |
-| `GzipKit.decompress_stream(io_in, io_out)` | Streaming decompression in 64KB chunks |
+| `GzipKit.compress_file(src, dest, level:, chunk_size:, &block)` | Compress a file to a gzip file with optional progress callback and chunk size |
+| `GzipKit.decompress_file(src, dest, chunk_size:, &block)` | Decompress a gzip file with optional progress callback and chunk size |
+| `GzipKit.compress_stream(io_in, io_out, level:, chunk_size:)` | Streaming compression (64 KB chunks by default) |
+| `GzipKit.decompress_stream(io_in, io_out, chunk_size:)` | Streaming decompression (64 KB chunks by default) |
 | `GzipKit.concat(data_a, data_b)` | Concatenate two gzip-compressed strings |
+| `GzipKit.equivalent?(blob_a, blob_b)` | Check whether two gzip blobs decompress to equal byte strings |
 | `GzipKit.inspect_header(data)` | Read gzip header metadata without decompressing |
 
 ## Development

data/lib/philiprehberger/gzip_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module GzipKit
-    VERSION = '0.2.1'
+    VERSION = '0.4.0'
   end
 end

data/lib/philiprehberger/gzip_kit.rb

@@ -5,6 +5,22 @@ require 'stringio'
 require_relative 'gzip_kit/version'
 
 module Philiprehberger
+  # GzipKit provides gzip compression and decompression with streaming support.
+  #
+  # The module exposes both string-oriented and IO-oriented entry points:
+  #
+  # - {GzipKit.compress} / {GzipKit.decompress} for in-memory string data
+  # - {GzipKit.compress_stream} / {GzipKit.decompress_stream} for IO-to-IO streaming
+  # - {GzipKit.compress_file} / {GzipKit.decompress_file} for file-to-file transforms
+  # - {GzipKit.compressed?} / {GzipKit.inspect_header} for gzip detection and header inspection
+  # - {GzipKit.concat} / {GzipKit.equivalent?} for combining and comparing gzip blobs
+  #
+  # Streaming and file methods read in 64 KB chunks by default. The chunk size can be
+  # tuned via the +chunk_size:+ keyword when dealing with very small or very large payloads.
+  #
+  # @example Compress and decompress a string
+  #   compressed = Philiprehberger::GzipKit.compress('hello')
+  #   Philiprehberger::GzipKit.decompress(compressed) # => "hello"
   module GzipKit
     class Error < StandardError; end
 
@@ -17,6 +33,14 @@ module Philiprehberger
     # @param level [Integer] compression level (Zlib::DEFAULT_COMPRESSION by default)
     # @param stats [Boolean] when true, return a hash with compression statistics
     # @return [String, Hash] gzip-compressed bytes, or a stats hash when stats: true
+    #
+    # @example Compress a string
+    #   Philiprehberger::GzipKit.compress('hello, world!')
+    #   # => "\x1F\x8B\b\x00..." (binary gzip bytes)
+    #
+    # @example Compress with stats
+    #   Philiprehberger::GzipKit.compress('a' * 10_000, stats: true)
+    #   # => { data: "...", ratio: 0.99, original_size: 10000, compressed_size: 41 }
     def self.compress(string, level: Zlib::DEFAULT_COMPRESSION, stats: false)
       io_out = StringIO.new
       io_out.binmode
@@ -43,9 +67,19 @@ module Philiprehberger
     # Decompress gzip bytes to a string.
     #
     # @param data [String] gzip-compressed bytes
-    # @return [String] decompressed string
+    # @param stats [Boolean] when true, return a hash with decompression statistics
+    # @return [String, Hash] decompressed string, or a stats hash when stats: true
     # @raise [Zlib::GzipFile::Error] if the data is not valid gzip
-    def self.decompress(data)
+    #
+    # @example Decompress gzip bytes
+    #   compressed = Philiprehberger::GzipKit.compress('hello')
+    #   Philiprehberger::GzipKit.decompress(compressed) # => "hello"
+    #
+    # @example Decompress with stats
+    #   compressed = Philiprehberger::GzipKit.compress('a' * 10_000)
+    #   Philiprehberger::GzipKit.decompress(compressed, stats: true)
+    #   # => { data: "aaaa...", ratio: 0.0041 }
+    def self.decompress(data, stats: false)
       io_in = StringIO.new(data)
       io_in.binmode
       result = String.new(encoding: Encoding::BINARY)
@@ -62,7 +96,16 @@ module Philiprehberger
         end
       end
 
-      result.force_encoding(Encoding::UTF_8)
+      decompressed = result.force_encoding(Encoding::UTF_8)
+
+      if stats
+        decompressed_size = decompressed.bytesize
+        compressed_size = data.bytesize
+        ratio = decompressed_size.zero? ? 0.0 : compressed_size.to_f / decompressed_size
+        { data: decompressed, ratio: ratio }
+      else
+        decompressed
+      end
     end
 
     # Check if data is gzip-compressed by inspecting magic bytes.
@@ -81,25 +124,29 @@ module Philiprehberger
     # @param src [String] path to the source file
     # @param dest [String] path to the destination gzip file
     # @param level [Integer] compression level (Zlib::DEFAULT_COMPRESSION by default)
+    # @param chunk_size [Integer] bytes per read chunk (defaults to 64 KB)
     # @yield [bytes_processed, total_bytes] progress callback
     # @yieldparam bytes_processed [Integer] bytes processed so far
     # @yieldparam total_bytes [Integer] total file size
     # @return [void]
-    def self.compress_file(src, dest, level: Zlib::DEFAULT_COMPRESSION, &block)
+    # @raise [ArgumentError] if chunk_size is not a positive Integer
+    def self.compress_file(src, dest, level: Zlib::DEFAULT_COMPRESSION, chunk_size: CHUNK_SIZE, &block)
+      validate_chunk_size!(chunk_size)
+
       File.open(src, 'rb') do |io_in|
         File.open(dest, 'wb') do |io_out|
           if block
             total_bytes = File.size(src)
             bytes_processed = 0
             gz = Zlib::GzipWriter.new(io_out, level)
-            while (chunk = io_in.read(CHUNK_SIZE))
+            while (chunk = io_in.read(chunk_size))
               gz.write(chunk)
               bytes_processed += chunk.bytesize
               block.call(bytes_processed, total_bytes)
             end
             gz.finish
           else
-            compress_stream(io_in, io_out, level: level)
+            compress_stream(io_in, io_out, level: level, chunk_size: chunk_size)
           end
         end
       end
@@ -109,24 +156,28 @@ module Philiprehberger
     #
     # @param src [String] path to the gzip source file
     # @param dest [String] path to the destination file
+    # @param chunk_size [Integer] bytes per read chunk (defaults to 64 KB)
     # @yield [bytes_processed, total_bytes] progress callback
     # @yieldparam bytes_processed [Integer] bytes decompressed so far
     # @yieldparam total_bytes [nil] always nil (total unknown until decompression completes)
     # @return [void]
-    def self.decompress_file(src, dest, &block)
+    # @raise [ArgumentError] if chunk_size is not a positive Integer
+    def self.decompress_file(src, dest, chunk_size: CHUNK_SIZE, &block)
+      validate_chunk_size!(chunk_size)
+
       File.open(src, 'rb') do |io_in|
         File.open(dest, 'wb') do |io_out|
           if block
             gz = Zlib::GzipReader.new(io_in)
             bytes_processed = 0
-            while (chunk = gz.read(CHUNK_SIZE))
+            while (chunk = gz.read(chunk_size))
               io_out.write(chunk)
               bytes_processed += chunk.bytesize
               block.call(bytes_processed, nil)
             end
             gz.close
           else
-            decompress_stream(io_in, io_out)
+            decompress_stream(io_in, io_out, chunk_size: chunk_size)
           end
         end
       end
@@ -149,6 +200,24 @@ module Philiprehberger
       result
     end
 
+    # Check whether two gzip-compressed blobs decompress to equal byte strings.
+    #
+    # Useful for comparing gzip outputs produced at different compression levels
+    # or with different metadata — only the decompressed payloads are compared.
+    #
+    # @param blob_a [String] first gzip-compressed string
+    # @param blob_b [String] second gzip-compressed string
+    # @return [Boolean] true iff both blobs decompress to equal byte strings
+    # @raise [Error] if either input is not valid gzip
+    def self.equivalent?(blob_a, blob_b)
+      raise Error, 'first argument is not valid gzip data' unless compressed?(blob_a)
+      raise Error, 'second argument is not valid gzip data' unless compressed?(blob_b)
+
+      decompress(blob_a).b == decompress(blob_b).b
+    rescue Zlib::GzipFile::Error => e
+      raise Error, "failed to decompress gzip data: #{e.message}"
+    end
+
     # Inspect the gzip header without decompressing.
     #
     # @param data [String] gzip-compressed data
@@ -173,32 +242,65 @@ module Philiprehberger
       gz&.close
     end
 
-    # Streaming compression from one IO to another, reading in 64KB chunks.
+    # Streaming compression from one IO to another.
     #
     # @param io_in [IO] readable input stream
     # @param io_out [IO] writable output stream
     # @param level [Integer] compression level (Zlib::DEFAULT_COMPRESSION by default)
+    # @param chunk_size [Integer] bytes per read chunk (defaults to 64 KB)
     # @return [void]
-    def self.compress_stream(io_in, io_out, level: Zlib::DEFAULT_COMPRESSION)
+    # @raise [ArgumentError] if chunk_size is not a positive Integer
+    #
+    # @example Compress from one IO to another
+    #   File.open('input.txt', 'rb') do |io_in|
+    #     File.open('output.gz', 'wb') do |io_out|
+    #       Philiprehberger::GzipKit.compress_stream(io_in, io_out)
+    #     end
+    #   end
+    #
+    # @example Tune the chunk size for small payloads
+    #   Philiprehberger::GzipKit.compress_stream(io_in, io_out, chunk_size: 4 * 1024)
+    def self.compress_stream(io_in, io_out, level: Zlib::DEFAULT_COMPRESSION, chunk_size: CHUNK_SIZE)
+      validate_chunk_size!(chunk_size)
+
       gz = Zlib::GzipWriter.new(io_out, level)
-      while (chunk = io_in.read(CHUNK_SIZE))
+      while (chunk = io_in.read(chunk_size))
         gz.write(chunk)
       end
       gz.finish
     end
 
-    # Streaming decompression from one IO to another, reading in 64KB chunks.
+    # Streaming decompression from one IO to another.
     #
     # @param io_in [IO] readable input stream containing gzip data
     # @param io_out [IO] writable output stream
+    # @param chunk_size [Integer] bytes per read chunk (defaults to 64 KB)
     # @return [void]
-    def self.decompress_stream(io_in, io_out)
+    # @raise [ArgumentError] if chunk_size is not a positive Integer
+    #
+    # @example Decompress from one IO to another
+    #   File.open('output.gz', 'rb') do |io_in|
+    #     File.open('restored.txt', 'wb') do |io_out|
+    #       Philiprehberger::GzipKit.decompress_stream(io_in, io_out)
+    #     end
+    #   end
+    def self.decompress_stream(io_in, io_out, chunk_size: CHUNK_SIZE)
+      validate_chunk_size!(chunk_size)
+
       gz = Zlib::GzipReader.new(io_in)
-      while (chunk = gz.read(CHUNK_SIZE))
+      while (chunk = gz.read(chunk_size))
         io_out.write(chunk)
       end
     ensure
       gz&.close
     end
+
+    # @api private
+    def self.validate_chunk_size!(chunk_size)
+      return if chunk_size.is_a?(Integer) && chunk_size.positive?
+
+      raise ArgumentError, "chunk_size must be a positive Integer, got: #{chunk_size.inspect}"
+    end
+    private_class_method :validate_chunk_size!
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-gzip_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-23 00:00:00.000000000 Z
 dependencies: []
 description: Simple API for gzip compression and decompression with support for strings,
   files, and IO streams. Configurable compression level. Built on Ruby stdlib zlib.
@@ -23,11 +23,11 @@ files:
 - README.md
 - lib/philiprehberger/gzip_kit.rb
 - lib/philiprehberger/gzip_kit/version.rb
-homepage: https://github.com/philiprehberger/rb-gzip-kit
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-gzip_kit
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-gzip-kit
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-gzip_kit
   source_code_uri: https://github.com/philiprehberger/rb-gzip-kit
   changelog_uri: https://github.com/philiprehberger/rb-gzip-kit/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-gzip-kit/issues