FAQ
エンジンと互換性
Excel 本体は必要ですか？
実行時には不要です。Formulon は Excel、COM、Microsoft ランタイムを起動せず、ワークブックの読み込み、数式評価、再計算、保存を Formulon 内で行います。
Excel を使うのは、開発・検証時に Oracle データ（実 Excel が返した参照値）を取得するときです。Windows Excel ブリッジによるピボットテーブルと印刷ページ分割の検証もテスト用の仕組みであり、本番実行時の依存ではありません。
既定の互換性プロファイルは？
既定は win-365-en_US です。Windows 版 Excel 365 の米国英語ロケール相当を基準にします。Mac と Windows で 14 ロケール、計 28 種類のプロファイルを選べます。対応一覧と実測・推定の区別はロケールプロファイルを参照してください。
Excel 関数は何件使えますか？
Formulon は 526 件の Excel 関数名を認識します。そのうち 511 件が実装済みで、この中には環境に依存する CELL / INFO の 2 件も含まれます。残る 15 件は、関数名と引数を認識して利用不可のエラーを返す外部サービススタブです。
外部サービススタブには COPILOT、PY、IMAGE、RTD、STOCKHISTORY、WEBSERVICE、TRANSLATE、DETECTLANGUAGE、CUBE 関数群があります。名前と引数の形は認識しますが、ローカルでは実行しません。詳しくは 数式カバレッジ。
COPILOT、PY、STOCKHISTORY、WEBSERVICE は実行できますか？
できません。これらは Microsoft 365 のクラウドサービス、クラウド Python 実行環境、市場データサービス、HTTP 通信、OLAP 接続など、Formulon の外にある実行環境を必要とします。
Formulon はこれらの関数名を認識し、未対応サービスのエラーを返します。外部サービスを内蔵したり、代替サービスへ接続したりする機能はありません。
数式の結果は Excel と完全に一致しますか？
Formulon は win-365-ja_JP などのプロファイルごとに、実 Excel から取得した Oracle データと突合します。ただし、すべてのワークブックについて無条件に同一結果を保証するものではありません。ロケール依存、揮発性関数、外部サービス依存、ファイル構造、Excel 側の未文書挙動は差分要因になります。
実 Excel を参照実装とし、その実測挙動を Oracle データとして取得します。それを win-365-ja_JP のような名前付きプロファイルにまとめ、参照実装との差分のうち許容するものは理由と最終確認済みの Excel ビルドとともに divergence.yaml に記録します。説明のつかない不一致として Formulon の出力に残すのではなく、明示的に管理する仕組みです。パイプライン全体は Oracle テスト を参照してください。
業務上重要なワークブックは、対象プロファイルと Formulon のバージョンを固定し、代表的な検証ファイルを持つ運用にしてください。
Excel 全体をクローンしようとしているのですか？
いいえ。Formulon は画面を持たない（ヘッドレスな）計算・ワークブック処理エンジンです。Excel のデスクトップ UI、グラフ描画、VBA 実行環境、Power Query、外部データ更新、旧 .xls の処理は対象外です。
.xlsx / .xlsb を読み込み、ローカルで数式を計算し、対応するワークブック構造を保持して保存します。同じコアを WASM、Python、CLI、Native Node、MCP から利用できます。
Excel、オフィスソフト、数式ライブラリ、クラウド表計算 API ではだめですか？
用途に応じて選んでください。VBA、Power Query、外部データ接続、最終的な見た目の確認が必要なら Excel が適しています。デスクトップのオフィスソフトは、ファイルの一括変換に向く場合があります。数式だけが必要で .xlsx の読み込み・保存がいらないなら、数式専用のライブラリで足ります。クラウド表計算 API は、データがすでにそのサービスにある場合に便利です。
Formulon は別の場所を狙っています。デスクトップアプリを自動操作したり、ワークブックをホスト型表計算サービスへ送ったりせず、ローカルで組み込める .xlsx 計算とワークブック変更が必要なアプリケーション向けです。
Excel 互換はそもそも無理では？
Excel の全機能に対する互換性は保証していません。Formulon は対象の Excel 環境をプロファイルで指定し、実際の Excel の結果を Oracle データとして記録して、許容する差分を明示します。
揮発性関数、文書化されていない型変換、ロケール依存の書式、浮動小数点の丸め、外部サービスなどには差分が残る可能性があります。また、ファイル内のデータを保持できても、その機能を実行できるとは限りません。実際に使うワークブックで検証してください。
どのロケールが実測で、どれが推定ですか？
数式 Oracle は対応する全 14 ロケールの Mac Excel 365 で取得し、いずれも CI の検証対象です。プライマリは mac-365-ja_JP です。win-365-ja_JP は Windows で実測しており、Windows COM ブリッジで取得するピボット・印刷のワークブック Oracle のプライマリでもあります。ほかの 13 種類の Windows プロファイルは、Mac での取得結果と既知のホスト差から推定しています。ロケールによって、区切り文字、真偽値とエラーの表記、日付の解析、テキスト書式、コードページ、関数名の表示、文字列の比較が変わります。
ファイル形式とワークブック機能
読み書きできるファイル形式は？
WASM、Python、Native Node、CLI、MCP は .xlsx と .xlsb を読み込めます。入力形式はファイルの内容から判定します。出力形式を明示するには saveAs / save_as を使います。CLI は出力拡張子が .xlsb なら XLSB、それ以外は XLSX を選びます。MCP の出力先は .xlsx または .xlsb に限られ、それぞれの拡張子に対応する形式を選びます。
.xlsb（MS-XLSB）の対応範囲は機能によって異なります。モデル化して書き出す要素、内容を解釈せず保持する要素、保存を保留または省略する要素があります。非対応数式は保存済みの計算結果に置き換わる場合があります。最新の詳細は ファイル形式の比較表 を参照してください。saveWithDiagnostics / save_with_diagnostics では deferredFeatureCount などのカウンターから、保存を保留または省略したデータを確認できます。
XLSB のピボットキャッシュ定義、キャッシュレコード、ピボットテーブルは、対応するレコード形式なら評価できます。未対応の形式はスキップします。外部参照は [Book1.xlsx]Sheet1!A1 のようなブック名やパスを受け付け、XLSX・XLSB にリンク情報と一緒に保存できます。評価には取得済みの外部キャッシュ値を使い、リンク先のファイルは取得しません。ふりがなは、各注釈が対応する元の文字範囲も保持します。
.xlsm / .xltm のようなマクロ付き OOXML パッケージは、vbaProject.bin をバイト列として保持するテストがあります。ただし、VBA は実行しません。旧 .xls（BIFF / Excel 97-2003）は対象外です。
VBA は実行しますか？
実行しません。VBA プロジェクトは往復保存で保持できますが、マクロは一切実行しません。マクロがセル値やワークブックの状態を書き換える前提のワークブックでは、Excel と結果が変わる可能性があります。
Power Query、DAX、外部接続は使えますか？
使えません。Power Query、DAX、ライブ外部接続、Web / OData / OLAP からのデータ更新は Formulon の対象外です。外部データを更新したい場合は、上流で Excel や別のデータ処理基盤を使い、更新後の .xlsx を Formulon に渡してください。
ピボットテーブルは対応していますか？
ピボットキャッシュとピボットテーブルの構造保持、操作、レイアウト取得、キャッシュの参照元シート情報の取得、キャッシュ内の項目番号による絞り込みは、C API、Native Node、WASM、Python で使えます。XLSB のピボットテーブルは、対応するレコード形式なら評価できます。詳しくは ピボットテーブル。
ピボットキャッシュを元データから更新したり、外部データ接続を再実行したりする機能はありません。その処理は Excel で行ってください。
印刷設定や改ページは保持できますか？
.xlsx のページ設定、余白、ヘッダー / フッター、印刷オプション、プリンター設定、改ページのメタデータは読み込み・保存で保持できます。WASM、Native Node、Python、C ABI では、専用の設定メソッドで印刷設定を変更し、取得できます。paginate API は指定範囲の最初と最後のセルを含めてページ分割を計算します。
Formulon は印刷プレビュー UI や PDF レンダラーではありません。最終的なページ描画は Excel や別のレンダリング層で確認してください。
スプレッドシート UI はありますか？
Formulon 本体はヘッドレスエンジンです。セルグリッドの表示や操作 UI は本体の責務ではありません。
@libraz/formulon-cell は、React / Vue アダプターを備えたブラウザ向けの表計算 UI キットです。埋め込み、設定オプション、モーダル のガイドを参照してください。
シートを作り直さずに言語を変えられますか？
はい。Cell は 7 言語の UI 辞書を備え、instance.setLocale() でマウント済みの画面と計算プロファイルを連動させます。言語切り替えデモでは、同じワークブックの保存数式と表示数式を確認できます。エンジンを直接使う場合は、数式の言語 APIで各プロファイルの数式表記を変換できます。
ユーザーがアップロードした任意の .xlsx を安全に処理できますか？
任意のスプレッドシートファイルを無害なものとして扱わないでください。Formulon は VBA、Power Query、外部接続、HTTP 経由の数式関数を実行しません。ただし、複雑な ZIP / XML データを解析し、CLI や MCP ではファイルも読み書きします。
信頼できないアップロードを扱う場合は、Formulon をアクセス権限を制限したプロセスなどで実行し、ファイルサイズと実行時間に上限を設けてください。ブラウザではワーカーを使うと、解析や再計算を画面の処理から分離できます。パッケージのバージョンを管理し、更新時も代表的なファイルで検証してください。
チャート、図形、画像、書式は再計算されますか？
Formulon の計算エンジンは多くのワークブック構造を読み取り、書き込み、保持できますが、保持することは描画や意味の解釈とは異なります。エンジン自体はグラフや図形を描画せず、印刷品質の PDF も生成しません。また、IMAGE 関数による画像取得も行いません。ブラウザーでグラフを表示するスプレッドシート UI には formulon-cell を使えます。
見た目の最終確認には Excel または別のレンダリング層を使ってください。Formulon は計算とワークブック変更のためのものです。
実行環境とパッケージ
なぜコアは C++17 なのですか？
C++17 を選んだのは、複数の環境に移植しやすくするためです。同じ計算ソースから、Emscripten / WASM、npm、PyPI、CLI、ネイティブ組み込み向けにビルドします。コアのビルドには C++17 対応のコンパイラが必要です。
実装では、C ABI、戻り値によるエラー処理、インライン化の抑制、WASM のサイズ上限によって、バインディングと生成物を管理します。C++17、Expected<T, Error>、コアでの例外・RTTI の不使用、Google スタイルの書式設定を共通の規約にしています。
なぜ Rust ではないのですか？
Rust のメモリ安全性には利点があります。Formulon では、OOXML の解析、ZIP 処理、正規表現、数値変換に miniz、pugixml、PCRE2、double-conversion などの C / C++ ライブラリを使っています。C++ で実装すると、それらを呼び出すための言語間の接続層を増やさず、C ABI、Emscripten、ネイティブ組み込みにも対応できます。
互換性の難所は、Excel の型変換、エラー伝播、ロケール、日付、動的配列、OOXML の読み込み・保存などの挙動を再現することです。Rust を選んでも、その検証作業は必要です。Formulon は既存の C++17 実装を、書式チェック、Oracle データとの比較、CTest で検証する構成を採用しています。
どの実行環境を選べばよいですか？
アプリケーションを動かす環境で選びます。
| 用途 | 推奨パッケージ |
|---|---|
| ブラウザ上で計算したい | @libraz/formulon（WASM） |
| ネイティブアドオンを使わず Node.js で計算したい | @libraz/formulon（WASM） |
| ソースからビルドして Node.js でネイティブ実行したい | @libraz/formulon-native（packages/npm-native からビルド） |
| Python バッチやノートブックで使いたい | formulon（PyPI） |
| CI やシェルから使いたい | GitHub Releases の CLI |
| AI エージェントにワークブック操作を渡したい | @libraz/formulon-mcp |
詳しくは 実行入口を選ぶ を参照してください。
Python wheel に Cython / NumPy / pybind11 は必要ですか？
不要です。formulon の wheel は py3-none-any で、formulon_capi.wasm と純 Python ラッパーを同梱します。実行時依存は wasmtime です。Python 3.9 以上が対象です。
Native Node は WASM と同じ機能を全部使えますか？
共通の Workbook API を使えますが、一部の機能には違いがあります。ソースツリーの packages/npm-native は、createDefault / createEmpty / createForProfile / loadBytes でワークブックを作成・読み込みできます。ふりがな、反復計算設定の取得、シートの表示・非表示・再表示禁止、印刷設定、範囲への書式 ID の適用、ピボットキャッシュの項目操作、型付き AutoFilter、ジオメトリとテーマ、入力規則の検査、コメント、画像、setCellStyle にも対応しています。テーブルの作成、AutoFilter XML、addCellStyleXf は WASM のみです。
Native Node は dispose() で明示的にメモリを解放します。memoryUsage() はセル、共有文字列、保持する未解析データ、ワークブックのメタデータを含むメモリ使用量の推定値を返し、V8 にも外部メモリ使用量を報告します。解放し忘れた場合はガベージコレクションが処理します。同じワークブックのメソッドが実行中（たとえばコールバックの中）に dispose() を呼ぶと TypeError を送出し、ハンドルはそのまま残ります。WASM では delete() で解放し、同じ規則に従います。
ソースツリー内のパッケージをビルドし、実行環境に合う .node バイナリを配置できるなら Native Node を選べます。ネイティブスレッドの利用や、loadBytes / save でのメモリコピー削減を重視する用途向けです。ブラウザやネイティブアドオンを配置できない Node.js 環境では WASM を使います。
WASM と Native Node では不正な JavaScript 引数をどう報告しますか？
どちらのパッケージも、エンジン呼び出しの前にすべての位置引数を検査します。必須引数の欠落、プリミティブ型またはネストしたフィールドの型の誤り、オブジェクトが宣言された位置へのプリミティブまたは null は TypeError、有限でない値・小数・範囲外の整数は RangeError になります。欠落した引数を既定値で補うことはありません。ネストしたレコードも検査し、ワークブックを変更する前に失敗します。メソッドがステータスで報告する不正な引数は kInvalidArgument（2）を返します。位置引数の 64 bit カーソルやオフセットは Number.MAX_SAFE_INTEGER 以下に制限され、省略または null のオプション項目は宣言された既定値を使います。
loadBytes や画像 API などのバイト入力には Uint8Array が必要です。Node の Buffer は Uint8Array なので使えますが、文字列は使えません。ネストした文字列項目は JavaScript の文字列または 1 バイトバッファーを受け取り、Native Node では Buffer も該当します。任意のオブジェクトを暗黙に文字列化することはありません。これらのバインディング入力エラーは、ステータスの戻り値、ホスト失敗、Excel のセルエラー値とは別のものです。
オフラインで動きますか？
ローカル計算はオフラインで動きます。WASM、Python、Native Node、CLI は、渡された数式やワークブックのバイト列をローカルで処理します。
外部サービス関数（WEBSERVICE、STOCKHISTORY、TRANSLATE、COPILOT など）は、オフラインでもオンラインでも Formulon では実行しません。
ワークブックデータはどこかに送信されますか？
コアエンジンはワークブックのバイト列をローカルで処理します。WASM、Python、Native Node、CLI の計算に Formulon 側のホストサービスは不要です。
ただし、ホストアプリケーションをそのように作れば、ファイルを外部に送ることはできます。MCP の運用も、エージェントに与えるクライアント権限とファイルシステム権限に依存します。
ブラウザでは COOP / COEP ヘッダーが必要ですか？
このヘッダーが必要なのは pthread 版の WASM だけです。既定の @libraz/formulon は共有メモリを使わず、ブラウザのクロスオリジン分離を必要としません。ワーカーによる並列実行には @libraz/formulon/threads を読み込んでください。ブラウザでは SharedArrayBuffer が必要なので、通常はページを次のヘッダー付きで配信します。
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corpこれらのヘッダーがない場合、@libraz/formulon/threads は pthread プールを初期化できず、初期化関数が失敗します。既定の @libraz/formulon にヘッダーは必要ありません。UI キットの設定は formulon-cell のバンドラ設定 を参照し、エンジン初期化の失敗は onError または try / catch で処理してください。
Vite のビルド警告は問題ですか？
ブラウザ向けのバンドラーでは、node:module や node:worker_threads をブラウザ用の出力から除外したという警告が出ることがあります。WASM の初期化コードには Node.js 用の分岐があり、threads 版には node:worker_threads の分岐も含まれるためです。ブラウザでは使わない分岐なので、多くの場合は動作に影響しません。
ビルドが失敗する場合は、ワーカーを ES モジュール形式にし、ビルドターゲットを es2022 以上にしてください。詳しくは トラブルシュート。
使いどころ
どんな用途に向いていますか？
Excel ワークブックをアプリや業務フローの一部として扱う用途に向いています。たとえば、ブラウザ上の見積もり・料金計算、サーバー側の帳票計算、CI での計算差分検査、Python バッチ、AI エージェントによるワークブック編集です。
反対に、Excel そのものを置き換えるデスクトップ UI、VBA 実行環境、Power Query / DAX 実行基盤、外部データ接続の更新基盤として使うものではありません。用途別の詳しい紹介は 利用例 を参照してください。
速いですか？
処理速度はワークブックごとに変わります。ワークブックの構造、数式の種類、動的配列、共有数式、ファイルサイズに加えて、読み込み・再計算・保存のどこを測るか、呼び出し元の言語の処理時間を含めるかにも左右されます。
WASM、Python、CLI、Native Node は同じ C++ コアを使います。応答時間や運用コストを見積もるには、実際に扱う代表的なワークブックで測定してください。
本番投入できますか？
1.0 より前の開発段階です。数式エンジンは広い範囲を扱えますが、API とパッケージ構成は今後変わる可能性があります。業務上重要な用途では、Formulon のバージョンと対象プロファイルを固定し、代表的なワークブックで継続的に検証してください。
本番で使いやすい領域は、入力ワークブックの形式と数式範囲を管理できるサーバー処理、CI、社内ツール、組み込み計算です。任意の Excel ファイルを完全互換で処理する汎用 Excel 代替としては扱わないでください。
実際の組み込みで壊れやすいのはどこですか？
よくある失敗は単純な四則演算ではありません。未対応の外部データ更新、マクロへの暗黙依存、ロケール依存のパース、揮発性関数、隠れたワークブック状態、未対応のファイル構造、保持された表示オブジェクトがレンダリングまたは再計算されたという思い込みです。
まず代表的なワークブックを少数用意し、数式をダンプし、対象 Excel プロファイルと出力を比較し、そのファイルを CI に入れてください。
Microsoft Excel と法的に結びついていますか？
実行時に Microsoft のランタイム、サービス、SDK、製品ライセンスは必要ありません。Excel は開発時に Oracle データを取得するための参照実装として使います。
Excel は Microsoft の製品および商標です。Formulon は独立した Apache-2.0 プロジェクトであり、Microsoft Excel そのものでも、Microsoft が支援する実装でもありません。
AI / MCP
formulon-mcp とは？
@libraz/formulon-mcp は、Formulon のワークブック操作 API を stdio MCP サーバーとして公開するパッケージです。AI エージェントが .xlsx または .xlsb を開き、構造を調べ、セルやシートを編集し、文書を組み立てて装飾し、印刷設定を扱い、再計算して保存するための 47 個のツールを提供します。画像操作 では画像を取得・挿入・削除でき、プレビューは対応する画像を描画して描画オブジェクトとページのメタデータを返します。Node.js 22 以上が必要です。
npx -y @libraz/formulon-mcp詳しくは MCP。
エージェントから任意コードを実行できますか？
ツールからシェルや汎用のコード評価器を呼び出す機能はありません。MCP サーバーは入力を検証し、開いているワークブックを sessionId で識別します。低レベルの formulon_workbook_call も、formulon-mcp の src/session/workbook-call.ts にある許可リストの Workbook メソッドだけを呼び出します。セッション ID はワークブックの識別子であり、アクセス権限を制限する仕組みではありません。
ただし、MCP はファイルを読み書きするツールです。運用時は、MCP クライアント側の権限、作業ディレクトリ、扱うファイルの範囲を制御してください。
ライセンス
ライセンスは？
formulon、formulon-cell、formulon-mcp は Apache-2.0 です。ライセンス条文の範囲で使用、改変、再配布できます。