purplelight 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '07534009e367f28d3374708991cb870f5fa168ee11a95142af8d357885af7abc'
-  data.tar.gz: e665d587dea94999326c0c42e88d2bcfd99bae01e305aee9e3051d3ddcd266e2
+  metadata.gz: 5964231e634be4a743207679e349623c275e0b20771b492bbc54c4261238e352
+  data.tar.gz: 82448e1f4b5ffb8e9846938653b16a4d7008aa29e722d9417863b80362370168
 SHA512:
-  metadata.gz: e4cabf4d438a8afa0d00902aa07b01320013f4e8588630fb2d5c4f9b2432e1910ac94c19ccce78bdb396a415ac3ea949527b83d22eadfbc036520656c4273869
-  data.tar.gz: b038e1fa40f36e985571019d7b4d7fe9c5013ea17314640f8d484ca9cbbb68292af08c5f91b1a006f34c473a24f3b83b03aece33d333685afb749437ac920ca4
+  metadata.gz: 4b8ac2ba82501978bcd1ae1b9db888f7dab387de76a7e473c5b0993a526398a727a029a0597a64c77bbbed976980e6adaad7a08f7e3967c9cfe6c7afa2d996ac
+  data.tar.gz: 15f536cfc05a0b70f7cdeb6bc7985e56b2e6dad6b2db53922e7aab12a821b8bb1294217390ff00c095b2cacb46c23e027d24d90a083e9e415a0df6e26fec9b59

data/README.md

