ライブラリ API リファレンス

このページの環境プロファイル・字句短縮・診断統一は、Storm Lua EngineのSDK統合ブランチに対応する実装の仕様です。既存の公開済みパッケージへ遡って適用されるものではありません。同じ版のSDKとStorm Minを使用してください。

@stormcat-works/stormmin が公開する関数は次の 6 つです。

compile(source: string, options?: CompileOptions): Promise<CompileResult>
compileProject(project: LuaProject, options?: ProjectCompileOptions): Promise<ProjectCompileResult>
analyze(project: LuaProject, options?: AnalyzeOptions): Promise<AnalyzeResult>
scanProperties(source: string): Promise<PropertyScanResult>
passMetadata(): Promise<PassMetadataEntry[]>
terminate(): void

CompileOptions

compile()/compileProject() に渡すオプションです。すべて省略可能です。

フィールド	型	既定値	説明
`mode`	`"smallest" \| "safe"`	`"smallest"`	`smallest` は aggressive なサイズ最小化。`safe` は host math の差などに対して保守的な変換だけを使用します。
`property`	`PropertyConfig`	`{ mode: "runtime" }`	`property.get*` の扱い。下記参照。
`zeroCostNewlines`	`boolean`	`true`	文字数コストがゼロの位置に改行を入れるかどうか。
`passToggles`	`Record<string, boolean>`	`{}`	個別 pass の有効/無効。未知・廃止済みのpass IDはエラーになります。
`numericMode`	`"tolerant" \| "exact"`	`"tolerant"`	`tolerant` は `numericTolerance` の範囲内での近似を許可。`exact` は近似やユニット再スケーリングなど exact semantics を保証できない pass を無効化します。
`numericTolerance`	`{ abs: number, rel: number }`	`{ abs: 0.000001, rel: 0.000001 }`（tolerant時）	数値近似を許容する絶対誤差・相対誤差。
`searchMode`	`"exhaustive" \| "fast"`	`"exhaustive"`	`fast` は簡易なサイズ見積りを使う bounded beam 探索。
`searchBeamWidth`	`number`	`4`	`fast` 探索時の beam 幅。1〜16 にクランプされます（小数は切り捨て後クランプ）。
`targetSize`	`number`	未指定	指定すると OBJ-2 satisfaction-style search が有効になります。詳細は目標サイズ探索を参照してください。
`sourceMap`	`boolean`	`false`	最適化後の Source Map v3 + `x_storm` provenance を生成します。
`sourceName`	`string`	`"input.lua"`	単一ファイル Source Map で使う原文ラベルです。

PropertyConfig:

フィールド	型	説明
`mode`	`"runtime" \| "hardcode"`	`runtime`（既定）は `property.getNumber()`/`property.getBool()` の呼び出しをそのまま維持します。`hardcode` は指定した builtin property read だけを literal 化します。シャドウされたローカル `property` は対象外です。
`numbers`	`Record<string, number>`	`hardcode` 時に使う数値プロパティの値。
`bools`	`Record<string, boolean>`	`hardcode` 時に使う真偽値プロパティの値。
`texts`	`Record<string, string>`	`hardcode` 時に使う文字列プロパティの値。

numericMode を省略し、かつ numericTolerance を { abs: 0, rel: 0 } と明示した場合は exact モードとして扱われます。

pack/unpack、bit 演算、index、numeric-for の境界など exact route に到達する binding は、tolerant モードでも近似の対象になりません。廃止済みのgeneral-expression-factoring、repeated-expression-factoring、scalar-vector-loop-synthesis、redundant-nil-fallback-eliminationは、true/falseのどちらを指定してもunknown-optimization-passになります。現在の登録は67件です。表示用のpassMetadata()は、全登録ID一覧と同じではありません。Engine SDKの全IDはpassIds()で取得できます。 numericMode: "exact"では、その意味論に合わない変換だけを無効化します。一部パスはexact-safeな部分だけを利用します。実際のdisabledPassesと数値前提を確認してください。環境設定にはenvironment?: "game" | "extended"（既定game）とhostBindings?: string[]があります。ホスト値・関数のdot区切りパスを宣言するにはextendedが必要です。実行環境と同じ設定を渡してください。extendedと_ENV入力はトークンと行番号を保つ字句短縮を使います。

CompileResult

フィールド	型	説明
`ok`	`boolean`	成功したかどうか。
`error`	`string`（非推奨）	失敗時のエラーメッセージ。
`code`	`string`	minify 後の Lua コード（成功時）。
`map`	`string`	`sourceMap: true` のとき、`code` と対応する最適化後 Source Map JSON。
`original`	`number`	元のコードの長さ（UTF-16 コード単位）。
`size`	`number`	出力コードの長さ（UTF-16 コード単位）。
`saved`	`number`	`original - size`。
`baseline`	`number`	入力をトークン単位で素朴に minify したときの長さ。削減効果の比較基準です。
`elapsedMs`	`number`	実行時間（ミリ秒）。
`passes`	`PassRecord[]`	実行された各 pass の記録。
`diagnostics`	`Diagnostic[]`	診断（警告・エラー）の一覧。
`search`	`SearchStats`	探索の統計情報。下記参照。
`apiAliases`	`string[]`	適用された API エイリアス化の一覧。
`disabledPasses`	`string[]`	実際に無効化された pass の一覧（既定無効・`exact` モード起因を含む）。
`assumptions`	`Assumptions`	この結果が前提とした数値意味論。下記参照。
`propertyMode`	`"runtime" \| "hardcode"`	適用された property モード。
`propertyReadsHardcoded`	`number`	hardcode 化された property read の件数。
`zeroCostNewlines`	`number`	ゼロコスト位置として改行に変換された箇所の数。

