philiprehberger-csv_kit 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a31a3bf217dace4e2ec6ba7214191c13a4c6123112f660b59faa3bf5819c1ea9
-  data.tar.gz: e1f0a82cd1f02cae5b80c9cd78426b7fec741facd8504f15fa02922c8dd4c489
+  metadata.gz: 7a49695d1e89645d30e0d325f7c7967db04b044f0cfe69ecf66cabfcc7e28470
+  data.tar.gz: 8a0cd35cd652e1893493ac4a0428251517c4a234cc0dca7b1addc9580b3688c6
 SHA512:
-  metadata.gz: cbe2e1d0ef8ae1294e0fa4d4b51ddf4b614afb3cc2b2b943af7d51969f87f181faf60961da29b2661096865f67ddde39245a617adb6c6f25f130a85cf625ad7b
-  data.tar.gz: e519bc86bf1a6c6d35ff992e32dd41f6ab7ca89fbcaf2a9eac24e3dac3a9848cbe9b0ceac337ef9fb9cb1a2b2684aa2d5ac4a58d8e61eed642a63accdb14fd67
+  metadata.gz: 528761ab2269e586d1d01c20885b5113dd12fe89b94b266b4bcb7452224cedd19a626100218d77def4db8b4d087117717dd3a6738aa5fe54c4c05f20b7592b5c
+  data.tar.gz: 2838f1cb2c0bb9caa43015b2f8f07e3b6252f80d4ad376160619d2c3dc50c4f1fecb65d6d5c47f9e86ffa2537e6b9ace01623a266aa2bc9cfd0fd4c0e9977512

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-15
+
+### Added
+- `CsvKit.find(path, &block)` — return the first row matching a predicate, stopping as soon as a match is found
+
+## [0.5.0] - 2026-04-09
+
+### Added
+- `CsvKit.each_hash(path, dialect:)` for streaming row-by-row iteration with constant memory; returns Enumerator if no block given
+- `Row` now includes `Enumerable` with `keys`, `values`, `size`, `each`, and `merge` methods
+
 ## [0.4.0] - 2026-04-09
 
 ### Added
@@ -84,3 +95,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Auto-detect delimiter
 - Type coercion and row validation
 - Quick load and filtering convenience methods
