fast_xlsx 0.8.0-aarch64-linux → 1.0.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9d5b58aae6c81cae9ba4ae99174dd9c7308f607860dae332715370c0183666b
-  data.tar.gz: 7a5ffc7c424376ac5357c223d2f7e6d908be8f1a97ede8e614814906d73af6d5
+  metadata.gz: ba21afc732e1edd388545b5c427f5aeb170be9fcb5eadf73da61df8ffca0dd3c
+  data.tar.gz: 77d783a5aa4ee4ad87937871559c6dc1589fa53fc78fd560ef0119741826e78e
 SHA512:
-  metadata.gz: b9b1fd3f7b7f252de5bfaf2c29644cea20955e764e83b7dce77458743ef4063bb626c7815e4f09ec4eb99e63c13f71a89c21164db33464fd394d65beb3f13e49
-  data.tar.gz: c379b6f0497b0803057730f0b5c3310a78f6d57455716c7749390d1eada6740d1afe8b8ec2596ed62f6de9675add9c776f28cc395d1ce2a425ae8e77af7c8f28
+  metadata.gz: f182d1a0b27c8cdf9e0beee826b5e25056f7b0c7d090b667c2c398c9a11ed77310954c012bca1dea679d728d88e4f44fd76dc9d5d47e86abeb25b55ca1f3e197
+  data.tar.gz: 8ea1468cad06b02183e5782309e0cb1515d1fa78a9c5a57f5c2a81774133dbfc8e85214e22349373664b2c2b48eeaff369ea06986ba1f0d695294f54a6e9747d

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [1.0.0] - 2026-10-18
+
+The first stable release, with the same API as 0.8.1. From now on fast_xlsx follows Semantic Versioning: no breaking change before 2.0, and anything to be removed first prints a deprecation warning for at least one minor release.
+
+### Fixed
+
+- Updated rust_xlsxwriter to 0.100, which brings zip 9.0 (RUSTSEC-2026-0367, -0368 and -0369; those affect extracting archives, which fast_xlsx never does).
+- In `memory: :constant` and `:low` mode, a temporary file that can't be created (e.g. an unwritable temp directory) raises `FastXlsx::Error` instead of crashing the process. The file is also created only when the first row is flushed, not by `add_worksheet`.
+
+## [0.8.1] - 2026-10-03
+
+### Fixed
+
+- Rails' `ActiveSupport::TimeWithZone` (e.g. `created_at`) and other objects that act like a `Time` without being one were written as text; they are dates now.
+
+### Changed
+
+- Writing `Time` values is about 25% faster (read through Ruby's C API instead of method calls), and `Date` values a little faster.
+
 ## [0.8.0] - 2026-10-02
 
 ### Changed

data/README.md

@@ -1,15 +1,17 @@
-# FastXlsx
+# fast_xlsx
 
-[![Gem Version](https://badge.fury.io/rb/fast_xlsx.svg)](https://badge.fury.io/rb/fast_xlsx)
+![fast_xlsx: fast .xlsx writer for Ruby, powered by Rust](docs/social-preview.jpg)
+
+[![Gem Version](https://img.shields.io/gem/v/fast_xlsx)](https://rubygems.org/gems/fast_xlsx)
 [![codecov](https://codecov.io/gh/7a6163/fast_xlsx/graph/badge.svg)](https://codecov.io/gh/7a6163/fast_xlsx)
 
-Fast `.xlsx` writer for Ruby, built on [rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter) via [magnus](https://github.com/matsadler/magnus).
+Write Excel `.xlsx` files from Ruby with a Rust engine ([rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter), via [magnus](https://github.com/matsadler/magnus)): 20,000 rows in under 100 ms, with memory that stays flat for large exports.
 
-> **Status: release candidate.** The API is frozen as of 0.8: 0.8.x releases only fix bugs, and 1.0 follows once it has been in real use without needing changes.
+> **Status: stable.** Since 1.0 the API follows [Semantic Versioning](https://semver.org): no breaking change before 2.0.
 
-**Roadmap:** [1.0.0](https://github.com/7a6163/fast_xlsx/milestone/1) (release plan) · [1.x](https://github.com/7a6163/fast_xlsx/milestone/2) (planned features)
+**Roadmap:** [1.x](https://github.com/7a6163/fast_xlsx/milestone/2) (planned features)
 
-**Contents:** [Installation](#installation) · [Getting started](#getting-started) · [Guide](#guide) · [Performance](#performance) · [Support and versioning](#support-and-versioning) · [Development](#development)
+**Contents:** [Installation](#installation) · [Getting started](#getting-started) · [Guide](#guide) · [Performance](#performance) · [Support and versioning](#support-and-versioning) · [Development](#development) · [Credits](#credits)
 
 ## Installation
 
@@ -81,7 +83,7 @@ The [Guide](#guide) below covers every feature; the [API docs](https://www.rubyd
 
 ## Guide
 
-[Writing cells](#writing-cells) · [Rails](#rails) · [Memory modes](#memory-modes) · [Formats](#formats) · [Columns and filters](#columns-and-filters) · [Sheet view and printing](#sheet-view-and-printing) · [Cell ranges](#cell-ranges) · [Layout](#layout) · [Outline groups](#outline-groups) · [Defined names](#defined-names) · [Protection](#protection) · [Conditional formats](#conditional-formats) · [Data validation](#data-validation) · [Comments](#comments) · [Images](#images) · [Tables](#tables) · [Charts](#charts) · [Errors](#errors)
+[Writing cells](#writing-cells) · [Rails](#rails) · [Polars](#polars) · [Memory modes](#memory-modes) · [Formats](#formats) · [Columns and filters](#columns-and-filters) · [Sheet view and printing](#sheet-view-and-printing) · [Cell ranges](#cell-ranges) · [Layout](#layout) · [Outline groups](#outline-groups) · [Defined names](#defined-names) · [Protection](#protection) · [Conditional formats](#conditional-formats) · [Data validation](#data-validation) · [Comments](#comments) · [Images](#images) · [Tables](#tables) · [Charts](#charts) · [Errors](#errors)
 
 ### Writing cells
 
@@ -126,6 +128,23 @@ def export
 end
 ```
 
+### Polars
+
+To write a [ruby-polars](https://github.com/ankane/ruby-polars) DataFrame (gem `polars-df`), hand its column names and rows to fast_xlsx:
+
+```ruby
+df = Polars.read_csv("sales.csv")
+summary = df.group_by("region").agg(Polars.col("amount").sum)
+
+wb = FastXlsx::Workbook.new(memory: :constant)
+ws = wb.add_worksheet("By region")
+ws.append(summary.columns, format: { bold: true })
+summary.iter_rows { |row| ws << row }   # in batches of 512 rows, so memory stays flat
+wb.save("by_region.xlsx")
+```
+
+Polars `Date` and `Datetime` columns become dates (a `Datetime` with a time zone keeps its local time), `Decimal` numbers, and nulls empty cells.
+
 ### Memory modes
 
 By default every cell stays in memory until the file is saved. For large exports, two modes write each finished row to a temp file instead:
@@ -370,7 +389,7 @@ Values are mapped by type:
 |---|---|
 | `Integer`, `Float`, any `Numeric` | number |
 | `String` | string |
-| `Time`, `DateTime` | date and time (`yyyy-mm-dd hh:mm:ss` unless formatted), in its own offset |
+| `Time`, `DateTime`, time-like objects such as Rails' `ActiveSupport::TimeWithZone` | date and time (`yyyy-mm-dd hh:mm:ss` unless formatted), in its own offset |
 | `Date` | date (`yyyy-mm-dd` unless formatted) |
 | `FastXlsx::Formula.new("SUM(A1:A9)")` | formula |
 | `FastXlsx::URL.new("https://…")`, `URL.new(url, text: "Title")` | hyperlink (optionally showing other text) |
@@ -402,15 +421,15 @@ Apple Silicon, Ruby 4.0.5. Each library uses its own idiomatic row-append API; x
 
 | Library | Time | vs fastest | Ruby objects allocated |
 |---|---:|---:|---:|
-| **fast_xlsx** (`memory: :constant`) | **77 ms** | 1.0x | 7 |
-| **fast_xlsx** (`memory: :low`) | **86 ms** | 1.1x | 7 |
-| **fast_xlsx** | **89 ms** | 1.1x | 10 |
-| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 183 ms | 2.4x | 561,728 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 200 ms | 2.6x | 20,079 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 238 ms | 3.1x | 320,076 |
-| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 608 ms | 7.8x | 1,483,899 |
-| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 689 ms | 8.9x | 745,122 |
-| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2755 ms | 35.6x | 8,700,448 |
+| **fast_xlsx** (`memory: :constant`) | **75 ms** | 1.0x | 7 |
+| **fast_xlsx** (`memory: :low`) | **81 ms** | 1.1x | 7 |
+| **fast_xlsx** | **85 ms** | 1.1x | 10 |
+| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 173 ms | 2.3x | 561,740 |
+| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 204 ms | 2.7x | 20,079 |
+| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 238 ms | 3.2x | 320,076 |
+| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 592 ms | 7.9x | 1,483,899 |
+| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 671 ms | 8.9x | 745,122 |
+| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2571 ms | 34.1x | 8,700,448 |
 
 All outputs are 689–750 KB.
 
@@ -448,8 +467,8 @@ BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb f
 
 - **Ruby:** CRuby 3.3 and later. A Ruby version is dropped only after it reaches its end of life, and only in a minor release. JRuby and TruffleRuby are not supported (this is a native extension).
 - **Precompiled gems:** Linux (x86_64 and aarch64, glibc and musl; ARM musl), macOS (arm64 and x86_64) and Windows (x64). Before each release the Linux x86_64, macOS arm64 and Windows gems are installed and loaded on Ruby 3.3, 3.4 and 4.0. Other platforms build from source and need a Rust toolchain.
-- **Versions:** from 1.0, [Semantic Versioning](https://semver.org): no breaking API change before 2.0. Until then a minor release (0.x.0) can change behaviour; the [changelog](CHANGELOG.md) lists every change under "Changed".
-- **Deprecations:** from 1.0, a method or option to be removed first prints a warning (with `warn`, so on by default) for at least one minor release, with the CHANGELOG naming its replacement; it goes only in the next major version.
+- **Versions:** [Semantic Versioning](https://semver.org) since 1.0: no breaking API change before 2.0. The [changelog](CHANGELOG.md) lists every change.
+- **Deprecations:** a method or option to be removed first prints a warning (with `warn`, so on by default) for at least one minor release, with the CHANGELOG naming its replacement; it goes only in the next major version.
 - **Output:** `.xlsx` files that open in Excel 2007 and later, LibreOffice and Google Sheets. Updating rust_xlsxwriter can change the bytes of the file but not what it contains.
 
 ## Development
@@ -498,6 +517,10 @@ git tag v0.1.0 && git push origin v0.1.0
 
 The `Build gems` workflow builds the source gem plus precompiled gems for each platform and pushes them to RubyGems (trusted publishing) and GitHub Packages. It refuses to publish if the tag and `VERSION` differ.
 
+## Credits
+
+Inspired by [fast_excel](https://github.com/Paxa/fast_excel), whose API and approach fast_xlsx builds on, and made possible by [rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter) and [magnus](https://github.com/matsadler/magnus).
+
 ## License
 
 MIT

data/SECURITY.md

@@ -0,0 +1,26 @@
+# Security policy
+
+## Supported versions
+
+Security fixes go into the latest release of the newest minor version. Until 1.0 that is 0.8.x; from 1.0, the latest 1.x.
+
+| Version | Supported |
+|---|---|
+| 0.8.x | ✅ |
+| < 0.8 | ❌ (upgrade to 0.8.x; the [changelog](CHANGELOG.md) lists every change) |
+
+## Reporting a vulnerability
+
+Please don't open a public issue. Report it privately through GitHub: on the repository's **Security** tab, choose **Report a vulnerability** ([direct link](https://github.com/7a6163/fast_xlsx/security/advisories/new)).
+
+Include what an attacker could do, the fast_xlsx, Ruby and platform versions, and a script or input that shows it, if you have one.
+
+What to expect:
+
+- An acknowledgement within a week.
+- A fix in a patch release, and a GitHub security advisory crediting you (unless you'd rather not be named), once users can upgrade.
+- If it turns out to be in a dependency (rust_xlsxwriter, magnus, rb-sys, the Rust zip crates), a report to that project as well.
+
+## Scope
+
+fast_xlsx only writes `.xlsx` files: it doesn't read or parse spreadsheets. Issues of interest include memory-safety bugs in the native extension (a crash or corruption reachable from Ruby), and output that makes Excel or other readers misbehave from data an application would reasonably pass in (cell text, formulas, URLs, images). Formulas and hyperlinks are written as given: an application writing untrusted input as a `FastXlsx::Formula` or `FastXlsx::URL` should validate it first, as with CSV formula injection.

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.8.0)
+    fast_xlsx (0.8.1)
       rb_sys (~> 0.9.130)
 
 GEM
@@ -77,7 +77,7 @@ DEPENDENCIES
 CHECKSUMS
   caxlsx (4.5.0) sha256=e3d98d859f148df05d5462086b5079b523f29c1766b569535f1d68629ce743ff
   fast_excel (0.5.0) sha256=59c418bdcf586a6030798d4e3a9f575742badaceaf7bb90f38eee5feb5bdc478
-  fast_xlsx (0.8.0)
+  fast_xlsx (0.8.1)
   ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
   ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39
   ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564

data/docs/MIGRATING_FROM_FAST_EXCEL.md

@@ -4,7 +4,7 @@ fast_xlsx started as a rewrite of [fast_excel](https://github.com/Paxa/fast_exce
 
 **Why switch**
 
-- 2.8–3.3× faster on the [README benchmark](../README.md#speed), and `memory: :constant` adds about 1 MB however large the file.
+- Faster writing (see the [README benchmark](../README.md#speed)), and `memory: :constant` adds about 1 MB however large the file.
 - Precompiled gems for Linux, macOS and Windows: no C compiler or FFI at install.
 - Dates show as dates without a format, every option is checked (a typo raises instead of being ignored), and saving doesn't block other threads.
 - Conditional formats, data validation, tables, charts, images, comments, protection and printing options as Ruby methods.

data/lib/fast_xlsx/version.rb

@@ -2,5 +2,5 @@
 
 module FastXlsx
   # The gem version.
-  VERSION = "0.8.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: fast_xlsx
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 1.0.0
 platform: aarch64-linux
 authors:
 - Zac
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies: []
-description: Writes Excel .xlsx files from Ruby through a native Rust extension (rust_xlsxwriter
-  + magnus).
+description: 'Writes Excel .xlsx files from Ruby through a native Rust extension (rust_xlsxwriter):
+  20,000 rows in under 100 ms, and memory that stays flat for large exports. Formats,
+  formulas, tables, charts, conditional formats, data validation and more.'
 email:
 - 579103+7a6163@users.noreply.github.com
 executables: []
@@ -24,6 +25,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- SECURITY.md
 - bench/Gemfile
 - bench/Gemfile.lock
 - bench/compare.rb
@@ -68,5 +70,5 @@ requirements: []
 rubygems_version: 3.5.23
 signing_key: 
 specification_version: 4
-summary: Fast xlsx writer for Ruby, powered by rust_xlsxwriter
+summary: Excel .xlsx writer for Ruby with a Rust engine
 test_files: []