🧩 Identity Blocks

Identity blocks provide pure business logic functions for identity operations in NodeBlocks applications. These blocks contain the core application logic and are designed to be used with applyPayloadArgs for payload context lifting.

---

🎯 Overview

Identity blocks are designed to:

• Separate business logic from payload handling
• Provide pure functions that take only required data
• Enable easy testing with isolated logic
• Support composition with payload context lifting
• Return Result types for proper error handling

---

📋 Identity Block Types

Identity Retrieval Blocks

Pure functions for getting identity information.

Identity Search Blocks

Pure functions for finding and filtering identities.

Identity Update Blocks

Pure functions for modifying identity data.

Identity Deletion Blocks

Pure functions for removing identities.

Identity Terminator Blocks

Response formatting functions for API responses.

---

🔧 Available Identity Blocks

getIdentityById

Retrieves a single identity by its unique identifier from the database.

Purpose: Queries the database for an identity with the specified ID and returns the identity object or an appropriate error.

Parameters:

• db: Collection - MongoDB collection for identity data
• identityId: string - Unique identifier for the identity to retrieve

Returns: Promise<Result<unknown, NodeblocksError>> - Result with identity object or error

Handler Process:

• Input: Database collection and identity ID string
• Process: Queries database for identity with matching ID, validates existence
• Output: Identity object or error with appropriate status code
• Errors: 404 (not found), 500 (database error)

Usage:

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

const { getIdentityById } = blocks;

// Used in route composition:
const getIdentityRoute = withRoute({
  handler: applyPayloadArgs(
    getIdentityById,
    [
      ['context', 'db', 'identities'],
      ['params', 'requestParams', 'identityId'],
    ],
    'identityId'
  )
});

---

findIdentities

Retrieves multiple identities from the database with optional filtering.

Purpose: Executes a database query with the provided filter and returns an array of matching identities.

Parameters:

• db: Collection - MongoDB collection for identity data
• filter: Record<string, unknown> - Optional filter object for querying specific identities

Returns: Promise<Result<T[], NodeblocksError>> - Result with array of identity objects or error

Handler Process:

• Input: Database collection and filter object for querying identities
• Process: Executes database query with provided filter, handles cursor operations
• Output: Array of identity objects or error with appropriate status code
• Errors: 500 (database error)

Usage:

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

const { findIdentities } = blocks;

// Used in route composition:
const listIdentitiesRoute = withRoute({
  handler: compose(applyPayloadArgs(
    findIdentities,
    [
      ['context', 'db', 'identities'],
      ['params', 'requestQuery'],
    ]
  ))
});

---

updateIdentity

Updates an existing identity in the database with validation and error handling.

Purpose: Validates the input data, updates the identity in the database, and returns the identity ID on success.

Parameters:

• db: Collection - MongoDB collection for identity data
• identityId: string - Unique identifier for the identity to update
• identity: T - Update data object with identity fields to modify

Returns: Promise<Result<string, NodeblocksError>> - Result with identity ID or error

Handler Process:

• Input: Database collection, identity ID, and update data object
• Process: Validates input data, updates base entity timestamps, performs database update
• Output: Identity ID on success or error with appropriate status code
• Errors: 400 (missing data), 404 (not found), 500 (database error)

Usage:

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

const { updateIdentity } = blocks;

// Used in route composition:
const updateIdentityRoute = withRoute({
  handler: compose(applyPayloadArgs(
    updateIdentity,
    [
      ['context', 'db', 'identities'],
      ['params', 'requestParams', 'identityId'],
      ['params', 'requestBody'],
    ],
    'identityId'
  ))
});

---

deleteIdentity

Permanently removes an identity from the database by its unique identifier.

Purpose: Executes a database delete operation and validates the deletion success.

Parameters:

• db: Collection - MongoDB collection for identity data
• identityId: string - Unique identifier for the identity to delete

Returns: Promise<Result<boolean, NodeblocksError>> - Result with success flag or error

Handler Process:

• Input: Database collection and identity ID string
• Process: Executes database delete operation, validates deletion success
• Output: Boolean success flag or error with appropriate status code
• Errors: 404 (not found), 500 (database error)

Usage:

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

const { deleteIdentity } = blocks;

// Used in route composition:
const deleteIdentityRoute = withRoute({
  handler: compose(applyPayloadArgs(
    deleteIdentity,
    [
      ['context', 'db', 'identities'],
      ['params', 'requestParams', 'identityId'],
    ],
    'identityId'
  ))
});

---

🎯 Identity Terminator Blocks

getIdentityTerminator

Formats single identity response for API response.

Purpose: Removes internal _id field and returns a clean identity object for API responses.

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing identity data or error

Returns: T - Normalized identity object without _id field

Response Formatting:

• Input: Result with identity data from database
• Processing: Removes internal _id field and returns clean identity object
• Output: Normalized identity object without database-specific fields

Usage:

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

const { getIdentityTerminator } = blocks;

// Used in route composition:
const getIdentityRoute = withRoute({
  handler: compose(applyPayloadArgs(
    getIdentityById,
    [
      ['context', 'db', 'identities'],
      ['params', 'requestParams', 'identityId'],
    ],
    'identityId'
  ), lift(getIdentityTerminator))
});

---

findIdentitiesTerminator

Normalizes identities list by removing database-specific fields from each item.

Purpose: Maps through the identities array and removes the _id field from each item.

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing identities array data or error

Returns: Array<Omit<T, '_id'>> - Array of normalized identity objects without _id fields

Response Formatting:

• Input: Result with identities array data from database
• Processing: Maps through identities array, removes _id field from each item
• Output: Array of normalized identity objects without database-specific fields

Usage:

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

const { findIdentitiesTerminator } = blocks;

// Used in route composition:
const listIdentitiesRoute = withRoute({
  handler: compose(applyPayloadArgs(
    findIdentities,
    [
      ['context', 'db', 'identities'],
      ['params', 'requestQuery'],
    ]
  ), lift(findIdentitiesTerminator))
});

---

deleteIdentityTerminator

Formats successful identity deletion response with proper status code.

Purpose: Validates deletion success and formats the response object with appropriate status code.

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing deletion operation data or error

Returns: { statusCode: number } - Response object with statusCode for successful deletion

Response Formatting:

• Input: Result with deletion operation data
• Processing: Validates deletion success, formats response object
• Output: Response object with 204 status code for successful deletion

Usage:

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

const { deleteIdentityTerminator } = blocks;

// Used in route composition:
const deleteIdentityRoute = withRoute({
  handler: compose(applyPayloadArgs(
    deleteIdentity,
    [
      ['context', 'db', 'identities'],
      ['params', 'requestParams', 'identityId'],
    ],
    'identityId'
  ), lift(deleteIdentityTerminator))
});

🔗 Related Documentation

• Identity Schemas - Identity validation schemas