rbxl 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9bedc3242085871b368d031e7791aeb925d8d2a53329aebaf1776a0a0d273eb
-  data.tar.gz: e4d6594b3c7d19b63f429b5cb5680df1d4e6e762dd86c2ab33499c97a5389918
+  metadata.gz: 5213a5a5d1091d4f8927631c50c7c690362eb284ba1eb31ee80bf3d9d0a1ec7b
+  data.tar.gz: 2e5120093c09738342b76fb160b7e259649049dcec66b325bdc88a21f59bc9dd
 SHA512:
-  metadata.gz: fac56fdc22b72ff9bf75c3273e8e9a61fbab953c3ddb280618522c121a71a8d530f09792d4c80682b94309b7042604af42b5bfeeab41420e67611cb57d0a57de
-  data.tar.gz: 72f58522b5d7d9a0e1ca16e153a578871e8a2355e12a9066c7f1b1ec1026c72124bdbd7ec72c9e293caf74dfcff0e21386c09db1155c7d2c7549e04ef93abdec
+  metadata.gz: '038c1112ff36766d74aea7b9092ace0a0eed88d9ad7c1db28356e3d7598edd52d93d21c128a40c7b4e822719a9e329bca4515118a76ca7fce3fed0a00407f342'
+  data.tar.gz: b14444ae769c953832fba7da2c6f09d1371ad14206160cc5d6fd711c583ed33300438322873e9863ba199d79fa60b30e642071546878e9b418530b4dc5d8007f

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.1.0
+
+- `Rbxl.open` and `Rbxl.new` now default `read_only: true` and `write_only: true` respectively, so the call site no longer needs the boilerplate. Explicitly passing `false` raises `NotImplementedError`.
+- Add `date_conversion: true` to `Rbxl.open`: numeric cells whose style points at a date/time `numFmt` (built-in ids 14–22, 27–36, 45–47, 50–58, or a custom format code containing date tokens) are returned as `Date` or `Time`. Off by default — no change in output shape or throughput when the flag is absent.
+- Fix Ruby reader path so self-closing `<row/>` and `<c/>` elements are iterated instead of silently dropped, and never yield `nil` for a row.
+
+## 1.0.2
+
+- Add `streaming: true` to `Rbxl.open` to feed worksheet XML to the native reader in 64 KiB chunks instead of buffering the full worksheet first.
+- Add `Rbxl.max_worksheet_bytes` and `Rbxl::WorksheetTooLargeError` so streaming reads can stop oversized worksheet XML entries mid-inflate.
+- Expand RDoc coverage across the public API.
+- Tighten RBS signatures to match the actual runtime types.
+- Reword public docs and gem metadata to describe reads as row-by-row and writes as append-only, reserving "streaming" for the new opt-in native read path.
+
 ## 1.0.1
 
 - Fix ZIP64 handling.

data/README.md

@@ -1,16 +1,25 @@
 # rbxl
 
