moostjs

Moost

TypeScript 向けのメタデータ駆動型イベント処理フレームワークです。デコレーターとコンポーザブル（Wooks 経由）で、HTTP、CLI、WebSocket、Workflow のイベントを処理します。イベントタイプごとにアダプターが 1 つあります。モジュールの抽象化はなく、コントローラーは Moost に直接登録されます。DI、インターセプター、パイプはすべてのアダプターで共有されます。1 つのコントローラーで @Get、@Cli、@Message メソッドを同時に公開でき、各アダプターは自身のハンドラータイプのみをバインドします。

以下を活用しています：@prostojs/mate（メタデータ）、@prostojs/infact（DI）、@wooksjs/event-core（非同期イベントコンテキスト）、@prostojs/dye（コンパイル時のターミナルカラー）。

ドメインマップ — 必要なものだけを読み込む

分野	ファイル	読み込むタイミング
コア概念、Moost クラス、ライフサイクル、登録、アプリの初期化／破棄	core.md	新規プロジェクト、複数アダプターのセットアップ、app.init()、@MoostInit／@InjectMoost／app.addInitHook()、起動時のセットアップ、Moost のサブクラス、app.dispose()／@MoostDispose、グレースフルシャットダウン、disposeOnSignals()（SIGTERM／SIGINT ハンドラー、開発時のリロードでの MaxListenersExceededWarning、Ctrl-C で誤ったアプリが破棄される）、ホットリロード後もリソースが残る、リロード後にタイマー／ジョブが重複する
デコレーター、メタデータ、カスタムデコレーター、Mate	decorators.md	デコレーターの作成／使用、メタデータの読み取り、コントローラーのサブクラス化／@Inherit／親ルートが 404 を返す／diagnostics.inheritance
DI スコープ、@Injectable、@Inject、@Provide、@Circular	di.md	サービス、スコープ設定、プロバイダー、置き換え；別のコントローラーとしてコードを実行する（withControllerContext、forkEventContext）
インターセプター：優先度、@Intercept、ガード、クラスベース	interceptors.md	認証／ロギング／エラー処理など、横断的な関心事
パイプ：@Pipe、@Resolve、TRANSFORM／VALIDATE	pipes.md	バリデーション、変換、カスタムパラメーターデコレーター
カスタムアダプター：TMoostAdapter、defineMoostEventHandler	custom-adapters.md	新しいイベントソース向けのアダプターを構築する
HTTP のセットアップ／ルーティング	event-http.md	MoostHttp、ルートデコレーター、ハンドラーの戻り値、fetch／SSR、invoke（現在のリクエスト内のルート）、withHttpContext、forwardHeaders／DEFAULT_FORWARD_HEADERS、匿名の 127.0.0.1 自己呼び出し
HTTP リクエストデータ	http-request.md	@Query/@Header/@Cookie/@Body/@Req/@Res/@Ip
HTTP レスポンスの制御	http-response.md	@SetStatus/@SetHeader/@SetCookie、参照、ボディサイズ制限、HttpError
HTTP 認証ガード	http-auth.md	defineAuthGuard、AuthGuard、@Authenticate
CLI	event-cli.md	CliApp、@Cli/@CliOption、ヘルプ、CLI インターセプター
ワークフロー	event-wf.md	@Step/@Workflow/@WorkflowSchema、一時停止／再開、アウトレット、状態戦略
WebSocket コア	event-ws.md	MoostWs/WsApp、@Message/@Connect/@Disconnect、ワイヤープロトコル
WebSocket ルーム	ws-rooms.md	useWsRooms、ブロードキャスト、WsBroadcastTransport
WebSocket のテスト	ws-testing.md	prepareTestWsMessageContext / prepareTestWsConnectionContext
Vite プラグイン：開発／ビルド、ミドルウェア、SSR／SPA、デプロイ	vite.md	moostVite、vite.config.ts、createSSRServer、ssrEntry／serverEntry、ssr.noExternal／ssr.external、ssrExternalCheck、開発サーバーの分離に関する警告／「開発時に Node によってネイティブに読み込まれる」／instantiate(MoostHttp) が vite serve でのみ失敗する、dist/server、HMR、「本番環境で useRequest() が undefined になる」、「Cannot read properties of undefined (reading 'headers')」、外部化された依存関係が wooks のコンポーザブルを呼び出す、開発サーバーで起動途中のアプリが配信される／編集後に一部の API ルートが index.html を返す／開発時に app.init() エラーが表示されない／「502 Moost app failed to load」／プラグインは init() を待つのか、SSR レンダリングの契約／ページごとの head-SEO／ステータス／ssrHead／TSSRRenderResult／TSSRRenderContext／ssrFetchForwarding（SSR での閲覧者 ID）
Swagger／OpenAPI	swagger.md	SwaggerController、Swagger* デコレーター、OpenAPI 仕様の生成、spec.json／UI の配信、securitySchemes
OpenTelemetry	otel.md	enableOtelForMoost、スパン／トレーシング、@OtelIgnoreSpan／@OtelIgnoreMeter、スパンプロセッサー、useOtelContext／useSpan／withSpan、moost.event.duration メトリクス
RBAC／ABAC アクセス制御	@aooth/arbac-moost (aooth ドキュメント)	認証、ロール／スコープ、認可ガード — このリポジトリには含まれません；@moostjs/arbac は非推奨で、aooth に置き換えられています

