メインコンテンツまでスキップ
バージョン: 0.4.2

🔧 共通ユーティリティ

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());

// ファイル名に使用
const filename = `upload-${generateUUID()}.jpg`;

// リクエストトラッキング
const trackingId = generateUUID();
console.log(`Processing request: ${trackingId}`);

ベストプラクティス​

// 良い - 一意性が保証されるUUIDを使用
const entityId = generateUUID();

// 悪い - 衝突の可能性があるランダム数値
const entityId = Math.random().toString();

// 良い - データベースキーとして使用
const user = {
  id: generateUUID(),
  email: 'user@example.com'
};

// 悪い - 予測可能なカウンター
let userCounter = 1;
const user = {
  id: `user-${userCounter++}`,
  email: 'user@example.com'
};

🔍 型チェック​

isObject​

値がオブジェクト型（null以外）かどうかを検証します。

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

const { isObject } = utils;

// 基本的な使用
console.log(isObject({}));           // true
console.log(isObject({ a: 1 }));     // true
console.log(isObject([]));           // true （配列もオブジェクト）
console.log(isObject(null));         // false
console.log(isObject(undefined));    // false
console.log(isObject('string'));     // false
console.log(isObject(123));          // false

実用的な使用例​

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

const { isObject } = utils;

// リクエストボディの検証
const validateRequestBody = (body: any) => {
  if (!isObject(body)) {
    throw new Error('リクエストボディはオブジェクトである必要があります');
  }
  
  if (Object.keys(body).length === 0) {
    throw new Error('リクエストボディは空にできません');
  }
  
  return body;
};

// 設定オブジェクトの検証
const mergeConfigs = (defaultConfig: any, userConfig: any) => {
  if (!isObject(defaultConfig)) {
    throw new Error('デフォルト設定はオブジェクトである必要があります');
  }
  
  if (userConfig && !isObject(userConfig)) {
    throw new Error('ユーザー設定はオブジェクトである必要があります');
  }
  
  return { ...defaultConfig, ...userConfig };
};

// データベース結果の検証
const processDbResult = (result: any) => {
  if (!isObject(result)) {
    throw new Error('無効なデータベース結果');
  }
  
  return result;
};

🔄 配列ユーティリティ​

isArray​

値が配列かどうかを検証します。

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

const { isArray } = utils;

console.log(isArray([]));           // true
console.log(isArray([1, 2, 3]));    // true
console.log(isArray({}));           // false
console.log(isArray('string'));     // false
console.log(isArray(null));         // false

使用例​

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

const { isArray } = utils;

// 配列データの処理
const processItems = (items: any) => {
  if (!isArray(items)) {
    throw new Error('アイテムは配列である必要があります');
  }
  
  return items.map(item => processItem(item));
};

// フィルタリング関数
const filterValidItems = (data: any) => {
  if (!isArray(data)) {
    return [];
  }
  
  return data.filter(item => isObject(item) && item.isValid);
};

🎯 型安全なヘルパー​

hasProperty​

オブジェクトが特定のプロパティを持つかどうかを検証します。

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

const { hasProperty } = utils;

const user = { id: '123', name: 'John' };

console.log(hasProperty(user, 'id'));    // true
console.log(hasProperty(user, 'email')); // false

// 安全なプロパティアクセス
const getUserEmail = (user: any) => {
  if (!isObject(user)) {
    return null;
  }
  
  if (!hasProperty(user, 'email')) {
    return null;
  }
  
  return user.email;
};

isEmpty​

値が空かどうかを検証します。

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

const { isEmpty } = utils;

console.log(isEmpty(null));        // true
console.log(isEmpty(undefined));   // true
console.log(isEmpty(''));          // true
console.log(isEmpty([]));          // true
console.log(isEmpty({}));          // true
console.log(isEmpty('hello'));     // false
console.log(isEmpty([1, 2]));      // false
console.log(isEmpty({ a: 1 }));    // false

// バリデーションでの使用
const validateInput = (input: any) => {
  if (isEmpty(input)) {
    throw new Error('入力は空にできません');
  }
  
  return input;
};

🔧 文字列ユーティリティ​

slugify​

文字列をURL対応のスラッグに変換します。

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

const { slugify } = utils;

console.log(slugify('Hello World'));     // 'hello-world'
console.log(slugify('商品名１２３'));      // 'shang-pin-ming-123'
console.log(slugify('Special@Chars!'));  // 'special-chars'

// ブログ投稿URLの生成
const createPostUrl = (title: string) => {
  const slug = slugify(title);
  return `/blog/${slug}`;
};

// ファイル名の正規化
const normalizeFilename = (filename: string) => {
  const [name, ext] = filename.split('.');
  return `${slugify(name)}.${ext}`;
};

🎯 デバッグユーティリティ​

inspect​

オブジェクトを人間が読める形式で出力します。

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

const { inspect } = utils;

const complexObject = {
  user: { id: '123', profile: { name: 'John' } },
  items: [1, 2, 3],
  metadata: { created: new Date() }
};

console.log(inspect(complexObject));
// 整形された出力で深いネストオブジェクトも表示

// デバッグログでの使用
const debugLog = (label: string, data: any) => {
  console.log(`[DEBUG] ${label}:`, inspect(data));
};

🔄 パフォーマンスユーティリティ​

throttle​

関数の実行頻度を制限します。

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

const { throttle } = utils;

// APIコールの制限
const throttledSearch = throttle((query: string) => {
  return searchAPI(query);
}, 300); // 300ms間隔で制限

// ログ出力の制限
const throttledLog = throttle((message: string) => {
  console.log(message);
}, 1000); // 1秒間隔で制限

debounce​

関数の実行を遅延させ、頻繁な呼び出しを防ぎます。

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

const { debounce } = utils;

// 入力検証の遅延
const debouncedValidation = debounce((input: string) => {
  return validateInput(input);
}, 500); // 500ms後に実行

// 自動保存機能
const debouncedSave = debounce((data: any) => {
  return saveToDatabase(data);
}, 2000); // 2秒後に実行

🎯 ベストプラクティス​

1. 型チェックの使用​

// 良い - 適切な型チェック
const processData = (data: any) => {
  if (!isObject(data)) {
    throw new Error('データはオブジェクトである必要があります');
  }
  
  if (!isArray(data.items)) {
    throw new Error('アイテムは配列である必要があります');
  }
  
  return data;
};

// 悪い - 型チェックなし
const processData = (data: any) => {
  return data.items.map(item => item.value); // 実行時エラーの可能性
};

2. UUID使用の一貫性​

// 良い - 一貫したUUID使用
const createEntity = (data: any) => {
  return {
    id: generateUUID(),
    ...data,
    createdAt: new Date().toISOString()
  };
};

// 悪い - 不一致なID生成
const createEntity = (data: any) => {
  return {
    id: Math.random().toString(36), // 予測可能
    ...data
  };
};

3. エラーハンドリング​

// 良い - 適切なエラーメッセージ
const validateUser = (user: any) => {
  if (!isObject(user)) {
    throw new Error('ユーザーオブジェクトが必要です');
  }
  
  if (isEmpty(user.email)) {
    throw new Error('メールアドレスが必要です');
  }
  
  return user;
};

// 悪い - 曖昧なエラー
const validateUser = (user: any) => {
  if (!user || !user.email) {
    throw new Error('Invalid user'); // 不明確
  }
  
  return user;
};

➡️ 次へ​

ハンドラーラッパーについて学習して、ログや機能を任意のハンドラーに追加する方法を理解しましょう！