csb 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cad937e169f1330223f51cefcd7c636c8132eee9223ea86c99e465bde7140e14
-  data.tar.gz: 529f7c0fdbd85a7ed4332587ae09cc1ef45730f5a6819f6b389da048219fc446
+  metadata.gz: dd0789e534f43fca7c3b34921ca5aa2c151a8385237a4f1509222a3bcf76852f
+  data.tar.gz: cce9f025f3fdaba91ea2e201585ac914d81191d99100eb971ba4266dd8e46111
 SHA512:
-  metadata.gz: 765f40840055d26afbca395312836480017ad08679d96fe295f6cf088a62ab1e09d019fbff41e2200cc9d6364beaef59ba26688f5290249787b83e9311f1e6bd
-  data.tar.gz: 07535155a1c0788a148b5fc8faadd7b03e76a661b134c5c47ecc5b2283e980ffc50ff0d4e5dbcf4fc19ae25bb5abcefbbd217484ff1da26d7f760e416ea6482e
+  metadata.gz: 160a693da16312599fe0f905be34c5086e5a54dc85234ac46fe5e758dd505d550830048aa98f3b9c31d0bd99d5827fd2affe1db8cd3a6cfa859f3d93fdca37f9
+  data.tar.gz: d9d703f251f3c29009c94002af15fcd6a0a6df80e268d241d9227c6ca8ef1e7a25f77a954e8c42a4fc26ecc91c2a199755aa552b178fd10384d2843503186e3c

data/.github/workflows/rspec.yml

@@ -16,15 +16,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ["3.1", "3.2", "3.3", "3.4", "4.0"]
-        gemfile: ["rails71", "rails72", "rails80", "rails81"]
-        exclude:
-          # rails 8.0: support ruby 3.2+
-          - ruby: "3.1"
-            gemfile: "rails80"
-          # rails 8.1: support ruby 3.2+
-          - ruby: "3.1"
-            gemfile: "rails81"
+        ruby: ["3.3", "3.4", "4.0"]
+        gemfile: ["rails72", "rails80", "rails81"]
     steps:
       - uses: actions/checkout@v6
 

data/README.md

@@ -3,20 +3,39 @@
 
 # Csb
 
-A simple and streaming support CSV template engine for Ruby on Rails.
+A simple, streaming CSV template engine for Ruby on Rails. (The name is short for **CSV builder**.)
 
-## Features
+## Why csb?
 
-- Support for streaming downloads
-- Output in UTF-8 with BOM
-- Readable code
-- High testability
+Writing CSV downloads in Rails by hand looks easy, but the naive approach has recurring problems:
+
+```ruby
+# app/views/posts/index.csv.erb (the typical hand-written version)
+CSV.generate do |csv|
+  csv << %w[Date Category Title Content]
+  @posts.each do |post|
+    csv << [l(post.created_at.to_date), post.category.name, post.title, post.content]
+  end
+end
+```
+
+- **Garbled in Excel** — UTF-8 without a BOM shows up as mojibake.
+- **Memory / timeout errors** — loading and building the whole CSV in memory breaks on large datasets.
+- **Hard to maintain** — headers and values are defined far apart, so adding columns hurts readability.
+- **Hard to test** — the export logic is buried in a view, leaving you stuck with slow system tests.
+
+csb solves each of these:
+
+- **Excel-friendly** — output UTF-8 with a BOM so Excel opens it without garbling.
+- **Streaming download** — stream row by row to handle hundreds of thousands of records without memory or timeout errors.
+- **Readable** — define each column's header and value together on one line.
+- **Testable** — extract column definitions into a model and unit-test them directly.
 
 ## Usage
 
 ### Template handler
 
-In app/controllers/reports_controller.rb:
+In `app/controllers/reports_controller.rb`:
 
 ```ruby
 def index
@@ -24,61 +43,66 @@ def index
 end
 ```
 
-In app/views/reports/index.csv.csb:
+In `app/views/reports/index.csv.csb`:
 
 ```ruby
 csv.items = @reports
 
-# When there are many records
+# For large datasets, pass an Enumerator so streaming starts immediately
+# instead of waiting for every record to load:
 # csv.items = @reports.find_each
 
-# When there are many records with decorator
+# Combine with a decorator (e.g. Draper) while keeping it lazy:
 # csv.items = @reports.find_each.lazy.map(&:decorate)
 
+# Optional per-view overrides:
 # csv.filename = "reports_#{Time.current.to_i}.csv"
 # csv.streaming = false
 # csv.csv_options = { col_sep: "\t" }
 
-csv.cols.add('Update date') { |r| l(r.updated_at.to_date) }
+csv.cols.add('Update date') { |r| l(r.updated_at.to_date) } # block receives the record
 csv.cols.add('Categories') { |r| r.categories.pluck(:name).join(' ') }
-csv.cols.add('Content', :content)
-csv.cols.add('Empty')
-csv.cols.add('Static', 'dummy')
+csv.cols.add('Content', :content) # a Symbol calls the method on the record
+csv.cols.add('Static', 'dummy')   # a String is output verbatim
+csv.cols.add('Empty')             # no value -> empty column
+csv.cols.add('Dup', :col1)        # the same header may be added more than once
+csv.cols.add('Dup', :col2)        # (columns are output in definition order)
 ```
 
 Output:
 
 ```csv
-Update date,Categories,Content,Empty,Static
-2019/06/01,category1 category2,content1,,dummy
-2019/06/02,category3,content2,,dummy
+Update date,Categories,Content,Static,Empty,Dup,Dup
+2019/06/01,category1 category2,content1,dummy,,a,b
+2019/06/02,category3,content2,dummy,,c,d
 ```
 
