バージョン: 0.9.0 (最新)

🧩 ブロック

Blocksは、特定の操作のコアアプリケーションロジックを含む純粋なビジネスロジック関数です。これらは、ビジネスロジックをペイロード処理とルーティングの懸念から分離する、再利用可能でテスト可能、かつ合成可能なビルディングブロックとして設計されています。

🔍 Blockとは何ですか？

blockは、必要なデータのみを受け取る（ペイロードコンテキストなし）純粋な関数で、適切なエラーハンドリングのためにResult型を返します。Blocksはhandlers内で使用され、ビジネスロジック操作を実行し、handlersをペイロードコンテキストを処理し、実際の作業のためにblocksを呼び出す薄いラッパーにします。

┌─────────────┐
│   Handler   │  ペイロードを受信し、データを抽出
├─────────────┤
│   Block ▷   │  ビジネスロジックを持つ純粋関数
│             │  getUserById(db, userId)
└─────────────┘

主要なポイント:

Pure functions – ペイロードコンテキストなし、必要なパラメータのみ（テストに最適！）。
Result types – 予測可能なエラーハンドリングのために常にResult<T, Error>を返します。
Reusable – 同じblockを異なるhandlersやservices間で使用できます。
Testable – 複雑なペイロード構造をモックすることなく、簡単にユニットテストできます。

📐 設計原則

• Separation of concerns – blocksはビジネスロジックを含み、handlersはペイロードコンテキストを処理します。
• Pure functions – blocksは必要なもののみを受け取り、隠れた依存関係はありません。
• Error handling – blocksは明示的なエラーハンドリングのためにResult型を返します。
• Composability – blocksは一緒に合成して、複雑な操作を構築できます。

🧑‍💻 HandlersでのBlocksの使用

Blocksは通常、applyPayloadArgsユーティリティを使用してhandlers内で使用され、ペイロードコンテキストをリフトし、必要なデータのみをblocksに渡します：

import { ok, err, Result } from 'neverthrow';
import { primitives, handlers, blocks } from '@nodeblocks/backend-sdk';

const { applyPayloadArgs } = primitives;
const { mergeData } = handlers;

export const getUserHandler: primitives.AsyncRouteHandler<
  Result<primitives.RouteHandlerPayload, primitives.NodeblocksError>
> = async (payload) => {
  const { context, params } = payload;
  const userId = params.requestParams?.userId;

  if (!userId) {
    return err(new primitives.NodeblocksError(400, 'User ID is required', 'getUserHandler'));
  }

  // Use block with applyPayloadArgs to lift payload context
  const result = await applyPayloadArgs(
    blocks.getUserById,
    payload
  )(context.db.profiles, userId);

  if (result.isErr()) {
    return err(result.error);
  }

  const user = result.value;
  return ok(mergeData(payload, { user }));
};

🔄 BlockとHandlerの比較

アスペクト	Block	Handler
入力	必要なデータパラメータのみ	完全なペイロードとコンテキスト
出力	`Result<T, Error>`	`Result<RouteHandlerPayload, NodeblocksError>`
目的	純粋なビジネスロジック	ペイロード処理 + blockオーケストレーション
テスト容易性	簡単 - データだけを渡す	ペイロードモックが必要
再利用性	高 - どこでも使用可能	低 - ルート構造に結びついている

📦 利用可能なBlockカテゴリ

Blocksはドメインエンティティごとに整理されています。各エンティティは一般的な操作のためのblocksを提供します：

Authentication Blocks – 認証と認可ロジック
Avatar Blocks – アバターの正規化とファイル管理
Chat Blocks – メッセージングとリアルタイム通信
File Storage Blocks – セキュアなファイル操作と署名付きURL
Identity Blocks – アイデンティティのライフサイクルとセキュリティ管理
Location Blocks – 階層的な場所管理
Mongo Blocks – MongoDBデータベース操作とユーティリティ
OAuth Blocks – サードパーティOAuthプロバイダー統合
Order Blocks – 注文処理と計算
Organization Blocks – 組織とワークスペースロジック
Product Blocks – 製品管理操作
Profile Blocks – プロフィール関係とソーシャルエンゲージメント
User Blocks – ユーザー取得、正規化、データフォーマット

ℹ️ 利用可能なblocksとその使用方法の完全なリストについては、Backend Blocksドキュメントを参照してください。

➡️ 次へ

Handler »を学習して、blocksがhandlers内でどのように使用されるかを確認するか、Backend Blocks »を探索して、異なるエンティティの利用可能なblock実装を確認してください。

🔍 Blockとは何ですか？​

📐 設計原則​

🧑‍💻 HandlersでのBlocksの使用​

🔄 BlockとHandlerの比較​

📦 利用可能なBlockカテゴリ​

➡️ 次へ​