🆔 エンティティユーティリティ

NodeBlocks SDKは、自動フィールド生成によるデータベースエンティティの作成と管理のための必須ユーティリティを提供します。これらのユーティリティは、自動タイムスタンプと一意の識別子を使用して、アプリケーション全体で一貫したエンティティ構造を確保します。

---

🎯 概要

エンティティユーティリティは、自動フィールド生成によるデータベースエンティティの作成と更新のための標準化された関数を提供します。エンティティ構造の一貫性を確保し、定型コードを削減します。

主な機能

• 自動ID生成: エンティティ識別子のためのUUID v4生成
• タイムスタンプ管理: 自動createdAtおよびupdatedAtフィールド生成
• 一貫した構造: 標準化されたエンティティ作成および更新パターン
• 型安全性: 適切な型指定による完全なTypeScriptサポート

---

🆔 エンティティ作成

createBaseEntity

自動フィールド生成により新しいエンティティを作成します。

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

const { createBaseEntity } = utils;

const userData = {
  email: 'user@example.com',
  name: 'John Doe',
  role: 'user'
};

const user = createBaseEntity(userData);

生成されるフィールド：

• id: UUID v4文字列
• createdAt: ISOタイムスタンプ文字列
• updatedAt: ISOタイムスタンプ文字列

結果：

{
  email: 'user@example.com',
  name: 'John Doe',
  role: 'user',
  id: '550e8400-e29b-41d4-a716-446655440000',
  createdAt: '2024-01-15T10:30:00.000Z',
  updatedAt: '2024-01-15T10:30:00.000Z'
}

ハンドラーでの使用

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

const { createBaseEntity } = utils;

const createUserHandler = async (payload: RouteHandlerPayload) => {
  const { params } = payload;

  // ベースフィールドを持つエンティティを作成
  const userEntity = createBaseEntity(params.requestBody);

  // データベースに保存
  const result = await payload.context.db.users.insertOne(userEntity);

  return ok(mergeData(payload, { userId: userEntity.id }));
};

---

🔄 エンティティ更新

updateBaseEntity

自動タイムスタンプ管理により既存のエンティティを更新します。

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

const { updateBaseEntity } = utils;

const updateData = {
  name: 'Jane Doe',
  email: 'jane@example.com'
};

const updatedUser = updateBaseEntity(updateData);

生成されるフィールド：

• updatedAt: 現在のISOタイムスタンプ文字列

結果：

{
  name: 'Jane Doe',
  email: 'jane@example.com',
  updatedAt: '2024-01-15T11:45:00.000Z'
}

更新ハンドラーでの使用

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

const { updateBaseEntity } = utils;

const updateUserHandler = async (payload: RouteHandlerPayload) => {
  const { params, context } = payload;
  const userId = params.requestParams?.userId;

  // タイムスタンプ付きで更新データを準備
  const updateData = updateBaseEntity(params.requestBody);

  // データベースで更新
  const result = await context.db.users.updateOne(
    { id: userId },
    { $set: updateData }
  );

  return ok(mergeData(payload, { updated: true }));
};

---

🔧 高度な使用法

カスタムエンティティ作成

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

const { createBaseEntity } = utils;

const createProduct = (productData: ProductData) => {
  const baseEntity = createBaseEntity(productData);

  // カスタムフィールドを追加
  return {
    ...baseEntity,
    status: 'active',
    category: productData.category || 'general'
  };
};

const product = createProduct({
  name: 'Sample Product',
  price: 29.99,
  description: 'A sample product'
});

バッチエンティティ作成

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

const { createBaseEntity } = utils;

const createMultipleUsers = (usersData: UserData[]) => {
  return usersData.map(userData => createBaseEntity(userData));
};

const users = createMultipleUsers([
  { name: 'User 1', email: 'user1@example.com' },
  { name: 'User 2', email: 'user2@example.com' }
]);

条件付き更新

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

const { updateBaseEntity } = utils;

const updateUserConditionally = (userId: string, updateData: Partial<User>) => {
  const baseUpdate = updateBaseEntity(updateData);

  // 条件付きロジックを追加
  if (updateData.status === 'inactive') {
    return {
      ...baseUpdate,
      deactivatedAt: new Date().toISOString()
    };
  }

  return baseUpdate;
};

---

📊 フィールド仕様

生成されるフィールド

フィールド	型	説明	生成元
id	string	UUID v4識別子	createBaseEntity
createdAt	string	作成時のISOタイムスタンプ	createBaseEntity
updatedAt	string	最終更新のISOタイムスタンプ	両方の関数

フィールド形式

• ID: UUID v4形式 (550e8400-e29b-41d4-a716-446655440000)
• タイムスタンプ: ISO 8601形式 (2024-01-15T10:30:00.000Z)

---

📐️ ベストプラクティス

1. 一貫した使用

// ✅ 良い例: 常にエンティティユーティリティを使用
const user = createBaseEntity(userData);
const updatedUser = updateBaseEntity(updateData);

// ❌ 避けるべき: 手動フィールド生成
const user = {
  ...userData,
  id: generateUUID(), // 一貫性がない
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
};

2. 型安全性

// ✅ 良い例: 適切な型指定を使用
interface UserData {
  email: string;
  name: string;
}

const userData: UserData = { email: 'user@example.com', name: 'John' };
const user = createBaseEntity(userData);

3. データベース統合

// ✅ 良い例: データベース操作で使用
const createUser = async (userData: UserData) => {
  const entity = createBaseEntity(userData);
  return await db.users.insertOne(entity);
};

const updateUser = async (userId: string, updateData: Partial<UserData>) => {
  const update = updateBaseEntity(updateData);
  return await db.users.updateOne({ id: userId }, { $set: update });
};

---

🔗 関連項目

• 共通ユーティリティ - UUID生成と型チェック
• ハンドラーコンポーネント - ハンドラーでのエンティティ使用