@@ -9,7 +9,7 @@ Purplelight is published on RubyGems: [purplelight on RubyGems](https://rubygems
 Add to your Gemfile:
 
 ```ruby
-gem 'purplelight', '~> 0.1.2'
+gem 'purplelight', '~> 0.1.3'
 ```
 
 Or install directly:

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rake/testtask'
 
 task default: [:spec]
@@ -10,5 +12,3 @@ rescue LoadError
     sh 'echo "RSpec not installed"'
   end
 end
-
-

data/bin/purplelight

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'optparse'
 require 'json'
@@ -20,7 +21,7 @@ options = {
 }
 
 parser = OptionParser.new do |opts|
-  opts.banner = "Usage: purplelight snapshot [options]"
+  opts.banner = 'Usage: purplelight snapshot [options]'
 
   opts.on('-u', '--uri URI', 'MongoDB connection URI (required)') { |v| options[:uri] = v }
   opts.on('-d', '--db NAME', 'Database name (required)') { |v| options[:db] = v }
@@ -30,19 +31,26 @@ parser = OptionParser.new do |opts|
   opts.on('--compression NAME', 'Compression: zstd|gzip|none') { |v| options[:compression] = v.to_sym }
   opts.on('--partitions N', Integer, 'Number of partitions') { |v| options[:partitions] = v }
   opts.on('--batch-size N', Integer, 'Mongo batch size (default 2000)') { |v| options[:batch_size] = v }
-  opts.on('--by-size BYTES', Integer, 'Shard by size (bytes); default 268435456') { |v| options[:sharding] = { mode: :by_size, part_bytes: v } }
+  opts.on('--by-size BYTES', Integer, 'Shard by size (bytes); default 268435456') do |v|
+    options[:sharding] = { mode: :by_size, part_bytes: v }
+  end
   opts.on('--single-file', 'Write a single output file') { options[:sharding] = { mode: :single_file } }
   opts.on('--prefix NAME', 'Output file prefix') do |v|
     options[:sharding] ||= {}
     options[:sharding][:prefix] = v
   end
   opts.on('-q', '--query JSON', 'Filter query as JSON') { |v| options[:query] = JSON.parse(v) }
-  opts.on('--read-preference MODE', 'Read preference mode: primary|primary_preferred|secondary|secondary_preferred|nearest') { |v| options[:read_preference] = v.to_sym }
-  opts.on('--read-tags TAGS', 'Comma-separated key=value list to target tagged nodes (e.g., nodeType=ANALYTICS,region=EAST)') do |v|
+  opts.on('--read-preference MODE',
+          'Read preference mode: primary|primary_preferred|secondary|secondary_preferred|nearest') do |v|
+    options[:read_preference] = v.to_sym
+  end
+  opts.on('--read-tags TAGS',
+          'Comma-separated key=value list to target tagged nodes (e.g., nodeType=ANALYTICS,region=EAST)') do |v|
     tags = {}
     v.split(',').each do |pair|
       k, val = pair.split('=', 2)
       next if k.nil? || val.nil?
+
       tags[k] = val
     end
     options[:read_tags] = tags unless tags.empty?
@@ -67,16 +75,16 @@ rescue OptionParser::ParseError => e
 end
 
 %i[uri db collection output].each do |k|
-  if options[k].nil? || options[k].to_s.empty?
-    warn "Missing required option: --#{k}"
-    warn parser
-    exit 1
-  end
+  next unless options[k].nil? || options[k].to_s.empty?
+
+  warn "Missing required option: --#{k}"
+  warn parser
+  exit 1
 end
 
 effective_read = nil
 if options[:read_tags]
-  effective_read = { mode: (options[:read_preference] || :secondary), tag_sets: [options[:read_tags]] }
+  effective_read = { mode: options[:read_preference] || :secondary, tag_sets: [options[:read_tags]] }
 elsif options[:read_preference]
   effective_read = { mode: options[:read_preference] }
 end
@@ -101,9 +109,7 @@ ok = Purplelight.snapshot(
   sharding: options[:sharding],
   read_preference: effective_read || options[:read_preference],
   resume: { enabled: true },
-  on_progress: ->(s) { $stderr.puts("progress: #{s.to_json}") }
+  on_progress: ->(s) { warn("progress: #{s.to_json}") }
 )
 
 exit(ok ? 0 : 1)
-
-

data/lib/purplelight/errors.rb

@@ -7,5 +7,3 @@ module Purplelight
   class OutputExistsError < Error; end
   class WriterClosedError < Error; end
 end
-
-

data/lib/purplelight/manifest.rb

@@ -7,6 +7,11 @@ require 'digest'
 require 'fileutils'
 
 module Purplelight
+  # Manifest persists snapshot run metadata and progress to a JSON file.
+  #
+  # It records configuration, partition checkpoints, and per-part byte/row
+  # counts so interrupted runs can resume safely and completed runs are
+  # reproducible. Methods are thread-safe where mutation occurs.
   class Manifest
     DEFAULT_VERSION = 1
 
@@ -42,9 +47,9 @@ module Purplelight
 
     def save!
       dir = File.dirname(path)
-      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
-      tmp = path + '.tmp'
-      File.open(tmp, 'w') { |f| f.write(JSON.pretty_generate(@data)) }
+      FileUtils.mkdir_p(dir)
+      tmp = "#{path}.tmp"
+      File.write(tmp, JSON.pretty_generate(@data))
       FileUtils.mv(tmp, path)
     end
 
@@ -67,7 +72,9 @@ module Purplelight
     def ensure_partitions!(count)
       @mutex.synchronize do
         if @data['partitions'].empty?
-          @data['partitions'] = Array.new(count) { |i| { 'index' => i, 'last_id_exclusive' => nil, 'completed' => false } }
+          @data['partitions'] = Array.new(count) do |i|
+            { 'index' => i, 'last_id_exclusive' => nil, 'completed' => false }
+          end
           save!
         end
       end
@@ -92,7 +99,8 @@ module Purplelight
     def open_part!(path)
       @mutex.synchronize do
         idx = @data['parts'].size
-        @data['parts'] << { 'index' => idx, 'path' => path, 'bytes' => 0, 'rows' => 0, 'complete' => false, 'checksum' => nil }
+        @data['parts'] << { 'index' => idx, 'path' => path, 'bytes' => 0, 'rows' => 0, 'complete' => false,
+                            'checksum' => nil }
         save!
         idx
       end
@@ -128,12 +136,10 @@ module Purplelight
 
     def save_maybe!(interval_seconds: 2.0)
       now = Time.now
-      if (now - @last_save_at) >= interval_seconds
-        save!
-        @last_save_at = now
-      end
+      return unless (now - @last_save_at) >= interval_seconds
+
+      save!
+      @last_save_at = now
     end
   end
 end
-
-

data/lib/purplelight/partitioner.rb

@@ -3,6 +3,11 @@
 require 'mongo'
 
 module Purplelight
+  # Partitioner builds MongoDB range filters to split work across workers.
+  #
+  # Given a Mongo collection and an optional base query, it returns N
+  # contiguous `_id` ranges that can be processed independently while
+  # maintaining ascending order. Optimized for ObjectId-based `_id`.
   class Partitioner
     # Builds contiguous _id range filters for N partitions.
     # For ObjectId _id, we sample quantiles to split into near-equal document counts.
@@ -20,9 +25,7 @@ module Purplelight
       cursor = base_query.projection(_id: 1).batch_size(1_000).no_cursor_timeout
       i = 0
       cursor.each do |doc|
-        if (i % step).zero?
-          boundaries << doc['_id']
-        end
+        boundaries << doc['_id'] if (i % step).zero?
         i += 1
         break if boundaries.size >= partitions
       end
@@ -30,7 +33,7 @@ module Purplelight
       ranges = []
       prev = nil
       boundaries.each_with_index do |b, idx|
-        if idx == 0
+        if idx.zero?
           prev = nil
           next
         end
@@ -80,5 +83,3 @@ module Purplelight
     end
   end
 end
-
-

data/lib/purplelight/queue.rb

@@ -14,10 +14,9 @@ module Purplelight
 
     def push(item, bytes:)
       @mutex.synchronize do
-        raise "queue closed" if @closed
-        while (@bytes + bytes) > @max_bytes
-          @cv.wait(@mutex)
-        end
+        raise 'queue closed' if @closed
+
+        @cv.wait(@mutex) while (@bytes + bytes) > @max_bytes
         @queue << [item, bytes]
         @bytes += bytes
         @cv.broadcast
@@ -27,9 +26,8 @@ module Purplelight
     def pop
       @mutex.synchronize do
         while @queue.empty?
-          if @closed
-            return nil
-          end
+          return nil if @closed
+
           @cv.wait(@mutex)
         end
         item, bytes = @queue.shift
@@ -51,5 +49,3 @@ module Purplelight
     end
   end
 end
-
-

data/lib/purplelight/snapshot.rb

@@ -12,6 +12,7 @@ require_relative 'manifest'
 require_relative 'errors'
 
 module Purplelight
+  # Snapshot orchestrates partition planning, parallel reads, and writing.
   class Snapshot
     DEFAULTS = {
       format: :jsonl,
@@ -23,10 +24,10 @@ module Purplelight
       read_concern: { level: :majority },
       read_preference: :primary,
       no_cursor_timeout: true
-    }
+    }.freeze
 
