Skip to main content
Version: 0.4.2 (Previous)

🔧 Common Validator Blocks

Common validator blocks provide generic validation functions that can be used across different domains in Nodeblocks applications. These validators ensure proper parameter validation, authentication, and access control for any type of resource.

🎯 Overview​

Common validator blocks are designed to:

  • Provide generic validation functions for reuse across domains
  • Ensure proper authentication and authorization for any resource
  • Validate common parameter types (UUIDs, numbers, required fields)
  • Support flexible access control with role-based and self-access patterns
  • Handle cross-cutting concerns in a consistent way

📋 Common Validator Types​

Authentication Validators​

Validators that check authentication and authorization for any resource.

Parameter Validators​

Validators that check parameter format and presence.

🔧 Available Common Validators​

validateResourceAccess​

Validates resource access based on allowed subjects and token type.

Purpose: Generic access control validator for any resource type

Parameters:

  • allowedSubjects: string[] - Array of allowed user types/subjects
  • authenticate: Authenticator - Authentication function (optional, defaults to getBearerTokenInfo)
  • payload: RouteHandlerPayload - Contains request context and data

Returns: void - Passes through if user has appropriate permissions

Throws:

  • NodeblocksError (401) with message "App token is not valid" or "User token is not valid" for invalid tokens
  • NodeblocksError (401) with message "Identity not found" if user identity doesn't exist
  • NodeblocksError (403) with message "User is not authorized to access this resource" for unauthorized access
  • NodeblocksError (401) with message "Token does not have a valid access type" for invalid token types

Supported Subjects:

  • 'self' - User can access their own resources (ID-based matching)
  • 'admin' - Administrator access (typeId: '100')
  • 'user' - Regular user access (typeId: '001')
  • 'guest' - Guest access (typeId: '000')

User ID Sources (for self-access, checked in order):

  • payload.context.data.userId
  • payload.params.requestParams.userId
  • payload.params.requestQuery.userId
  • payload.params.requestBody.userId

User Type Configuration (defaults):

{
  admin: '100',
  guest: '000', 
  user: '001'
}

Access Logic:

  • App tokens: Always pass if appId is valid
  • User tokens:
    • For 'self' subject: Match user ID with resource user ID
    • For role subjects: Match user typeId with configured typeId
    • At least one subject must match for access to be granted

Usage:

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

const { validateResourceAccess } = validators;

// Admin-only access
compose(validateResourceAccess(['admin']), adminHandler);

// Self or admin access
compose(validateResourceAccess(['self', 'admin']), userHandler);

// Any authenticated user access
compose(validateResourceAccess(['admin', 'user', 'guest']), publicHandler);

requireParam​

Creates a validator that ensures a required parameter is present and not null.

Purpose: Factory function to create parameter requirement validators

Parameters:

  • key: string - The parameter name to validate

Returns: Validator - Validator function that checks for parameter presence

Throws: Error with message "Missing required parameter: [parameterName]" if parameter is null

Usage:

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

const { requireParam } = validators;

// Validate userId parameter
compose(requireParam('userId'), getUserHandler);

// Validate multiple parameters
compose(
  requireParam('userId'),
  requireParam('organizationId'),
  getUserHandler
);

isUUID​

Creates a validator that ensures a parameter follows valid UUID v4 format.

Purpose: Factory function to create UUID format validators

Parameters:

  • key: string - The parameter name to validate as UUID

Returns: Validator - Validator function that checks UUID format

Throws: Error with message "Invalid UUID format for parameter: [parameterName]" if parameter exists but doesn't match UUID format

UUID Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (where x is hexadecimal and y is 8, 9, a, or b)

Usage:

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

const { isUUID } = validators;

// Validate categoryId parameter
compose(isUUID('categoryId'), getCategoryHandler);

// Validate multiple UUID parameters
compose(
  isUUID('userId'),
  isUUID('organizationId'),
  getUserHandler
);

isNumber​

Creates a validator that ensures a parameter can be converted to a valid number.

Purpose: Factory function to create numeric format validators

Parameters:

  • key: string - The parameter name to validate as numeric

Returns: Validator - Validator function that checks numeric conversion

Throws: Error with message "Parameter [parameterName] must be a number" if parameter exists but cannot be parsed as number

Usage:

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

const { isNumber } = validators;

// Validate limit parameter
compose(isNumber('limit'), getItemsHandler);

// Validate pagination parameters
compose(
  isNumber('page'),
  isNumber('limit'),
  getItemsHandler
);

🔗 Related Documentation​