Tapsi Utilities Starter

Common Infrastructure Utilities for Spring Boot Applications

Overview

Tapsi Utilities Starter is a comprehensive Kotlin library that provides essential utilities and extensions for Spring Boot applications. It offers a collection of commonly used functions, security services, reactive programming utilities, and formatting tools to accelerate development and maintain consistency across projects.

Features

🔧 Common Extensions

• Type casting utilities with safe casting operations
• Collection extensions for enhanced data manipulation
• String utilities including Persian/English number conversion
• Method reflection utilities for reactive type detection

🔐 Security Utilities

• Encryption/Decryption services with salt support
• Hash services for secure password handling
• JWT token utilities for authentication
• Security properties for configuration management

⚡ Reactive Programming

• Reactor extensions for Mono and Flux operations
• Context utilities for reactive context management
• CompletableFuture integration with reactive streams
• Tuple extensions for reactive data handling

⏰ Time Management

• Time operations for date/time manipulation
• Time value objects for type-safe time handling
• Time extensions for common time operations

🎨 Formatting & Generation

• Random code generators for unique identifiers
• Format utilities for data presentation
• Custom formatters for specialized formatting needs

✅ Validation Framework

• Validator interface for reactive validation patterns
• CompositeValidator for combining multiple validators
• ValidatorFactory for Spring context-based validator management
• Auto-configuration for seamless validator integration

🚀 Spring Boot Integration

• Auto-configuration for seamless integration
• Spring context utilities for dependency injection
• Bean management utilities

Installation

Maven

<dependency>
    <groupId>box.tapsi.libs</groupId>
    <artifactId>utilities-starter</artifactId>
    <version>0.9.5</version>
</dependency>

Quick Start

1. Add Dependency

Include the library in your Spring Boot project's dependencies.

2. Auto-Configuration

The library automatically configures necessary beans when included in your classpath.

3. Use Utilities

import box.tapsi.libs.utilities.*
import box.tapsi.libs.utilities.validator.*

// Common extensions
val castedValue: String = anyObject.castOrThrow<String>()
val persianNumbers = "12345".toPersianNumber() // "۱۲۳۴۵"

// Security services
@Autowired
lateinit var encryptionService: EncryptionService

val encrypted = encryptionService.encrypt("sensitive data", "salt")
val decrypted = encryptionService.decrypt(encrypted, "salt")

// Random code generation
@Autowired
lateinit var codeGenerator: CodeGenerator

val uniqueCode = codeGenerator.generate(8, "ORDER") // "ORDER-12345678"

// Time operations
@Autowired
lateinit var timeOperator: TimeOperator

val now = timeOperator.now()
val formattedDate = timeOperator.format(now, "yyyy-MM-dd")

// Validation framework
@Autowired
lateinit var validatorFactory: ValidatorFactory

val validator = validatorFactory.getValidator<User>("userValidator", "emailValidator")
validator.validate(user).subscribe()

Usage Examples

Common Extensions

// Safe type casting
val result: String = someObject.castOrThrow<String>()

// Collection utilities
val items = listOf("a", "b", "a", "c")
val distinctLast = items.distinctLastBy { it } // ["b", "a", "c"]

// Number conversion
val persian = "123".toPersianNumber() // "۱۲۳"
val english = "۱۲۳".toEnglishNumber() // "123"

// Method reflection
val method = MyClass::class.java.getMethod("getData")
val isReactive = method.isReturningPublisher() // true if returns Mono/Flux

Security Services

@Service
class UserService(
  private val encryptionService: EncryptionService,
  private val hashService: HashService
) {

  fun createUser(password: String): User {
    val salt = encryptionService.generateSalt()
    val hashedPassword = hashService.hash(password, salt)

    return User(
      passwordHash = hashedPassword,
      salt = salt
    )
  }

  fun verifyPassword(password: String, user: User): Boolean {
    return hashService.verify(password, user.passwordHash, user.salt)
  }
}

Reactive Extensions

// Mono extensions
Mono.just("data")
  .withContext("key", "value")
  .subscribe()

// Context utilities
Mono.deferContextual { ctx ->
  val userId = ctx.get<String>("userId")
  getUserById(userId)
}

Time Operations

@Service
class SchedulingService(
  private val timeOperator: TimeOperator
) {

  fun scheduleTask() {
    val now = timeOperator.now()
    val tomorrow = timeOperator.addDays(now, 1)
    val formatted = timeOperator.format(tomorrow, "yyyy-MM-dd HH:mm:ss")

    // Schedule logic here
  }
}

Validation Framework

// Define custom validators
@Component("emailValidator")
class EmailValidator : Validator<User> {
  override fun validate(input: User): Mono<Void> {
    return if (input.email.isValidEmail()) {
      Mono.empty()
    } else {
      Mono.error(ValidationException("Invalid email format"))
    }
  }
}

