バージョン: 0.14.0 (最新)

🪪 バリデーター

バリデーターは withRoute({ validators }) を通じてルートに接続する関数です。HTTP バリデーターは非同期です。WebSocket バリデーターは同期または非同期にできます。スキーマ検証を超えるビジネスロジックの検査、すなわち認証、認可、リソースの存在、所有権を実行します。

バリデーター登録 API はありません。validators 名前空間からインポートし、src/routes/ のルートコンポーザーに接続します。

import { validators } from '@nodeblocks/backend-sdk';

type Validator = (payload: RouteHandlerPayload) => Promise<void>;
type WsValidator = (payload: WsRouteHandlerPayload) => void | Promise<void>;

ファクトリーバリデーターは Validator を生成するために呼び出す必要があります（例: isAuthenticated()。isAuthenticated のままではありません）。doesCategoryExist のような直接バリデーターはそのまま使用します。() で呼び出さないでください。

🔍 バリデーターとは？

バリデーターは、リクエストパイプライン内でハンドラーのビジネスロジックより前に実行されます。ルートハンドラーと同じペイロードオブジェクトを受け取ります（HTTP は RouteHandlerPayload、WebSocket は WsRouteHandlerPayload）。

バリデーターを使う理由:

DB 負荷の高いハンドラーチェーンの前に、認証とアクセス制御を強制する
SDK の述語をルート間で再利用する（hasOrgRole、ownsProfile など）
柔軟なアクセス規則のために all()（AND）または some()（OR）で合成する
一貫した HTTP エラーレスポンスのために NodeblocksError をスローする（WebSocket の失敗時は接続を閉じます）

📐 スキーマとバリデーター

2 つの検証レイヤーは異なる時点で実行されます。withSchema による形状検証についてはスキーマ »を参照してください。

HTTP リクエスト
  → ルートバリデーター（defService）
  → ハンドラー開始
    → スキーマ検証（withNextRoute ラッパー）
    → ハンドラーチェーン（blocks / handlers）

レイヤー	目的	定義場所
ルートバリデーター	ビジネスロジック — 認証、権限、存在	`withRoute` の `validators`
スキーマ検証	リクエスト形状 — パス、クエリ、本文フィールド	機能の `withSchema`（`compose(schema, route)`）

実行順序: defService はまずルートバリデーターを実行し、その後ハンドラーを呼び出します。スキーマ検証は withNextRoute 経由でスキーマにラップされたハンドラー内部で実行されます。正しい順序は バリデーター → スキーマ → ハンドラーチェーン です。

⚙️ コンテキストとパス

バリデーターは RouteHandlerPayload を受け取ります。

{
  context: {
    db,              // service dataStores からマッピング
    configuration,   // サービス構成（Identity タイプ ID、組織ロール）
    authenticate,    // デフォルトは getBearerTokenInfo、Cookie サービスは getCookieTokenInfo を注入
    // ...任意のドライバー（mailService、fileStorageDriver など）
  },
  params: {
    requestParams,   // パスパラメーター
    requestQuery,    // クエリ文字列
    requestBody,     // JSON 本文（POST/PUT/PATCH/DELETE）
  },
}

パス引数には、ペイロードを起点とする Ramda の path タプルを使用します。SDK ルートでは一貫して次を使用します。

['params', 'requestParams', 'profileId']
['params', 'requestBody', 'identityId']
['params', 'requestQuery', 'channelId']

Cookie 認証を使用する場合、サービスは context.authenticate として getCookieTokenInfo を注入します。サービスルーターをマウントする前に cookie-parser ミドルウェアを登録してください。

構成の依存関係

一部のバリデーターはサービス構成を必要とします。

バリデーター	必須構成
`checkIdentityType`	`configuration.identity.typeIds`、`db.identities`
`hasOrgRole`、`hasOrgRoleSameOrAbove`、`hasOrgRoleAssignmentPermission`	`configuration.organization.roles`、`db.organizations`
`hasOrgOwnerRemainingAfterMembersUpsert`、`hasOrgOwnerRemainingAfterMemberRemoval`	`configuration.organization.roles`、`db.organizations`

🔀 合成

エクスポート	動作
`all(...validators)`	逐次 AND — バリデーターを 1 つずつ実行し、最初のスローで即座に失敗
`some(...validators)`	並行 OR — `Promise.allSettled` ですべてのバリデーターを実行。いずれかが成功すれば通過し、すべて失敗した場合は入力順で最初に収集されたエラーをスロー

多くの SDK ルートは、管理者または組織メンバーのアクセスに some(checkIdentityType(['admin']), hasOrgRole(...)) を使用します。

import { validators } from '@nodeblocks/backend-sdk';

const { isAuthenticated, some, checkIdentityType, hasOrgRole } = validators;

validators: [
  isAuthenticated(),
  some(
    checkIdentityType(['admin']),
    hasOrgRole(['owner', 'admin'], ['params', 'requestParams', 'organizationId'])
  ),
],

