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)

20. Transform Utils

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",
})

26. Pagination

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"

OpenTelemetry Tracing

Distributed tracing guide

Snowflake ID Generator

Distributed ID generation

Transaction Code Generator

Human-readable codes

Message Broker

Event-driven architecture

Feature Flags

Feature flag management

Tech Stack

Complete tech stack

Utility Packages: Semua 30 utility packages terdokumentasi lengkap. Gunakan sesuai kebutuhan dan ikuti best practices yang ada.

​Utility Packages Reference

​📊 Package Overview

​🔴 HIGH PRIORITY

​1. OpenTelemetry (OTEL)

​2. Snowflake ID Generator

​3. Transaction Code Generator

​4. Logger

​🟡 MEDIUM PRIORITY

​5. Message Broker

​6. Cache (Redis)

​7. Database (MySQL)

​8. AWS Utils

​9. Google Utils (Firebase)

​10. Excel Utils

​11. Hash & Crypto

​12. JWT

​13. HTTP Utils

​14. gRPC Utils

​15. Validator

​16. Feature Flag

​17. ID Generator

​🟢 LOW PRIORITY

​18. Filter Utils

​19. Mapper Utils

​20. Transform Utils

​21. Time Utils

​22. Lang (Localization)

​23. Parser Utils

​24. Payload Utils

​25. Response Utils

​26. Pagination

​27. Error Utils

​28. File Utils

​29. Finance Utils

​30. Unit Test Utils

​📚 Quick Reference

​Import Paths

​📚 Related Documentation

OpenTelemetry Tracing

Snowflake ID Generator

Transaction Code Generator

Message Broker

Feature Flags

Tech Stack

Utility Packages Reference

📊 Package Overview

🔴 HIGH PRIORITY

1. OpenTelemetry (OTEL)

2. Snowflake ID Generator

3. Transaction Code Generator

4. Logger

🟡 MEDIUM PRIORITY

5. Message Broker

6. Cache (Redis)

7. Database (MySQL)

8. AWS Utils

9. Google Utils (Firebase)

10. Excel Utils

11. Hash & Crypto

12. JWT

13. HTTP Utils

14. gRPC Utils

15. Validator

16. Feature Flag

17. ID Generator

🟢 LOW PRIORITY

18. Filter Utils

19. Mapper Utils

20. Transform Utils

21. Time Utils

22. Lang (Localization)

23. Parser Utils

24. Payload Utils

25. Response Utils

26. Pagination

27. Error Utils

28. File Utils

29. Finance Utils

30. Unit Test Utils

📚 Quick Reference

Import Paths

📚 Related Documentation