-`openpyxl` inspired Ruby gem for large-ish `.xlsx` files.
+[![Gem Version](https://badge.fury.io/rb/rbxl.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/rbxl)
 
-Current scope is intentionally small:
+Fast, memory-friendly Ruby gem for row-by-row `.xlsx` reads and append-only writes.
 
-- `write_only` workbook generation
-- `read_only` row streaming
-- `close()` for read-only workbooks
-- minimal `openpyxl`-like API
+`rbxl` is built for the two workbook workflows that scale cleanly:
+
+- read-only row-by-row iteration
+- write-only workbook generation
+
+The API is intentionally small and `openpyxl`-inspired, with an optional
+native extension for faster XML parsing when you need more throughput.
+
+Supported:
+
+- write-only workbook generation
+- read-only row-by-row iteration
+- opt-in date/time conversion driven by the workbook's `numFmt` styles
 - optional C extension (`rbxl/native`) for maximum performance
 
-Out of scope for this MVP:
+Out of scope:
 
 - preserving arbitrary workbook structure on save
 - rich style round-tripping
@@ -21,7 +30,7 @@ Out of scope for this MVP:
 ```ruby
 require "rbxl"
 
-book = Rbxl.new(write_only: true)
+book = Rbxl.new
 sheet = book.add_sheet("Report")
 sheet.append(["id", "name", "score"])
 sheet.append([1, "alice", 100])
@@ -32,7 +41,7 @@ book.save("report.xlsx")
 ```ruby
 require "rbxl"
 
-book = Rbxl.open("report.xlsx", read_only: true)
+book = Rbxl.open("report.xlsx")
 sheet = book.sheet("Report")
 
 sheet.each_row do |row|
@@ -44,8 +53,38 @@ p sheet.calculate_dimension
 book.close
 ```
 
-`write_only` workbooks are save-once by design. This matches the optimized
-mode tradeoff: low flexibility in exchange for simpler memory behavior.
+`Rbxl.open` defaults to read-only and `Rbxl.new` defaults to write-only;
+the `read_only:` / `write_only:` keywords remain for call-site clarity and
+to leave room for a future read/write mode. Write-only workbooks are
+save-once by design — this matches the optimized mode tradeoff: low
+flexibility in exchange for simpler memory behavior.
+
+### Date / time conversion
+
+Numeric cells in `.xlsx` files are serial days since 1899-12-31; whether
+they display as `44562`, `2022-01-01`, or `12:00` depends on the cell's
+`numFmt` style. `rbxl` leaves cells as raw `Float` by default so the read
+path stays allocation-light. Pass `date_conversion: true` to opt into
+interpreting the style:
+
+```ruby
+require "rbxl"
+
+book = Rbxl.open("schedule.xlsx", date_conversion: true)
+book.sheet("Timeline").each_row(values_only: true) do |row|
+  row.each { |v| p v }  # => Date / Time / Float / String / ...
+end
+book.close
+```
+
+With the flag on, `rbxl` parses `xl/styles.xml` once at first use and
+converts numeric cells whose style maps to a built-in date `numFmtId`
+(14–22, 27–36, 45–47, 50–58) or to a custom `formatCode` containing date
+tokens. Whole-number serials return `Date`; fractional serials return
+`Time` so the time-of-day portion is preserved. The flag is off by
+default; leaving it off skips the styles parse entirely and keeps the
+native fast path in use. Turning it on routes reads through the pure-Ruby
+worksheet parser.
 
 ## Native C Extension
 
@@ -62,6 +101,20 @@ book.sheet("Data").rows(values_only: true).each { |row| process(row) }
 book.close
 ```
 
+For large worksheets where peak memory matters more than squeezing out the
+last few percent of throughput, opt into chunk-fed worksheet inflation:
+
+```ruby
+require "rbxl"
+require "rbxl/native"
+
+Rbxl.max_worksheet_bytes = 64 * 1024 * 1024
+
+book = Rbxl.open("large.xlsx", read_only: true, streaming: true)
+book.sheet("Data").rows(values_only: true).each { |row| process(row) }
+book.close
+```
+
 The C extension is **opt-in by design**:
 
 - **Portability first**: `require "rbxl"` alone works everywhere Ruby and
@@ -77,9 +130,17 @@ The C extension is **opt-in by design**:
   compile the C extension. If libxml2 is not found, compilation is silently
   skipped and the gem installs successfully without it. You only notice when
   you try `require "rbxl/native"`.
-- **Current boundary cost is explicit**: worksheet ZIP entries are still
+- **Default path buffers the worksheet**: the worksheet ZIP entry is
   inflated into a Ruby string before crossing into C. The extension removes
   XML parse overhead, but not ZIP I/O or that intermediate buffer.
+- **Opt-in streaming**: passing `streaming: true` to `Rbxl.open` feeds the
+  worksheet XML to the native parser in 64 KiB chunks pulled from the ZIP
+  input stream, so peak memory stays roughly independent of sheet size.
+  Pair with `Rbxl.max_worksheet_bytes` to cap uncompressed worksheet
+  inflation and stop high-compression zip-bomb style entries mid-inflate.
+  Throughput is usually within a few percent of the default path. Without
+  `require "rbxl/native"`, the flag is accepted but the pure-Ruby reader
+  still takes the buffered path.
 
 Requirements for the C extension:
 
@@ -88,7 +149,7 @@ Requirements for the C extension:
 
 ## Design Notes
 
-- Writer avoids a full workbook object graph and streams rows into sheet XML.
+- Writer avoids a full workbook object graph; rows are buffered per sheet and the XML is emitted in a single pass at `save`.
 - Reader uses a pull parser for worksheet XML so it can iterate rows without building the full DOM.
 - Strings written by the MVP use `inlineStr` to avoid shared string bookkeeping during generation.
 - Reader supports both shared strings and inline strings.
@@ -96,22 +157,27 @@ Requirements for the C extension:
 
 ## Development
 
+Development in this repository assumes Ruby 3.4.8 (`.ruby-version`).
+
 ```bash
 bundle install
 cd benchmark && npm install && cd ..
 
 # Run tests (pure Ruby)
-ruby -Ilib -Itest test/rbxl_test.rb
+bundle exec ruby -Ilib -Itest test/rbxl_test.rb
 
 # Run tests (with native extension)
 cd ext/rbxl_native && ruby extconf.rb && make && cd ../..
-ruby -Ilib -Itest -r rbxl/native test/rbxl_test.rb
-ruby -Ilib -Itest test/fast_ext_test.rb
+bundle exec ruby -Ilib -Itest -r rbxl/native test/rbxl_test.rb
+bundle exec ruby -Ilib -Itest test/fast_ext_test.rb
 
 # Benchmarks
-ruby -Ilib benchmark/compare.rb                     # pure Ruby
-ruby -Ilib -r rbxl/native benchmark/compare.rb      # with native
-RBXL_BENCH_WARMUP=1 RBXL_BENCH_ITERATIONS=5 ruby -Ilib benchmark/read_modes.rb
+bundle exec ruby -Ilib benchmark/compare.rb                     # pure Ruby
+bundle exec ruby -Ilib -r rbxl/native benchmark/compare.rb      # with native
+RBXL_BENCH_WARMUP=1 RBXL_BENCH_ITERATIONS=5 bundle exec ruby -Ilib benchmark/read_modes.rb
+
+# Generate API docs
+bundle exec rake rdoc
 ```
 
 ## Benchmarks
@@ -128,30 +194,34 @@ best read as:
 
 5000 rows x 10 columns, Ruby 3.4 / Python 3.13 / Node 24:
 
-![Benchmark chart](benchmark/chart.png)
+![Benchmark chart](benchmark/chart-20260417-044037.png)
 
 ### Portable Baseline (`require "rbxl"`)
 
 | benchmark | real (s) |
 |---|---|
 | rbxl write | 0.08 |
-| rbxl read | 0.33 |
-| rbxl read values | 0.23 |
+| rbxl read | 0.29 |
+| rbxl read values | 0.22 |
+| fast_excel write | 0.18 |
+| fast_excel write constant | 0.12 |
 | exceljs write | 0.08 |
-| exceljs read | 0.17 |
+| exceljs read | 0.19 |
 | sheetjs write | 0.13 |
-| sheetjs read | 0.19 |
-| openpyxl write | 0.35 |
-| openpyxl read | 0.22 |
+| sheetjs read | 0.20 |
+| openpyxl write | 0.36 |
+| openpyxl read | 0.21 |
 | openpyxl read values | 0.18 |
+| excelize write | 0.15 |
+| excelize read | 0.14 |
 
 ### Performance Mode (`require "rbxl/native"`)
 
 | benchmark | real (s) | vs exceljs/openpyxl |
 |---|---|---|
-| rbxl write | **0.04** | about 2x / 9x faster |
-| rbxl read | **0.07** | about 2.6x / 3.2x faster |
-| rbxl read values | **0.03** | about 6.8x faster than openpyxl values |
+| rbxl write | **0.05** | about 1.8x faster than exceljs, 2.5x faster than fast_excel constant, 7.7x faster than openpyxl |
+| rbxl read | **0.09** | about 2.3x faster than exceljs, 2.4x faster than openpyxl |
+| rbxl read values | **0.04** | about 4.8x faster than openpyxl values |
 
 The comparison script uses these libraries when available:
 
@@ -159,12 +229,14 @@ Benchmark notes:
 
 - `RBXL_BENCH_WARMUP` and `RBXL_BENCH_ITERATIONS` control warmup and repeated runs.
 - Read comparisons use the same `rbxl.xlsx` fixture for `rbxl`, `roo`, `rubyXL`, and `openpyxl`.
+- `fast_excel` adds write-only comparisons for both its default mode and `constant_memory: true`.
 - JS comparisons use the same `rbxl.xlsx` fixture for `exceljs` and `sheetjs`.
 - Write comparisons still measure each library producing its own workbook.
 - `rss_delta_kb` is best-effort process RSS on Linux and should be treated as directional.
 - Install JS benchmark dependencies with `cd benchmark && npm install`.
 
 - `rbxl` for write/read
+- `fast_excel` for write / constant-memory write
 - `exceljs` for write/read
 - `sheetjs` for write/read
 - `excelize` (Go) for write/read

data/Rakefile

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
 require "bundler/gem_helper"
+require "rdoc/task"
 
 Bundler::GemHelper.install_tasks
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+end

data/ext/rbxl_native/native.c

@@ -359,11 +359,15 @@ static void on_characters(void *ctx, const xmlChar *ch, int len)
 /* Ensure-style cleanup wrapper                                        */
 /* ------------------------------------------------------------------ */
 
+#define IO_READ_CHUNK_BYTES (64 * 1024)
+
 typedef struct {
     parse_ctx     *ctx;
     xmlParserCtxtPtr parser;
-    const char    *data;
-    long           data_len;
+    const char    *data;      /* string mode only */
+    long           data_len;  /* string mode only */
+    VALUE          io;        /* io mode only (Qnil in string mode) */
+    long           max_bytes; /* io mode cap; 0 = unbounded */
 } parse_args;
 
 static VALUE do_parse(VALUE arg)
@@ -375,6 +379,39 @@ static VALUE do_parse(VALUE arg)
     return Qnil;
 }
 
+static VALUE do_parse_io(VALUE arg)
+{
+    parse_args *a = (parse_args *)arg;
+    static ID id_read = 0;
+    if (!id_read) id_read = rb_intern("read");
+    VALUE chunk_size = INT2NUM(IO_READ_CHUNK_BYTES);
+    long total = 0;
+
+    while (1) {
+        VALUE chunk = rb_funcall(a->io, id_read, 1, chunk_size);
+        if (NIL_P(chunk)) break;
+        Check_Type(chunk, T_STRING);
+
+        long n = RSTRING_LEN(chunk);
+        if (n == 0) break;
+
+        total += n;
+        if (a->max_bytes > 0 && total > a->max_bytes) {
+            a->ctx->error = 1;
+            snprintf(a->ctx->error_msg, sizeof(a->ctx->error_msg),
+                     "worksheet bytes exceed limit (%ld)", a->max_bytes);
+            break;
+        }
+
+        xmlParseChunk(a->parser, RSTRING_PTR(chunk), (int)n, 0);
+        if (a->ctx->error) break;
+    }
+
+    /* Terminate the parser so any trailing buffered state flushes. */
+    xmlParseChunk(a->parser, NULL, 0, 1);
+    return Qnil;
+}
+
 static VALUE cleanup_parse(VALUE arg)
 {
     parse_args *a = (parse_args *)arg;
@@ -392,7 +429,7 @@ static VALUE cleanup_parse(VALUE arg)
 /* Common parse setup                                                  */
 /* ------------------------------------------------------------------ */
 
-static VALUE run_parse(parse_ctx *ctx, VALUE xml_str)
+static xmlParserCtxtPtr setup_push_parser(parse_ctx *ctx)
 {
     xmlSAXHandler handler;
     memset(&handler, 0, sizeof(handler));
@@ -408,11 +445,25 @@ static VALUE run_parse(parse_ctx *ctx, VALUE xml_str)
         rb_raise(rb_eRuntimeError, "failed to create libxml2 parser context");
     }
 
-    /* Disable network access and limit entity expansion */
-    xmlCtxtUseOptions(parser,
-        XML_PARSE_NONET | XML_PARSE_NOENT | XML_PARSE_HUGE);
+    /* XXE / entity-expansion defense:
+     *   - NONET: no network access
+     *   - NOENT omitted: user-defined entities are NOT substituted, so
+     *     external entities are never resolved and billion-laughs style
+     *     expansion cannot trigger. Predefined entities (& etc.) still
+     *     reach the characters callback via libxml2's default SAX2 handler.
+     *   - HUGE omitted: keep libxml2's built-in parser limits active.
+     *   Real xlsx files stay well under these limits (Excel caps cell text
+     *   at 32,767 chars), so no throughput loss. */
+    xmlCtxtUseOptions(parser, XML_PARSE_NONET);
+    return parser;
+}
 
-    parse_args args = { ctx, parser, RSTRING_PTR(xml_str), RSTRING_LEN(xml_str) };
+static VALUE run_parse(parse_ctx *ctx, VALUE xml_str)
+{
+    xmlParserCtxtPtr parser = setup_push_parser(ctx);
+    parse_args args = { ctx, parser,
+                        RSTRING_PTR(xml_str), RSTRING_LEN(xml_str),
+                        Qnil, 0 };
 
     /* rb_ensure guarantees cleanup even if rb_yield raises */
     rb_ensure(do_parse, (VALUE)&args, cleanup_parse, (VALUE)&args);
@@ -424,6 +475,20 @@ static VALUE run_parse(parse_ctx *ctx, VALUE xml_str)
     return INT2NUM(ctx->row_count);
 }
 
+static VALUE run_parse_io(parse_ctx *ctx, VALUE io, long max_bytes)
+{
+    xmlParserCtxtPtr parser = setup_push_parser(ctx);
+    parse_args args = { ctx, parser, NULL, 0, io, max_bytes };
+
+    rb_ensure(do_parse_io, (VALUE)&args, cleanup_parse, (VALUE)&args);
+
+    if (ctx->error) {
+        rb_raise(rb_eRuntimeError, "rbxl_native: %s", ctx->error_msg);
+    }
+
+    return INT2NUM(ctx->row_count);
+}
+
 /* ------------------------------------------------------------------ */
 /* Ruby method: Rbxl::Native.parse_sheet(xml_string, shared_strings) */
 /* ------------------------------------------------------------------ */
@@ -473,6 +538,59 @@ static VALUE rb_native_parse_full(VALUE self, VALUE xml_str, VALUE shared_string
     return run_parse(&ctx, xml_str);
 }
 
+/* ------------------------------------------------------------------ */
+/* Ruby method: Rbxl::Native.parse_sheet_io(io, shared_strings, max_bytes) */
+/*   Chunk-fed streaming variant of parse_sheet.                        */
+/*   max_bytes may be nil to disable the worksheet byte cap.            */
+/* ------------------------------------------------------------------ */
+
+static VALUE rb_native_parse_io(VALUE self, VALUE io, VALUE shared_strings, VALUE max_bytes)
+{
+    (void)self;
+    Check_Type(shared_strings, T_ARRAY);
+
+    long max = NIL_P(max_bytes) ? 0 : NUM2LONG(max_bytes);
+
+    parse_ctx ctx;
+    memset(&ctx, 0, sizeof(ctx));
+    ctx.shared_strings     = shared_strings;
+    ctx.shared_strings_len = RARRAY_LEN(shared_strings);
+    ctx.current_row        = Qnil;
+    ctx.full_mode          = 0;
+    dynbuf_init(&ctx.text_buf);
+    dynbuf_init(&ctx.raw_buf);
+
+    return run_parse_io(&ctx, io, max);
+}
+
+/* ------------------------------------------------------------------ */
+/* Ruby method: Rbxl::Native.parse_sheet_full_io(io, shared_strings, max_bytes) */
+/* ------------------------------------------------------------------ */
+
+static VALUE rb_native_parse_full_io(VALUE self, VALUE io, VALUE shared_strings, VALUE max_bytes)
+{
+    (void)self;
+    Check_Type(shared_strings, T_ARRAY);
+
+    long max = NIL_P(max_bytes) ? 0 : NUM2LONG(max_bytes);
+
+    VALUE mRbxl = rb_const_get(rb_cObject, rb_intern("Rbxl"));
+
+    parse_ctx ctx;
+    memset(&ctx, 0, sizeof(ctx));
+    ctx.shared_strings     = shared_strings;
+    ctx.shared_strings_len = RARRAY_LEN(shared_strings);
+    ctx.current_row        = Qnil;
+    ctx.full_mode          = 1;
+    ctx.cReadOnlyCell      = rb_const_get(mRbxl, rb_intern("ReadOnlyCell"));
+    ctx.cRow               = rb_const_get(mRbxl, rb_intern("Row"));
+    dynbuf_init(&ctx.text_buf);
+    dynbuf_init(&ctx.raw_buf);
+    dynbuf_init(&ctx.cell_ref);
+
+    return run_parse_io(&ctx, io, max);
+}
+
 /* ================================================================== */
 /* Native writer — generate sheet XML from Ruby Array of Arrays        */
 /* ================================================================== */
@@ -673,5 +791,7 @@ void Init_rbxl_native(void)
     VALUE mNative = rb_define_module_under(mRbxl, "Native");
     rb_define_module_function(mNative, "parse_sheet", rb_native_parse, 2);
     rb_define_module_function(mNative, "parse_sheet_full", rb_native_parse_full, 2);
+    rb_define_module_function(mNative, "parse_sheet_io", rb_native_parse_io, 3);
+    rb_define_module_function(mNative, "parse_sheet_full_io", rb_native_parse_full_io, 3);
     rb_define_module_function(mNative, "generate_sheet", rb_native_generate, 1);
 }