-    def self.snapshot(**options)
-      new(**options).run
+    def self.snapshot(...)
+      new(...).run
     end
 
     def initialize(client:, collection:, output:, format: DEFAULTS[:format], compression: DEFAULTS[:compression],
@@ -61,6 +62,7 @@ module Purplelight
       @running = true
     end
 
+    # rubocop:disable Naming/PredicateMethod
     def run
       dir, prefix = resolve_output(@output, @format)
       manifest_path = File.join(dir, "#{prefix}.manifest.json")
@@ -68,11 +70,13 @@ module Purplelight
 
       manifest = if @resume && @resume[:enabled] && File.exist?(manifest_path)
                    m = Manifest.load(manifest_path)
-                   unless m.compatible_with?(collection: @collection.name, format: @format, compression: @compression, query_digest: query_digest)
+                   unless m.compatible_with?(collection: @collection.name, format: @format, compression: @compression,
+                                             query_digest: query_digest)
                      if @resume[:overwrite_incompatible]
                        m = Manifest.new(path: manifest_path)
                      else
-                       raise IncompatibleResumeError, "existing manifest incompatible with request; pass overwrite_incompatible: true to reset"
+                       raise IncompatibleResumeError,
+                             'existing manifest incompatible with request; pass overwrite_incompatible: true to reset'
                      end
                    end
                    m
@@ -81,12 +85,13 @@ module Purplelight
                  end
 
       manifest.configure!(collection: @collection.name, format: @format, compression: @compression, query_digest: query_digest, options: {
-        partitions: @partitions, batch_size: @batch_size, rotate_bytes: @rotate_bytes, hint: @hint
-      })
+                            partitions: @partitions, batch_size: @batch_size, rotate_bytes: @rotate_bytes, hint: @hint
+                          })
       manifest.ensure_partitions!(@partitions)
 
       # Plan partitions
