🧩 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

⚠️ Note: Identity normalization (removing _id and password fields) is now handled by normalizeIdentity and normalizeIdentitiesWithoutPassword from the authentication blocks for enhanced security.

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

buildLockIdentityPayload

Builds identity lock payload for identity status management.

Purpose: Creates a standardized lock payload object for identity locking operations.

Parameters: None

Returns: Result<Record<string, unknown>, NodeblocksError> - Result containing lock payload or error

Handler Process:

• Input: No parameters required
• Process: Creates a standardized lock payload object
• Output: Result containing lock status payload
• Errors: None expected (always returns success)

Example Usage:

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

const result = await blocks.buildLockIdentityPayload();
if (result.isOk()) {
  const payload = result.value; // { locked: true }
}

buildUnlockIdentityPayload

Builds identity unlock payload for identity status management.

Purpose: Creates a standardized unlock payload object for identity unlocking operations.

Parameters: None

Returns: Result<Record<string, unknown>, NodeblocksError> - Result containing unlock payload or error

Handler Process:

• Input: No parameters required
• Process: Creates a standardized unlock payload object
• Output: Result containing unlock status payload
• Errors: None expected (always returns success)

Example Usage:

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

const result = await blocks.buildUnlockIdentityPayload();
if (result.isOk()) {
  const payload = result.value; // { locked: false }
}

---

buildIdentityIdFilter

Builds identity ID filter object for database queries.

Function Signature:

buildIdentityIdFilter(
  identityId: string
): Result<{ identityId: string }, never>

Handler Process:

• Input: Identity ID string parameter
• Process: Converts input to string and wraps in filter object structure
• Output: Filter object with identityId property for database queries
• Errors: None (always succeeds)

Example Usage:

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

const result = blocks.buildIdentityIdFilter('identity-123');
if (result.isOk()) {
  const filter = result.value; // { identityId: 'identity-123' }
  // Use in database queries
}

// Used in route composition:
const getIdentityRoute = withRoute({
  handler: compose(
    applyPayloadArgs(
      buildIdentityIdFilter,
      [['params', 'requestParams', 'identityId']],
      'filter'
    )
  )
});

Parameters:

• identityId: Unique identifier string to filter by

Returns: Result<{ identityId: string }, never> with filter object for database queries

---

🔗 Related Documentation

• Identity Schemas - Identity validation schemas