PassRecord:

{ name: string; saved?: number; detail?: string; elapsedMs?: number }

Assumptions:

{
  finiteNumbers: boolean;
  integerFloatSubtypeMayChange: boolean;
  numericMode: "exact" | "tolerant";
  numericTolerance: { abs: number; rel: number };
}

SearchStats:

フィールド	型	説明
`mode`	`"exhaustive" \| "fast" \| "satisficing"`	実際の経路。通常の目標サイズ探索は`satisficing`、意味を保持する字句短縮は`lexical`です。
`beamWidth`	`number \| null`	`fast` 探索時（satisficing でない場合）の beam 幅。
`candidates` / `attempted`	`number`	候補数・試行数。
`parseRejected` / `semanticRejected`	`number`	パース/意味検証で棄却された候補数。
`coreVariants` / `structuralVariants` / `structuralExplored`	`number`	探索段階ごとの候補数。
`structural` / `layout`	`string`	採用された候補の structural/layout バリアント名。
`candidateSizes`	`{ structural: string, layout: string, size: number }[]`	各候補のバリアント名とサイズ。
`targetSize` (`number`) / `targetMet` (`boolean`) / `stoppedEarly` (`boolean`) / `checkpoints` (`number`) / `stage` (`string`)	—	`targetSize` 指定時（satisficing）のみ含まれるフィールド。目標サイズ探索を参照してください。

ProjectCompileOptions / ProjectCompileResult

ProjectCompileOptions は CompileOptions に minify?: boolean（既定 true）を加えたものです。 ProjectCompileResult は CompileResult の統計フィールドに加えて、次を含みます。

フィールド	型	説明
`map`	`string`	Source Map v3 の JSON 文字列。`minify: false` では従来どおり生成され、`minify: true` では `sourceMap: true` のとき含まれます。
`usedModules`	`string[]`	実際にリンクに使われたモジュールキーの一覧。
`injectedAmbient`	`Record<string, string[]>`	注入された ambient 名前空間のメンバー一覧。

失敗時（ok: false）は diagnostics のみが返され、code/map は含まれません。

analyze / AnalyzeResult

analyze(project: LuaProject, options?: AnalyzeOptions): Promise<AnalyzeResult>

AnalyzeOptions: { disabledRules?: string[] } AnalyzeResult: { ok: boolean; diagnostics: Diagnostic[] } ok は内部エラーの場合にのみ false になります。Lua の構文エラーは ok: true のまま diagnostics に syntax-error として報告されます。

Diagnostic

compile()/compileProject()/analyze() すべてで共通のスキーマです。

{
  code: string;
  severity: "error" | "warning" | "info";
  message: string;
  module?: string;
  range?: { line: number; col: number; endLine?: number; endCol?: number };
}

code は安定な kebab-case 識別子で、廃止されることはあっても意味の変更・再利用はされません。message は常に英語固定で、ローカライズが必要な場合は code をキーにします。診断コードの一覧は診断コードリファレンスを参照してください。

LuaProject

interface LuaProject {
  entry: string;
  modules: Record<string, string>;
  ambient?: Record<string, AmbientNamespace>;
}

interface AmbientNamespace {
  members: Record<string, AmbientMember>;
}

type AmbientMember =
  | { kind: "module"; source: string }
  | { kind: "environmentOnly" };

モジュールキーの命名規則は require によるモジュール分割を参照してください。

scanProperties / passMetadata

scanProperties(source: string): Promise<{
  ok: boolean;
  numbers: string[];
  bools: string[];
  texts: string[];
  dynamicCount: number;
}>

passMetadata(): Promise<{ id: string; recordName: string }[]>

scanProperties はソース中の property.get* 呼び出しを検出し、種類ごとのキー一覧と、動的（キーが定数でない）呼び出しの件数を返します。passMetadata は全 pass の ID と表示名のペアを返します（同じ pass ID が複数の表示名で登場することがあります）。どちらも Node.js / ブラウザの両方で利用できます。

terminate

terminate(): void

ブラウザでは内部の Worker を終了し、保留中の呼び出しをすべて reject します。Node.js では no-op です。

はじめに

ガイド

リファレンス

FAQ・トラブルシューティング

ライブラリ API リファレンス

CompileOptions

CompileResult

ProjectCompileOptions / ProjectCompileResult

analyze / AnalyzeResult

Diagnostic

LuaProject

scanProperties / passMetadata

terminate

​CompileOptions

​CompileResult

​ProjectCompileOptions / ProjectCompileResult

​analyze / AnalyzeResult

​Diagnostic

​LuaProject

​scanProperties / passMetadata

​terminate

CompileOptions

CompileResult

ProjectCompileOptions / ProjectCompileResult

analyze / AnalyzeResult

Diagnostic

LuaProject

scanProperties / passMetadata

terminate