hucreを読む：XLSX処理をTypeScriptだけで組み立てる設計

hucreが解こうとしている配布と実行環境の問題

hucreは、純粋なTypeScriptで書かれた依存関係なしのスプレッドシートエンジンです。READMEの説明では、XLSX、CSV、ODS、JSON、NDJSON、XMLを読み書きし、スキーマ検証、ストリーム処理、ラウンドトリップ保存まで扱います。単にセルを二次元配列へ変換するだけでなく、表計算ファイルを複数の入出力形式へ橋渡しすることが中心です。

サブパスから機能を選べる点も設計上の特徴です。XLSXだけならhucre/xlsx、CSVだけならhucre/csv、ODSならhucre/ods、JSONとNDJSONならhucre/json、表形式XMLならhucre/xmlを読み込みます。READMEには、インポートした部分だけをバンドルするtree shakingを前提に、CSV処理約3.7KB、XLSX読み取り約34KB、読み書き約68KB、全体約129KBという計測値が記載されています。これはプロジェクト側の計測であり、利用するbundlerや設定を変えた独立測定ではありません。

XLSXの読み書きでモデル化される範囲

基本APIはreadXlsxとwriteXlsxです。読み取り時にはシートを番号や名前で絞り込み、スタイルを解析し、1900年系と1904年系の日付システムを自動判定できます。書き込み側は、シート名、列定義、行データを持つモデルからXLSXを構成します。READMEが列挙する機能には、結合セル、固定ペイン、オートフィルター、データ検証、ハイパーリンク、画像、コメント、テーブル、条件付き書式、名前付き範囲、印刷設定、シート保護、数値書式、非表示シート、スパークラインがあります。

ただし、列挙された機能がすべて同じ深さで新規作成できるとは限りません。条件付き書式には13種類のルールが示され、top10やaboveAverageは既定形式でのラウンドトリップに限られ、timePeriodルールは読み込み時に破棄されます。数式もhucreが計算するのではなく、式を保存してExcelなどの外部アプリケーションに計算を任せる扱いです。機能名だけで適合性を判断せず、必要な要素が読み取り、書き込み、保存のどこまで対応するかを確認してください。

大量行ではストリームAPIの選択が先になる

大きなワークブック向けには、読み取り用のstreamXlsxRows、書き込み用のwriteXlsxStreamとXlsxStreamWriterが用意されています。ストリーム読み取りはZIPアーカイブを順に解析し、ReadableStreamを直接受け取ります。アーカイブの構造上、一回の通過で処理できない場合だけバッファリングへ戻る設計です。書き込みはイテラブルから行を取り出すたびにバイトを出力するため、入力全体を同時にメモリへ置く方式とは性格が異なります。

READMEのNode 24計測では、5列の混合データを30万行処理した際、writeXlsxStreamのピークヒープは41MB、XlsxStreamWriterは328MBでした。100万行では67MBと1,037MBで、300万行ではバッファリング方式が現実的でないと説明されています。この比較は特定環境でのプロジェクト側測定です。実サービスへ入れる場合は、セル型、文字列の長さ、圧縮、同時処理数を含めて自分のデータで再測定してください。文字列は既定でインライン保存され、ZIP64は明示的に有効にしない限り使われず、圧縮は実行環境のCompressionStreamに依存します。

ラウンドトリップと再構築APIは目的が異なる

hucreには、既存ファイルの構造をできるだけ残すopenXlsxとsaveXlsxの経路と、モデルから新しいワークブックを組み立てるreadXlsxとwriteXlsxの経路があります。前者はhucreが再生成しない部品をバイト単位でコピーするため、チャート、VBAマクロ、未モデル化のコンテンツを編集後も残せます。後者はモデルが表現する要素だけで出力を再構成します。マクロ有効ファイルを維持したい場合、readXlsxとwriteXlsxではvbaProject.binを保持しない点が判断材料になります。

