メインコンテンツまでスキップ
バージョン: 0.13.0 (Previous)

🔧 ユーティリティ

Nodeblocks SDK は、堅牢で保守しやすいバックエンドサービスの構築に役立つ包括的なユーティリティ関数セットを提供します。これらのユーティリティはカテゴリ別に整理され、SDK 全体で使用される関数型プログラミングパターンとシームレスに連携するよう設計されています。

インポート名前空間​

ユーティリティは SDK の 3 つの名前空間にまたがっています。すべてが utils にあるわけではありません。

import { utils, primitives, handlers } from '@nodeblocks/backend-sdk';
名前空間ソースこのページのカテゴリ
utilssrc/utils/*Authentication、Entity、Common、Logging、Cookie、Cache、Schema
primitivessrc/primitives/combinators.tsComposition、Handler ユーティリティ
handlerssrc/handlers/utils.tsmergeData（合成パイプラインで使用）

🔐 Authentication ユーティリティ (utils)​

安全な API エンドポイントのための包括的な認証・トークン管理ユーティリティです。

  • getBearerTokenInfo: Authorization ヘッダーからのデフォルト Bearer トークン認証
  • getCookieTokenInfo: Web アプリケーション向け Cookie ベースのトークン認証
  • generateUserAccessToken: セキュリティ検証付きユーザーアクセストークンの作成
  • generateAppAccessToken: サービス間通信向けアプリアクセストークンの作成
  • generateRefreshToken: セッション管理用リフレッシュトークンの作成
  • generateOnetimeToken: 一時アクセス用ワンタイムトークンの作成
  • decryptAndVerifyJWT: 暗号化された JWT の復号と検証
  • tokenPassesSecurityCheck: トークンに対するフィンガープリント／IP／ユーザーエージェントの検証
  • defaultRefreshTokenBodyAuth: リクエスト本文からリフレッシュトークンを検証
  • defaultRefreshTokenCookieAuth: Cookie からリフレッシュトークンを検証
  • resolveRefreshTokenFromRequest: Cookie および／または本文からリフレッシュトークンを解決
  • deriveCookieMaxAge: expiresIn をミリ秒単位の Cookie maxAge へ変換

完全なエクスポート一覧は Authentication ユーティリティ を参照してください。

Authentication ユーティリティを学ぶ →

🆔 Entity ユーティリティ (utils)​

自動フィールド生成によるデータベースエンティティの作成・管理に不可欠なユーティリティです。

  • createBaseEntity: 自動生成された id、createdAt、updatedAt フィールドを持つエンティティを作成
  • updateBaseEntity: updatedAt タイムスタンプを自動で更新
  • BaseEntity: 標準エンティティ基本フィールドの TypeScript 型

Entity ユーティリティを学ぶ →

🔧 Composition ユーティリティ (primitives)​

ハンドラーの合成、非同期操作の処理、複雑なビジネスロジックパイプラインの構築に不可欠なユーティリティです。

  • compose: 複数の関数を単一のパイプラインに結合
  • lift: 前の合成ステップからの非同期 Promise を同期ターミネーター（通常は orThrow）へ橋渡し
  • flatMap: Result を返す同期操作を連結
  • flatMapAsync: Result を返す非同期操作を連結
  • applyPayloadArgs: ペイロードから引数を抽出し、純粋関数に適用
  • orThrow: エラー型を HTTP コードにマッピングし、成功データを抽出
  • match: ネストしたパス検査用の述語ヘルパー
  • ifElse: 分岐用の関数型条件
  • hasValue: 空でない述語（null／undefined／空でない）
  • withSoftDelete: 検索／更新／削除操作に論理削除フィルターを適用するハンドラーラッパー
  • mergeData (handlers): 後続ハンドラー用にデータをペイロードコンテキストへマージ
  • notFromEmitter、markAsFromEmitter: RxJS／WebSocket パイプラインでエミッター ID によりメッセージをフィルター／タグ付け

either や mapMatchingErrorToFalse などの追加 primitives エクスポートは、Composition ユーティリティに記載されています。

Composition ユーティリティを学ぶ →

🎭 Handler ユーティリティ (primitives)​

任意のハンドラーに適用できる、横断的関心事とミドルウェア風ユーティリティです。

  • withLogging: 任意の関数に包括的なログ記録を追加
  • withPagination: MongoDB find() 操作に自動ページネーションを追加
  • withPaginatedProperty: findOne() 結果のネスト配列をページネーション
  • DEFAULT_REDACTION: withLogging のデフォルトフィールドマスキング規則
  • DEFAULT_SANITIZATION: withLogging のデフォルトサニタイズ規則

Handler ユーティリティを学ぶ →

🔧 Common ユーティリティ (utils)​

一般的な操作のための汎用ユーティリティ関数です。

  • generateUUID: UUID v4 文字列を生成
  • isObject: 値がオブジェクトまたは関数かを検査（実行時検査）
  • isError: 値が Error インスタンスかを検査
  • isResult: neverthrow の Ok／Err インスタンスの型ガード

Common ユーティリティを学ぶ →

📝 Logging ユーティリティ (utils)​

構造化ログのための Pino による事前構成済みログ設定です。

  • nodeblocksLogger: 見やすいフォーマットを備えた事前構成済み Pino ロガー
  • nodeblocksHTTPLogger: HTTP リクエスト／レスポンスのログミドルウェア
  • Logger: ロガー統合用 TypeScript 型エイリアス（pino.Logger）

Logging ユーティリティを学ぶ →

🍪 Cookie ユーティリティ (utils)​

Cookie ベース認証および Set-Cookie オプション解決のヘルパーです。

  • CookieOptions、DEFAULT_COOKIE_OPTS、withCookieOptDefaults、isCookieMode、whenCookieAuth

Cookie ユーティリティを学ぶ →

💾 Cache ユーティリティ (utils)​

サービスレベルのメモ化のための TTL 付きインメモリ LRU キャッシュです。

  • createCache: maxEntries、ttl、get／set／del／clear／pruneExpired／size を持つファクトリー

Cache ユーティリティを学ぶ →

📋 Schema ユーティリティ (utils)​

NoSQL インジェクション保護を備えた AJV スキーマヘルパーです。

  • createAjvInstance、addMongoFilterKeyword、applySchemaDefaults、applyDefaultSchemaEnhancements

スキーマ検証とは異なる、ルートレベルのビジネスロジックバリデーターについては Validator を参照してください。

Schema ユーティリティを学ぶ →

➡️ 次のステップ​