data/lib/rbxl/cell.rb

@@ -1,3 +1,18 @@
 module Rbxl
+  # Generic value-object cell used by the pure-Ruby reader path.
+  #
+  # Yielded as an element of {Rbxl::Row#cells} when a worksheet is iterated
+  # without +values_only+. Cells are keyword-constructed and expose the
+  # decoded Ruby value plus the Excel-style coordinate.
+  #
+  #   cell = Rbxl::Cell.new(value: 42, coordinate: "B3")
+  #   cell.value      # => 42
+  #   cell.coordinate # => "B3"
+  #
+  # @!attribute [rw] value
+  #   @return [Object] decoded Ruby value for the cell (String, Numeric,
+  #     Boolean, or +nil+)
+  # @!attribute [rw] coordinate
+  #   @return [String, nil] Excel-style coordinate such as +"B3"+
   Cell = Struct.new(:value, :coordinate, keyword_init: true)
 end

data/lib/rbxl/empty_cell.rb

@@ -1,11 +1,26 @@
 module Rbxl
+  # Placeholder cell returned when a coordinate in a padded row has no data.
+  #
+  # Used only when {Rbxl::ReadOnlyWorksheet#each_row} is called with
+  # <tt>pad_cells: true</tt>. The object carries the synthetic coordinate so
+  # that downstream code can still locate the slot in the worksheet grid.
+  #
+  #   cell = Rbxl::EmptyCell.new(coordinate: "C5")
+  #   cell.coordinate # => "C5"
+  #   cell.value      # => nil
   class EmptyCell
