Skip to content

tapsi-box/utilities-starter

Repository files navigation

Tapsi Utilities Starter

License: MIT Kotlin Spring Boot Maven Central

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.4</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

Authors

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

About

Tapsi Utilities Starter - Common Infrastructure Utilities for Spring Boot Applications

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 2

  •  
  •  

Languages