+
+[0.5.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.5.0
+[0.4.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.4.0
+[0.3.1]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.3.1
+[0.3.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.3.0
+[0.2.6]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.6
+[0.2.5]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.5
+[0.2.4]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.4
+[0.2.3]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.3
+[0.2.2]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.2
+[0.2.1]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.1
+[0.2.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.2.0
+[0.1.2]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.1.2
+[0.1.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.1.0

data/README.md

@@ -54,6 +54,30 @@ Philiprehberger::CsvKit.count("data.csv")
 # => 1000
 ```
 
+### Streaming Row-by-Row
+
+Iterate rows with constant memory. Returns an `Enumerator` if no block is given:
+
+```ruby
+Philiprehberger::CsvKit.each_hash("large.csv") do |row|
+  puts row[:name]
+end
+
+# Or compose with Enumerator methods:
+adults = Philiprehberger::CsvKit.each_hash("data.csv")
+  .select { |r| r[:age].to_i >= 18 }
+  .first(10)
+```
+
+### Find First Match
+
+Return the first row that matches a predicate, streaming and stopping on the first hit:
+
+```ruby
+user = Philiprehberger::CsvKit.find("users.csv") { |row| row[:email] == "a@b.com" }
+# => {email: "a@b.com", name: "Alice"} or nil
+```
+
 ### Filter Rows
 
 ```ruby
@@ -153,8 +177,10 @@ delimiter = Philiprehberger::CsvKit::Detector.detect("data.tsv")
 | `CsvKit.to_hashes(path, dialect:)` | Load CSV into array of symbolized hashes |
 | `CsvKit.pluck(path, *keys, dialect:)` | Extract specific columns |
 | `CsvKit.filter(path, dialect:, &block)` | Filter rows, return CSV string |
+| `CsvKit.find(path, dialect:, &block)` | Return the first row matching the predicate, or nil |
 | `CsvKit.headers(path, dialect:)` | Return header row as array of symbols |
 | `CsvKit.count(path, dialect:)` | Count data rows without loading into memory |
+| `CsvKit.each_hash(path, dialect:, &block)` | Stream rows as symbolized hashes; returns Enumerator if no block |
 | `CsvKit.process(path_or_io, dialect:, &block)` | Streaming DSL with transforms and validations |
 | `Processor#headers(*names)` | Override header names |
 | `Processor#transform(key, &block)` | Register column transform |
@@ -176,6 +202,11 @@ delimiter = Philiprehberger::CsvKit::Detector.detect("data.tsv")
 | `Dialect.new(name_or_hash)` | Create a dialect from preset or custom hash |
 | `Detector.detect(path_or_io)` | Auto-detect CSV delimiter |
 | `Row#[](key)` | Access value by symbol key |
+| `Row#keys` | Column names as array of symbols |
+| `Row#values` | Column values as array |
+| `Row#size` | Number of columns |
+| `Row#each { \|k, v\| }` | Iterate key-value pairs (Enumerable) |
+| `Row#merge(other)` | Return new Row with merged data |
 | `Row#to_h` | Convert row to plain hash |
 
 ## Development

data/lib/philiprehberger/csv_kit/row.rb

@@ -4,11 +4,50 @@ module Philiprehberger
   module CsvKit
     # Wraps a CSV row as a hash with symbolized keys.
     class Row
+      include Enumerable
+
       # @param data [Hash{Symbol => String}]
       def initialize(data)
         @data = data
       end
 
+      # Iterate over key-value pairs.
+      #
+      # @yield [Symbol, Object] key and value
+      def each(&)
+        @data.each(&)
+      end
+
+      # Return column names.
+      #
+      # @return [Array<Symbol>]
+      def keys
+        @data.keys
+      end
+
+      # Return column values.
+      #
+      # @return [Array<Object>]
+      def values
+        @data.values
+      end
+
+      # Return the number of columns.
+      #
+      # @return [Integer]
+      def size
+        @data.size
+      end
+
+      # Merge another hash or Row into this row, returning a new Row.
+      #
+      # @param other [Hash, Row] data to merge
+      # @return [Row]
+      def merge(other)
+        other_data = other.is_a?(Row) ? other.to_h : other
+        Row.new(@data.merge(other_data))
+      end
+
       # Access a value by symbolized key.
       #
       # @param key [Symbol] column name

data/lib/philiprehberger/csv_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CsvKit
-    VERSION = '0.4.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/philiprehberger/csv_kit.rb

@@ -80,6 +80,42 @@ module Philiprehberger
       n
     end
 
+    # Stream rows one at a time as symbolized hashes with constant memory.
+    # Returns an Enumerator if no block is given.
+    #
+    # @param path [String] file path
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
+    # @yield [Hash{Symbol => String}] each row
+    # @return [Enumerator, nil]
+    def self.each_hash(path, dialect: nil, &block)
+      csv_opts = { headers: true }
+      csv_opts = Dialect.new(dialect).merge_into(csv_opts) if dialect
+
+      enum = Enumerator.new do |yielder|
+        CSV.foreach(path, **csv_opts) do |row|
+          yielder.yield(row.to_h.transform_keys(&:to_sym))
+        end
+      end
+
+      block ? enum.each(&block) : enum
+    end
+
+    # Find the first row matching a predicate, streaming (stops as soon as a match is found).
+    #
+    # @param path [String] file path
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
+    # @yield [Hash{Symbol => String}] each row as a symbolized hash
+    # @return [Hash{Symbol => String}, nil] the first matching row or nil
+    def self.find(path, dialect: nil, &block)
+      csv_opts = { headers: true }
+      csv_opts = Dialect.new(dialect).merge_into(csv_opts) if dialect
+      CSV.foreach(path, **csv_opts) do |row|
+        hash = row.to_h.transform_keys(&:to_sym)
+        return hash if block.call(hash)
+      end
+      nil
+    end
+
     # Filter rows and return matching rows as a CSV string.
     #
     # @param path [String] file path

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_kit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-10 00:00:00.000000000 Z
+date: 2026-04-15 00:00:00.000000000 Z
 dependencies: []
 description: Streaming CSV processor with row-by-row transforms, validations, column
-  plucking, filtering, writing, error recovery, and automatic delimiter detection.
+  plucking, streaming each_hash iteration, filtering, writing, error recovery, and
+  automatic delimiter detection.
 email:
 - me@philiprehberger.com
 executables: []