effect-utils

# @overeng Effect Utils 本番環境で利用可能なEffectユーティリティと統合のコレクション。 ## パッケージ ### Notion統合 型安全なスキーマ生成を備えた、フル機能のEffectネイティブNotion APIクライアント。 #### @overeng/notion-effect-client 型付きクエリを備えたNotion API用のEffectネイティブHTTPクライアント - **スキーマ対応クエリ** - Effectスキーマを渡すことで、自動デコード付きの完全に型付けされた結果を取得 - **Markdown変換** - カスタマイズ可能なトランスフォーマーでページ/ブロックをMarkdownに変換 - **ストリーミングAPI** - すべてのリスト操作でEffect Streamsによる自動ページネーション #### @overeng/notion-effect-schema すべてのNotion API型に対応する包括的なEffectスキーマ - **完全なカバレッジ** - 全27ブロック型と21以上のプロパティ型に対応するスキーマ - **プロパティ変換** - 使いやすいアクセスのための`asString`、`asNumber`、`asOption`バリアント - **書き込みサポート** - ページの作成/更新のための専用書き込みスキーマ #### @overeng/notion-effect-cli Notionデータベースから型安全なスキーマを生成するCLIツール - **スキーマ生成** - ライブのNotionデータベースから型付きスキーマを生成 - **ドリフト検出** - CI/CD用の`diff`コマンドでスキーマ変更を追跡 - **APIラッパー生成** - `--include-api`で型付きCRUD操作を生成 ### AI統合 | パッケージ | 説明 | | --- | --- | | @overeng/effect-ai-claude-cli | Effect AI用のClaude CLIプロバイダー | API呼び出しに課金される代わりに、**Claude Codeサブスクリプション**を使用できます。`claude` CLIに委譲することでEffect AIのLanguageModelインターフェースを実装します。 - **サブスクリプションベース** - 既存のClaude Codeサブスクリプションを使用（APIよりはるかに安価） - **APIキー不要** - CLIがサブスクリプション経由で認証を処理 - **完全なLanguageModelサポート** - `@effect/ai`のChat、generateTextなどで動作 ### スキーマフォーム Effectスキーマ用のヘッドレスフォームライブラリと、アクセシブルなReact Aria実装。 | パッケージ | 説明 | | --- | --- | | @overeng/effect-schema-form | スキーマイントロスペクションを備えたヘッドレスフォームコンポーネント | | @overeng/effect-schema-form-aria | Tailwind CSSによるスタイル付きReact Ariaコンポーネント（Storybook） | - **スキーマイントロスペクション** - Effect Schema構造からフォームフィールドを自動生成 - **ヘッドレスアーキテクチャ** - 独自のコンポーネントを持ち込むか、事前構築されたReact Aria実装を使用 - **タグ付き構造体サポート** - ラベル付きグループによる判別可能なユニオンの自動処理 - **柔軟なレンダリング** - プロバイダーパターン、レンダープロップ、またはフックAPIによる完全な制御 - **デフォルトでアクセシブル** - WCAG準拠のReact Aria Components ### React統合 Effectを活用したアプリケーションを構築するためのReactフックとユーティリティ。 | パッケージ | 説明 | | --- | --- | | @overeng/effect-react | フックとコンテキストプロバイダーを備えたEffectランタイム用React統合 | | @overeng/react-inspector | Effect SchemaをサポートするDevToolsスタイルのインスペクター（Storybook） | - **EffectProvider** - LayerからEffectランタイムを初期化し、Reactツリーに提供 - **フックAPI** - コンポーネント内でEffectを実行するための`useEffectRunner`、`useEffectCallback`、`useEffectOnMount` - **自動エラーハンドリング** - カスタムエラーコンポーネントを備えた組み込みエラーバウンダリ - **DevToolsインスペクター** - Effect Schemaを認識するブラウザスタイルのオブジェクト/テーブルインスペクター - **型安全なランタイムアクセス** - 高度なユースケースのためのEffectランタイムへの直接アクセス ### Playwright統合 | パッケージ | 説明 | | --- | --- | | @overeng/utils/node/playwright | OTEL統合を備えたEffectネイティブPlaywrightラッパー | - **サービスタグ** - 依存性注入のための`PwPage`、`PwBrowserContext` - **構造化エラー** - 一貫したエラーハンドリングのためにすべての操作を`PwOpError`でラップ - **OTELスパン** - クロスプロセストレース伝播による自動トレーシング - **テストヘルパー** - Playwrightテストでの自動レイヤー提供のための`withTestCtx` ### ユーティリティ | パッケージ | 説明 | | --- | --- | | @overeng/utils | 分散ロック、ログブリッジ、デバッグユーティリティ | 主な機能: - BroadcastChannel経由のSharedWorker→タブログブリッジ（`@overeng/utils/browser`） - スコープ/ファイナライザーのデバッグとアクティブハンドルの監視 - TTL有効期限付きのファイルシステムベースの分散ロック - オプションのログ/保持機能を備えたワークスペース対応コマンドヘルパー ### 開発者ツール | パッケージ | 説明 | | --- | --- | | @overeng/genie | TypeScriptベースの設定ファイルジェネレーター | | @overeng/oxc-config | 共有oxlintおよびoxfmt設定 | **Genie**はTypeScriptソース（`.genie.ts`ファイル）から`package.json`、`tsconfig.json`、GitHubワークフローファイルを生成します。機能は以下の通りです: - **型安全な設定** - 完全なオートコンプリートを備えたTypeScriptとして設定を定義 - **一貫したフォーマット** - oxfmtによる自動フォーマット - **読み取り専用保護** - 生成されたファイルはデフォルトで読み取り専用 - **CI統合** - `--check`モードでファイルが最新であることを検証 ## クイックスタート ### 開発シェルに入る このリポジトリは一貫したツールチェーンを提供するために`devenv`を使用します。シェル内でコマンドを実行してください: ```bash devenv shell ``` ### 依存関係ビューの公開 ```bash devenv tasks run buck2:editor:publish ``` ### すべてのTypeScriptプロジェクトをチェック ```bash devenv tasks run buck2:quick ``` ソース側のツールやエディターが必要とする場合、Buckが生成した宣言をパッケージの`dist`ディレクトリに公開します: ```bash devenv tasks run buck2:typescript:materialize-dist ``` ### テストの実行 ```bash # すべてのテスト devenv tasks run test:run # 単一パッケージ（例: utils、genie） devenv tasks run test:utils devenv tasks run test:genie # 統合テスト（NotionパッケージにはNOTION_API_TOKENが必要） NOTION_API_TOKEN=secret_xxx devenv tasks run test:integration # ウォッチモード devenv tasks run test:watch ``` ### 型チェック Buckはリポジトリ全体のTypeScriptチェックの唯一の権威です: ```bash devenv tasks run buck2:quick ``` クロスセルBuckプロバイダーアイデンティティを個別に監査: ```bash devenv tasks run buck2:providers:check ``` ### Nixアーティファクトインポートチェック リポジトリ製品を実体化せずに、汎用およびJavaScript Buck製品インポート境界を検証: ```bash devenv tasks run nix:buck2-artifact-import:check devenv tasks run nix:javascript-product-import:check ``` `check:all`は何もビルドせずにホストシステムのすべてのflake出力も評価します: ```bash devenv tasks run nix:flake:eval ``` ### リンティング ```bash # フォーマット + リントのチェック devenv tasks run lint:check # フォーマット + リント問題の自動修正 devenv tasks run lint:fix ``` ## パッケージ構造 各パッケージはモダンなESM規約に従います: - ソースファイルは`src/`内（`.ts`拡張子のTypeScript） - エントリポイントは`src/mod.ts` - コンパイル済み出力は`dist/`内（gitignore対象） - 開発用エクスポートはソースファイルを指す - 公開用エクスポートはコンパイル済みJavaScriptを指す ## コントリビューション このモノレポは以下を使用します: - パッケージ管理のための**bun workspaces** - インクリメンタルビルドのための**TypeScriptプロジェクト参照** - リンティングとフォーマットのための**oxlint + oxfmt** - テストのための**Vitest** - コア機能のための**Effect** パッケージ固有のドキュメントについては、各パッケージのREADMEを参照してください。