🔧 共通ユーティリティ

Nodeblocks SDKは、一般的な操作のための汎用ユーティリティ関数を提供します。これらのユーティリティは、アプリケーション全体で頻繁に使用されるUUID生成や型チェックなどの基本的なタスクを処理します。

---

🎯 概要

共通ユーティリティは、日常的なプログラミングタスクのための基本的なヘルパー関数を提供します。一般的な操作のシンプルさと信頼性に焦点を当てています。

主な機能

• UUID生成: 信頼性の高いUUID v4生成
• 型チェック: オブジェクトとエラーの型バリデーション
• クロスプラットフォーム: 異なる環境間で一貫して動作
• 軽量: 最小限の依存関係とオーバーヘッド

---

🆔 UUID生成

generateUUID

一意の識別子のためのUUID v4文字列を生成します。

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

const { generateUUID } = utils;

const id = generateUUID();
// 戻り値: "550e8400-e29b-41d4-a716-446655440000"

使用例

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

const { generateUUID } = utils;

// 一意のIDを生成
const userId = generateUUID();
const sessionId = generateUUID();
const requestId = generateUUID();

// オブジェクトで使用
const user = {
  id: generateUUID(),
  name: 'John Doe',
  email: 'john@example.com'
};

// 複数のIDを生成
const ids = Array.from({ length: 5 }, () => generateUUID());

エンティティユーティリティとの統合

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

const { generateUUID, createBaseEntity } = utils;

// 追加のUUIDフィールドを持つカスタムエンティティ作成
const createOrder = (orderData: OrderData) => {
  const baseEntity = createBaseEntity(orderData);
  
  return {
    ...baseEntity,
    orderNumber: generateUUID(), // 追加のUUIDフィールド
    trackingId: generateUUID()   // 別のUUIDフィールド
  };
};

---

🔍 型チェック

isObject

値がオブジェクト型（関数を含む）かどうかをチェックします。

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

const { isObject, isError } = utils;

// オブジェクトチェック
isObject({});           // true
isObject([]);           // true
isObject(() => {});     // true
isObject(null);         // false
isObject(undefined);    // false
isObject('string');     // false
isObject(123);          // false
isObject(true);         // false

isError

値がErrorインスタンスかどうかをチェックします。

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

const { isError } = utils;

// エラーチェック
isError(new Error('message'));     // true
isError(new TypeError('type'));    // true
isError(new ReferenceError());     // true
isError('error string');           // false
isError({});                       // false
isError(null);                     // false
isError(undefined);                // false

使用例

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

const { isObject, isError } = utils;

// 関数パラメータをバリデート
const processData = (data: unknown) => {
  if (!isObject(data)) {
    throw new Error('Data must be an object');
  }
  
  // TypeScriptはdataがオブジェクトであることを認識
  return Object.keys(data);
};

// 安全なオブジェクト操作
const safeMerge = (target: unknown, source: unknown) => {
  if (!isObject(target) || !isObject(source)) {
    return target;
  }
  
  return { ...target, ...source };
};

// 条件付き処理
const processValue = (value: unknown) => {
  if (isObject(value)) {
    // オブジェクトを処理
    return JSON.stringify(value);
  } else {
    // プリミティブを処理
    return String(value);
  }
};

エラー処理の例

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

const { isError } = utils;

// isErrorを使用したエラー処理
const safeAsyncOperation = async () => {
  try {
    return await riskyOperation();
  } catch (error) {
    if (isError(error)) {
      // Errorインスタンスを処理
      return { error: error.message };
    } else {
      // 他のタイプのスローされた値を処理
      return { error: 'Unknown error occurred' };
    }
  }
};

// エラー処理用の型ガード
const handleResult = (result: unknown) => {
  if (isError(result)) {
    // TypeScriptはresultがError型であることを認識
    console.error('Operation failed:', result.message);
    return false;
  }

  return result;
};

---

🔧 高度な使用法

カスタム型ガード

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

const { isObject, isError } = utils;

// カスタム型ガードを構築
const isUserObject = (value: unknown): value is User => {
  return isObject(value) && 
         'id' in value && 
         'name' in value && 
         'email' in value;
};

const isProductObject = (value: unknown): value is Product => {
  return isObject(value) && 
         'id' in value && 
         'name' in value && 
         'price' in value;
};

// 使用
const validateUser = (data: unknown) => {
  if (!isUserObject(data)) {
    throw new Error('Invalid user data');
  }

  // TypeScriptはdataがUser型であることを認識
  return data.name;
};

// エラー型ガード
const isApiError = (error: unknown): error is ApiError => {
  return isError(error) &&
         'statusCode' in error &&
         'message' in error;
};

const isValidationError = (error: unknown): error is ValidationError => {
  return isError(error) &&
         'field' in error &&
         'value' in error;
};