@Component("ageValidator")
class AgeValidator : Validator<User> {
  override fun validate(input: User): Mono<Void> {
    return if (input.age >= 18) {
      Mono.empty()
    } else {
      Mono.error(ValidationException("User must be at least 18 years old"))
    }
  }
}

// Use ValidatorFactory to combine validators
@Service
class UserService(
  private val validatorFactory: ValidatorFactory
) {
  
  fun createUser(user: User): Mono<User> {
    val validator = validatorFactory.getValidator<User>("emailValidator", "ageValidator")
    
    return validator.validate(user)
      .then(Mono.just(user))
      .doOnNext { saveUser(it) }
  }
}

// Manual composite validator usage
@Service
class OrderService {
  
  fun validateOrder(order: Order): Mono<Void> {
    val validators = listOf(
      OrderAmountValidator(),
      OrderItemValidator(),
      OrderStatusValidator()
    )
    
    val compositeValidator = CompositeValidator(validators)
    return compositeValidator.validate(order)
  }
}

Configuration

Security Properties

tapsi:
  security:
    crypto:
      algorithm: AES
      key-size: 256
    hash:
      algorithm: SHA-256
      iterations: 10000

Auto-Configuration

The library provides Spring Boot auto-configuration. You can customize behavior by:

1. Excluding auto-configuration classes if needed
2. Overriding bean definitions in your configuration
3. Using conditional beans for specific scenarios

Validator Configuration

The validator framework is automatically configured when the library is included:

// Validator beans are automatically discovered and registered
@Component("userValidator")
class UserValidator : Validator<User> { ... }

@Component("orderValidator") 
class OrderValidator : Validator<Order> { ... }

// ValidatorFactory is automatically available for injection
@Service
class MyService(
  private val validatorFactory: ValidatorFactory
) {
  fun validateUser(user: User) {
    val validator = validatorFactory.getValidator<User>("userValidator")
    // Use validator...
  }
}

The ValidatorAutoConfiguration class automatically:

• Scans for Validator implementations
• Registers them as Spring beans
• Provides ValidatorFactory for validator management
• Enables composite validation patterns

Testing

The library includes comprehensive test coverage and provides test utilities:

@SpringBootTest
class MyServiceTest {

  @Test
  fun `should encrypt and decrypt data`() {
    val encryptionService = EncryptionServiceImpl()
    val original = "test data"
    val salt = encryptionService.generateSalt()

    val encrypted = encryptionService.encrypt(original, salt)
    val decrypted = encryptionService.decrypt(encrypted, salt)

    assertEquals(original, decrypted)
  }

  @Test
  fun `should validate user with composite validator`() {
    val emailValidator = EmailValidator()
    val ageValidator = AgeValidator()
    val validators = listOf(emailValidator, ageValidator)
    val compositeValidator = CompositeValidator(validators)
    
    val validUser = User(email = "test@example.com", age = 25)
    
    compositeValidator.validate(validUser)
      .test()
      .verifyComplete()
  }

  @Test
  fun `should fail validation for invalid user`() {
    val emailValidator = EmailValidator()
    val ageValidator = AgeValidator()
    val validators = listOf(emailValidator, ageValidator)
    val compositeValidator = CompositeValidator(validators)
    
    val invalidUser = User(email = "invalid-email", age = 16)
    
    compositeValidator.validate(invalidUser)
      .test()
      .verifyError()
  }
}

Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Development Setup

# Clone the repository
git clone https://github.com/tapsi-box/utilities-starter.git

# Navigate to project directory
cd utilities-starter

# Build the project
./gradlew build

# Run tests
./gradlew test

# Run code quality checks
./gradlew detekt
./gradlew spotlessCheck

Code Quality

This project maintains high code quality standards:

• Kotlin with strict compiler options
• Detekt for static code analysis
• Spotless for code formatting
• Comprehensive testing with JUnit 5
• Spring Boot Test integration

Dependencies

Core Dependencies

• Spring Framework 6.2.10 - Core Spring functionality
• Spring Boot 3.5.5 - Auto-configuration support
• Reactor Core 3.7.9 - Reactive programming support
• Spring Security Crypto 6.5.3 - Security utilities
• JJWT 0.12.5 - JWT handling
• Jackson 2.17.0 - JSON processing
• Micrometer 1.15.3 - Metrics support

Test Dependencies

• JUnit 5 - Testing framework
• Spring Boot Test - Integration testing
• Reactor Test - Reactive testing utilities
• Mockito Kotlin - Mocking framework

Version Compatibility

Library Version	Spring Boot	Kotlin	Java
0.0.9	3.5.x	1.9.23	17+

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Project Wiki

Authors

• Mahdi Bohloul - @mahdibohloul

Acknowledgments

• Spring Boot team for the excellent framework
• Kotlin team for the amazing language
• Reactor team for reactive programming support
• All contributors and users of this library

---

Made with ❤️ by the Tapsi team