-      partition_filters = Partitioner.object_id_partitions(collection: @collection, query: @query, partitions: @partitions)
+      partition_filters = Partitioner.object_id_partitions(collection: @collection, query: @query,
+                                                           partitions: @partitions)
 
       # Reader queue
       queue = ByteQueue.new(max_bytes: @queue_size_bytes)
@@ -94,13 +99,16 @@ module Purplelight
       # Writer
       writer = case @format
                when :jsonl
-                 WriterJSONL.new(directory: dir, prefix: prefix, compression: @compression, rotate_bytes: @rotate_bytes, logger: @logger, manifest: manifest)
+                 WriterJSONL.new(directory: dir, prefix: prefix, compression: @compression,
+                                 rotate_bytes: @rotate_bytes, logger: @logger, manifest: manifest)
                when :csv
-                 single_file = (@sharding && @sharding[:mode].to_s == 'single_file')
-                 WriterCSV.new(directory: dir, prefix: prefix, compression: @compression, rotate_bytes: @rotate_bytes, logger: @logger, manifest: manifest, single_file: single_file)
+                 single_file = @sharding && @sharding[:mode].to_s == 'single_file'
+                 WriterCSV.new(directory: dir, prefix: prefix, compression: @compression, rotate_bytes: @rotate_bytes,
+                               logger: @logger, manifest: manifest, single_file: single_file)
                when :parquet
-                 single_file = (@sharding && @sharding[:mode].to_s == 'single_file')
-                 WriterParquet.new(directory: dir, prefix: prefix, compression: @compression, logger: @logger, manifest: manifest, single_file: single_file)
+                 single_file = @sharding && @sharding[:mode].to_s == 'single_file'
+                 WriterParquet.new(directory: dir, prefix: prefix, compression: @compression, logger: @logger,
+                                   manifest: manifest, single_file: single_file)
                else
                  raise ArgumentError, "format not implemented: #{@format}"
                end
@@ -117,6 +125,7 @@ module Purplelight
         loop do
           batch = queue.pop
           break if batch.nil?
+
           writer.write_many(batch)
         end
       ensure
@@ -124,10 +133,11 @@ module Purplelight
       end
 
       progress_thread = Thread.new do
-        last = Time.now
+        Time.now
         loop do
           sleep 2
           break unless @running
+
           @on_progress&.call({ queue_bytes: queue.size_bytes })
         end
       end
@@ -140,11 +150,12 @@ module Purplelight
       progress_thread.join
       true
     end
+    # rubocop:enable Naming/PredicateMethod
 
     private
 
-    def resolve_output(output, format)
-      if File.directory?(output) || output.end_with?("/")
+    def resolve_output(output, _format)
+      if File.directory?(output) || output.end_with?('/')
         dir = output
         prefix = @sharding[:prefix] || @collection.name
       else
@@ -192,7 +203,7 @@ module Purplelight
           last_id = doc['_id']
           doc = @mapper.call(doc) if @mapper
           if encode_lines
-            line = Oj.dump(doc, mode: :compat) + "\n"
+            line = "#{Oj.dump(doc, mode: :compat)}\n"
             bytes = line.bytesize
             buffer << line
           else
