xlsxrb 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 305368e1e5925e21411db3a34effb2aa2fb59328bf0aca626762657a7c2291c4
-  data.tar.gz: 6878a769b5ac0aca48a301f7cfbc632f263ff4befb96157c16f4f58bc1ef627e
+  metadata.gz: b1be4d5d307820e8ed44e46d2a990e069501f413cace5e4920f61c6c43f964ff
+  data.tar.gz: 22df70618c1f06ccc7bdcd3e4a1d0529bc6385f122f9563e29370ef13e16dcf1
 SHA512:
-  metadata.gz: a3b70b346fc5481c3242b45ada1135e0a13da6cbf9fd7db2f3a8f084c5560041a0f4187b2b8142da93fd88f12b769f50f6dd4abe75612c6b1fdb0856604721d8
-  data.tar.gz: 5e18aa8c063522115e1320c74d550402cd9020088239b4d3061de2736a50dcab42487e20f1cb7d1e291f8fe31461251ca62703b299d2bb41d83ad1d1c03c79c6
+  metadata.gz: 80cd57b81f5649d930e873b354f2b587a05c19557ff2906ffc85aadd630d38db5487ba1bfda4a4588658c2902343658aac09c3cfbd59e3550d35be45187ae80d
+  data.tar.gz: 474385c247bed4e3b35182f7e3ecb4949d2eb5fa4adaea91b221179103cc1dc278ccd041b50cffd3dd3c3e31572e29e816f7a03ac99580f30096d0cebdd18290

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 ## [Unreleased]
 - No unreleased changes.
 
+## [0.1.8] - 2026-08-18
+
+### Changed
+- **Unified Symmetric Entrypoints**: Consolidated reading into `Xlsxrb.read` (supporting file path, IO, and raw binary string) and writing into `Xlsxrb.write` (supporting streaming blocks or in-memory Workbooks). Removed legacy `open`, `foreach`, and `generate` methods.
+- **Streaming-First Defaults**: `Xlsxrb.read` yields and returns lightweight `StreamSheet` instances with $O(1)$ constant-memory consumption by default.
+- **Explicit In-Memory Materialization (`#load`)**: Stripped accidental random-access memory traps from `StreamSheet`; introduced explicit `StreamSheet#load` / `Workbook#load` (inspired by ActiveRecord Relations) to transition from lazy streaming to in-memory `Elements::Worksheet` / `Elements::Workbook`.
+- **`CoordinateAccess` Module**: Extracted coordinate lookup methods (`[]`, `cell_value`, `row_at`, `first_row`, `last_row`, `cells`, `cells_hash`) into a dedicated `Xlsxrb::Elements::CoordinateAccess` mixin module included in `Elements::Worksheet`.
+
+### Added
+- **Default Cell Streaming (`Xlsxrb::StreamRow`)**: Enabled streaming along both row and cell dimensions via `row.each_cell` and `sheet.each_cell`, parsing cells on-demand to handle sheets with thousands of columns in $O(1)$ constant memory.
+
 ## [0.1.7] - 2026-08-16
 
 ### Added

data/README.md

@@ -6,16 +6,18 @@ A Ruby library for reading and writing XLSX files with streaming support.
 
 The Ruby ecosystem already has great XLSX libraries. Each is well-designed for its purpose:
 
