zfb-md-wasm
@takazudo/zfb-md-wasm のリファレンス — zfb の markdown/MDX パイプラインの WebAssembly ビルド。エクスポート、async のシグネチャ、オプション / 結果の型(ZfbMdWasmOptions、ParseDialect、PipelineOptions、Diagnostic、ParseToAstOptions、HighlightCodeOptions、HighlightRole)、生の mdast の形、パッケージのエントリポイント。
概要
@takazudo/zfb-md-wasm は、zfb の markdown/MDX → JS/HTML パイプラインを WebAssembly にコンパイルして提供します。このページはシグネチャと型のリファレンスです。パッケージのインストール、ブラウザでのコンパイル済みモジュールの評価、JSX ランタイムの import map 設定、パリティ保証の制限といったナラティブな解説については、ブラウザでの Markdown プレビュー を参照してください。
このパッケージは、ビルド時に .wasm モジュールを SSR ルートへインポートすることとは無関係です — そちらは別の機能で、Wasm のインポート で扱います。
エクスポート
| エクスポート | シグネチャ | 説明 |
|---|---|---|
init | () => Promise<void> | wasm モジュールを事前にインスタンス化します。任意 — 他のすべての関数は、初回使用時にモジュールを遅延的に初期化します。 |
compile | (source: string, options?: ZfbMdWasmOptions) => Promise<CompileResult> | MDX → JSX → SWC → ES モジュール JS。 |
renderHtml | (source: string, options?: ZfbMdWasmOptions) => Promise<RenderHtmlResult> | Markdown → mdast → ビジター → hast → HTML 文字列。 |
parseToAst | (source: string, options?: ParseToAstOptions) => Promise<ParseToAstResult> | Markdown/MDX → 生の mdast ツリー、zfb ビジター適用前。 |
highlightCode | (code: string, options: HighlightCodeOptions) => Promise<HighlightCodeResult> | 任意のソース文字列に対する、直接的なセマンティッククラスのシンタックスハイライト。 |
version | () => Promise<string> | リリース時にスタンプされるパッケージのバージョン文字列。 |
toMdastRoot | (ast: MdastRoot | null) => Root | 生の parseToAst ツリーを検証し、厳密でエコシステム互換の mdast の Root へ変換します。唯一の同期エクスポートです。 |
ZfbMdWasmTrapError | class extends Error | wasm トラップ(Rust の panic / 内部障害)が発生したときにスローされます。スローの前にインスタンスは自動で再インスタンス化されます。 |
ZfbMdWasmTrapRecoveryLimitError | class extends Error | トラップ回復の上限(16 回)を使い切ったときにスローされます。 |
MdastAdapterError | class extends TypeError | サポートされていない、または不正なノードに対して toMdastRoot がスローします。 |
init、compile、renderHtml、parseToAst、highlightCode、version はすべて async です — 基盤となる wasm モジュールが既にインスタンス化されているかどうかにかかわらず、各呼び出しは Promise を返します。
Note
パーサー・オプションの診断と Promise の reject は別の経路です。Markdown のパースエラー、不正なオプション JSON、未知のテーマは、解決された結果の 構造化 diagnostics として返ります。一方、ネットワークやファイルの読み込み、glue の import、初期化、不正な JavaScript 値(JSON にシリアライズできないオプション値など) によって呼び出しが reject することもあります。これらは通常の例外であり、必ずしも WASM トラップではありません。await 後は diagnostics を確認し、reject は catch、 リソースの解放や UI の処理中状態の解除は finally で扱ってください。
本物の WASM トラップは ZfbMdWasmTrapError / ZfbMdWasmTrapRecoveryLimitError と、エラークラスに記載した回数制限付きの回復契約に従います。 通常の読み込み・初期化失敗はこの回復回数に含まれません。失敗した初期化はクリアされ、 後続の呼び出しで再試行できます。
init()
function init(): Promise<void>wasm モジュールを事前にインスタンス化します。前もって呼び出すことで制御できるのは、fetch / コンパイルのコストが いつ 発生するかだけです — init() を一度も呼ばなかった場合、他のすべての関数は初回使用時にモジュールを遅延的に初期化します。
compile(source, options?)
function compile(source: string, options?: ZfbMdWasmOptions): Promise<CompileResult>MDX → JSX → SWC → ES モジュール JS。zfb 自身のビルドが使うのと同じエミッタです。options のデフォルトは {} です。development はここでのみ消費され、renderHtml は無視します。一方、dialect は renderHtml だけが消費し、compile は無視します。旧 jsxRuntime オプションは削除されました。エミッタは zfb 固有の JSX 方言を使い、v3 のオプション契約では旧フィールドを未知のものとして拒否します。
renderHtml(source, options?)
function renderHtml(source: string, options?: ZfbMdWasmOptions): Promise<RenderHtmlResult>Markdown/MDX → mdast → ビジター → hast → HTML 文字列。SWC を完全にスキップします。options のデフォルトは {} です。明示的な dialect がない場合、.md のファイル名は CommonMark、.mdx は MDX を選びます。filename を省略すると "<anonymous>.md" が使われるため CommonMark になります。dialect: "markdown" | "mdx" は、拡張子のゲートを免除せずに、どちらの有効な拡張子も上書きします。
parseToAst(source, options?)
function parseToAst(source: string, options?: ParseToAstOptions): Promise<ParseToAstResult>Markdown/MDX → 生の mdast ツリー。ZfbMdWasmOptions では なく、独立した閉じた ParseToAstOptions ドキュメントを受け取ります — その pipeline サブオブジェクトは gfm のみを受け付けます(バリデーションと位置の契約 を参照)。options のデフォルトは {} です。
highlightCode(code, options)
function highlightCode(code: string, options: HighlightCodeOptions): Promise<HighlightCodeResult>任意のソース文字列に対する、直接的なセマンティッククラスのシンタックスハイライト — Markdown のフェンスは関与せず、options のデフォルトもありません。language は必須です。
version()
function version(): Promise<string>リリース時にスタンプされるパッケージのバージョン文字列。公開されるアーティファクトはリリース時にパッケージの semver をスタンプします。ローカルの開発ビルドでは、Rust マニフェストのバージョンのプレースホルダにフォールバックします。
toMdastRoot(ast)
function toMdastRoot(ast: MdastRoot | null): Root // ecosystem "mdast" Root (@types/mdast)生の parseToAst().ast ツリーを検証し、切り離された @types/mdast 互換の Root を返します。型はエコシステムが使うのと同じ mdast / mdast-util-directive / mdast-util-mdx のコンテンツモデルレジストリに対して付けられます。この厳密なアダプタは、parseToAst が返す前方互換の生の階層とは意図的に分けられています。サポートされていない、または不正なノードは、黙って破棄されたり強制変換されたりするのではなく、MdastAdapterError を スロー します。同期処理であり、wasm の境界には一切触れません。
エラークラス
ZfbMdWasmTrapError extends Error— wasm トラップを観測した async 呼び出しがスローします。(cause: unknown)で構築され、.causeで公開されます。このエラーがスローされる 前 に、トラップしたインスタンスは破棄され、キャッシュ済みのコンパイル済みWebAssembly.Moduleから新しいインスタンスが起動されます。そのため、直後の呼び出しはすでに置き換え後のインスタンスを使います — 呼び出し間で存続するキャッシュやグローバルはないため、再インスタンス化で失われるのは時間だけです。ZfbMdWasmTrapRecoveryLimitError extends Error— プロセスで自動トラップ回復を 16 回使い切ると、ZfbMdWasmTrapErrorの代わりにスローされます。(maxRecoveries: number, cause: unknown)で構築され、causeは.causeで公開されます。それ以降の回復は(回復に使うリソースの無制限な増加を避けるため)、JS レルムがリロードされるまで無効のままになります。MdastAdapterError extends TypeError—toMdastRootがスローします。path: string(問題のノードを指す JSON パス風のポインタ、例:"$.children[2].value")とnodeType: string | null(観測されたノードのtype、または値が型付きレコードですらなかった場合はnull)を持ちます。
型リファレンス
ZfbMdWasmOptions
compile と renderHtml が共有するオプションドキュメント。すべてのフィールドは任意で、{} はすべてのデフォルトを選びます。
| フィールド | 型 | 説明 |
|---|---|---|
filename? | string | .md または .mdx で終わる必要があります。デフォルトは compile では "<anonymous>.mdx"、renderHtml では "<anonymous>.md" です。 |
dialect? | "markdown" | "mdx" | renderHtml だけが消費し、ファイル名による推論を上書きします。compile は受け取って無視します。 |
development? | boolean | compile でのみ消費されます。renderHtml は受け取って無視します。 |
pipeline? | PipelineOptions | 共有のパイプライン設定。 |
PipelineOptions
zfb_content::facade::PipelineOptions をそのまま反映します。
| フィールド | 型 | 説明 |
|---|---|---|
theme? | string | null | syntect のテーマ名。未指定または明示的な null の場合は組み込みのデフォルト("base16-ocean.dark")が保たれます — フェンス付きコードは 常に ハイライトされ、「シンタックスハイライトなし」という値は存在しません。codeHighlight.mode: "class" とは排他です。 |
gfm? | GfmOptions | 拡張ごとの GFM トグル。 |
cjkFriendly? | boolean | — |
hardBreaks? | boolean | — |
codeHighlight? | CodeHighlightOptions | null | フェンス付きコードのハイライトの出力モードと、クラスモードのつまみ。未指定、null、または { mode: "inline" } は、既存のインライン着色の挙動をバイト単位で再現します。 |
features? | MarkdownFeaturesConfig | Record<string, unknown> — TypeScript 側では開いたままにされています。wasm の境界はこれを そのまま Rust 自身の deny_unknown_fields デシリアライザへ渡し、そのデシリアライザがキーの権威あるバリデータになります。 |
GfmOptions
| フィールド | 型 |
|---|---|
strikethrough? | boolean |
table? | boolean |
autolinkLiteral? | boolean |
taskListItem? | boolean |
footnoteDefinition? | boolean |
CodeHighlightOptions
zfb_content::facade::CodeHighlightOptions をそのまま。
| フィールド | 型 | 説明 |
|---|---|---|
mode? | "inline" | "class" | フェンス付きコードのハイライトの出力モード。デフォルトは "inline"。 |
classPrefix? | string | クラスモードのロールクラスに付くクラス名プレフィックス(例: デフォルトの "hi-" は hi-kw、hi-str、… を生みます)。mode が "class" のときのみ意味を持ちます。 |
roleClasses? | Partial<Record<HighlightRole, string>> | null | クラスモードでのロールごとのクラス上書き。未指定または null の場合、すべてのロールで {classPrefix}{role} が使われます。mode が "class" のときのみ意味を持ちます。 |
CompileResult / RenderHtmlResult
| フィールド | 型 | 説明 |
|---|---|---|
code(CompileResult) / html(RenderHtmlResult) | string | null | 成功時は ES モジュール JS ソース、または HTML 断片。失敗時は null。 |
frontmatter | unknown | パースされた YAML frontmatter を JSON として。存在しない、または抽出できない場合は null。 |
diagnostics | Diagnostic[] | 成功時は空。 |
Diagnostic
1 つの診断エントリ。line / column はサポートされる唯一の診断位置で、1 始まりです。
| フィールド | 型 | 説明 |
|---|---|---|
severity | "error" | — |
source | "options" | "frontmatter" | "markdown" | "compile" | — |
message | string | このパッケージまたは上流の依存関係が出す不透明な表示テキスト。パースしたり書き換えたりしないでください — 埋め込まれた座標が含まれる場合、それは依存関係自身の座標系を使います。代わりに構造化された line / column を使ってください。 |
line | number | null | 基になるエラーが位置を持たない場合は null。"markdown" / "frontmatter" では元のソースを指し、"options" ではオプション JSON ドキュメントを指します。 |
column | number | null | 位置のルールは line と同じ。"markdown" / "frontmatter" では JavaScript の UTF-16 コードユニットです — バリデーションと位置の契約 を参照。 |
ParseToAstOptions
parseToAst が消費する、独立した閉じたオプションドキュメント。ビジター / シリアライザのオプションは受け付けません。
| フィールド | 型 | 説明 |
|---|---|---|
filename? | string | .md または .mdx で終わる必要があります。明示的な dialect がない場合、.md は CommonMark を、.mdx は MDX を選びます。filename を省略すると "<anonymous>.mdx" が使われ、したがって MDX になります。 |
dialect? | "markdown" | "mdx" | どちらの有効な拡張子も上書きしますが、拡張子のゲートは免除しません。 |
directives? | boolean | 汎用の remark-directive 構文をパースします。デフォルトは false。 |
frontmatter? | "extract" | "node" | "none" | YAML の処理ポリシー。デフォルトは "extract"。"extract" は除去された本文をパースし、YAML を JSON として返します(YAML ノードなし)。"node" は論理ソース全体をパースし、JSON に加えて正規の YAML ノードを返します。"none" は論理ソースの全バイトを Markdown/MDX としてパースし、常に null を返します。不正な、または閉じられていない YAML は "extract" / "node" を 1 つの frontmatter 診断とともに失敗させます。"none" は診断を生成しません。 |
pipeline? | ParsePipelineOptions | { gfm?: GfmOptions } — parseToAst が受け付ける 唯一の パイプラインのつまみです。theme、cjkFriendly、hardBreaks、codeHighlight、features はこの閉じたドキュメントには含まれません。 |
ParseToAstResult
| フィールド | 型 | 説明 |
|---|---|---|
ast | MdastRoot | null | 成功時はシリアライズされた生の mdast ルート、失敗時は null。 |
frontmatter | unknown | CompileResult.frontmatter と同じ契約。 |
diagnostics | Diagnostic[] | 成功時は空。 |
HighlightCodeOptions
任意コードの直接的なセマンティッククラスハイライトのためのオプション。
| フィールド | 型 | 説明 |
|---|---|---|
language | string | 必須の構文トークン。例: "html"、"css"、"javascript"。 |
mode? | "class" | サポートされる唯一の直接出力モード。デフォルトは "class"。 |
classPrefix? | string | セマンティックロールクラスのプレフィックス。デフォルトは "hi-"。 |
roleClasses? | Partial<Record<HighlightRole, string>> | フルネームのロール上書き。例: { keyword: "text-violet-600" }。 |
HighlightCodeResult と HighlightDiagnostic
| フィールド | 型 | 説明 |
|---|---|---|
html | string | null | 完全なセマンティックな <pre><code> ラッパー、または無効なオプション / 内部エラーの場合は null。 |
diagnostics | HighlightDiagnostic[] | 直接ハイライトが使う source は、Diagnostic とは異なる、より小さな集合です。 |
HighlightDiagnostic のフィールド: severity: "error" | "warning"、source: "options" | "highlight" | "internal"、message: string、line: number | null(常に null — JSON オプションのパース位置は 1 始まりですが、この呼び出しは位置を報告しません)、column: number | null(同じ)。
無効なオプション(language の欠落 / 空文字列、サポートされない mode、不正な classPrefix、未知のロールキー、余分なフィールド)は { html: null, diagnostics: [{ severity: "error", source: "options", … }] } を返します。未知だが空でない language は別で、エスケープされたフォールバックの markup と { severity: "warning", source: "highlight" } の診断とともに成功します。
HighlightRole
highlightCode が出力する、固定された 18 個のロールからなるセマンティックな分類体系(Rust の正規の HiRole::FULL_NAMES に対して機械的に検証されています):
| ロール | デフォルトクラス | ロール | デフォルトクラス |
|---|---|---|---|
"escape" | hi-esc | "variable" | hi-var |
"operator" | hi-op | "tag" | hi-tag |
"comment" | hi-com | "attribute" | hi-attr |
"string" | hi-str | "punctuation" | hi-punct |
"number" | hi-num | "inserted" | hi-ins |
"constant" | hi-const | "deleted" | hi-del |
"keyword" | hi-kw | "heading" | hi-hd |
"function" | hi-fn | "type" | hi-ty |
"namespace" | hi-ns | "property" | hi-prop |
各ロールのデフォルトクラスは ${classPrefix}${suffix} です(デフォルトの classPrefix は "hi-")。roleClasses の上書きはキーに フルネーム(keyword)を使い、クラスのサフィックス(kw)は使いません。
生の mdast の形(parseToAst / toMdastRoot)
parseToAst の ast フィールドは、シリアライズされた 生の markdown-rs mdast ツリー(MdastRoot。存在する場合は常に root 型の Root ノード)です — パーサ自身のノードの形を、その serde 表現を通して、開いた unist 形状のキャリアへ変換したもので、意図的に zfb ビジター適用 前 です。ツリー内のすべてのノードは常に position: { start: AstPosition; end: AstPosition } を持ちます。AstPoint の column と offset(0 始まり)は JavaScript の UTF-16 コードユニット で、String.prototype.slice、mdast-util-to-hast、remark/unist 自身の規約と一致します — Unicode スカラー値ではないため、サロゲートペアの文字(多くの絵文字)は column / offset を 1 ではなく 2 進めます。
コア mdast と MDX の完全なノードセット(Root、Paragraph、Heading、List、Code、Link、MdxJsxFlowElement、…)に加えて、前方互換の UnknownMdastNode キャッチオールが、node.type で型を絞り込みたい呼び出し元のために、名前付きの型としてパッケージから再エクスポートされています。remark-parse / remark-mdx からの、文書化された 2 つの相違点: mdxJsxAttribute(およびその値属性 / 式属性の兄弟)は position を持ちません — markdown-rs は属性の位置をモデル化しません。また、トップレベルの MDX import / export は段落へと格下げされます(mdxjsEsm ノードなし、estree データなし) — wasm の境界には JS/acorn パーサが存在しないためです。_markdownRsStops(MDX の式 / ESM ノードに付く)は内部的で不安定な、markdown-rs の再パース用の管理情報であり、position とは異なり UTF-8 バイト ベースです。これで文字列をスライスしては決していけません。
directives: true の場合(ParseToAstOptions を参照。デフォルトは false)、ツリーは 3 つの汎用 remark-directive ノード型も持てます。いずれも同じ DirectiveNodeBase の形(position、name、attributes、children)を共有します:
containerDirective— ブロック形式、:::nameleafDirective— ブロック形式、::nametextDirective— インライン形式、:name
DirectiveNodeBase の name はディレクティブの名前文字列で、attributes は Record<string, string> です — 真偽値の属性は空文字列で表され、true やキーの省略にはなりません。directives をデフォルトの false のままにすると、ディレクティブのように見えるテキストは markdown-rs がパースしたそのままで残り、これら 3 つのノード型はどれも現れません。
toMdastRoot(上記参照)は、この生の階層を、生のキャリアではなく通常の mdast / unist-util-visit のツールを使いたい利用者のために、厳密でエコシステム互換のツリーへ変換します。
バリデーションと位置の契約
未知のフィールドは拒否されます。Rust 側で
deny_unknown_fields方式により、ZfbMdWasmOptionsの 両方の ネストレベル(トップレベルとpipeline)で行われます。ParseToAstOptionsは 別の、より厳格な 閉じたドキュメントです: そのpipelineサブオブジェクトはgfmのみを受け付けます —theme、cjkFriendly、hardBreaks、codeHighlight、featuresをそこに渡すと、たとえそれらがcompile/renderHtmlにとって有効なPipelineOptionsフィールドであっても拒否されます。Diagnostic.line/.column(compile/renderHtml由来)とAstPoint.column/.offset(parseToAst由来)は、上で説明した同じ JavaScript の UTF-16 コードユニット 規約を共有します。純粋な ASCII のソースはバイトオフセットが UTF-16 オフセットと等しいため、これが問題になるのはソースに非 ASCII のコンテンツが含まれる場合だけです。
パッケージのエントリポイント
ルート(.)は完全な後方互換 API のままです。既存のルートと . のインポートに移行は必要ありません。追加された . と . は独立した SWC-free グラフです。swc_core と zfb-render を除外しつつ、 zfb-content と syntect-fancy は意図的に保持します。parse は syntect-free ではありません。
| サブパス | gzip-9 wasm(6.1.4) | 正確なランタイム値 | 正確な型の面 | 使う場面 |
|---|---|---|---|---|
. | 1,535,686 B | init、compile、renderHtml、parseToAst、highlightCode、version、toMdastRoot、MdastAdapterError、ZfbMdWasmTrapError、ZfbMdWasmTrapRecoveryLimitError、__forceTrapForTests、__getTrapRecoveryStateForTests | 現在の compile/render/parse/raw-mdast/highlight の完全な型セット | MDX のコンパイル、または複数の現在の API を使う場合 |
. | 822,467 B | init、highlightCode、version、ZfbMdWasmTrapError、ZfbMdWasmTrapRecoveryLimitError、__forceTrapForTests、__getTrapRecoveryStateForTests | HighlightRole、HighlightCodeOptions、HighlightCodeResult、HighlightDiagnostic、HighlightDiagnosticSource | コードだけをハイライトする場合。公開 API / リソースは互換のまま |
. | 1,115,876 B | init、renderHtml、version、ZfbMdWasmTrapError、ZfbMdWasmTrapRecoveryLimitError、__forceTrapForTests、__getTrapRecoveryStateForTests | RenderHtmlResult、Diagnostic、DiagnosticSource、ZfbMdWasmOptions、ParseDialect、PipelineOptions、GfmOptions、CodeHighlightMode、CodeHighlightOptions、MarkdownFeaturesConfig、HighlightRole | コンパイラのバイトを含めず Markdown を HTML へ描画する場合 |
. | 301,493 B | init、parseToAst、toMdastRoot、MdastAdapterError、version、ZfbMdWasmTrapError、ZfbMdWasmTrapRecoveryLimitError、__forceTrapForTests、__getTrapRecoveryStateForTests | ParseToAstResult、ParseToAstOptions、ParseDialect、FrontmatterPolicy、ParsePipelineOptions、Diagnostic、DiagnosticSource、AstPoint、AstPosition、RawMdastData、MarkdownRsStop、MdastNode、MdastRoot、UnknownMdastNode、Root、Paragraph、Heading、ThematicBreak、Blockquote、List、ListItem、Html、Code、Definition、Text、DirectiveNodeBase、ContainerDirective、LeafDirective、TextDirective、Emphasis、Strong、InlineCode、Break、Link、Image、ReferenceKind、LinkReference、ImageReference、FootnoteDefinition、FootnoteReference、TableAlign、Table、TableRow、TableCell、Delete、Yaml、MdxFlowExpression、MdxTextExpression、MdxJsxFlowElement、MdxJsxTextElement、MdxJsxAttributeContent、MdxJsxAttribute、MdxJsxAttributeValueExpression、MdxJsxExpressionAttribute | AST をパースし、必要なら利用側の制御されたコードで解釈する場合 |
focused エントリのリソースペアは非公開で、互いに置き換えられません:
wasm-render/zfb_md_wasm_render_glue.zfb-resource.mjs
wasm-render/zfb_md_wasm_render_bg.wasm
wasm-parse/zfb_md_wasm_parse_glue.zfb-resource.mjs
wasm-parse/zfb_md_wasm_parse_bg.wasm宣言サイドカーも対応するディレクトリに閉じています。各エントリは独立した createWasmApi 状態(コンパイル済みモジュール、インスタンス、世代、リトライ状態、 終端状態)を作ります。複数エントリをインポートすると、独立したペアとインスタンスが 意図どおりロードされます。
Node の直接利用とブラウザ対応バンドラでは、同じサブパスをインポートします:
import { renderHtml } from "@takazudo/zfb-md-wasm/render";
import { parseToAst, toMdastRoot } from "@takazudo/zfb-md-wasm/parse";ブラウザで遅延ロードする場合は、ユーザー操作からインポートします。browser 条件は 選択したエントリ自身のペアだけへ静的な ?url エッジを張ります:
renderButton.addEventListener("click", async () => {
const { renderHtml } = await import("@takazudo/zfb-md-wasm/render");
const { html } = await renderHtml(source, { filename: "preview.md" });
preview.innerHTML = html ?? "";
});
parseButton.addEventListener("click", async () => {
const { parseToAst, toMdastRoot } = await import("@takazudo/zfb-md-wasm/parse");
const parsed = await parseToAst(source, { filename: "preview.md" });
const root = parsed.ast === null ? null : toMdastRoot(parsed.ast);
inspect(root);
});compile はルートだけにあり、ホストによる評価、JSX ランタイム、コンポーネントを必要とする モジュールソースを返します。toMdastRoot は、すでにパースされたデータを利用側の制御された AST-to-React レンダラーで解釈するためのアダプタです。slim エントリは author JavaScript を評価しません。 renderHtml はサニタイザーではなく、生 HTML は信頼できないままです。MDX の JSX / 式 / ESM 形状の AST ノードは不活性なデータとして扱われます。
Cloudflare Workers(workerd)
@takazudo/ と @takazudo/ には workerd エクスポート条件があります。Worker 向けのエントリは、コンパイル済みの .wasm モジュールを静的にインポートし、インスタンスごとに新しい wasm-bindgen グルーのクロージャを 作ります。パッケージのルートと / には workerd エントリはありません。
たとえば、Worker の fetch 内で Markdown をパースできます:
import { parseToAst } from "@takazudo/zfb-md-wasm/parse";
export default {
async fetch(request: Request): Promise<Response> {
const source = new URL(request.url).searchParams.get("source") ?? "# Hello";
const result = await parseToAst(source, { filename: "post.md" });
return Response.json(result);
},
};Wrangler はデフォルトのモジュールルールで .wasm のインポートを処理するため、追加設定は 不要です。バンドル済みの Worker を Miniflare で実行する場合は、コピーされた wasm ファイルを コンパイル済みモジュールとして登録します:
import { Miniflare } from "miniflare";
const miniflare = new Miniflare({
modules: true,
scriptPath: "dist/worker.js",
modulesRoot: "dist",
modulesRules: [{ type: "CompiledWasm", include: ["**/*.wasm"] }],
});@cloudflare/vite-plugin を使う経路は未検証です。
wasm トラップが発生すると、代替インスタンスの準備ができたあと、失敗した呼び出しが ZfbMdWasmTrapError を投げます。復旧のたびに同じコンパイル済みモジュールを使い、 新しいグルーのクロージャから代替インスタンスを作るため、次の呼び出しはその代替インスタンスを 使います。16 回の復旧に成功したあとでさらにトラップが発生すると、そのエントリは終端状態になり、 その呼び出しと以後の呼び出しは ZfbMdWasmTrapRecoveryLimitError を投げます。 そのエントリを再び使うには Worker の isolate を作り直してください。parse と highlight の 復旧状態は互いに独立しています。
出荷アーティファクトのサイズと上限
歴史的な記録である 6.1.4 のアーティファクトの行は次のとおりです。final wasm は wasm-bindgen と wasm-opt を通した最適化後の値、gzip-9 は Node の gzipSync(..., { level: 9 })、glue は グルーコードのバイト数とその gzip です:
| エントリ / グラフ | final wasm | gzip-9 | glue | glue gzip-9 |
|---|---|---|---|---|
| root(full) | 3,421,090 B | 1,535,686 B | 14,998 B | 4,199 B |
| highlight | 1,544,777 B | 822,467 B | 8,758 B | 2,637 B |
| render | 2,244,162 B | 1,115,876 B | 8,772 B | 2,661 B |
| parse | 736,830 B | 301,493 B | 11,159 B | 3,797 B |
#2447 の決定スナップショットでは、split パッケージの構成が 3,638,607 B、root + highlight が 2,314,818 B、クリーンな本番 4 ステップの上限は 210 秒、選択されたスナップショットの中央値は 155.015 秒 [153.496, 165.977] でした。歴史的な参考上限は root 1,600,000 B、highlight 880,000 B、 render 1,125,000 B、parse 325,000 B、完全な packed tarball は 3,900,000 B です。4 つのエントリは いずれも上限の内側で出荷されており、上限までの余裕は root 64,314 B、highlight 57,533 B、 render 9,124 B、parse 23,507 B です。これらは永続的な保証ではなく 6.1.4 の測定値です — 実際にインストールしたバージョンで測り直してください。
正確なバイト数とダイジェストは、そのバージョンの成果物で確認します。 上の表は、名前のあるバージョン時点の歴史的な測定であり、現在の配布サイズや保証される容量ではありません。SHA-256 ダイジェストは事情が異なります。各リリースは自身の バージョン文字列を個々の .wasm に焼き込む(version() が返す値です)ため、コンパイル結果が 同一でバイトサイズがまったく動かないドキュメントのみのパッチであっても、4 つのダイジェストは 毎リリース変わります。semver ではなくコンテンツダイジェストでこれらのアーティファクトを 検証している場合は、アップグレードのたびに再ピン留めしてください。「サイズが変わっていない」を 「再検証は不要」と読み替えてはいけません。
highlight グラフから swc_core をゲートで外したこと(#2449 / #2450)は、 証明可能性の勝利であって、サイズの勝利ではありません。#2447 の SWC 保持ベースラインは raw 1,484,705 B、gzip-9 767,009 B で、#2450 の結果は raw で 7,965 B、gzip-9 で 8,765 B(結果は 758,244 B)小さくなりました。wasm-opt は 到達不能な swc_core を既にデッドストリップしていたのであり、#2450 の完全パリティと swc_core 不在のアサーションが、その創発的な性質を保証されたものへと変えました。 highlight だけを使う利用者にとって意味のある差は、root と highlight の差のほうです: raw で 1,876,313 B、gzip-9 で 713,219 B 小さく、highlight は root の raw バイトの約 45%、 gzip 後のバイトの約 54% に収まります。
各サブパスの exports マップは、default 条件(src/ / src/ にある、動的な Node の fs または fetch ローダ)よりも先に browser 条件(src/ / src/ が使う、静的でバンドラフレンドリーなリソースパス)を解決します。両方の条件は同じ types エントリと、同じ基盤の createWasmApi ランタイムを共有します。
このパッケージは ESM 専用 で("type": "module"、require のサポートなし)、Node ≥ 20.0.0 を必要とします。このページに焼き込まれたバージョン番号を信頼するのではなく、実行時に version()(上記)を呼ぶか、インストール済みパッケージ自身の package.json を確認してください — バージョン番号はリリースごとに変わります。
関連項目
Playground — ブラウザで Rust パイプラインをインタラクティブに試せます。
ブラウザでの Markdown プレビュー — ナラティブなガイド: インストール、コンパイル済みモジュールの評価、JSX ランタイムの import map の落とし穴、リソースの遅延ロード、パリティ保証の明示的な制限。
Wasm のインポート — ビルド時に
.wasmモジュールを SSR ルートへインポートするという、別の無関係な機能。シンタックスハイライト — このパッケージの
fancy-regexバックエンドと比較するための、ネイティブ zfb の syntect のセットアップ。