📦 SDK バリデーターカタログ

すべてのバリデーターは src/validators/index.ts に対応する validators 名前空間からエクスポートされます。

合成

エクスポート	シグネチャ
`all`	`(...validators: Validator[]) => Validator`
`some`	`(...validators: Validator[]) => Validator`

認証と Identity

エクスポート	シグネチャ	注記
`isAuthenticated`	`() => Validator`	`context.authenticate` を呼び出します。デフォルトは `getBearerTokenInfo`
`checkIdentityType`	`(allowedTypes) => Validator`	認証も実行。`db.identities` と `configuration.identity.typeIds` が必要

Organization

エクスポート	シグネチャ	注記
`hasOrgRole`	`(allowedRoles, organizationIdPath) => Validator`	`configuration.organization.roles` によりロールキーをマッピング
`hasOrgRoleSameOrAbove`	`(orgIdPath, identityIdPath, rolesByRankAsc?) => Validator`	デフォルトのランク順: `['member', 'admin', 'owner']`
`hasOrgRoleAssignmentPermission`	`(orgIdPath, membersPath, rolesByRankAsc?) => Validator`	メンバーの upsert 時のロール割り当てを検証
`hasOrgOwnerRemainingAfterMembersUpsert`	`(orgIdPath, membersPath) => Validator`	組織不変条件のみ — 認証なし
`hasOrgOwnerRemainingAfterMemberRemoval`	`(orgIdPath, identityIdPath) => Validator`	組織不変条件のみ — 認証なし

リソース所有権

汎用的な所有権チェック:

ownsResource(resource, ownerIdPathInResource, resourceIdPathInPayload)

使用できる resource コレクション: chatChannels、chatMessages、orders、profiles、subscriptions、notifications。

ドメインラッパーは partial(ownsResource, [collection, [ownerField]]) です。リソース ID のパスだけを渡します。

エクスポート	コレクション	所有者フィールド
`ownsProfile`	`profiles`	`identityId`
`ownsOrder`	`orders`	`identityId`
`ownsChannel`	`chatChannels`	`ownerId`
`ownsMessage`	`chatMessages`	`senderId`
`ownsSubscription`	`subscriptions`	`subscribedId`
`ownsNotification`	`notifications`	`receiverId`

ほとんどの所有権バリデーターは内部で認証します。明確にするため、SDK ルートでは isAuthenticated() も含めることがよくあります。

Chat

エクスポート	シグネチャ	注記
`hasSubscription`	`(channelIdPath, subscribedIdPath?) => Validator`	パスを省略すると、`subscribedId` はトークンの `identityId` がデフォルト
`hasOrganizationAccessToMessageTemplate`	`(allowedRoles, messageTemplateIdPath) => Validator`	`hasOrgRole` と異なり、DB の生の `member.role` 文字列を比較
`channelExists`	`(channelIdPath) => Validator`	存在確認のみ — 認証なし

その他

エクスポート	シグネチャ	注記
`isSelf`	`(identityIdPath) => Validator`	対象 Identity が認証済みユーザーと一致することを確認
`doesCategoryExist`	直接の `Validator`	`params.requestParams.categoryId` を読み取り — ファクトリーではない

ユーティリティ関数

これらはバリデーターと一緒にエクスポートされますが、ルートバリデーターそのものではありません。

エクスポート	モジュール	目的
`getResourceById`	`ownsResource`	コレクションから `id` によってドキュメントを取得
`getSubscriptionByChannelAndSubscriber`	`hasSubscription`	`channelId` + `subscribedId` でサブスクリプションを取得

🔗 ルートでのバリデーター使用

src/routes/ の withRoute にバリデーターを接続します。それらは compose(withSchema, withRoute) により機能へ合成されます。

管理者またはリソース所有者

src/routes/profile.ts から:

import { handlers, primitives, validators } from '@nodeblocks/backend-sdk';

const { getProfileById } = handlers;
const { withRoute } = primitives;
const { isAuthenticated, some, checkIdentityType, ownsProfile } = validators;

export const getProfileRoute = withRoute({
  method: 'GET',
  path: '/profiles/:profileId',
  validators: [
    isAuthenticated(),
    some(
      checkIdentityType(['admin']),
      ownsProfile(['params', 'requestParams', 'profileId'])
    ),
  ],
  // ハンドラーチェーンは省略。バリデーターが先に実行される。
  handler: getProfileById,
});

不変条件を伴う組織メンバーの upsert

src/routes/organization.ts から:

import { validators } from '@nodeblocks/backend-sdk';

const {
  isAuthenticated,
  all,
  some,
  checkIdentityType,
  hasOrgRole,
  hasOrgRoleAssignmentPermission,
  hasOrgOwnerRemainingAfterMembersUpsert,
} = validators;

