philiprehberger-csv_builder 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbaf1a09bda94dd3fff6302860abacf5ad60eb1376520f145f984da9ec8fb7b1
-  data.tar.gz: 625b0af93c07cc624d51a2aed8239c5bebd465981bea6cdc7b9ef91433a2c645
+  metadata.gz: 9a4ffc869b5a686e7e0d33b193f309354328b4ea6aa12bd5421ff1d906aa8cce
+  data.tar.gz: 74f124f09a30ff6fd71f7caaaf13364c2bf63032adf8bf03b5d61dc1cf328caa
 SHA512:
-  metadata.gz: 562365a1e93a6d9386a31630011021186ecf45029f6764e05fa594ccd872dcbe0a932477897c469dade5a95a2ca02d0d9c7f2a656b48210ff5d4c71c6d7ff9cf
-  data.tar.gz: 7805ee034ea1c75bf1e8ccbea4854d1bbaab80ddbc0def7b7ba30b0be301280bfec22d8b9450e34da4e43fb9943b627c0a11a1397cd9fe5c1b04ded3a441f843
+  metadata.gz: fa82a727dacd0a8047b60a431045eeb40a99331346d96e5e2f9025137fbf83bce1ccbfb92e5bd502331943311e2543d6e7eb68d527ee61a9cc7bb79e9dbe8e36
+  data.tar.gz: 753166a7741b788a23133861c93d09441b7c8852b62bf1753d3b87565250aa017e38741c321a0388524d78885fa66a734ca112c63c27d8aba4c8c55b103ec37e

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-04-15
+
+### Added
+- `Builder#column_stats` — per-column statistics (count, unique, nil_count, sample) across filtered records
+
+## [0.8.0] - 2026-04-15
+
+### Added
+- `Builder#row_count` — number of data rows the builder will emit (applies filters, sorts, offsets, limits)
+
 ## [0.7.0] - 2026-04-15
 
 ### Added
@@ -97,6 +107,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for hash records with symbol and string keys
 - Proper CSV escaping for values with commas and quotes
 
+[0.9.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.9.0
+[0.8.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.8.0
 [0.7.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.7.0
 [0.6.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.6.0
 [0.5.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.5.0

data/README.md

@@ -294,6 +294,20 @@ builder = Philiprehberger::CsvBuilder.build(records, encoding: 'ISO-8859-1') do
 end
 ```
 
+### Row Count
+
+Get the number of rows that will be emitted (respects filters, sorts, offsets, and limits) without building the CSV:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name
+  filter { |r| r[:active] }
+  limit 50
+end
+
+builder.row_count  # => 50
+```
+
 ### Streaming
 
 ```ruby
@@ -370,6 +384,31 @@ builder.to_a
 # => [["name", "email"], ["Alice", "alice@example.com"], ["Bob", "bob@example.com"]]
 ```
 
+### Column Statistics
+
+Inspect per-column statistics without generating CSV output:
+
+```ruby
+records = [
+  { name: 'Alice', email: 'alice@example.com' },
+  { name: 'Bob', email: nil },
+  { name: 'Alice', email: 'alice@example.com' }
+]
+
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name
+  column :email
+end
+
+builder.column_stats
+# => {
+#   name:  { count: 3, unique: 2, nil_count: 0, sample: ["Alice", "Bob"] },
+#   email: { count: 3, unique: 1, nil_count: 1, sample: ["alice@example.com"] }
+# }
+```
+
+Statistics respect filters, limits, and offsets. The `nil_count` includes both `nil` values and values matching the configured `empty_value`.
+
 ### Headers
 
 ```ruby
@@ -406,6 +445,8 @@ builder.headers  # => ["name", "email"]
 | `Builder#append_to(path)` | Append data rows (no header, no BOM) to an existing CSV file |
 | `Builder#to_io(io)` | Stream CSV to any IO object |
 | `Builder#headers` | Return column header names |
+| `Builder#column_stats` | Per-column statistics: count, unique, nil_count, and sample values |
+| `Builder#row_count` | Number of data rows after filters, sorts, offsets, and limits |
 
 ## Development
 

data/lib/philiprehberger/csv_builder/builder.rb

@@ -166,6 +166,33 @@ module Philiprehberger
         @row_number_header ? [@row_number_header] + base : base
       end
 
+      # Number of data rows the builder will emit (headers and footer excluded).
+      # Applies all configured filters, sorts, offsets, and limits.
+      #
+      # @return [Integer]
+      def row_count
+        filtered_records.size
+      end
+
+      # Per-column statistics across filtered records.
+      #
+      # @return [Hash{Symbol => Hash}] column name mapped to stats hash
+      #   with keys :count, :unique, :nil_count, :sample
+      def column_stats
+        recs = filtered_records
+        @columns.to_h do |col|
+          values = recs.map { |r| col.extract(r, empty_value: @empty_value) }
+          nil_count = values.count { |v| v.nil? || v == @empty_value }
+          unique_values = values.reject { |v| v.nil? || v == @empty_value }.uniq
+          [col.name, {
+            count: values.size,
+            unique: unique_values.size,
+            nil_count: nil_count,
+            sample: unique_values.first(3)
+          }]
+        end
+      end
+
       # Return the filtered records
       #
       # @return [Array]

data/lib/philiprehberger/csv_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CsvBuilder
-    VERSION = '0.7.0'
+    VERSION = '0.9.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_builder
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies: []
 description: Build CSV files from record collections using a declarative DSL with
   column definitions, custom transforms, filtering, sorting, pagination via limit/offset,