@@ -201,12 +212,12 @@ module Purplelight
             buffer << doc
           end
           buffer_bytes += bytes
-          if buffer.length >= batch_size || buffer_bytes >= 1_000_000
-            queue.push(buffer, bytes: buffer_bytes)
-            manifest.update_partition_checkpoint!(idx, last_id)
-            buffer = []
-            buffer_bytes = 0
-          end
+          next unless buffer.length >= batch_size || buffer_bytes >= 1_000_000
+
+          queue.push(buffer, bytes: buffer_bytes)
+          manifest.update_partition_checkpoint!(idx, last_id)
+          buffer = []
+          buffer_bytes = 0
         end
         unless buffer.empty?
           queue.push(buffer, bytes: buffer_bytes)
@@ -215,12 +226,7 @@ module Purplelight
           buffer_bytes = 0
         end
         manifest.mark_partition_complete!(idx)
-      rescue => e
-        # Re-raise to fail the thread; could implement retry/backoff
-        raise e
       end
     end
   end
 end
-
-

data/lib/purplelight/version.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
 module Purplelight
-  VERSION = "0.1.2"
+  VERSION = '0.1.3'
 end
-
-

data/lib/purplelight/writer_csv.rb

@@ -8,13 +8,16 @@ require 'fileutils'
 begin
   require 'zstds'
 rescue LoadError
+  # zstd not available; fallback handled later via gzip
 end
 
 module Purplelight
+  # WriterCSV writes documents to CSV files with optional compression.
   class WriterCSV
     DEFAULT_ROTATE_BYTES = 256 * 1024 * 1024
 
-    def initialize(directory:, prefix:, compression: :zstd, rotate_bytes: DEFAULT_ROTATE_BYTES, logger: nil, manifest: nil, single_file: false, columns: nil, headers: true)
+    def initialize(directory:, prefix:, compression: :zstd, rotate_bytes: DEFAULT_ROTATE_BYTES, logger: nil,
+                   manifest: nil, single_file: false, columns: nil, headers: true)
       @directory = directory
       @prefix = prefix
       @compression = compression
@@ -35,9 +38,9 @@ module Purplelight
       @closed = false
 
       @effective_compression = determine_effective_compression(@compression)
-      if @effective_compression.to_s != @compression.to_s
-        @logger&.warn("requested compression '#{@compression}' not available; using '#{@effective_compression}'")
-      end
+      return unless @effective_compression.to_s != @compression.to_s
+
+      @logger&.warn("requested compression '#{@compression}' not available; using '#{@effective_compression}'")
     end
 
     def write_many(array_of_docs)
@@ -53,6 +56,7 @@ module Purplelight
 
       array_of_docs.each do |doc|
         next if doc.is_a?(String)
+
         row = @columns.map { |k| extract_value(doc, k) }
         @csv << row
         @rows_written += 1
@@ -65,16 +69,17 @@ module Purplelight
     def rotate_if_needed
       return if @single_file
       return if @rotate_bytes.nil?
+
       raw_bytes = @io.respond_to?(:pos) ? @io.pos : @bytes_written
       return if raw_bytes < @rotate_bytes
+
       rotate!
     end
 
     def close
       return if @closed
-      if @csv
-        @csv.flush
-      end
+
+      @csv&.flush
       if @io
         finalize_current_part!
         @io.close
@@ -86,6 +91,7 @@ module Purplelight
 
     def ensure_open!
       return if @io
+
       FileUtils.mkdir_p(@directory)
       path = next_part_path
       @part_index = @manifest&.open_part!(path) if @manifest
@@ -99,16 +105,15 @@ module Purplelight
     def build_compressed_io(raw)
       case @effective_compression.to_s
       when 'zstd'
-        if defined?(ZSTDS)
-          return ZSTDS::Writer.open(raw, level: 10)
-        else
-          @logger&.warn("zstd gem not loaded; using gzip")
-          return Zlib::GzipWriter.new(raw)
-        end
+        return ZSTDS::Writer.open(raw, level: 10) if defined?(ZSTDS)
+
+        @logger&.warn('zstd gem not loaded; using gzip')
+        Zlib::GzipWriter.new(raw)
+
       when 'gzip'
