🆔 Entity Utilities

The Nodeblocks SDK provides essential utilities for creating and managing database entities with automatic field generation. These utilities ensure consistent entity structure across your application with automatic timestamps and unique identifiers.

---

🎯 Overview

Entity utilities provide standardized functions for creating and updating database entities with automatic field generation. They ensure consistency in entity structure and reduce boilerplate code.

Key Features

• Automatic ID Generation: UUID v4 generation for entity identifiers
• Timestamp Management: Automatic createdAt and updatedAt field generation
• Consistent Structure: Standardized entity creation and update patterns
• Type Safety: Full TypeScript support with proper typing

---

🆔 Entity Creation

createBaseEntity

Creates a new entity with automatic field generation.

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

const { createBaseEntity } = utils;

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

const user = createBaseEntity(userData);

Generated fields:

• id: UUID v4 string
• createdAt: ISO timestamp string
• updatedAt: ISO timestamp string

Result:

{
  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'
}

Usage in Handlers

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

const { createBaseEntity } = utils;

const createUserHandler = async (payload: RouteHandlerPayload) => {
  const { params } = payload;
  
  // Create entity with base fields
  const userEntity = createBaseEntity(params.requestBody);
  
  // Save to database
  const result = await payload.context.db.users.insertOne(userEntity);
  
  return ok(mergeData(payload, { userId: userEntity.id }));
};

---

🔄 Entity Updates

updateBaseEntity

Updates an existing entity with automatic timestamp management.

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

const { updateBaseEntity } = utils;

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

const updatedUser = updateBaseEntity(updateData);

Generated fields:

• updatedAt: Current ISO timestamp string

Result:

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

Usage in Update Handlers

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

const { updateBaseEntity } = utils;

const updateUserHandler = async (payload: RouteHandlerPayload) => {
  const { params, context } = payload;
  const userId = params.requestParams?.userId;
  
  // Prepare update data with timestamp
  const updateData = updateBaseEntity(params.requestBody);
  
  // Update in database
  const result = await context.db.users.updateOne(
    { id: userId },
    { $set: updateData }
  );
  
  return ok(mergeData(payload, { updated: true }));
};

---

🔧 Advanced Usage

Custom Entity Creation

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

const { createBaseEntity } = utils;

const createProduct = (productData: ProductData) => {
  const baseEntity = createBaseEntity(productData);
  
  // Add custom fields
  return {
    ...baseEntity,
    status: 'active',
    category: productData.category || 'general'
  };
};

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

Batch Entity Creation

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' }
]);

Conditional Updates

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

const { updateBaseEntity } = utils;

const updateUserConditionally = (userId: string, updateData: Partial<User>) => {
  const baseUpdate = updateBaseEntity(updateData);
  
  // Add conditional logic
  if (updateData.status === 'inactive') {
    return {
      ...baseUpdate,
      deactivatedAt: new Date().toISOString()
    };
  }
  
  return baseUpdate;
};

---

📊 Field Specifications

Generated Fields

Field	Type	Description	Generated By
id	string	UUID v4 identifier	createBaseEntity
createdAt	string	ISO timestamp of creation	createBaseEntity
updatedAt	string	ISO timestamp of last update	Both functions

Field Format

• ID: UUID v4 format (550e8400-e29b-41d4-a716-446655440000)
• Timestamps: ISO 8601 format (2024-01-15T10:30:00.000Z)

---

📐️ Best Practices

1. Consistent Usage

// ✅ Good: Always use entity utilities
const user = createBaseEntity(userData);
const updatedUser = updateBaseEntity(updateData);

// ❌ Avoid: Manual field generation
const user = {
  ...userData,
  id: generateUUID(), // Inconsistent
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
};

2. Type Safety

// ✅ Good: Use proper typing
interface UserData {
  email: string;
  name: string;
}

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

3. Database Integration

// ✅ Good: Use in database operations
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 });
};

---

🔗 See Also

• Common Utilities - UUID generation and type checking
• Handler Component - Using entities in handlers