// エラー型ガードでの使用
const handleApiResponse = (result: unknown) => {
  if (isApiError(result)) {
    // TypeScriptはresultがApiErrorであることを認識
    console.error(`API Error ${result.statusCode}: ${result.message}`);
  } else if (isValidationError(result)) {
    // TypeScriptはresultがValidationErrorであることを認識
    console.error(`Validation Error in ${result.field}: ${result.value}`);
  } else {
    console.log('Success:', result);
  }
};

UUIDユーティリティ

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

const { generateUUID } = utils;

// UUIDバリデーション
const isValidUUID = (uuid: string): boolean => {
  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
  return uuidRegex.test(uuid);
};

// プレフィックス付きUUIDを生成
const generatePrefixedUUID = (prefix: string): string => {
  return `${prefix}-${generateUUID()}`;
};

// ショートUUIDを生成（最初の8文字）
const generateShortUUID = (): string => {
  return generateUUID().split('-')[0];
};

// 使用
const orderId = generatePrefixedUUID('order'); // "order-550e8400-e29b-41d4-a716-446655440000"
const shortId = generateShortUUID();           // "550e8400"

オブジェクトユーティリティ

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

const { isObject, isError } = utils;

// 深いオブジェクトバリデーション
const isDeepObject = (value: unknown): boolean => {
  if (!isObject(value)) return false;
  
  // すべての値がオブジェクトまたはプリミティブであるかチェック
  return Object.values(value).every(val => 
    isObject(val) || typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean'
  );
};

// 安全なオブジェクトアクセス
const safeGet = (obj: unknown, path: string): unknown => {
  if (!isObject(obj)) return undefined;
  
  return path.split('.').reduce((current, key) => {
    return isObject(current) ? current[key] : undefined;
  }, obj);
};

// 使用
const data = { user: { profile: { name: 'John' } } };
const userName = safeGet(data, 'user.profile.name'); // "John"
const invalid = safeGet(data, 'user.profile.age');   // undefined

// エラー処理ユーティリティ
const createErrorResult = (error: unknown): ErrorResult => {
  if (isError(error)) {
    return {
      success: false,
      error: error.message,
      type: error.name
    };
  }

  return {
    success: false,
    error: String(error),
    type: 'UnknownError'
  };
};

const logError = (error: unknown): void => {
  if (isError(error)) {
    console.error(`[${error.name}] ${error.message}`);
    if (error.stack) {
      console.error(error.stack);
    }
  } else {
    console.error('Unknown error:', error);
  }
};

---

📊 パフォーマンスに関する考慮事項

UUID生成

• パフォーマンス: UUID生成は高速で効率的
• 一意性: 衝突確率が極めて低い
• 分布: UUID空間全体に均等に分布

型チェック

• パフォーマンス: isObjectとisErrorは速度のために最適化
• 精度: null、undefined、プリミティブ型などのエッジケースを処理
• 互換性: 配列、関数、すべてのErrorサブクラスで動作

---

📐️ ベストプラクティス

1. 一貫したUUID使用

// ✅ 良い: すべての一意の識別子にgenerateUUIDを使用
const userId = generateUUID();
const orderId = generateUUID();
const sessionId = generateUUID();

// ❌ 避ける: 異なるID生成方法を混在
const userId = generateUUID();
const orderId = Date.now().toString(); // 一貫性がない

2. isObjectによる型安全性

// ✅ 良い: 型ガードにisObjectを使用
const processData = (data: unknown) => {
  if (!isObject(data)) {
    throw new Error('Expected object');
  }
  // TypeScriptはdataがオブジェクトであることを認識
  return Object.keys(data);
};

// ❌ 避ける: 直接の型アサーション
const processData = (data: unknown) => {
  const obj = data as object; // 安全でない
  return Object.keys(obj);
};

3. エラー処理

// ✅ 良い: 型チェックによる適切なエラー処理
const safeProcess = (data: unknown) => {
  try {
    if (!isObject(data)) {
      return { error: 'Invalid data type' };
    }
    return { success: true, data };
  } catch (error) {
    if (isError(error)) {
      // Errorインスタンスを具体的に処理
      return { error: error.message, type: error.name };
    } else {
      // 他のスローされた値を処理
      return { error: String(error), type: 'UnknownError' };
    }
  }
};

// ✅ 良い: 型安全なエラー処理
const handleAsyncOperation = async (): Promise<Result> => {
  try {
    const result = await riskyAsyncOperation();
    return { success: true, data: result };
  } catch (error) {
    if (isError(error)) {
      // TypeScriptはerrorがError型であることを認識
      return { success: false, error: error.message };
    }
    return { success: false, error: 'Unknown error' };
  }
};

---

🔗 関連項目

• Entity Utilities - エンティティ作成でのUUIDの使用
• Authentication Utilities - トークン生成とバリデーション
• Error Handling - エラー処理パターン