-        return Zlib::GzipWriter.new(raw)
+        Zlib::GzipWriter.new(raw)
       when 'none'
-        return raw
+        raw
       else
         raise ArgumentError, "unknown compression: #{@effective_compression}"
       end
@@ -116,6 +121,7 @@ module Purplelight
 
     def rotate!
       return unless @io
+
       finalize_current_part!
       @io.close
       @io = nil
@@ -131,26 +137,24 @@ module Purplelight
 
     def next_part_path
       ext = 'csv'
-      if @single_file
-        filename = format("%s.%s", @prefix, ext)
-      else
-        filename = format("%s-part-%06d.%s", @prefix, @file_seq, ext)
-      end
-      filename += ".zst" if @effective_compression.to_s == 'zstd'
-      filename += ".gz" if @effective_compression.to_s == 'gzip'
+      filename = if @single_file
+                   format('%<prefix>s.%<ext>s', prefix: @prefix, ext: ext)
+                 else
+                   format('%<prefix>s-part-%<seq>06d.%<ext>s', prefix: @prefix, seq: @file_seq, ext: ext)
+                 end
+      filename += '.zst' if @effective_compression.to_s == 'zstd'
+      filename += '.gz' if @effective_compression.to_s == 'gzip'
       File.join(@directory, filename)
     end
 
     def determine_effective_compression(requested)
       case requested.to_s
       when 'zstd'
-        return (defined?(ZSTDS) ? :zstd : :gzip)
-      when 'gzip'
-        return :gzip
+        (defined?(ZSTDS) ? :zstd : :gzip)
       when 'none'
-        return :none
+        :none
       else
-        return :gzip
+        :gzip
       end
     end
 
@@ -176,5 +180,3 @@ module Purplelight
     end
   end
 end
-
-

data/lib/purplelight/writer_jsonl.rb

@@ -11,10 +11,12 @@ rescue LoadError
 end
 
 module Purplelight
+  # WriterJSONL writes newline-delimited JSON with optional compression.
   class WriterJSONL
     DEFAULT_ROTATE_BYTES = 256 * 1024 * 1024
 
-    def initialize(directory:, prefix:, compression: :zstd, rotate_bytes: DEFAULT_ROTATE_BYTES, logger: nil, manifest: nil, compression_level: nil)
+    def initialize(directory:, prefix:, compression: :zstd, rotate_bytes: DEFAULT_ROTATE_BYTES, logger: nil,
+                   manifest: nil, compression_level: nil)
       @directory = directory
       @prefix = prefix
       @compression = compression
@@ -31,21 +33,20 @@ module Purplelight
       @closed = false
 
       @effective_compression = determine_effective_compression(@compression)
-      if @effective_compression.to_s != @compression.to_s
-        @logger&.warn("requested compression '#{@compression}' not available; using '#{@effective_compression}'")
-      end
+      return unless @effective_compression.to_s != @compression.to_s
+
+      @logger&.warn("requested compression '#{@compression}' not available; using '#{@effective_compression}'")
     end
 
     def write_many(array_of_docs)
       ensure_open!
       # If upstream already produced newline-terminated strings, join fast.
-      if array_of_docs.first.is_a?(String)
-        buffer = array_of_docs.join
-        rows = array_of_docs.size
-      else
-        buffer = array_of_docs.map { |doc| Oj.dump(doc, mode: :compat) + "\n" }.join
-        rows = array_of_docs.size
-      end
+      buffer = if array_of_docs.first.is_a?(String)
+                 array_of_docs.join
+               else
+                 array_of_docs.map { |doc| "#{Oj.dump(doc, mode: :compat)}\n" }.join
+               end
+      rows = array_of_docs.size
       write_buffer(buffer)
       @rows_written += rows
       @manifest&.add_progress_to_part!(index: @part_index, rows_delta: rows, bytes_delta: buffer.bytesize)
