メインコンテンツまでスキップ
バージョン: 0.5.0 (最新)

🔧 共通ユーティリティ

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 } = utils;

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

使用例​

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

const { isObject } = 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 { isObject } = 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;
};

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 } = 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

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

UUID生成​

  • パフォーマンス: UUID生成は高速で効率的
  • 一意性: 非常に低い衝突確率
  • 分布: UUID空間全体に適切に分布

型チェック​

  • パフォーマンス: isObjectは速度のために最適化されている
  • 正確性: nullやundefinedなどのエッジケースを処理
  • 互換性: 配列や関数で動作

📐️ ベストプラクティス​

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) {
    return { error: 'Processing failed' };
  }
};

🔗 関連項目​