+A link such as `link_to 'Download CSV', reports_path(format: :csv)` triggers the streaming download automatically.
+
 ### Directly
 
+When you want to generate the CSV outside of a request (e.g. in a background job), use `Csb::Builder`:
+
 ```ruby
 csv = Csb::Builder.new(items: items)
 csv.cols.add('Update date') { |r| l(r.updated_at.to_date) }
 csv.cols.add('Categories') { |r| r.categories.pluck(:name).join(' ') }
 csv.cols.add('Content', :content)
-csv.cols.add('Empty')
-csv.cols.add('Static', 'dummy')
-csv.build
-
-# =>
-# Update date,Categories,Content,Empty,Static
-# 2019/06/01,category1 category2,content1,,dummy
-# 2019/06/02,category3,content2,,dummy
+csv.build # => returns the CSV string
+
+# File.write('reports.csv', csv.build)
 ```
 
 ### Testing
 
+Move the column definitions out of the view so you can unit-test them:
+
 ```ruby
-# Your view
+# app/views/articles/index.csv.csb
 csv.items = @articles
 csv.cols = Article.csb_cols
 
-# Your Model
+# app/models/article.rb
 def self.csb_cols
   Csb::Cols.new do |cols|
     cols.add('Update date') { |r| I18n.l(r.updated_at.to_date) }
@@ -86,16 +110,20 @@ def self.csb_cols
     cols.add('Title', :title)
   end
 end
+```
 
-# Your test
-require 'csb/testing'
+```ruby
+# spec/models/article_spec.rb
+require 'csb/testing' # adds col_pairs and as_table
 
+# Assert a single record, row by row:
 expect(Article.csb_cols.col_pairs(article)).to eq [
   ['Update date', '2020-01-01'],
   ['Categories', 'test rspec'],
   ['Title', 'Testing'],
 ]
 
+# Assert the whole table (header row + value rows):
 expect(Article.csb_cols.as_table(articles)).to eq [
   ['Update date', 'Categories', 'Title'],
   ['2020-01-01', 'test rspec', 'Testing'],
@@ -132,10 +160,17 @@ Csb.configure do |config|
   config.utf8_bom = true # default: false
   config.streaming = false # default: true
   config.csv_options = { col_sep: "\t" } # default: {}
+
+  # Called when an error is raised during streaming. Without this, errors that
+  # happen mid-stream are not reported even if you use a tool like Bugsnag.
   config.after_streaming_error = ->(error) do # default: nil
     Rails.logger.error(error)
     Bugsnag.notify(error)
   end
+
+  # Error classes to ignore (not re-raise) during streaming, e.g. when the
+  # client disconnects before the download finishes.
+  config.ignore_class_names = %w[Puma::ConnectionError] # default: %w[Puma::ConnectionError]
 end
 ```
 

data/csb.gemspec

@@ -20,15 +20,15 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|\.claude)/}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = '>= 3.1.0'
+  spec.required_ruby_version = '>= 3.3.0'
 
-  spec.add_dependency "rails", ">= 7.1.4"
+  spec.add_dependency "rails", ">= 7.2.0"
   spec.add_dependency "csv"
 
   spec.add_development_dependency "rake"

data/gemfiles/rails72.gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem 'rails', '~> 7.2.0'
 

data/gemfiles/rails80.gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem 'rails', '~> 8.0.0'
 

data/gemfiles/rails81.gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem 'rails', '~> 8.1.0'
 

data/lib/csb/version.rb

@@ -1,3 +1,3 @@
 module Csb
-  VERSION = '0.15.0'
+  VERSION = '0.16.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: csb
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - aki77
 bindir: exe
 cert_chain: []
-date: 2026-01-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.1.4
+        version: 7.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.1.4
+        version: 7.2.0
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -98,7 +98,6 @@ files:
 - bin/console
 - bin/setup
 - csb.gemspec
-- gemfiles/rails71.gemfile
 - gemfiles/rails72.gemfile
 - gemfiles/rails80.gemfile
 - gemfiles/rails81.gemfile
@@ -126,14 +125,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A simple and streaming support CSV template engine for Ruby on Rails.
 test_files: []

data/gemfiles/rails71.gemfile

@@ -1,5 +0,0 @@
-source "http://rubygems.org"
-
-gem 'rails', '~> 7.1.4'
-
-gemspec path: '../'