スキャフォールド

npm create moost@latest [name] -- [--http|--cli|--ws|--ssr] [--wf] [--oxc] [--force]

プロジェクトタイプのフラグは最大1つまで指定してください（--http --ws は例外で、HTTP アプリに WebSocket アドオンを追加します）。フラグを指定するとアドオンが事前選択され、対応する対話型の切り替えが省略されます。詳細：core.md。

クイックスタート

import { Moost } from 'moost'
import { MoostHttp } from '@moostjs/event-http'

const app = new Moost()
app.adapter(new MoostHttp()).listen(3000)
app.registerControllers(AppController)
await app.init()

その他のエントリーポイント：

• CLI：new CliApp().controllers(AppController).useHelp({ name: 'my-cli' }).start() — Moost + MoostCli のシンタックスシュガーです（event-cli.md）
• スタンドアロン WS：await new WsApp().controllers(ChatController).start(3000)（event-ws.md）
• 1つの HTTP サーバーを複数のアダプターで共有する場合：まずアダプターを取得します — const http = app.adapter(new MoostHttp())、続けて http.listen(3000) を呼び出し、app.adapter(new MoostWs({ httpApp: http.getHttpApp() })) を指定します（event-ws.md）
• Moost のサブクラス自体がコントローラーです — メソッドに直接デコレーターを適用します（core.md）

横断的な情報

DI スコープ — @Injectable() / @Injectable(true) / @Injectable('SINGLETON') は、アプリのライフタイム全体で1つのインスタンスを使います。@Injectable('FOR_EVENT') はイベントごとに新しいインスタンスを使います。@Controller() は暗黙的に @Injectable(true)（SINGLETON）を設定します。クラスのプロパティにリクエストごとの状態を保持する場合や、プロパティレベルの ref/resolver デコレーターを使う場合は 'FOR_EVENT' を使用してください。FOR_EVENT にはアクティブなイベントコンテキストが必要です（コンポーザブルは SINGLETON のコンストラクターでは動作しません）。スコープのライフタイム（HTTP のレスポンスとハンドラー、ワークフローの実行および WS メッセージごとの所有権、0.6.42 より前の scope isn't registered バグ）については、di.md#scopes を参照してください。

Wooks のコンポーザブルはハンドラー内で動作します — すべての @wooksjs/* コンポーザブル（例：useRequest、useResponse、useHeaders）は Moost のハンドラー内で直接使用できます。同じイベントコンテキストで実行されます。

ロギング — コンポーザブル：useLogger('topic')（moost から、@wooksjs/event-core から再エクスポート）。プロパティ：@InjectEventLogger()（イベントごと）/ @InjectMoostLogger('topic')（アプリレベル。@LoggerTopic、次にクラスの @Id にフォールバック）。スタンドアロン：createLogger({ transports: [loggerConsoleTransport] }) — loggerConsoleTransport はすでに構築済みのトランスポート定数です。関数を呼び出さず、そのまま渡してください。

再エクスポート — moost は、@wooksjs/event-core の current、useLogger、key、cached、eventTypeKey、createEventContext、run に加えて、@prostojs/infact の createProvideRegistry / createReplaceRegistry を再エクスポートします。moost は独自の globalKey(name) もエクスポートします。これは重複を防ぐコンテキストキーのファクトリーで、globalThis 経由で名前ごとにスロットを登録します。moost が複数回ロードされる場合（デュアル ESM/CJS、または重複インストール）に set/get が同期しなくなるのを防ぐため、moost が所有するコンテキストキーには key の代わりにこれを使用してください。@moostjs/event-http は httpKind、HttpError、useHttpContext、prerenderJson（および型 TPrerenderJsonOptions）を再エクスポートします。@moostjs/event-cli は cliKind と、moost の Param / Controller / Intercept / Description / Optional / defineBeforeInterceptor / defineAfterInterceptor / defineInterceptor を再エクスポートします（注：defineErrorInterceptor は再エクスポートされません — moost からインポートしてください）。@moostjs/event-wf は wfKind、useWfState、StepRetriableError、outlet のプリミティブを再エクスポートします。@moostjs/event-ws は wsConnectionKind / wsMessageKind、WsError、すべての useWs* コンポーザブル、currentConnection、prepareTestWs* を再エクスポートします。

アーキテクチャに関する参考情報

• デコレーターシステム — すべてのデコレーターは getMoostMate()（シングルトンの Mate、'moost' ワークスペース）を経由します。メタデータはバインド時に読み取られます：decorators.md
• インターセプターの優先順位とフェーズ — interceptors.md
• パイプの優先順位とスコープレベル — pipes.md
• イベントハンドラーのライフサイクル（defineMoostEventHandler）— custom-adapters.md
• アダプターパターン — 各アダプターは TMoostAdapter<H> を実装し、app.adapter(a) でアタッチされます。opts.handlers は、アダプター自身の handler.type でフィルターされます：custom-adapters.md