@@ -54,11 +55,13 @@ module Purplelight
     def rotate_if_needed
       return if @rotate_bytes.nil?
       return if @bytes_written < @rotate_bytes
+
       rotate!
     end
 
     def close
       return if @closed
+
       if @io
         finalize_current_part!
         @io.close
@@ -70,6 +73,7 @@ module Purplelight
 
     def ensure_open!
       return if @io
+
       FileUtils.mkdir_p(@directory)
       path = next_part_path
       @part_index = @manifest&.open_part!(path) if @manifest
@@ -85,17 +89,17 @@ module Purplelight
         if defined?(ZSTDS)
           # ZSTDS::Writer supports IO-like interface
           level = @compression_level || 3
-          return ZSTDS::Writer.open(raw, level: level)
+          ZSTDS::Writer.open(raw, level: level)
         else
-          @logger&.warn("zstd gem not loaded; this should have been handled earlier")
+          @logger&.warn('zstd gem not loaded; this should have been handled earlier')
           level = @compression_level || Zlib::DEFAULT_COMPRESSION
-          return Zlib::GzipWriter.new(raw, level)
+          Zlib::GzipWriter.new(raw, level)
         end
       when 'gzip'
         level = @compression_level || 1
-        return Zlib::GzipWriter.new(raw, level)
+        Zlib::GzipWriter.new(raw, level)
       when 'none'
-        return raw
+        raw
       else
         raise ArgumentError, "unknown compression: #{@compression}"
       end
@@ -109,6 +113,7 @@ module Purplelight
 
     def rotate!
       return unless @io
+
       finalize_current_part!
       @io.close
       @io = nil
@@ -124,25 +129,21 @@ module Purplelight
 
     def next_part_path
       ext = 'jsonl'
-      filename = format("%s-part-%06d.%s", @prefix, @file_seq, ext)
-      filename += ".zst" if @effective_compression.to_s == 'zstd'
-      filename += ".gz" if @effective_compression.to_s == 'gzip'
+      filename = format('%<prefix>s-part-%<seq>06d.%<ext>s', prefix: @prefix, seq: @file_seq, ext: ext)
+      filename += '.zst' if @effective_compression.to_s == 'zstd'
+      filename += '.gz' if @effective_compression.to_s == 'gzip'
       File.join(@directory, filename)
     end
 
     def determine_effective_compression(requested)
       case requested.to_s
       when 'zstd'
-        return (defined?(ZSTDS) ? :zstd : :gzip)
-      when 'gzip'
-        return :gzip
+        (defined?(ZSTDS) ? :zstd : :gzip)
       when 'none'
-        return :none
+        :none
       else
-        return :gzip
+        :gzip
       end
     end
   end
 end
-
-

data/lib/purplelight/writer_parquet.rb

@@ -10,10 +10,12 @@ end
 require 'fileutils'
 
 module Purplelight
+  # WriterParquet writes Parquet files via Apache Arrow when available.
   class WriterParquet
     DEFAULT_ROW_GROUP_SIZE = 10_000
 
-    def initialize(directory:, prefix:, compression: :zstd, row_group_size: DEFAULT_ROW_GROUP_SIZE, logger: nil, manifest: nil, single_file: true, schema: nil)
+    def initialize(directory:, prefix:, compression: :zstd, row_group_size: DEFAULT_ROW_GROUP_SIZE, logger: nil,
+                   manifest: nil, single_file: true, schema: nil)
       @directory = directory
       @prefix = prefix
       @compression = compression
@@ -39,8 +41,9 @@ module Purplelight
 
     def close
       return if @closed
+
       ensure_open!
-      if !@buffer_docs.empty?
+      unless @buffer_docs.empty?
         table = build_table(@buffer_docs)
         write_table(table, @writer_path, append: false)
       end
@@ -51,9 +54,9 @@ module Purplelight
     private
 
     def ensure_dependencies!
