🏢 Organization Handler Blocks
Organization handler blocks provide core business logic functions for organization management operations in Nodeblocks applications. These handlers encapsulate common patterns for organization database operations, data transformation, and response formatting.
🎯 Overview
Organization handler blocks are designed to:
- Encapsulate organization business logic in reusable functions
- Handle organization database operations with proper error management
- Transform organization data between different formats
- Ensure type safety with TypeScript integration
- Support composition with other organization blocks
📋 Organization Handler Types
Organization Async Handlers
Functions that perform asynchronous organization operations (database calls, API requests, etc.).
Organization Sync Handlers
Functions that perform synchronous organization operations (data transformation, validation, etc.).
Organization Terminator Handlers
Functions that format and return the final organization response.
🔧 Available Organization Handlers
createOrganization
Creates a new organization in the database with owner assignment.
Purpose: Handles creation of organizations with owner assignment and entity management
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with organizationId or error
Example Usage:
// Used in route composition:
const createOrganizationRoute = withRoute({
handler: compose(createOrganization, lift(formatOrganizationResponse))
});
Key Features:
- Validates request body is present and not empty
- Validates ownerId is provided
- Assigns owner role to the initial user
- Creates base entity with timestamps and ID
- Inserts organization into database
- Returns organizationId on success
- Handles database errors gracefully
getOrganizationById
Retrieves a single organization by ID.
Purpose: Fetches organization data with existence validation
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with organization or error
Example Usage:
compose(getOrganizationById, normalizeTerminator);
Key Features:
- Validates organizationId is provided
- Finds organization by ID in database
- Returns 404 if organization not found
- Returns organization data on success
- Handles database errors gracefully
findOrganizations
Finds multiple organizations with optional filtering.
Purpose: Handles querying organizations with filter support
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with organizations array or error
Example Usage:
compose(findOrganizations, listTerminator);
Key Features:
- Accepts optional filter from request query
- Returns all organizations if no filter provided
- Returns array of organizations
- Handles database errors gracefully
updateOrganization
Updates an existing organization by ID.
Purpose: Handles updating organizations with validation and conflict detection
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with update result or error
Example Usage:
compose(updateOrganization, terminator);
Key Features:
- Validates organizationId is provided
- Validates request body is present and not empty
- Updates base entity with timestamps
- Checks if organization exists before updating
- Returns update result on success
- Handles not found and update failures
- Handles database errors gracefully
deleteOrganization
Deletes an organization by ID.
Purpose: Handles safe deletion of organizations with existence validation
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with deletion result or error
Example Usage:
compose(deleteOrganization, deleteTerminator);
Key Features:
- Validates organizationId is provided
- Deletes organization by ID from database
- Returns 404 if organization not found
- Returns deletion result on success
- Handles database errors gracefully
getOrganizationUserRole
Retrieves a user's role within an organization.
Purpose: Fetches user role information for organization access control
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with role or error
Example Usage:
compose(getOrganizationUserRole, roleTerminator);
Key Features:
- Validates organizationId and userId are provided
- Finds organization and user by ID
- Returns 404 if organization or user not found
- Returns user role on success
- Handles database errors gracefully
checkOrganizationUserExistence
Checks if a user exists within an organization.
Purpose: Validates user membership in organization for access control
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with isUserInOrganization flag or error
Example Usage:
compose(checkOrganizationUserExistence, existenceTerminator);
Key Features:
- Validates organizationId and userId are provided
- Finds organization by ID
- Checks if user exists in organization users array
- Returns boolean flag for user existence
- Handles database errors gracefully
findOrganizationUsers
Finds users within an organization (placeholder implementation).
Purpose: Handles querying organization users with pagination support
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with organizationUsers object or error
Example Usage:
compose(findOrganizationUsers, usersTerminator);
Key Features:
- Validates organizationId is provided
- Finds organization by ID
- Returns users array with count and total
- Handles database errors gracefully
- (TODO: add pagination logic)
upsertOrganizationUsers
Adds or updates users in an organization with role merging.
Purpose: Handles adding/updating organization users with role management
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with upsert result or error
Example Usage:
compose(upsertOrganizationUsers, upsertTerminator);
Key Features:
- Validates organizationId is provided
- Validates users array is present and not empty
- Finds organization by ID
- Merges new users with existing users by ID
- Sanitizes user IDs and roles
- Updates users array in database
- Returns upsert result on success
- Handles not found and update failures
- Handles database errors gracefully
deleteOrganizationUser
Removes a user from an organization.
Purpose: Handles safe removal of users from organizations
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with deletion result or error
Example Usage:
compose(deleteOrganizationUser, deleteTerminator);
Key Features:
- Validates organizationId and userId are provided
- Removes user from organization users array
- Returns 404 if organization not found
- Returns deletion result on success
- Handles not found and update failures
- Handles database errors gracefully
findOrganizationsForUser
Finds organizations for a specific user (placeholder implementation).
Purpose: Handles querying user's organizations with role filtering
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with organizationsForUser object or error
Example Usage:
compose(userSchema, findOrganizationsForUser, orgsTerminator);
Key Features:
- Validates userId is provided
- Accepts optional roles filter
- Finds organizations where user is a member (optionally by role)
- Returns organizations array with count and total
- Handles database errors gracefully
- (TODO: add pagination and expand logic)
🎯 Organization Terminator Handlers
normalizeOrganizationTerminator
Normalizes organization data by removing database-specific fields.
Purpose: Cleans organization data for API response
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Normalized organization object
Example Usage:
compose(schema, getOrganizationById, normalizeOrganizationTerminator);
normalizeOrganizationsListTerminator
Normalizes organizations list by removing database-specific fields from each item.
Purpose: Cleans organizations array data for API response
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Array of normalized organization objects
Example Usage:
compose(schema, findOrganizations, normalizeOrganizationsListTerminator);
deleteOrganizationTerminator
Terminates organization deletion with proper status code.
Purpose: Formats successful deletion response with 204 status
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Response object with 204 statusCode
Example Usage:
compose(schema, deleteOrganization, deleteOrganizationTerminator);
normalizeOrganizationUserRoleTerminator
Normalizes organization user role data for API response.
Purpose: Formats user role data for API response
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Object containing normalized role data
Example Usage:
compose(schema, getOrganizationUserRole, normalizeOrganizationUserRoleTerminator);
normalizeOrganizationUserExistenceTerminator
Normalizes organization user existence data for API response.
Purpose: Formats user existence check data for API response
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Object containing normalized existence data
Example Usage:
compose(schema, checkOrganizationUserExistence, normalizeOrganizationUserExistenceTerminator);
normalizeOrganizationUsersListTerminator
Normalizes organization users list (placeholder implementation).
Purpose: Formats organization users list for API response
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Object containing normalized users list data
Example Usage:
compose(schema, findOrganizationUsers, normalizeOrganizationUsersListTerminator);
deleteOrganizationUserTerminator
Terminates organization user deletion with proper status code.
Purpose: Formats successful user deletion response with 204 status
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Response object with 204 statusCode
Example Usage:
compose(schema, deleteOrganizationUser, deleteOrganizationUserTerminator);
upsertOrganizationUsersTerminator
Terminates organization users upsert with proper status code.
Purpose: Formats successful users upsert response with 204 status
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Response object with 204 statusCode
Example Usage:
compose(schema, upsertOrganizationUsers, upsertOrganizationUsersTerminator);
normalizeOrganizationsForUserTerminator
Normalizes organizations for user data for API response.
Purpose: Formats organizations for user data for API response
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Object containing normalized organizations for user data
Example Usage:
compose(schema, findOrganizationsForUser, normalizeOrganizationsForUserTerminator);