+    # @return [String] Excel-style coordinate such as +"C5"+
     attr_reader :coordinate
 
+    # @param coordinate [String] Excel-style coordinate
     def initialize(coordinate:)
       @coordinate = coordinate
     end
 
+    # Always +nil+; exposed so callers can treat {EmptyCell} like any other
+    # cell object without a type check.
+    #
+    # @return [nil]
     def value
       nil
     end

data/lib/rbxl/errors.rb

@@ -1,7 +1,36 @@
 module Rbxl
+  # Base class for all errors raised by Rbxl. Rescue this class to catch any
+  # library-specific failure without catching unrelated +StandardError+
+  # subclasses from the caller's code.
   class Error < StandardError; end
+
+  # Raised by {Rbxl::ReadOnlyWorkbook#sheet} when the requested sheet name
+  # is not present in the workbook.
   class SheetNotFoundError < Error; end
+
+  # Raised when an operation is attempted against a workbook whose
+  # underlying resources have already been released via +close+.
   class ClosedWorkbookError < Error; end
+
+  # Raised by {Rbxl::WriteOnlyWorkbook#save} when the workbook has already
+  # been persisted once. Write-only workbooks are save-once by design.
   class WorkbookAlreadySavedError < Error; end
+
+  # Raised by {Rbxl::ReadOnlyWorksheet#calculate_dimension} when the sheet
+  # lacks a stored +<dimension>+ element and the caller has not opted into
+  # scanning the worksheet with <tt>force: true</tt>.
   class UnsizedWorksheetError < Error; end
