パッケージと実行入口
| 実行入口 | パッケージ | 実行環境 |
|---|---|---|
| JavaScript / WASM | @libraz/formulon | ブラウザ、ワーカー、Node |
| Native Node | @libraz/formulon-native | Node.js N-API アドオン。npm には公開していないため、ソースからビルドします（Native Node）。リリース CI は darwin-arm64、linux-x64、linux-arm64 向けにビルドします |
| Python | formulon | wasmtime で動く py3-none-any wheel |
| CLI | GitHub Releases の formulon-<version>-<os>-<arch>.tar.gz | 単体の formulon バイナリ。darwin-arm64、linux-x64、linux-arm64 向け |
| C ABI | src/c_api/formulon_c.h と formulon_static（または共有ライブラリの formulon） | 独自ホスト向け。ソースからビルドします |
| MCP | @libraz/formulon-mcp | エージェント向け stdio MCP サーバー |
| 表計算 UI | @libraz/formulon-cell | ブラウザ向け表計算 UI キット |
すべての実行入口は同じ計算コアを呼び出します。違いはパッケージ構成、ホスト言語、メモリ所有権と、後述のメソッド差分です。
formulon-cell と formulon-mcp は C ABI に直接接続せず、WASM パッケージの上に構築されています。ブラウザや Node から @libraz/formulon を使う場合と同じ経路で計算コアに到達します。
用語: 実行入口
共有する C++17 計算コアを各ホスト環境から呼び出すためのパッケージ境界です。WASM、Python、CLI などは、直接または間接に C ABI 経由で同じコアを呼びます。ホスト言語、メモリ所有権、入出力の形、文書化された互換性の境界は実行入口ごとに異なる場合がありますが、共通の数式挙動は共有コアが定めます。
実行入口ごとの成熟度
| 実行入口 | 成熟度 | 補足 |
|---|---|---|
| WASM | 最も広い JS API | 生成された formulon.d.ts。ブラウザ、ワーカー、Node 対応 |
| Python | 広いワークブック API | wasmtime で動くラッパー。with ブロックを抜けるとワークブックを解放 |
| CLI | 用途を絞ったツール | eval / recalc / dump / paginate |
| Native Node | WASM と同じメソッド構成のネイティブバイナリ | 戻り値の形と値の意味は WASM と同じ。違いは下表のとおり |
| C ABI | 低レベル API 境界 | 他の実行入口が包んでいるすべての関数 |
| MCP | エージェント向け API | WASM の上に構築し、許可リストに基づいて呼び出す |
formulon-cell | UI キット | TypeScript、React、Vue から埋め込める表計算 UI |
メソッド差分
3 つのライブラリ用バインディングは、ワークブックモデル、ジオメトリ、テーマとスタイル、型付き AutoFilter、入力規則、コメント、画像、ピボットテーブル、印刷設定、プロファイル関連のヘルパーを共通で持ちます。違いがあるのは次の項目です。
| 機能 | WASM | Native Node | Python |
|---|---|---|---|
| ワークブックの解放 | delete()。メソッド実行中は TypeError | dispose()（GC による最終化は予備）。メソッド実行中は TypeError | close() または with ブロック |
| メモリ使用量の推定 | — | memoryUsage() | memory_usage() |
| 並列再計算 | recalcParallel()。ワーカーを使うのは @libraz/formulon/threads だけ | recalcParallel() | — |
| スカラーの読み取り専用評価 | evaluateFormulaText() | evaluateFormulaText() | —（evaluate_formula_array() を使う） |
| 反復計算の進捗コールバック | setIterativeProgress() | setIterativeProgress() | — |
| ログの受け取り先 | setLogSink() | setLogSink() | —（set_log_min_level() のみ） |
| テーブルの作成 | createTable() / updateTable() / removeTable() | — | table_create() / table_update() / table_remove() |
| シートの AutoFilter XML | getSheetAutoFilterXml() / setSheetAutoFilterXml() | — | get_auto_filter_xml() / set_auto_filter_xml() |
| 名前付きスタイルの XF レコード | addCellStyleXf() | — | add_cell_style_xf() |
| スタイルの一括登録、有効化だけの反復切り替え | — | — | add_batch()、set_iterative_enabled() |
引数の契約はバインディング間で共通です。2 つの JS パッケージは、エンジン呼び出しの前にすべての位置引数を検査します。引数の欠落、型の誤り、オブジェクトが宣言された位置へのプリミティブまたは null は TypeError で、どちらのパッケージも既定値で補いません。メソッドがステータスで報告する不正な引数は、どちらも kInvalidArgument（2）を返します。@libraz/formulon-native の TypeScript 宣言は @libraz/formulon と同じ列挙型（PivotAxis、PivotAggregation、PivotSortOrder など）を使うため、一方のパッケージの型で書いたコードは他方でもコンパイルできます。Python は Value のペイロードを検証し（ValueError または TypeError）、整数引数の範囲を検査します（ValueError）。C ABI は不正な UTF-8 を kBindingUtf8EncodingError（7002）で拒否し、インデックス、個数、アウトラインレベルの引数の範囲を検査します。どのバインディングもこれらのステータスを返します。C の公開レコードは固定レイアウトなので、ネイティブのクライアントはリンクするヘッダーに合わせて再コンパイルする必要があります。
CLI が公開するのは一部だけです。並列再計算の --threads、--iterative、4 つのサブコマンドがあります。
実行入口ごとの結果が食い違ったとき
同じワークブック・同じプロファイルで 2 つの実行入口が異なる値を返したら、不具合か、文書化された互換性差分として扱います。リポジトリの make parity-test は、CLI、npm の WASM パッケージ、Python wheel で共有の検証用ワークブックを評価し、ビルドされていないチャネルと値の不一致を分けて報告します。その他の違いはネイティブスレッド、コピーコスト、WASM のメモリ上限などの運用面です。
次に読むもの
- WASM API ─ JavaScript API
- Python API ─ トップレベルラッパー
- CLI リファレンス ─ コマンド API
- 実行入口を選ぶ ─ 判断ガイド