Utility Packages Reference
Dokumentasi lengkap semua utility packages yang tersedia di MStore Backend (pkg/utils/).
📊 Package Overview
| Category | Packages | Priority |
|---|
| Observability | OpenTelemetry, Logger, Loki | 🔴 HIGH |
| ID Generation | Snowflake, Transaction Code, ID Generator | 🔴 HIGH |
| Message Broker | Kafka, NATS, RabbitMQ, MQTT, Redis Pub/Sub | 🟡 MEDIUM |
| Cache & Database | Redis, MySQL, Transactions | 🟡 MEDIUM |
| Cloud Services | AWS (S3, Cognito), Google (Firebase) | 🟡 MEDIUM |
| Data Processing | Excel, Filter, Mapper, Transform | 🟡 MEDIUM |
| Security & Auth | Hash, JWT, Validator | 🟡 MEDIUM |
| HTTP & gRPC | HTTP Utils, gRPC Client/Server | 🟡 MEDIUM |
| Supporting | Time, Lang, Parser, Payload, Response | 🟢 LOW |
🔴 HIGH PRIORITY
1. OpenTelemetry (OTEL)
Package: pkg/utils/logger/otel.go
Documentation: OpenTelemetry Tracing
Quick Example:
ctx, span := utils_logger.StartLayerSpan(ctx, LayerService, "ProcessOrder")
defer utils_logger.EndLayerSpan(span, nil)
utils_logger.TraceStep(ctx, "validate_input")
2. Snowflake ID Generator
Package: pkg/utils/snowflake/
Documentation: Snowflake ID Generator
Quick Example:
gen, _ := snowflake.New(0, 1)
id := gen.Next() // 1234567890123456789
3. Transaction Code Generator
Package: pkg/utils/txcode/
Documentation: Transaction Code Generator
Quick Example:
code := txcode.GenerateDisplayCode("MC01", "BRN001", time.Now(), 1)
// Output: MC01-BRN001-251013-001-5UJW-7
4. Logger
Package: pkg/utils/logger/
Features:
- Structured logging (Zap)
- Log levels (Debug, Info, Warn, Error)
- Loki integration
- OTEL integration
- Sensitive data sanitization
Quick Example:
import utils_logger "gitlab.com/mushola-store/mstore_backend/pkg/utils/logger"
// Initialize
logger := utils_logger.GetLogger()
// Log with context
logger.InfoWithMapTraceID(ctx, "User logged in", map[string]interface{}{
"user_id": userID,
"ip_address": ipAddr,
})
// Log error
logger.Error("Failed to process payment", "error", err, "transaction_id", txID)
🟡 MEDIUM PRIORITY
5. Message Broker
Package: pkg/utils/message_broker/
Documentation: Message Broker & Event-Driven
Supported Brokers:
- Kafka - Event streaming
- NATS - Microservice RPC
- RabbitMQ - Task queues
- MQTT - IoT devices
- Redis Pub/Sub - Real-time notifications
6. Cache (Redis)
Package: pkg/utils/cache/redis.go
Features:
- Redis connection management
- Get/Set/Delete operations
- TTL support
- Pub/Sub
Quick Example:
import utils_cache "gitlab.com/mushola-store/mstore_backend/pkg/utils/cache"
// Initialize connection
redisConn := &utils_cache.PayloadRedisConnection{
Host: "localhost",
Port: "6379",
Password: "",
}
redisConn.InitRedisConnection()
// Get connection
redis := redisConn.GetConnection()
// Set value with TTL
redis.Set(ctx, "user:123", userData, 1*time.Hour)
// Get value
val, err := redis.Get(ctx, "user:123").Result()
// Delete
redis.Del(ctx, "user:123")
// Pub/Sub
redis.Publish(ctx, "notifications", message)
pubsub := redis.Subscribe(ctx, "notifications")
7. Database (MySQL)
Package: pkg/utils/database/
Features:
- MySQL connection pooling
- Transaction management
- Query helpers
- Migration support
Quick Example:
import utils_db "gitlab.com/mushola-store/mstore_backend/pkg/utils/database"
// Initialize connection
db, err := utils_db.InitMySQL(config)
// Transaction
tx := db.Begin()
defer func() {
if r := recover(); r != nil {
tx.Rollback()
}
}()
// Execute queries
if err := tx.Create(&user).Error; err != nil {
tx.Rollback()
return err
}
tx.Commit()
8. AWS Utils
Package: pkg/utils/aws/
Features:
- S3 file upload/download
- Cognito authentication
- Session management
Quick Example:
import utils_aws "gitlab.com/mushola-store/mstore_backend/pkg/utils/aws"
// Initialize AWS session
aws := &utils_aws.AwsConnectionPayload{
Region: "ap-southeast-1",
AccessKey: os.Getenv("AWS_ACCESS_KEY"),
SecretKey: os.Getenv("AWS_SECRET_KEY"),
}
aws.InitAwsSession()
// S3 Operations
aws.NewS3Session()
s3 := aws.GetS3Session()
// Upload file
file, _ := os.Open("document.pdf")
defer file.Close()
_, err := s3.PutObject(&s3.PutObjectInput{
Bucket: aws.String("my-bucket"),
Key: aws.String("documents/document.pdf"),
Body: file,
})
// Download file
result, _ := s3.GetObject(&s3.GetObjectInput{
Bucket: aws.String("my-bucket"),
Key: aws.String("documents/document.pdf"),
})
defer result.Body.Close()
// Cognito
aws.NewCognitoSession()
cognito := aws.GetCognitoSession()
9. Google Utils (Firebase)
Package: pkg/utils/google/firebase.go
Features:
- Firebase Authentication
- Push Notifications (FCM)
- Firestore operations
Quick Example:
import utils_google "gitlab.com/mushola-store/mstore_backend/pkg/utils/google"
// Initialize Firebase
firebase := utils_google.InitFirebase(ctx, credentialsPath)
// Send push notification
message := &messaging.Message{
Notification: &messaging.Notification{
Title: "New Order",
Body: "You have a new order #12345",
},
Token: deviceToken,
}
response, err := firebase.Send(ctx, message)
10. Excel Utils
Package: pkg/utils/excel/
Features:
- Read Excel files
- Write Excel files
- Template support
- Data validation
Quick Example:
import utils_excel "gitlab.com/mushola-store/mstore_backend/pkg/utils/excel"
// Read Excel
data, err := utils_excel.ReadExcel("data.xlsx", "Sheet1")
// Write Excel
headers := []string{"ID", "Name", "Email"}
rows := [][]interface{}{
{1, "John Doe", "[email protected]"},
{2, "Jane Smith", "[email protected]"},
}
err = utils_excel.WriteExcel("output.xlsx", "Sheet1", headers, rows)
// Read with validation
validatedData, errors := utils_excel.ReadAndValidateExcel(
"import.xlsx",
"Products",
validationRules,
)
11. Hash & Crypto
Package: pkg/utils/hash/
Features:
- Password hashing (bcrypt)
- Token generation
- Encryption/Decryption
Quick Example:
import utils_hash "gitlab.com/mushola-store/mstore_backend/pkg/utils/hash"
// Hash password
hashedPassword, err := utils_hash.HashPassword("mypassword123")
// Verify password
isValid := utils_hash.VerifyPassword("mypassword123", hashedPassword)
// Generate token
token := utils_hash.GenerateToken(32) // 32 bytes random token
// Encrypt/Decrypt
encrypted, _ := utils_hash.Encrypt("sensitive data", encryptionKey)
decrypted, _ := utils_hash.Decrypt(encrypted, encryptionKey)
12. JWT
Package: pkg/utils/jwt/
Features:
- JWT token generation
- Token validation
- Refresh tokens
- Claims extraction
Quick Example:
import utils_jwt "gitlab.com/mushola-store/mstore_backend/pkg/utils/jwt"
// Generate JWT
claims := map[string]interface{}{
"user_id": 123,
"role": "admin",
"exp": time.Now().Add(24 * time.Hour).Unix(),
}
token, err := utils_jwt.GenerateJWT(claims, secretKey)
// Validate JWT
validClaims, err := utils_jwt.ValidateJWT(token, secretKey)
// Extract claims
userID := validClaims["user_id"].(float64)
role := validClaims["role"].(string)
// Refresh token
newToken, err := utils_jwt.RefreshJWT(oldToken, secretKey)
13. HTTP Utils
Package: pkg/utils/http/
Features:
- HTTP client wrapper
- Request/Response helpers
- Retry logic
- Timeout handling
Quick Example:
import utils_http "gitlab.com/mushola-store/mstore_backend/pkg/utils/http"
// GET request
response, err := utils_http.Get(ctx, "https://api.example.com/users")
// POST request
payload := map[string]interface{}{
"name": "John Doe",
"email": "[email protected]",
}
response, err := utils_http.Post(ctx, "https://api.example.com/users", payload)
// With headers
headers := map[string]string{
"Authorization": "Bearer " + token,
"Content-Type": "application/json",
}
response, err := utils_http.PostWithHeaders(ctx, url, payload, headers)
// With retry
response, err := utils_http.PostWithRetry(ctx, url, payload, 3, 2*time.Second)
14. gRPC Utils
Package: pkg/utils/grpc/
Features:
- gRPC client setup
- gRPC server setup
- Interceptors
- Load balancing
Quick Example:
import utils_grpc "gitlab.com/mushola-store/mstore_backend/pkg/utils/grpc"
// gRPC Client
conn, err := utils_grpc.NewGRPCClient("localhost:50051")
defer conn.Close()
client := pb.NewUserServiceClient(conn)
response, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: 123})
// gRPC Server
server := utils_grpc.NewGRPCServer()
pb.RegisterUserServiceServer(server, &userServiceImpl{})
listener, _ := net.Listen("tcp", ":50051")
server.Serve(listener)
15. Validator
Package: pkg/utils/validator/
Features:
- Struct validation
- Custom validation rules
- Error messages
Quick Example:
import (
"github.com/go-playground/validator/v10"
utils_validator "gitlab.com/mushola-store/mstore_backend/pkg/utils/validator"
)
type CreateUserRequest struct {
Email string `validate:"required,email"`
Password string `validate:"required,min=8"`
Age int `validate:"required,gte=18"`
}
// Validate
validate := validator.New()
req := CreateUserRequest{
Email: "[email protected]",
Password: "pass123",
Age: 17,
}
err := validate.Struct(req)
if err != nil {
// Handle validation errors
for _, err := range err.(validator.ValidationErrors) {
fmt.Printf("Field: %s, Error: %s\n", err.Field(), err.Tag())
}
}
16. Feature Flag
Package: pkg/utils/featureflag/goff.go
Documentation: Feature Flags
Quick Example:
import utils_ff "gitlab.com/mushola-store/mstore_backend/pkg/utils/featureflag"
// Check feature flag
if utils_ff.IsEnabled("new_checkout_flow") {
// Use new checkout
} else {
// Use old checkout
}
// With user context
if utils_ff.IsEnabledForUser("beta_features", userID) {
// Show beta features
}
17. ID Generator
Package: pkg/utils/id_generator/
Features:
- UUID generation
- ULID generation
- Custom ID formats
Quick Example:
import utils_id "gitlab.com/mushola-store/mstore_backend/pkg/utils/id_generator"
// Generate UUID
uuid := utils_id.GenerateUUID()
// Output: 550e8400-e29b-41d4-a716-446655440000
// Generate ULID
ulid := utils_id.GenerateULID()
// Output: 01ARZ3NDEKTSV4RRFFQ69G5FAV
// Custom format
customID := utils_id.GenerateCustomID("USR", 8)
// Output: USR-A3F5K2M9
🟢 LOW PRIORITY
18. Filter Utils
Package: pkg/utils/filter/array.go
Quick Example:
import utils_filter "gitlab.com/mushola-store/mstore_backend/pkg/utils/filter"
// Filter array
numbers := []int{1, 2, 3, 4, 5, 6}
evens := utils_filter.Filter(numbers, func(n int) bool {
return n%2 == 0
})
// Result: [2, 4, 6]
// Map array
doubled := utils_filter.Map(numbers, func(n int) int {
return n * 2
})
// Result: [2, 4, 6, 8, 10, 12]
// Reduce array
sum := utils_filter.Reduce(numbers, 0, func(acc, n int) int {
return acc + n
})
// Result: 21
19. Mapper Utils
Package: pkg/utils/mapper/
Quick Example:
import utils_mapper "gitlab.com/mushola-store/mstore_backend/pkg/utils/mapper"
// Map struct to struct
type UserDTO struct {
ID uint64
Name string
Email string
}
type UserResponse struct {
UserID uint64 `json:"user_id"`
FullName string `json:"full_name"`
EmailAddr string `json:"email"`
}
user := UserDTO{ID: 1, Name: "John", Email: "[email protected]"}
var response UserResponse
utils_mapper.MapStruct(user, &response)
Package: pkg/utils/transform/
Quick Example:
import utils_transform "gitlab.com/mushola-store/mstore_backend/pkg/utils/transform"
// String transformations
snake := utils_transform.ToSnakeCase("HelloWorld") // hello_world
camel := utils_transform.ToCamelCase("hello_world") // helloWorld
pascal := utils_transform.ToPascalCase("hello_world") // HelloWorld
// Struct transformations
jsonStr := utils_transform.StructToJSON(user)
utils_transform.JSONToStruct(jsonStr, &user)
21. Time Utils
Package: pkg/utils/time/
Quick Example:
import utils_time "gitlab.com/mushola-store/mstore_backend/pkg/utils/time"
// Format time
formatted := utils_time.FormatDateTime(time.Now())
// Output: 2025-10-13 15:30:45
// Parse time
t, _ := utils_time.ParseDateTime("2025-10-13 15:30:45")
// Time calculations
tomorrow := utils_time.AddDays(time.Now(), 1)
lastWeek := utils_time.SubtractDays(time.Now(), 7)
// Business days
isBusinessDay := utils_time.IsBusinessDay(time.Now())
nextBusinessDay := utils_time.NextBusinessDay(time.Now())
22. Lang (Localization)
Package: pkg/utils/lang/
Quick Example:
import utils_lang "gitlab.com/mushola-store/mstore_backend/pkg/utils/lang"
// Get translation
message := utils_lang.Translate("en", "welcome_message")
// Output: "Welcome to MStore!"
messageID := utils_lang.Translate("id", "welcome_message")
// Output: "Selamat datang di MStore!"
// With parameters
message := utils_lang.TranslateWithParams("en", "order_created", map[string]string{
"order_id": "12345",
})
// Output: "Order #12345 has been created"
23. Parser Utils
Package: pkg/utils/parser/
Quick Example:
import utils_parser "gitlab.com/mushola-store/mstore_backend/pkg/utils/parser"
// Parse JSON
var data map[string]interface{}
utils_parser.ParseJSON(jsonString, &data)
// Parse XML
var xmlData XMLStruct
utils_parser.ParseXML(xmlString, &xmlData)
// Parse CSV
rows, _ := utils_parser.ParseCSV("data.csv")
// Parse query string
params := utils_parser.ParseQueryString("?name=John&age=30")
// Result: map[string]string{"name": "John", "age": "30"}
24. Payload Utils
Package: pkg/utils/payload/
Quick Example:
import utils_payload "gitlab.com/mushola-store/mstore_backend/pkg/utils/payload"
// Extract from Fiber context
var payload CreateUserPayload
utils_payload.ExtractPayload(ctx, &payload)
// Validate payload
if err := utils_payload.ValidatePayload(&payload); err != nil {
return err
}
// Sanitize payload
utils_payload.SanitizePayload(&payload)
25. Response Utils
Package: pkg/utils/response/
Quick Example:
import utils_response "gitlab.com/mushola-store/mstore_backend/pkg/utils/response"
// Success response
return utils_response.Success(ctx, data, "User created successfully")
// Error response
return utils_response.Error(ctx, 400, "Invalid input", err)
// Paginated response
return utils_response.Paginated(ctx, data, pagination)
// Custom response
return utils_response.Custom(ctx, 201, map[string]interface{}{
"success": true,
"data": data,
"message": "Created",
})
Package: pkg/utils/pagination/
Quick Example:
import utils_pagination "gitlab.com/mushola-store/mstore_backend/pkg/utils/pagination"
// Cursor-based pagination
cursor := utils_pagination.NewCursor(lastID, 20)
users, nextCursor, err := repo.FindWithCursor(ctx, cursor)
// Offset-based pagination
page := utils_pagination.NewPage(1, 20)
users, total, err := repo.FindWithPage(ctx, page)
// Response
return utils_response.Paginated(ctx, users, map[string]interface{}{
"next_cursor": nextCursor,
"has_more": len(users) == 20,
})
27. Error Utils
Package: pkg/utils/error/
Quick Example:
import utils_error "gitlab.com/mushola-store/mstore_backend/pkg/utils/error"
// Wrap error with context
err := utils_error.Wrap(err, "failed to create user")
// Create custom error
err := utils_error.New("USER_NOT_FOUND", "User not found", 404)
// Check error type
if utils_error.IsNotFound(err) {
// Handle not found
}
// Error with stack trace
err := utils_error.WithStack(err)
28. File Utils
Package: pkg/utils/file/
Quick Example:
import utils_file "gitlab.com/mushola-store/mstore_backend/pkg/utils/file"
// Read file
content, err := utils_file.ReadFile("config.json")
// Write file
err := utils_file.WriteFile("output.txt", []byte("Hello World"))
// Check if exists
exists := utils_file.Exists("data.csv")
// Get file info
info, _ := utils_file.GetFileInfo("document.pdf")
fmt.Printf("Size: %d bytes\n", info.Size)
// Copy file
err := utils_file.CopyFile("source.txt", "destination.txt")
29. Finance Utils
Package: pkg/utils/finance/
Quick Example:
import utils_finance "gitlab.com/mushola-store/mstore_backend/pkg/utils/finance"
// Currency formatting
formatted := utils_finance.FormatCurrency(1234567.89, "IDR")
// Output: "Rp 1.234.567,89"
// Calculate tax
taxAmount := utils_finance.CalculateTax(1000000, 0.11) // 11% PPN
// Result: 110000
// Calculate discount
discountAmount := utils_finance.CalculateDiscount(1000000, 0.10) // 10% discount
// Result: 100000
// Round to nearest
rounded := utils_finance.RoundToNearest(1234.567, 2)
// Result: 1234.57
30. Unit Test Utils
Package: pkg/utils/unit_test/
Quick Example:
import utils_test "gitlab.com/mushola-store/mstore_backend/pkg/utils/unit_test"
// Mock database
mockDB := utils_test.NewMockDB()
// Mock HTTP client
mockHTTP := utils_test.NewMockHTTPClient()
mockHTTP.On("Get", "https://api.example.com/users").Return(response, nil)
// Assert helpers
utils_test.AssertEqual(t, expected, actual)
utils_test.AssertNotNil(t, value)
utils_test.AssertError(t, err)
📚 Quick Reference
Import Paths
// Observability
utils_logger "gitlab.com/mushola-store/mstore_backend/pkg/utils/logger"
// ID Generation
"gitlab.com/mushola-store/mstore_backend/pkg/utils/snowflake"
"gitlab.com/mushola-store/mstore_backend/pkg/utils/txcode"
// Message Broker
utils_mb "gitlab.com/mushola-store/mstore_backend/pkg/utils/message_broker"
// Cache & Database
utils_cache "gitlab.com/mushola-store/mstore_backend/pkg/utils/cache"
utils_db "gitlab.com/mushola-store/mstore_backend/pkg/utils/database"
// Cloud Services
utils_aws "gitlab.com/mushola-store/mstore_backend/pkg/utils/aws"
utils_google "gitlab.com/mushola-store/mstore_backend/pkg/utils/google"
// Data Processing
utils_excel "gitlab.com/mushola-store/mstore_backend/pkg/utils/excel"
utils_filter "gitlab.com/mushola-store/mstore_backend/pkg/utils/filter"
utils_mapper "gitlab.com/mushola-store/mstore_backend/pkg/utils/mapper"
utils_transform "gitlab.com/mushola-store/mstore_backend/pkg/utils/transform"
// Security & Auth
utils_hash "gitlab.com/mushola-store/mstore_backend/pkg/utils/hash"
utils_jwt "gitlab.com/mushola-store/mstore_backend/pkg/utils/jwt"
// HTTP & gRPC
utils_http "gitlab.com/mushola-store/mstore_backend/pkg/utils/http"
utils_grpc "gitlab.com/mushola-store/mstore_backend/pkg/utils/grpc"
// Supporting
utils_time "gitlab.com/mushola-store/mstore_backend/pkg/utils/time"
utils_lang "gitlab.com/mushola-store/mstore_backend/pkg/utils/lang"
utils_parser "gitlab.com/mushola-store/mstore_backend/pkg/utils/parser"
utils_response "gitlab.com/mushola-store/mstore_backend/pkg/utils/response"
Utility Packages: Semua 30 utility packages terdokumentasi lengkap. Gunakan sesuai kebutuhan dan ikuti best practices yang ada.