rbxl 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9bedc3242085871b368d031e7791aeb925d8d2a53329aebaf1776a0a0d273eb
-  data.tar.gz: e4d6594b3c7d19b63f429b5cb5680df1d4e6e762dd86c2ab33499c97a5389918
+  metadata.gz: 76445404b974d2ddcd664b9f796fd693b7c5c36d1d56cf34fccc2b7f1fd1b51d
+  data.tar.gz: e41c2dcccc060b7bb7e3a5608f2f57dfaa7f063daf3f82f1a4fa0bf6f85cb098
 SHA512:
-  metadata.gz: fac56fdc22b72ff9bf75c3273e8e9a61fbab953c3ddb280618522c121a71a8d530f09792d4c80682b94309b7042604af42b5bfeeab41420e67611cb57d0a57de
-  data.tar.gz: 72f58522b5d7d9a0e1ca16e153a578871e8a2355e12a9066c7f1b1ec1026c72124bdbd7ec72c9e293caf74dfcff0e21386c09db1155c7d2c7549e04ef93abdec
+  metadata.gz: f41de8a1367b9033d5391ac8f46ff8b363ae79c6331bd4601bbf64fbbdf6e437c53052f38c7f130aa21833c2d60603853b1553507a6e4c7c291317da3c3f749f
+  data.tar.gz: fe624cb616255d3437811354c073fe527f2e01bc562b93c3e19732e324aa4b227d50480b68a6e15d858c6bc276cd1da7c8456fd7ff94ea8447dea6a4b9cad70c

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 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,11 +1,19 @@
 # rbxl
 
-`openpyxl` inspired Ruby gem for large-ish `.xlsx` files.
+Fast, memory-friendly Ruby gem for row-by-row `.xlsx` reads and append-only writes.
+
+`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.
 
 Current scope is intentionally small:
 
 - `write_only` workbook generation
-- `read_only` row streaming
+- `read_only` row-by-row iteration
 - `close()` for read-only workbooks
 - minimal `openpyxl`-like API
 - optional C extension (`rbxl/native`) for maximum performance
@@ -62,6 +70,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 +99,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 +118,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 +126,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 +163,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 +198,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

data/lib/rbxl/read_only_workbook.rb

@@ -1,24 +1,75 @@
 module Rbxl
+  # Read-only workbook backed by a ZIP archive.
+  #
+  # The workbook opens the underlying <tt>.xlsx</tt> once and keeps a single
+  # +Zip::File+ handle open for the lifetime of the object. Worksheets are
+  # opened lazily via {#sheet}, so callers can process very large sheets
+  # without materializing the full workbook in memory.
+  #
+  # Typical use:
+  #
+  #   book = Rbxl.open("big.xlsx", read_only: true)
+  #   begin
+  #     book.sheet_names                    # => ["Data"]
+  #     book.sheet("Data").each_row do |row|
+  #       process(row.values)
+  #     end
+  #   ensure
+  #     book.close
+  #   end
+  #
+  # After {#close} every subsequent {#sheet} call raises
+  # {Rbxl::ClosedWorkbookError}.
   class ReadOnlyWorkbook
+    # Namespace for the main SpreadsheetML schema.
     MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+
+    # Namespace used for document-level relationships.
     REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+
+    # Namespace used by the OPC package relationships layer.
     PACKAGE_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
 
-    attr_reader :path, :sheet_names
+    # @return [String] filesystem path the workbook was opened from
+    attr_reader :path
 
-    def self.open(path)
-      new(path)
+    # @return [Array<String>] visible sheet names in workbook order
+    attr_reader :sheet_names
+
+    # Convenience constructor equivalent to <tt>new(path, streaming:)</tt>.
+    #
+    # @param path [String, #to_path] path to the <tt>.xlsx</tt> file
+    # @param streaming [Boolean] feed worksheet XML to the native parser in
+    #   chunks (see {Rbxl.open})
+    # @return [Rbxl::ReadOnlyWorkbook]
+    def self.open(path, streaming: false)
+      new(path, streaming: streaming)
     end
 
-    def initialize(path)
+    # Opens the ZIP archive, pre-loads shared strings, and indexes the
+    # worksheet entries keyed by visible sheet name.
+    #
+    # @param path [String, #to_path] path to the <tt>.xlsx</tt> file
+    # @param streaming [Boolean] forwarded to produced worksheets
+    def initialize(path, streaming: false)
       @path = path
       @zip = Zip::File.open(path)
+      @streaming = streaming
       @shared_strings = load_shared_strings
       @sheet_entries = load_sheet_entries
       @sheet_names = @sheet_entries.keys.freeze
       @closed = false
     end
 
+    # Returns a row-by-row worksheet by visible sheet name.
+    #
+    # The returned object shares the workbook's ZIP handle. Closing the
+    # workbook invalidates any worksheets produced by prior calls.
+    #
+    # @param name [String] visible sheet name as listed in {#sheet_names}
+    # @return [Rbxl::ReadOnlyWorksheet]
+    # @raise [Rbxl::SheetNotFoundError] if +name+ is not present
+    # @raise [Rbxl::ClosedWorkbookError] if the workbook has been closed
     def sheet(name)
       ensure_open!
 
@@ -26,9 +77,13 @@ module Rbxl
         raise SheetNotFoundError, "sheet not found: #{name}"
       end
 
-      ReadOnlyWorksheet.new(zip: @zip, entry_path: entry_path, shared_strings: @shared_strings, name: name)
+      ReadOnlyWorksheet.new(zip: @zip, entry_path: entry_path, shared_strings: @shared_strings, name: name, streaming: @streaming)
     end
 
+    # Releases the underlying ZIP file handle. Idempotent; subsequent calls
+    # are no-ops.
+    #
+    # @return [void]
     def close
       return if closed?
 
@@ -36,6 +91,7 @@ module Rbxl
       @closed = true
     end
 
+    # @return [Boolean] whether {#close} has been called
     def closed?
       @closed
     end
@@ -50,7 +106,18 @@ module Rbxl
       entry = @zip.find_entry("xl/sharedStrings.xml")
       return [] unless entry
 
+      max_count = Rbxl.max_shared_strings
+      max_bytes = Rbxl.max_shared_string_bytes
+
+      # Reject zip-bomb style entries up front using the ZIP directory's
+      # declared uncompressed size, before allocating any decompression buffer.
+      if max_bytes && entry.size && entry.size > max_bytes
+        raise SharedStringsTooLargeError,
+              "shared strings uncompressed size #{entry.size} exceeds limit #{max_bytes}"
+      end
+
       strings = []
+      total_bytes = 0
       io = entry.get_input_stream
       reader = Nokogiri::XML::Reader(io)
 
@@ -92,7 +159,17 @@ module Rbxl
           when "rPh"
             in_phonetic = false
           when "si"
-            strings << current_fragments.join.freeze
+            value = current_fragments.join.freeze
+            total_bytes += value.bytesize
+            if max_bytes && total_bytes > max_bytes
+              raise SharedStringsTooLargeError,
+                    "shared strings total size exceeds limit #{max_bytes}"
+            end
+            strings << value
+            if max_count && strings.size > max_count
+              raise SharedStringsTooLargeError,
+                    "shared strings count exceeds limit #{max_count}"
+            end
             in_si = false
             in_run = false
             in_phonetic = false