XLSとXLSBの読み取りにも対応しますが、扱えるのはシート名、セル値、結合範囲に限られます。数式はキャッシュされた値として現れ、式の文字列にはなりません。スタイル、列幅、行高、表示状態、名前付き範囲、ワークブックのプロパティは無視されます。つまり、古い形式からの変換は値とシートを取り出す作業であり、完全な見た目の複製ではありません。元ファイルの構造を保つ必要があるか、データだけ移せればよいかを最初に分ける必要があります。

ODS変換で静かに落ちる情報を先に列挙する

ODSのリーダーとライターは、同じ範囲の機能をモデル化しています。そのため、ODSを読み込んでODSへ保存する経路では、XLSXとの変換より情報のずれを抑えやすい構成です。値、数式、結合セル、太字、斜体、フォントサイズ、フォント色、背景色、数値書式は保持されます。

一方、XLSXからODSへ変換すると、罫線、配置、列幅、固定ペイン、データ検証、名前付き範囲、画像、ページ設定が失われます。ODSリーダーはcontent.xmlとmeta.xmlを開き、styles.xmlやsettings.xmlを開かないため、LibreOfficeで作られた名前付きスタイルは直接設定された書式だけが読み戻されます。これは一時的な注意書きではなく、READMEが説明する現在のモデルの境界です。帳票をそのまま別形式へ渡す処理では、変換後の見た目とメタデータを実ファイルで照合する工程が必要です。

チャート、ピボット、CLIを採用判断に結び付ける

チャートは読み取り用のChartレコード、書き込み用のSheetChart、型付き上書きに使うcloneChartヘルパーでラウンドトリップします。新規作成できるチャートは棒、縦棒、折れ線、円、ドーナツ、散布、面の7種類で、それ以外は例外になります。読み取り側はコンボチャートなど追加の種類も解析できます。ピボットテーブルは構造を読み書きできますが、書き込み側はキャッシュ、レイアウト、関連付けを出力し、事前計算済みの値セルは作りません。初回にExcelが開いた時点で値が計算されます。

高レベルAPIのreadとwriteは形式を自動検出し、readObjectsとwriteObjectsはヘッダー付きの表とオブジェクト配列を変換します。CLIはnpx hucreで使え、convert、inspect、validateを提供します。XLSとXLSBは入力として読めますが、出力はXLSX、ODS、CSV、TSVなどに限られます。HTMLとMarkdownの出力やfromHtmlもありますが、READMEはfromMarkdownがなく、fromHtmlもtoHtmlの逆変換ではないと説明しています。hucreは形式を一つに統一する道具ではなく、必要な保持範囲を見極めて使う部品です。

MITライセンスと公開情報から見えない部分

プロジェクトのライセンスはMITです。再利用、変更、再配布の自由度を確認する出発点にはなりますが、利用者の業務データに対する適合性や運用支援まで示すものではありません。READMEには、本番サポート、セキュリティ監査、長期保守計画についての詳しい記述はありません。そこをプロジェクトの説明から補って断定することはできません。

採用前の確認順は、まず対象形式と必要な保存要素を表にし、次にストリーム処理が必要な行数でメモリを測り、その後にマクロ、チャート、ピボット、スタイル、数式の往復を試すのが現実的です。公開リリースにはv1.1.0、v1.0.0、v0.6.2などが記録されていますが、版を固定するだけではファイル互換性は証明されません。実際に使う版、実データ、実行環境を組み合わせて確認してから導入範囲を決めてください。

編集部の結論

hucreは、TypeScriptの実行環境で表計算データを読み書きし、必要な形式だけを小さく取り込みたい開発者に合います。採用前には対象ファイルのチャート、マクロ、罫線、名前付き範囲、数式キャッシュを実データで確認してください。READMEが明記する変換の制限を受け入れられない業務では、別のライブラリや形式別の処理を比較してから決めるべきです。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes