csb 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f3c40d4cda232b9b624e8a27b5caba77c8c93d960d1aac52c01b3929948bf27
-  data.tar.gz: 8609d2baf77aec7cc54fd82952a5450614148b23300d8522ec906e815f814bb6
+  metadata.gz: dd0789e534f43fca7c3b34921ca5aa2c151a8385237a4f1509222a3bcf76852f
+  data.tar.gz: cce9f025f3fdaba91ea2e201585ac914d81191d99100eb971ba4266dd8e46111
 SHA512:
-  metadata.gz: bbc1bc6aef832923ad36d2ebb8b3a91d7d2cf4eaff9df7d8ab661710dc454ed7a3a9aa6f50c78d702d4ca0ffdd6ce1acc3ea3eb98590efeb2bdaf72f847b0fd6
-  data.tar.gz: '0933b426a58a65747c58a6069104bc7d40fa02b2c900a748588c5d33d1a407fd4cf4e4af53a6b25ed8c74b8e0bfe44dad92ecdcda4c076bbd4339028525c79fc'
+  metadata.gz: 160a693da16312599fe0f905be34c5086e5a54dc85234ac46fe5e758dd505d550830048aa98f3b9c31d0bd99d5827fd2affe1db8cd3a6cfa859f3d93fdca37f9
+  data.tar.gz: d9d703f251f3c29009c94002af15fcd6a0a6df80e268d241d9227c6ca8ef1e7a25f77a954e8c42a4fc26ecc91c2a199755aa552b178fd10384d2843503186e3c

data/.github/workflows/rspec.yml

@@ -16,14 +16,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ["3.1", "3.2", "3.3", "3.4"]
-        gemfile: ["rails71", "rails72", "rails80"]
-        exclude:
-          # rails 8.0: support ruby 3.2+
-          - ruby: "3.1"
-            gemfile: "rails80"
+        ruby: ["3.3", "3.4", "4.0"]
+        gemfile: ["rails72", "rails80", "rails81"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# Changelog
+
+For changelogs from version 0.13.0 onwards, please see the [GitHub Releases page](https://github.com/aki77/csb/releases).
+
 ## 0.12.0
 
 - Drop support for Rails versions below 7.1.4

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

@@ -13,21 +13,24 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/aki77/csb"
   spec.license       = "MIT"
 
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/aki77/csb"
+  spec.metadata["changelog_uri"] = "https://github.com/aki77/csb/releases"
+
   # 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 "bundler", "~> 2.0"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "ostruct"

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

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

data/lib/csb/railtie.rb

@@ -1,4 +1,4 @@
-require 'rails/railtie'
+require 'rails'
 
 module Csb
   class Railtie < Rails::Railtie

data/lib/csb/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: csb
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - aki77
 bindir: exe
 cert_chain: []
-date: 2025-07-04 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
@@ -37,20 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -112,9 +98,9 @@ files:
 - bin/console
 - bin/setup
 - csb.gemspec
-- gemfiles/rails71.gemfile
 - gemfiles/rails72.gemfile
 - gemfiles/rails80.gemfile
+- gemfiles/rails81.gemfile
 - lib/csb.rb
 - lib/csb/builder.rb
 - lib/csb/col.rb
@@ -128,7 +114,10 @@ files:
 homepage: https://github.com/aki77/csb
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/aki77/csb
+  source_code_uri: https://github.com/aki77/csb
+  changelog_uri: https://github.com/aki77/csb/releases
 rdoc_options: []
 require_paths:
 - lib
@@ -136,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: '../'