-| Library                                            | Read | Write | Model                 | Write String Storage | Rich Formatting |
-| -------------------------------------------------- | ---- | ----- | --------------------- | -------------------- | --------------- |
-| [roo](https://rubygems.org/gems/roo)               | ✅   | ❌    | Streaming             | N/A (Read-only)      | ⚠️ (Formulas, Basic styles) |
-| [creek](https://rubygems.org/gems/creek)           | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Raw cell values) |
-| [xsv](https://rubygems.org/gems/xsv)               | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Fast plain text) |
-| [caxlsx / axlsx](https://rubygems.org/gems/caxlsx) | ❌   | ✅    | In-Memory             | Inline (opt: SST)    | ✅ (Charts, Styles) |
-| [xlsxtream](https://rubygems.org/gems/xlsxtream)   | ❌   | ✅    | Streaming             | Inline (opt: SST)    | ❌ (Plain data only) |
-| [fast_excel](https://rubygems.org/gems/fast_excel) | ❌   | ✅    | Streaming (C Ext)     | SST (opt: Inline)    | ⚠️ (Basic styles) |
-| [rubyXL](https://rubygems.org/gems/rubyXL)         | ✅   | ✅    | In-Memory             | Inline / Direct      | ✅ (DOM editing) |
-| **[xlsxrb](https://github.com/niku/xlsxrb)**       | ✅   | ✅    | **Streaming / In-Memory** | **SST**          | ✅ **(Full Features)** |
+| Library                                                    | Read | Write | Model                 | Write String Storage | Rich Formatting |
+| ---------------------------------------------------------- | ---- | ----- | --------------------- | -------------------- | --------------- |
+| [roo](https://rubygems.org/gems/roo)                       | ✅   | ❌    | Streaming             | N/A (Read-only)      | ⚠️ (Formulas, Basic styles) |
+| [creek](https://rubygems.org/gems/creek)                   | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Raw cell values) |
+| [xsv](https://rubygems.org/gems/xsv)                       | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Fast plain text) |
+| [simple_xlsx_reader](https://rubygems.org/gems/simple_xlsx_reader) | ✅ | ❌ | Streaming         | N/A (Read-only)      | ❌ (Plain data & types) |
+| [caxlsx / axlsx](https://rubygems.org/gems/caxlsx)         | ❌   | ✅    | In-Memory             | Inline (opt: SST)    | ✅ (Charts, Styles) |
+| [write_xlsx](https://rubygems.org/gems/write_xlsx)         | ❌   | ✅    | In-Memory             | SST                  | ✅ (Charts, Styles) |
+| [xlsxtream](https://rubygems.org/gems/xlsxtream)           | ❌   | ✅    | Streaming             | Inline (opt: SST)    | ❌ (Plain data only) |
+| [fast_excel](https://rubygems.org/gems/fast_excel)         | ❌   | ✅    | Streaming (C Ext)     | SST (opt: Inline)    | ⚠️ (Basic styles) |
+| [rubyXL](https://rubygems.org/gems/rubyXL)                 | ✅   | ✅    | In-Memory             | Inline / Direct      | ✅ (DOM editing) |
+| **[xlsxrb](https://github.com/niku/xlsxrb)**               | ✅   | ✅    | **Streaming / In-Memory** | **SST**          | ✅ **(Full Features)** |
 
 Each of these libraries makes deliberate tradeoffs, and they do so thoughtfully:
 * **Memory & Execution Model (Streaming vs In-Memory)**: Streaming libraries write or read rows sequentially on-the-fly to maintain a constant, low-memory footprint regardless of row count. In-memory libraries build complete document object trees, offering flexible random access and cell updates at the cost of high RAM usage on large sheets.
@@ -78,12 +80,12 @@ For visual demonstrations of various features, check the [Visual Examples Galler
 ### Quick Start: Streaming (Recommended)
 
 #### Streaming Write
-Generate large files efficiently by writing data directly to the file stream:
+Generate large files efficiently with $O(1)$ constant memory by writing data directly to the stream:
 ```ruby
 require "xlsxrb"
 
-Xlsxrb.generate("large_output.xlsx") do |stream_writer|
-  stream_writer.sheet("Sales Data") do |sheet|
+Xlsxrb.write("large_output.xlsx") do |writer|
+  writer.sheet("Sales Data") do |sheet|
     sheet.row(["Date", "Amount", "Status"])
     sheet.row([Date.today, 100, true])
     sheet.column(0, width: 15.5)
@@ -92,15 +94,63 @@ end
 ```
 
 #### Streaming Read
-Read rows one at a time without loading the entire file into memory:
+Read rows and cells lazily one at a time with $O(1)$ constant memory (even for wide sheets with thousands of columns):
 ```ruby
 require "xlsxrb"
 
-Xlsxrb.foreach("large_file.xlsx") do |sheet|
+# Stream row-by-row and cell-by-cell (O(1) memory)
+Xlsxrb.read("large_file.xlsx") do |sheet|
   sheet.each_row do |row|
-    puts "Row #{row.index}: #{row.cells.map(&:value).join(', ')}"
+    row.each_cell do |cell|
+      puts "#{cell.ref}: #{cell.value}"
+    end
   end
 end
+
+# Or stream all cells across the sheet directly
+Xlsxrb.read("large_file.xlsx") do |sheet|
+  sheet.each_cell do |cell|
+    puts "#{cell.ref} = #{cell.value}"
+  end
+end
+```
+
+### Ruby-Idiomatic Core APIs
+
+`xlsxrb` provides clean, standard Ruby interfaces (`Enumerable`, `Row#to_a`, `sheet["A1"]`) that feel natural to every Ruby developer without learning complex library-specific APIs:
+
+#### Reading Spreadsheets
+```ruby
+require "xlsxrb"
+
+# 1. Read from file path, IO, or raw binary string (O(1) constant memory streaming)
+workbook = Xlsxrb.read("data.xlsx")
+sheet = workbook.sheets.first
+
+# 2. Extract sheet data into 2D array of values via standard Enumerable
+matrix = sheet.map(&:to_a) # => [["Name", "Score"], ["Alice", 100], ["Bob", 95]]
+
+# 3. Explicitly load into memory for coordinate random access (e.g. sheet["A1"])
+doc_sheet = sheet.load
+doc_sheet["A1"]         # => #<Xlsxrb::Elements::Cell value="Name" ...>
+doc_sheet["A1"].value   # => "Name"
+```
+
+#### Writing & In-Memory Export (Rails & Mailers)
+```ruby
+# Build workbook
+wb = Xlsxrb.build do |b|
+  b.sheet("Report") do |s|
+    s.row(["Metric", "Value"])
+    s.row(["Users", 1000])
+  end
+end
+
+# Save directly to file:
+Xlsxrb.write("report.xlsx", wb)
+
+# Or export to binary string (ideal for Rails send_data & ActionMailer):
+binary_data = Xlsxrb.write(wb)
 ```
 
 ### In-Memory Building & Modifying
@@ -154,8 +204,8 @@ end
 Whether you use standard descriptive block variable names (`|stream_writer|`, `|sheet|`, `|workbook|`) or short names (`|wb|`, `|s|`), your editor will automatically provide complete method suggestions and parameter hints:
 
 ```ruby
-Xlsxrb.generate("output.xlsx") do |stream_writer| # or |wb|
-  stream_writer.sheet("Data") do |sheet|           # or |s|
+Xlsxrb.write("output.xlsx") do |writer| # or |wb|
+  writer.sheet("Data") do |sheet|      # or |s|
     sheet.row(["Product", "Price"], styles: :bold)
     sheet.auto_filter("A1:B100")
   end
@@ -182,25 +232,27 @@ The following benchmarks measure the time, peak memory, and GC count required to
 
 | Library                | Model       | Write String Storage | Time (Median) | Time (Mean) | Peak Memory | GC Count |
 | ---------------------- | ----------- | -------------------- | ------------- | ----------- | ----------- | -------- |
-| xlsxtream 3.1.0        | Streaming   | Inline String        | 1.23 s        | 1.25 s      | 18.1 MB     | 1061.0   |
-| xlsxrb (Streaming)     | Streaming   | SST (Shared)         | 1.62 s        | 1.62 s      | 94.5 MB     | 39.0     |
-| fast_excel 0.5.0 (C)   | Streaming   | SST (Shared)         | 2.03 s        | 2.03 s      | 147.9 MB    | 263.0    |
-| xlsxrb (In-Memory)     | In-Memory   | SST (Shared)         | 4.06 s        | 4.06 s      | 280.3 MB    | 32.0     |
-| caxlsx 4.5.0           | In-Memory   | Inline String        | 5.36 s        | 5.35 s      | 188.7 MB    | 23.0     |
-| rubyXL 3.4.38          | In-Memory   | Inline String        | 38.02 s       | 38.03 s     | 2166.0 MB   | 104.0    |
+| xlsxtream 3.1.0        | Streaming   | Inline String        | 1.19 s        | 1.20 s      | 18.2 MB     | 1072.0   |
+| xlsxrb (Streaming)     | Streaming   | SST (Shared)         | 1.73 s        | 1.65 s      | 94.4 MB     | 39.0     |
+| fast_excel 0.5.0 (C)   | Streaming   | SST (Shared)         | 1.89 s        | 1.89 s      | 148.2 MB    | 245.0    |
+| xlsxrb (In-Memory)     | In-Memory   | SST (Shared)         | 3.84 s        | 3.83 s      | 278.3 MB    | 32.0     |
+| write_xlsx 1.15.0      | In-Memory   | SST (Shared)         | 4.32 s        | 4.34 s      | 201.2 MB    | 33.0     |
+| caxlsx 4.5.0           | In-Memory   | Inline String        | 5.15 s        | 5.12 s      | 188.6 MB    | 23.0     |
+| rubyXL 3.4.38          | In-Memory   | Inline String        | 38.81 s       | 37.82 s     | 2186.8 MB   | 103.0    |
 
-> **Note**: All libraries are evaluated in their **default, out-of-the-box configuration**. Under the same Microsoft Excel-standard Shared String Table (SST) architecture, Pure Ruby `xlsxrb` (Streaming: 1.62s, In-Memory: 4.06s) writes 1,000,000 cells faster than the C-extension `fast_excel` (2.03s) and in-memory gems like `caxlsx` (5.36s).
+> **Note**: All libraries are evaluated in their **default, out-of-the-box configuration**. Under the same Microsoft Excel-standard Shared String Table (SST) architecture, Pure Ruby `xlsxrb` (Streaming: 1.73s, In-Memory: 3.84s) writes 1,000,000 cells faster than the C-extension `fast_excel` (1.89s) and in-memory gems like `write_xlsx` (4.32s) and `caxlsx` (5.15s).
 
 ### Read Performance (1,000,000 cells)
 
-| Library                | Model       | Time (Median) | Time (Mean) | Peak Memory | GC Count |
-| ---------------------- | ----------- | ------------- | ----------- | ----------- | -------- |
-| xlsxrb (Streaming)     | Streaming   | 3.38 s        | 3.37 s      | 90.6 MB     | 40.0     |
-| xlsxrb (In-Memory)     | In-Memory   | 5.75 s        | 5.94 s      | 250.9 MB    | 55.0     |
-| creek 2.6.3            | Streaming   | 7.90 s        | 7.93 s      | 835.7 MB    | 481.0    |
-| roo 3.0.0              | Streaming   | 10.34 s       | 10.28 s     | 139.0 MB    | 107.0    |
-| xsv 1.4.1              | Streaming   | 16.39 s       | 17.28 s     | 75.4 MB     | 2215.0   |
-| rubyXL 3.4.38          | In-Memory   | 35.45 s       | 35.38 s     | 2281.3 MB   | 146.0    |
+| Library                  | Model       | Time (Median) | Time (Mean) | Peak Memory | GC Count |
+| ------------------------ | ----------- | ------------- | ----------- | ----------- | -------- |
+| xlsxrb (Streaming)       | Streaming   | 3.17 s        | 3.22 s      | 91.4 MB     | 43.0     |
+| simple_xlsx_reader 5.1.0 | Streaming   | 4.48 s        | 4.45 s      | 38.5 MB     | 1669.0   |
+| xlsxrb (In-Memory)       | In-Memory   | 5.71 s        | 5.89 s      | 224.8 MB    | 63.0     |
+| creek 2.6.3              | Streaming   | 8.14 s        | 8.02 s      | 834.6 MB    | 477.0    |
+| xsv 1.4.1                | Streaming   | 14.61 s       | 14.50 s     | 76.1 MB     | 2224.0   |
+| roo 3.0.0                | Streaming   | 15.69 s       | 13.36 s     | 119.7 MB    | 441.0    |
+| rubyXL 3.4.38            | In-Memory   | 37.13 s       | 40.35 s     | 2537.6 MB   | 146.0    |
 
 ### Running the Benchmarks Locally (Reproducibility)
 
@@ -224,7 +276,7 @@ As an extra layer of "defense in depth", `xlsxrb` configures the workbook to **n
 If you absolutely need external links to update automatically, you can explicitly override this (though **it is highly discouraged due to security risks**):
 
 ```ruby
-Xlsxrb.generate("file.xlsx") do |wb|
+Xlsxrb.write("file.xlsx") do |wb|
   # WARNING: Enabling this can expose users to malicious external reference vulnerabilities!
   wb.workbook_property(:update_links, "always") 
   # ...
@@ -237,7 +289,7 @@ To support reliability, compliance with the ECMA-376 specification, and consiste
 
 ### Multi-Tier Testing Strategy
 * **Round-Trip Testing**: Unit tests verify that every generated sheet can be reliably parsed back by the reader with identical content and styling.
-* **Contract Consistency**: Ensures semantic output consistency between the Streaming (`Xlsxrb.generate`) and In-Memory (`Xlsxrb.build`) APIs.
+* **Contract Consistency**: Ensures semantic output consistency between the Streaming (`Xlsxrb.write`) and In-Memory (`Xlsxrb.build`) APIs.
 * **Property-Based Testing (PBT)**: Automatically generates random data to catch edge cases (e.g., huge numbers, special characters) preventing unexpected crashes.
 * **Concurrency Validation**: Thread and Ractor safety checks to guarantee no global variable pollution during parallel execution.
 * **Security & DoS Protection**: Hardened against malicious files, including memory exhaustion (ZIP Bombs) and infinite parsing loops.

data/Rakefile

@@ -7,9 +7,19 @@ require "fileutils"
 require "open3"
 require "tmpdir"
 
+def dotnet_available?
+  system("which dotnet > /dev/null 2>&1")
+end
+
 desc "Build the Open XML SDK runner"
 task :build_sdk_runner do
-  sh "dotnet build vendor/sdk_runner/sdk_runner.csproj -c Release"
+  if dotnet_available?
+    sh "dotnet build vendor/sdk_runner/sdk_runner.csproj -c Release"
+  elsif File.exist?(sdk_runner_dll)
+    puts "dotnet not found in PATH, but pre-built sdk_runner.dll exists. Skipping build."
+  else
+    warn "dotnet command not found and sdk_runner.dll is missing. Cannot build SDK runner."
+  end
 end
 
 def reader_fixture_dir
@@ -38,10 +48,13 @@ rescue ArgumentError
 end
 
 desc "Ensure SDK-generated reader fixtures exist"
-task ensure_reader_fixtures: :build_sdk_runner do
+task :ensure_reader_fixtures do
   missing_specs = reader_fixture_specs.reject { |_scenario_name, fixture_path| File.exist?(fixture_path) }
   next if missing_specs.empty?
 
+  Rake::Task[:build_sdk_runner].invoke
+  raise "Cannot generate #{missing_specs.size} missing reader fixture(s) because dotnet is not installed." unless dotnet_available?
+
   FileUtils.mkdir_p(reader_fixture_dir)
 
   queue = Queue.new
@@ -77,7 +90,7 @@ task ensure_reader_fixtures: :build_sdk_runner do
   raise failures.pop
 end
 
-Rake::TestTask.new(:test) do |t|
+Rake::TestTask.new(test: :ensure_reader_fixtures) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList["test/**/*_test.rb"]
@@ -85,8 +98,6 @@ Rake::TestTask.new(:test) do |t|
   t.options = "--parallel --n-workers=#{workers}"
 end
 
-task test: %i[build_sdk_runner ensure_reader_fixtures]
-
 namespace :test do
   desc "Run tests with runtime type checking enabled (RBS_TEST=1)"
   task :rbs do

data/benchmark.rb

@@ -16,6 +16,8 @@ gemfile(true) do
   gem "roo", "3.0.0"
   gem "creek", "2.6.3"
   gem "xsv", "1.4.1"
+  gem "write_xlsx", "1.15.0"
+  gem "simple_xlsx_reader", "5.1.0"
 end
 
 RUNS = (ENV["RUNS"] || "3").to_i
@@ -28,10 +30,12 @@ AVAILABLE_GEMS = {
   "xlsxtream" => true,
   "fast_excel" => true,
   "caxlsx" => true,
+  "write_xlsx" => true,
   "rubyXL" => true,
   "creek" => true,
   "roo" => true,
-  "xsv" => true
+  "xsv" => true,
+  "simple_xlsx_reader" => true
 }
 
 puts "=" * 80
@@ -120,6 +124,16 @@ RUNNER_SCRIPT = <<~'RUBY'
       end
       p.serialize(filename)
     end
+  when ["write_xlsx", "write"]
+    require "write_xlsx"
+    measure do
+      wb = WriteXLSX.new(filename)
+      sheet = wb.add_worksheet("Data")
+      rows.times do |r|
+        sheet.write_row(r, 0, generate_row(r, cols))
+      end
+      wb.close
+    end
   when ["rubyXL", "write"]
     require "rubyXL"
     measure do
@@ -137,7 +151,7 @@ RUNNER_SCRIPT = <<~'RUBY'
   when ["xlsxrb_stream", "write"]
     require_relative "lib/xlsxrb"
     measure do
-      Xlsxrb.generate(filename) do |wb|
+      Xlsxrb.write(filename) do |wb|
         wb.sheet("Data") do |sheet|
           rows.times do |r|
             sheet.row(generate_row(r, cols))
@@ -161,7 +175,7 @@ RUNNER_SCRIPT = <<~'RUBY'
     require_relative "lib/xlsxrb"
     measure do
       count = 0
-      Xlsxrb.foreach(filename) do |sheet|
+      Xlsxrb.read(filename) do |sheet|
         sheet.each do |row|
           row.cells.each do |cell|
             _val = cell.value
@@ -222,6 +236,19 @@ RUNNER_SCRIPT = <<~'RUBY'
         end
       end
     end
+  when ["simple_xlsx_reader", "read"]
+    require "simple_xlsx_reader"
+    measure do
+      doc = SimpleXlsxReader.open(filename)
+      count = 0
+      doc.sheets.each do |sheet|
+        sheet.rows.each do |row|
+          row.each do |_val|
+            count += 1
+          end
+        end
+      end
+    end
   when ["rubyXL", "read"]
     require "rubyXL"
     measure do
@@ -281,7 +308,6 @@ def run_benchmark_series(name, lib, mode, rows, cols, filename, runs)
     end
   end
   puts
-
   return nil if results.empty?
 
   times = results.map { |r| r[:time] }.sort
@@ -314,6 +340,7 @@ write_targets = [
   ["xlsxrb (Streaming)", "xlsxrb_stream", "Streaming", "SST (Shared)"],
   ["fast_excel 0.5.0 (C)", "fast_excel", "Streaming", "SST (Shared)"],
   ["caxlsx 4.5.0", "caxlsx", "In-Memory", "Inline String"],
+  ["write_xlsx 1.15.0", "write_xlsx", "In-Memory", "SST (Shared)"],
   ["xlsxrb (In-Memory)", "xlsxrb_inmemory", "In-Memory", "SST (Shared)"],
   ["rubyXL 3.4.38", "rubyXL", "In-Memory", "Inline String"]
 ]
@@ -337,6 +364,7 @@ read_targets = [
   ["xlsxrb (In-Memory)", "xlsxrb_inmemory", "In-Memory"],
   ["creek 2.6.3", "creek", "Streaming"],
   ["roo 3.0.0", "roo", "Streaming"],
+  ["simple_xlsx_reader 5.1.0", "simple_xlsx_reader", "Streaming"],
   ["xsv 1.4.1", "xsv", "Streaming"],
   ["rubyXL 3.4.38", "rubyXL", "In-Memory"]
 ]

data/docs/ARCHITECTURE.md

@@ -29,7 +29,7 @@ As a strict rule, **we do not accept dynamic method definitions using `method_mi
 Even in cases where proxy patterns (e.g. `WorksheetProxy`) or OOXML builder mappings (e.g. `ChartBuilder`, `SeriesBuilder`) would traditionally benefit from dynamic delegation to avoid boilerplate, we explicitly generate and write out those delegations in the source code.
 
 ### 1. **`Xlsxrb` Module is the ONLY Entrypoint:**
-   The `Xlsxrb` module provides the top-level methods: `generate`, `build`, `read`, `foreach`, and `modify`. Users should **never** instantiate internal classes (like `Xlsxrb::Ooxml::WorkbookWriter`) directly.
+   The `Xlsxrb` module provides the top-level methods: `read`, `write`, `build`, and `modify`. Users should **never** instantiate internal classes (like `Xlsxrb::Ooxml::WorkbookWriter`) directly.
 
 2. **The `@api public` Contract (SemVer Guarantee):**
    Any module, class, or method tagged with `# @api public` in its YARD documentation is guaranteed to follow Semantic Versioning.
@@ -38,7 +38,7 @@ Even in cases where proxy patterns (e.g. `WorksheetProxy`) or OOXML builder mapp
    - Major versions (1.x -> 2.x) are the only time breaking changes to `@api public` components are permitted.
 
 3. **Block-Yielded Objects are Public APIs:**
-   All builder objects yielded into blocks (e.g., `writer` in `Xlsxrb.generate { |writer| }`, `sheet` in `writer.sheet { |sheet| }`, `chart` in `sheet.chart { |chart| }`) are explicitly marked as `@api public`. Their exposed methods constitute the DSL and are strictly protected by the SemVer contract.
+   All builder objects yielded into blocks (e.g., `writer` in `Xlsxrb.write { |writer| }`, `sheet` in `writer.sheet { |sheet| }`, `chart` in `sheet.chart { |chart| }`) are explicitly marked as `@api public`. Their exposed methods constitute the DSL and are strictly protected by the SemVer contract.
 
 ---
 
@@ -46,10 +46,11 @@ Even in cases where proxy patterns (e.g. `WorksheetProxy`) or OOXML builder mapp
 
 ```
 lib/
-  xlsxrb.rb                          # Facade: Xlsxrb.read / .write / .foreach / .generate / .build
+  xlsxrb.rb                          # Facade: Xlsxrb.read / .write / .build / .modify
   xlsxrb/
     version.rb                       # Xlsxrb::VERSION
     elements.rb                      # Requires for Elements layer
+    stream_row.rb                    # Lazy/streaming row and cell reader (O(1) memory)
     ooxml.rb                         # Requires for Ooxml layer
     ooxml/                           # Layer 1 – Low-level OOXML
       reader.rb                      #   Xlsxrb::Ooxml::Reader (core reading logic)
@@ -94,19 +95,20 @@ This layer directly handles ZIP extraction, XML parsing (via SAX), and XML gener
 * **`Xlsxrb::Ooxml::XmlBuilder`**: Emits well-formed XML strings via `<<` to a writable IO, supporting streaming generation without building a DOM.
 * **Part-specific parsers/writers**: `WorksheetParser`, `SharedStringsParser`, `StylesParser`, `WorkbookParser`, etc., each encapsulating the SAX event handling for one OpenXML part.
 
-### 2. High-Level Domain Model (The "Elements" Layer)
+### 2. High-Level Domain Model (The "Elements" Layer) & Streaming Row Layer
 
-**Namespace:** `Xlsxrb::Elements`
+**Namespace:** `Xlsxrb::Elements` and `Xlsxrb::StreamRow`
 
 **Responsibility:**
 This layer provides idiomatic, easy-to-use Ruby objects representing Excel concepts. It utilizes Ruby 3.2+ `Data` classes for immutability and precise structural definition. All domain models are encapsulated here to keep the top-level namespace clean.
 
-**Core Objects (`Data` classes):**
-* **`Xlsxrb::Elements::Workbook`**: Represents the entire file structure. Contains `sheets` (Array of Worksheet), shared styles metadata, and `unmapped_data`.
-* **`Xlsxrb::Elements::Worksheet`**: Represents a single sheet. Contains `name`, `rows` (Array of Row), `columns` (Array of Column), and sheet-level properties.
-* **`Xlsxrb::Elements::Row`**: Represents one row. Contains `index` (0-based), `cells` (Array of Cell), and row-level attributes (height, hidden, etc.).
-* **`Xlsxrb::Elements::Column`**: Represents column formatting. Contains `index` (0-based), `width`, and column-level attributes.
-* **`Xlsxrb::Elements::Cell`**: Represents a single cell. Contains `row_index`, `column_index` (both 0-based), `value` (Ruby native type), `formula`, `style`, and `unmapped_data`.
+**Core Objects:**
+* **`Xlsxrb::Elements::Workbook`**: Represents the entire file structure (`Data` class). Contains `sheets` (Array of Worksheet), shared styles metadata, and `unmapped_data`.
+* **`Xlsxrb::Elements::Worksheet`**: Represents a single sheet (`Data` class). Contains `name`, `rows` (Array of Row), `columns` (Array of Column), and sheet-level properties.
+* **`Xlsxrb::Elements::Row`**: Represents one in-memory row (`Data` class). Contains `index` (0-based), `cells` (Array of Cell), and row-level attributes.
+* **`Xlsxrb::StreamRow`**: Represents a streaming row with lazy cell parsing. Provides `row.each_cell` / `row.each` for $O(1)$ constant memory streaming, caching cells on-demand if indexed or converted to an array.
+* **`Xlsxrb::Elements::Column`**: Represents column formatting (`Data` class). Contains `index` (0-based), `width`, and column-level attributes.
+* **`Xlsxrb::Elements::Cell`**: Represents a single cell (`Data` class). Contains `row_index`, `column_index` (both 0-based), `value` (Ruby native type), `formula`, `style`, and `unmapped_data`.
 
 **Design Principles:**
 * **Zero-based Indexing:** To maintain consistency with Ruby's core language (Arrays/Enumerable), all indices (rows, columns, and worksheets) are **0-based**. For Excel-style coordination, use string references like `cell("A1")`.
@@ -115,17 +117,19 @@ This layer provides idiomatic, easy-to-use Ruby objects representing Excel conce
 
 ### 3. The Facade / Entrypoint Layer
 
-**Namespace:** `Xlsxrb` module methods
+**Namespace:** `Xlsxrb`
 
 **Responsibility:**
-Acts as the primary bridge, offering both In-Memory and Streaming APIs.
+Acts as the primary bridge, offering symmetric In-Memory and Streaming APIs.
 
 | Method | Type | Description |
 | :--- | :--- | :--- |
-| **`Xlsxrb.read(source)`** | In-Memory | Loads the entire file into a `Workbook` object. |
-| **`Xlsxrb.foreach(source, **options)`** | **Streaming** | Yields each `Row` one by one. Ideal for large files. |
-| **`Xlsxrb.write(target, workbook)`** | In-Memory | Saves a `Workbook` object to a file or IO. |
-| **`Xlsxrb.generate(target, &block)`** | **Streaming** | Provides a DSL to stream data directly to a file/IO. |
+| **`Xlsxrb.read(source, &block)`** | **Streaming** | Streams sheets (`StreamSheet`) and rows (`StreamRow`) with $O(1)$ constant memory. |
+| **`Xlsxrb.write(target, &block)`** | **Streaming** | Streams rows directly to file/IO with minimal memory. |
+| **`Xlsxrb.read(source)`** | In-Memory | Loads from file path, IO, or raw binary string into a `Workbook`. |
+| **`Xlsxrb.write(target, wb)`** / **`Xlsxrb.write(wb)`** | In-Memory | Saves `Workbook` to file/IO, or returns raw binary string (single argument). |
+| **`Xlsxrb.build(&block)`** | In-Memory | Builds an immutable `Workbook` using DSL. |
+| **`Xlsxrb.modify(source, target, &block)`** | In-Memory | Updates cells/sheets of an existing workbook. |
 
 ### Facade Expansion Policy
 
@@ -134,7 +138,7 @@ The long-term API goal is that **all spreadsheet features implemented in the low
 This applies to both:
 
 * **In-Memory DSL** (`Xlsxrb.build` -> `WorkbookBuilder` / `WorksheetBuilder`)
-* **Streaming DSL** (`Xlsxrb.generate` -> `StreamWriter`)
+* **Streaming DSL** (`Xlsxrb.write` -> `StreamWriter`)
 
 The Facade should not expose only a hand-picked subset forever. If a feature is stable and supported in the low-level writer, the default expectation is that it should eventually gain a high-level entry point.
 
@@ -193,7 +197,7 @@ If a low-level feature is workbook-scoped, do not force it into a worksheet-only
 
 For each feature, choose a single primary Facade shape and reuse it across modes:
 
-* `Xlsxrb.build` and `Xlsxrb.generate` should feel structurally similar
+* `Xlsxrb.build` and `Xlsxrb.write` should feel structurally similar
 * streaming and in-memory APIs may differ internally, but the surface API should remain as close as possible
 * differences are acceptable only when memory or ordering constraints make them unavoidable
 
@@ -291,28 +295,26 @@ Ooxml::WorkbookWriter      ── writes workbook.xml, styles.xml, sharedStrings
 Ooxml::ZipWriter           ── writes ZIP output ──► target (path / IO)
 ```
 
-### `Xlsxrb.foreach(source, **options)` — Streaming Read
+### `Xlsxrb.read(source, &block)` — Streaming Read
 
 ```
-source (path / IO)
+source (path / IO / binary string)
   │
   ▼
 Ooxml::ZipReader           ── locates xl/sharedStrings.xml, xl/worksheets/sheetN.xml
   │
   ▼  (SAX parse SST first — kept in memory as a flat Array of strings)
   │
-  ▼  (then SAX stream worksheet)
-Ooxml::WorksheetParser     ── on each </row> event:
-  │                           1. build Elements::Row with resolved cell values
-  │                           2. yield Row to caller's block
-  │                           3. discard Row (GC eligible)
+  ▼  (then SAX stream worksheet with StreamRow lazy cell scanner)
+Ooxml::WorksheetParser     ── yields StreamRow to caller's block
+  │
   ▼
-caller's block receives Elements::Row, processes, moves on
+caller's block receives StreamRow, streams cells via each_cell with O(1) memory
 ```
 
-Key memory invariant: only **one Row** (plus the shared-string table) is alive at any time.
+Key memory invariant: only **one Row / Cell** (plus the shared-string table) is parsed at any time.
 
-### `Xlsxrb.generate(target, &block)` — Streaming Write
+### `Xlsxrb.write(target, &block)` — Streaming Write
 
 ```
 caller's block
@@ -418,7 +420,7 @@ Every new high-level DSL feature must satisfy the following quality rules before
 If a feature is intended to exist in both writing modes, tests must cover:
 
 * `Xlsxrb.build` / `Xlsxrb.write`
-* `Xlsxrb.generate`
+* `Xlsxrb.write`
 
 If a feature can only exist in one mode for a technical reason, that restriction must be documented explicitly in code comments and user-facing docs.