SDK APIリファレンス

公開エントリーポイント

概念	Python	TypeScript	Rust
App	`App(state)`	`new App(state)`	`App::new(state)`
Action登録	`@app.action`または`@app.action(name)`	`app.action(name, schema, handler)`	`app.action::<Input, _, _>(name, handler)?`
ビュー登録	`app.mount(view)`または`@app.surface(name)`	`app.surface(name, view)`	`app.surface(name, view)?`
stdio起動	`await app.start()`	`await app.start()`	`app.start().await`
Transport指定	`await app.start(transport)`	`await app.start(transport)`	`app.start_with(transport).await`
状態更新	`await ctx.update(mutator)`	`await ctx.update(mutator)`	`ctx.update(mutator).await?`

Pythonはハンドラーの第1引数の型注釈から入力スキーマを推論します。明示する場合はschema=を使います。状態更新にはasync with ctx.update() as state:も使えます。TypeScriptはスキーマ引数が必須です。Rustはハンドラーの入力型へデシリアライズし、型付きの入力式とフィールド参照にはActionInputをderiveします。

Runtimeと宣言

App.build()はTransportを選ばずRuntimeを作ります。Runtimeにはupdate・handleとAction呼び出しがあります。handleはJSONのgetSurface観測とinvokeコマンドを受け取ります。キーが部品のIDになり、ルートは常にrootです。

Action.call(input)は部品に渡すAction宣言を作ります。Rustではaction.call(input)?です。入力部品への結び付けやブラウザ上の値の参照には、先にフィールドを選びます。

言語	入力部品への結び付け	Actionに渡す入力式
Python	`form.field("temperature", float).bind()`	`form.field("temperature", float).value()`
TypeScript	`form.field("temperature").bind()`	`form.field("temperature").value()`
Rust	`form.field(RunInput::field_temperature()).bind()?`	`form.field(RunInput::field_temperature()).value()`

ここでformは数値のtemperatureフィールドを持つLocalで、RustのRunInputはActionInputをderiveした型です。Pythonではform.temperatureを部品のbind=やActionのinput=に直接渡すこともできます。bind()とvalue()はPointer引数を取らず、現在のLocalを参照します。フィールドを選ばなければ値全体が対象です。Actionに到達する前に入力は確定済みJSONになります。ブラウザが持つ入力も参照してください。

Transport

Python・TypeScriptはStdioTransport・CallbackTransport・WebSocketTransportを公開します。TypeScriptのWebSocketServerTransportとUnixSocketServerTransportは@omochi-ui/sdk/node、PythonのUnixSocketServerTransportはパッケージ直下です。RustはTransport trait、StdioTransport・CallbackTransport・UnixSocketServerTransportを持ちます。

Python・TypeScriptのruntime.shutdown()はTransportからの新しいメッセージの受け付けとバックグラウンド処理を停止し、ResourceRegistryを閉じます。組み込みのサーバーTransportはリスナーも閉じ、Unixのサービス公開情報を削除します。後片付けの完了はPythonのruntime.wait_closed()、TypeScriptのruntime.waitClosed()で待てます。すでに実行中のActionが完了してからstart()が戻る場合があります。

TypeScriptのshutdown()は初回も停止を要求した時点で解決済みのPromiseを返すため、await runtime.shutdown()だけでは後片付けの完了を待ちません。spawn(async signal => { ... })とspawn(promise)のどちらで登録したタスクも、停止を要求してから自分の後片付けを続けられます。タスクの外からawait runtime.shutdown(); await runtime.waitClosed();を呼ぶと、登録された全タスクの終了とResourceRegistryのクローズを待てます。waitClosed()はタスク自身の終了も待つため、登録タスク内では待たないでください。後片付けのエラーはwaitClosed()とstart()に伝わります。ActionやTransportが先に失敗していた場合、start()は先に発生したエラーを維持します。

独自TransportはPythonのasync stop_receiving()、TypeScriptのstopReceiving()でRuntime終了時の後片付けに参加できます。このフックで受信を止め、Transport自身が所有するリソースを解放します。Callback・WebSocketアダプターは受信ループを止めますが、接続自体の所有者は呼び出し元です。独自Transportのclose()をRuntimeが自動で呼ぶことはありません。

エラー

Python・TypeScriptでは宣言不正がDeclarationError、プロトコル不正がProtocolError、機能の非対応がCapabilityErrorです。RustはErrorとResultを使います。Context更新とTransportの失敗は呼び出し元へ伝わり、完了済みの更新は巻き戻りません。

型付きシグネチャ

実行例・コンポーネント・メディアも参照してください。