-      unless defined?(Arrow) && defined?(Parquet)
-        raise ArgumentError, "Parquet support requires gems: red-arrow and red-parquet. Add them to your Gemfile."
-      end
+      return if defined?(Arrow) && defined?(Parquet)
+
+      raise ArgumentError, 'Parquet support requires gems: red-arrow and red-parquet. Add them to your Gemfile.'
     end
 
     def reset_buffers
@@ -64,6 +67,7 @@ module Purplelight
 
     def ensure_open!
       return if @writer_path
+
       FileUtils.mkdir_p(@directory)
       @writer_path = next_part_path
       @part_index = @manifest&.open_part!(@writer_path) if @manifest
@@ -82,7 +86,7 @@ module Purplelight
       Arrow::Table.new(columns)
     end
 
-    def write_table(table, path, append: false)
+    def write_table(table, path, append: false) # rubocop:disable Lint/UnusedMethodArgument
       # Prefer Arrow's save with explicit parquet format; compression defaults per build.
       if table.respond_to?(:save)
         table.save(path, format: :parquet)
@@ -95,7 +99,7 @@ module Purplelight
         writer.close
         return
       end
-      raise "Parquet writer not available in this environment"
+      raise 'Parquet writer not available in this environment'
     end
 
     def finalize_current_part!
@@ -107,9 +111,9 @@ module Purplelight
     def next_part_path
       ext = 'parquet'
       filename = if @single_file
-                   format("%s.%s", @prefix, ext)
+                   format('%<prefix>s.%<ext>s', prefix: @prefix, ext: ext)
                  else
-                   format("%s-part-%06d.%s", @prefix, @file_seq, ext)
+                   format('%<prefix}s-part-%<seq>06d.%<ext>s', prefix: @prefix, seq: @file_seq, ext: ext)
                  end
       File.join(@directory, filename)
     end
@@ -117,21 +121,13 @@ module Purplelight
     def infer_columns(docs)
       keys = {}
       docs.each do |d|
-        d.keys.each { |k| keys[k.to_s] = true }
+        d.each_key { |k| keys[k.to_s] = true }
       end
       keys.keys.sort
     end
 
     def extract_value(doc, key)
-      val = doc[key] || doc[key.to_sym]
-      case val
-      when Time
-        val
-      else
-        val
-      end
+      doc[key] || doc[key.to_sym]
     end
   end
 end
-
-

data/lib/purplelight.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
-require_relative "purplelight/version"
-require_relative "purplelight/errors"
-require_relative "purplelight/manifest"
-require_relative "purplelight/snapshot"
+require_relative 'purplelight/version'
+require_relative 'purplelight/errors'
+require_relative 'purplelight/manifest'
+require_relative 'purplelight/snapshot'
 
+# Purplelight is a lightweight toolkit for extracting and snapshotting data.
+#
+# The top-level module exposes a convenience API entrypoint via `.snapshot`.
+# See `Purplelight::Snapshot` for supported options and formats.
 module Purplelight
   # Convenience top-level API.
   # See Purplelight::Snapshot for options.
-  def self.snapshot(**options)
-    Snapshot.snapshot(**options)
+  def self.snapshot(...)
+    Snapshot.snapshot(...)
   end
 end
-
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purplelight
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Alexander Nicholson
@@ -9,34 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: mongo
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.19'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.19'
-- !ruby/object:Gem::Dependency
-  name: oj
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.16'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.16'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -66,33 +38,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.6'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: mongo
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.12'
-  type: :development
+        version: '2.19'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: '2.19'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: oj
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
+        version: '3.16'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '3.16'
 description: High-throughput, resumable snapshots of MongoDB collections with partitioning,
   multi-threaded readers, and size-based sharded outputs.
 email:
@@ -118,6 +90,7 @@ files:
 licenses:
 - MIT
 metadata:
+  rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/alexandernicholson/purplelight
   source_code_uri: https://github.com/alexandernicholson/purplelight
   changelog_uri: https://github.com/alexandernicholson/purplelight/releases