# Helper

> Helper Utilities Layer

- Skill: `harshamendu/helper` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add harshamendu/helper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/harshamendu/helper/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Harshamendu (https://skillmd.com/u/harshamendu)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/harshamendu/helper

---

# Helper Utilities Layer

> **📝 Note:** This guide uses generic placeholder names to be reusable across any Spring Boot microservice.
> Replace with your actual implementation:
> - `{YourService}` → Your service name (e.g., `OrderService`, `PaymentService`)
> - `BusinessService` → Your core service (e.g., `OrderService`, `UserService`)
> - `DataService` → Your data processing service (e.g., `PaymentService`, `InventoryService`)
> - `IntegrationService` → Your external integration (e.g., `PaymentGatewayService`)
> - `{RequestType}` → Your request DTO (e.g., `CreateOrderRequest`)
> - `{ResponseType}` → Your response DTO (e.g., `OrderResponse`)


## Purpose
The helper layer provides reusable utility methods for common operations in authentication services, including token manipulation, parameter extraction, collection operations, and data transformation. These pure, stateless functions promote code reuse and maintain consistency across the application.

## Architecture
- **Utility Class Pattern**: Static methods with no instance state
- **Generic Programming**: Type-safe generic methods
- **Functional Programming**: Stream-based operations
- **Pure Functions**: No side effects, deterministic outputs

## Package Structure
```
helper/
└── ServiceHelpers.java    # Authentication service utility methods
```

## Quick Reference

### Basic Utility Pattern
```java
public class ServiceHelpers {
    private ServiceHelpers() {
        throw new AssertionError("Cannot instantiate utility class");
    }
    
    public static String stripBearerPartFromToken(String bearerToken) {
        // Pure function - no side effects
    }
    
    public static <T> T getMandatoryParam(Map<String, Object> params, String paramName) {
        // Type-safe generic extraction
    }
}
```

### Service Integration
```java
@Service
public class ProcessingServiceImpl implements ProcessingService {
    public AuthenticatedTokens refreshAccessToken(String authorization) {
        // Token manipulation
        String refreshToken = stripBearerPartFromToken(authorization);
        
        // Type-safe parameter extraction
        List<String> roles = getMandatoryParam(tokenData, "roles");
        
        // Collection operations
        List<String> authRoles = filterAuthRoles(roles);
        List<String> merged = mergeRolesWithEntitlement(authRoles, resource accesss);
        
        return buildTokenResponse(merged);
    }
}
```

## Core Operations

### Token Manipulation
- `stripBearerPartFromToken()` - Remove "Bearer " prefix (case-insensitive, idempotent)

### Parameter Extraction
- `getMandatoryParam()` - Type-safe generic extraction with validation

### Collection Operations
- `extractServiceIds()` - Stream-based service ID extraction
- `getDefaultProfiles()` - Filter and map profiles
- `removeDuplicates()` - Dedup while preserving order (LinkedHashSet)
- `filterAuthRoles()` - Filter to authentication roles only
- `mergeRolesWithEntitlement()` - Merge with null safety and dedup

## Key Principles

1. **Pure Functions**: No side effects, same input → same output
2. **Immutability**: Always return new collections, never modify inputs
3. **Type Safety**: Generic methods prevent ClassCastException
4. **Null Safety**: Return empty collections instead of null
5. **Idempotent**: Safe to call multiple times with same result
6. **Static Import Friendly**: Clean, readable code in services

## Example Package
```
com.example.microserviceorch.helper.example
```

See `guides/` for detailed patterns and best practices.
See `examples/` for complete working code samples.