🧩 Block

Blocks are pure business logic functions that contain the core application logic for specific operations. They are designed to be reusable, testable, and composable building blocks that separate business logic from payload handling and routing concerns.

---

🔍 What is a Block?

A block is a pure function that takes only the data it needs (no payload context) and returns a Result type for proper error handling. Blocks are used within handlers to perform business logic operations, making handlers thin wrappers that handle payload context and call blocks for the actual work.

┌─────────────┐
│   Handler   │  Receives payload, extracts data
├─────────────┤
│   Block ▷   │  Pure function with business logic
│             │  getUserById(db, userId)
└─────────────┘

Key take-aways:

1. Pure functions – no payload context, only required parameters (great for testing!).
2. Result types – always return Result<T, Error> for predictable error handling.
3. Reusable – same block can be used across different handlers and services.
4. Testable – easy to unit test without mocking complex payload structures.

---

📐 Design Principles

• Separation of concerns – blocks contain business logic, handlers handle payload context.
• Pure functions – blocks take only what they need, no hidden dependencies.
• Error handling – blocks return Result types for explicit error handling.
• Composability – blocks can be composed together to build complex operations.

---

🧑‍💻 Using Blocks in Handlers

Blocks are typically used within handlers using the applyPayloadArgs utility to lift payload context and pass only required data to blocks:

import { ok, err, Result } from 'neverthrow';
import { primitives, handlers, blocks } from '@nodeblocks/backend-sdk';

const { applyPayloadArgs } = primitives;
const { mergeData } = handlers;

export const getUserHandler: primitives.AsyncRouteHandler<
  Result<primitives.RouteHandlerPayload, primitives.NodeblocksError>
> = async (payload) => {
  const { context, params } = payload;
  const userId = params.requestParams?.userId;

  if (!userId) {
    return err(new primitives.NodeblocksError(400, 'User ID is required', 'getUserHandler'));
  }

  // Use block with applyPayloadArgs to lift payload context
  const result = await applyPayloadArgs(
    blocks.getUserById,
    payload
  )(context.db.profiles, userId);

  if (result.isErr()) {
    return err(result.error);
  }

  const user = result.value;
  return ok(mergeData(payload, { user }));
};

---

🔄 Block vs Handler

Aspect	Block	Handler
Input	Only required data parameters	Full payload with context
Output	Result<T, Error>	Result<RouteHandlerPayload, NodeblocksError>
Purpose	Pure business logic	Payload handling + block orchestration
Testability	Easy - just pass data	Requires payload mocking
Reusability	High - can be used anywhere	Lower - tied to route structure

---

📦 Available Block Categories

Blocks are organized by domain entity. Each entity provides blocks for common operations:

• Authentication Blocks – authentication and authorization logic
• Avatar Blocks – avatar normalization and file management
• Chat Blocks – messaging and real-time communication
• File Storage Blocks – secure file operations and signed URLs
• Identity Blocks – identity lifecycle and security management
• Location Blocks – hierarchical location management
• Mongo Blocks – MongoDB database operations and utilities
• OAuth Blocks – third-party OAuth provider integration
• Order Blocks – order processing and calculations
• Organization Blocks – organization and workspace logic
• Product Blocks – product management operations
• Profile Blocks – profile relationships and social engagement
• User Blocks – user retrieval, normalization, and data formatting

ℹ️ See the Backend Blocks documentation for a complete list of available blocks and their usage.

---

➡️ Next

Learn about Handler » to see how blocks are used within handlers, or explore Backend Blocks » to see available block implementations for different entities.