+
+  # Raised when the shared strings table in an opened workbook exceeds the
+  # configured count or byte limits (see {Rbxl.max_shared_strings} and
+  # {Rbxl.max_shared_string_bytes}). Guards against malicious or malformed
+  # +.xlsx+ files that would otherwise exhaust memory before the first row
+  # is read.
+  class SharedStringsTooLargeError < Error; end
+
+  # Raised when a worksheet's XML payload exceeds {Rbxl.max_worksheet_bytes}
+  # while iterating in +streaming: true+ mode. Applies to the uncompressed
+  # bytes consumed from the ZIP entry, so high-compression zip-bomb style
+  # worksheets are stopped mid-inflate rather than after the fact.
+  class WorksheetTooLargeError < Error; end
 end

data/lib/rbxl/native.rb

@@ -1,9 +1,22 @@
 require "nokogiri"
 
+# Opt-in loader for the libxml2-backed native extension.
+#
+# Requiring this file replaces the pure-Ruby worksheet XML parser and
+# serializer with a C implementation that uses libxml2's SAX2 API directly.
+# The public API exposed by {Rbxl} is unchanged; only the hot paths are
+# swapped.
+#
+# The shared object is located in one of two places:
+#
+# 1. An installed gem layout (+rbxl_native/rbxl_native.so+ on the load path).
+# 2. A development build tree under <tt>ext/rbxl_native/</tt>.
+#
+# If neither is available a +LoadError+ is raised with guidance on how to
+# build the extension.
 begin
   require "rbxl_native/rbxl_native"
 rescue LoadError
-  # Try loading from ext/ build directory (development)
   ext_path = File.expand_path("../../ext/rbxl_native", __dir__)
   so = Dir.glob(File.join(ext_path, "**", "rbxl_native.{so,bundle,dll}")).first
   if so

data/lib/rbxl/read_only_cell.rb

@@ -1,3 +1,13 @@
 module Rbxl
+  # Immutable cell value object used by the read-only worksheet path.
+  #
+  # Produced during row-by-row iteration when cells are yielded without
+  # +values_only+. Implemented as a +Data+ class so instances are frozen and
+  # hash-equal by value.
+  #
+  # @!attribute [r] coordinate
+  #   @return [String] Excel-style coordinate such as +"A1"+
+  # @!attribute [r] value
+  #   @return [Object, nil] decoded Ruby value (String, Numeric, Boolean, or +nil+)
   ReadOnlyCell = Data.define(:coordinate, :value)
 end