validators: [
  isAuthenticated(),
  some(
    checkIdentityType(['admin']),
    all(
      hasOrgRole(['owner', 'admin'], ['params', 'requestParams', 'organizationId']),
      hasOrgRoleAssignmentPermission(
        ['params', 'requestParams', 'organizationId'],
        ['params', 'requestBody']
      )
    )
  ),
  hasOrgOwnerRemainingAfterMembersUpsert(
    ['params', 'requestParams', 'organizationId'],
    ['params', 'requestBody']
  ),
],

カテゴリーの存在

import { validators } from '@nodeblocks/backend-sdk';

const { isAuthenticated, doesCategoryExist } = validators;

validators: [isAuthenticated(), doesCategoryExist],

🛠️ カスタムバリデーターの作成

import { primitives } from '@nodeblocks/backend-sdk';

const validateIdentityExists: primitives.Validator = async ({ context, params }) => {
  const identityId = params.requestParams?.identityId;
  const identity = await context.db.identities.findOne({ id: String(identityId) });

  if (!identity) {
    throw new primitives.NodeblocksError(
      404,
      'Identity not found',
      'validateIdentityExists'
    );
  }
};

ファクトリーパターン

const requireResourceExists = (collectionName: string, paramName: string) => {
  return async (payload: primitives.RouteHandlerPayload) => {
    const { context, params } = payload;
    const resourceId = params.requestParams?.[paramName];

    const resource = await context.db[collectionName].findOne({
      id: String(resourceId),
    });
    if (!resource) {
      throw new primitives.NodeblocksError(
        404,
        `${collectionName} not found`,
        'requireResourceExists'
      );
    }
  };
};

NodeblocksError(status, message, source) をスローしてリクエストを拒否します。バリデーターは成功時に void へ解決する必要があります。

🌐 WebSocket バリデーター

WebSocket ルートでは withRoute({ protocol: 'ws', validators }) に WsValidator を使用します。defService はクライアント接続時に、接続 URL のクエリ文字列から導出された params とともにバリデーターを実行します。

{ context, params: { requestQuery: { /* URL から取得 */ } } }

該当する場合は同じバリデーターファクトリーを接続するか、WS 固有の検査にはカスタム WsValidator 関数を書いてください。

WebSocket ルート構成はルート »、チャットストリーミングのセットアップはWebSocket サービスガイド »を参照してください。

🚨 エラー処理

バリデーターは NodeblocksError をスローします。defService はスローされたエラーを正規化して Express へ渡します。エラーレスポンスを送るにはアプリケーションレベルで nodeBlocksErrorMiddleware() をマウントしてください。

import { middlewares } from '@nodeblocks/backend-sdk';

const { nodeBlocksErrorMiddleware } = middlewares;

app.use(nodeBlocksErrorMiddleware());

クライアントは次を受け取ります。

{
  "error": {
    "message": "Category does not exist"
  }
}

stack は NODE_ENV === 'development' の場合にのみ含まれます。省略可能な data はエラーに設定されている場合に含まれます。

完全なエラーモデルはエラーハンドリング »を参照してください。

📐 推奨事項

ハンドラーより先にルートバリデーター — スキーマはハンドラーラッパー内部で形状を検証し、バリデーターは先にビジネスロジックを通過させます。
SDK バリデーターを優先する — 場当たり的な DB 検査の代わりに hasOrgRole、ownsProfile などを使用します。
ファクトリーを呼び出す — isAuthenticated()、checkIdentityType([...])、hasOrgRole([...], path) を使い、doesCategoryExist は () なしで直接使用します。
選択肢には some() を使用する — 管理者 OR 組織所有者 OR リソース所有者のアクセスパターンに使います。
タイプ ID とロール ID を構成する — タイプ／ロールバリデーターを使用する場合、configuration.identity.typeIds と configuration.organization.roles を設定します。
論理的に合成する — 認証 → 認可 → リソースの存在／不変条件の順にします。
クエリにインデックスを付ける — バリデーターはしばしば id でクエリするため、それらのフィールドに MongoDB インデックスを確保します。

➡️ 次へ

スキーマ » — リクエスト形状の検証とスキーマとバリデーターの違い
ルート » — withRoute とハンドラーチェーンへのバリデーター接続
機能 » — 機能でのスキーマとルートの組み合わせ
サービス » — defService による合成済み機能のマウント
エラーハンドリング » — NodeblocksError とミドルウェア

🔍 バリデーターとは？​

📐 スキーマとバリデーター​

⚙️ コンテキストとパス​

構成の依存関係​

🔀 合成​

📦 SDK バリデーターカタログ​

合成​

認証と Identity​

Organization​

リソース所有権​

Chat​

その他​

ユーティリティ関数​

🔗 ルートでのバリデーター使用​

管理者またはリソース所有者​

不変条件を伴う組織メンバーの upsert​

カテゴリーの存在​

🛠️ カスタムバリデーターの作成​

ファクトリーパターン​

🌐 WebSocket バリデーター​

🚨 エラー処理​

📐 推奨事項​

➡️ 次へ​