obrimbasecli/essential/visible/service/helper/progress/progress.go

/*
|--------------------------------------------------------------------------
| Progress
|--------------------------------------------------------------------------
|
| Name:
|   - Progress
|
| Purpose:
|   - Manage lifecycle-aware countable and uncountable progress tracking.
|
| Guidelines:
|   - Validate all inputs before processing.
|   - Support countable and uncountable progress workflows.
|   - Generate standardized responses.
|   - Generate CLI-friendly progress messages and visuals.
|
| Examples:
|   - ObrimProgress("countable", config)
|   - ObrimProgress("uncountable", config)
|
|--------------------------------------------------------------------------
*/

/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
|   - Rajon Ahmed
|   - Scionite
|
|--------------------------------------------------------------------------
*/

package progress

import (
	"fmt"
	"math"
	"strings"
	"sync"

	"go/module/name/essential/external/service/helper/log"
	"go/module/name/essential/external/service/helper/retriever"
	"go/module/name/essential/external/service/helper/status"
)

var (
	// Variable Purpose: Protect progress state transitions from concurrent corruption.
	obrimProgressMutex sync.Mutex
)

type obrimProgressResponse struct {
	Status  bool           `json:"status"`
	Code    string         `json:"code"`
	Payload map[string]any `json:"payload"`
}

// Function Name: ObrimProgress
// Function Purpose: Manage lifecycle-aware countable and uncountable progress tracking operations.
func ObrimProgress(progressType string, config map[string]any) map[string]any {
	obrimProgressMutex.Lock()
	defer obrimProgressMutex.Unlock()

	_, _ = retriever.ObrimRetriever(
		"json",
		map[string]any{
			"resource": "application/metadata",
			"path":     "application.lower",
		},
	)

	if !obrimProgressValidate(progressType, config) {
		status.ObrimStatus("ERROR", "Progress configuration is invalid.")
		log.ObrimLog("ERROR", "FAILED_PROGRESS_MISCONFIGURED")

		return obrimProgressBuildResponse(
			false,
			"FAILED_PROGRESS_MISCONFIGURED",
			nil,
		)
	}

	// Variable Purpose: Current lifecycle state.
	state := fmt.Sprintf("%v", config["state"])

	if !obrimProgressHandleState(state) {
		status.ObrimStatus("ERROR", "Invalid lifecycle state.")
		log.ObrimLog("ERROR", "FAILED_PROGRESS_MISCONFIGURED")

		return obrimProgressBuildResponse(
			false,
			"FAILED_PROGRESS_MISCONFIGURED",
			nil,
		)
	}

	switch progressType {
	case "countable":
		return obrimProgressCountable(config)

	case "uncountable":
		return obrimProgressUncountable(config)

	default:
		status.ObrimStatus("ERROR", "Unsupported progress type.")
		log.ObrimLog("ERROR", "FAILED_PROGRESS_MISCONFIGURED")

		return obrimProgressBuildResponse(
			false,
			"FAILED_PROGRESS_MISCONFIGURED",
			nil,
		)
	}
}

// Function Name: obrimProgressValidate
// Function Purpose: Validate input parameters and configuration consistency.
func obrimProgressValidate(progressType string, config map[string]any) bool {
	if config == nil {
		return false
	}

	// Variable Purpose: Lifecycle state.
	stateValue, stateExists := config["state"]
	if !stateExists {
		return false
	}

	state := fmt.Sprintf("%v", stateValue)

	switch state {
	case "started", "running", "completed", "canceled":
	default:
		return false
	}

	switch progressType {
	case "countable":
		currentValue, currentExists := config["current"]
		targetValue, targetExists := config["target"]

		if !currentExists || !targetExists {
			return false
		}

		current, currentOK := currentValue.(int)
		target, targetOK := targetValue.(int)

		if !currentOK || !targetOK {
			return false
		}

		if target <= 0 {
			return false
		}

		_ = current

	case "uncountable":
		placeholderValue, placeholderExists := config["placeholder"]

		if !placeholderExists {
			return false
		}

		placeholder := fmt.Sprintf("%v", placeholderValue)

		if strings.TrimSpace(placeholder) == "" {
			return false
		}

	default:
		return false
	}

	return true
}

// Function Name: obrimProgressHandleState
// Function Purpose: Process lifecycle state transitions.
func obrimProgressHandleState(state string) bool {
	switch state {
	case "started":
		log.ObrimLog("INIT", "Progress tracking started.")
		status.ObrimStatus("INFO", "Progress tracking started.")

	case "running":
		log.ObrimLog("SYNC", "Progress tracking updated.")
		status.ObrimStatus("INFO", "Progress tracking running.")

	case "completed":
		log.ObrimLog("SUCCESS", "Progress tracking completed.")
		status.ObrimStatus("SUCCESS", "Progress tracking completed.")

	case "canceled":
		log.ObrimLog("ERROR", "Progress tracking canceled.")
		status.ObrimStatus("WARNING", "Progress tracking canceled.")

	default:
		return false
	}

	return true
}

// Function Name: obrimProgressGenerateMessage
// Function Purpose: Generate human-readable progress messages.
func obrimProgressGenerateMessage(progressType string, data map[string]any) string {
	if progressType == "countable" {
		return fmt.Sprintf(
			"Progress %d%% complete.",
			data["percentage"].(int),
		)
	}

	return fmt.Sprintf(
		"Activity in progress: %s",
		data["placeholder"].(string),
	)
}

// Function Name: obrimProgressGenerateVisual
// Function Purpose: Generate CLI-friendly visual progress representations.
func obrimProgressGenerateVisual(progressType string, data map[string]any) string {
	if progressType == "countable" {
		// Variable Purpose: Percentage value.
		percentage := data["percentage"].(int)

		// Variable Purpose: Total bar width.
		barWidth := 20

		// Variable Purpose: Filled segments.
		filled := int(math.Round(float64(percentage) / 100 * float64(barWidth)))

		if filled > barWidth {
			filled = barWidth
		}

		if filled < 0 {
			filled = 0
		}

		return fmt.Sprintf(
			"[%s%s] %d%%",
			strings.Repeat("#", filled),
			strings.Repeat("-", barWidth-filled),
			percentage,
		)
	}

	return "[....................]"
}

// Function Name: obrimProgressBuildResponse
// Function Purpose: Construct standardized utility response payloads.
func obrimProgressBuildResponse(
	statusValue bool,
	code string,
	payload map[string]any,
) map[string]any {
	return map[string]any{
		"status":  statusValue,
		"code":    code,
		"payload": payload,
	}
}

// Function Name: obrimProgressCountable
// Function Purpose: Process countable progress tracking workflows.
func obrimProgressCountable(config map[string]any) map[string]any {
	// Variable Purpose: Current lifecycle state.
	state := config["state"].(string)

	// Variable Purpose: Current progress value.
	current := config["current"].(int)

	// Variable Purpose: Target progress value.
	target := config["target"].(int)

	// Variable Purpose: Calculated percentage.
	percentage := obrimProgressCalculatePercentage(current, target)

	// Variable Purpose: Payload object.
	payload := map[string]any{
		"state":      state,
		"current":    current,
		"target":     target,
		"percentage": percentage,
	}

	payload["message"] = obrimProgressGenerateMessage("countable", payload)
	payload["visual"] = obrimProgressGenerateVisual("countable", payload)

	return obrimProgressBuildResponse(
		true,
		"SUCCESS_PROGRESS_COUNTABLE",
		payload,
	)
}

// Function Name: obrimProgressCalculatePercentage
// Function Purpose: Calculate and normalize completion percentages.
func obrimProgressCalculatePercentage(current int, target int) int {
	if current < 0 {
		return 0
	}

	if target <= 0 {
		return 0
	}

	percentage := int(
		math.Round(
			(float64(current) / float64(target)) * 100,
		),
	)

	if percentage > 100 {
		return 100
	}

	if percentage < 0 {
		return 0
	}

	return percentage
}

// Function Name: obrimProgressUncountable
// Function Purpose: Process uncountable progress tracking workflows.
func obrimProgressUncountable(config map[string]any) map[string]any {
	// Variable Purpose: Current lifecycle state.
	state := config["state"].(string)

	// Variable Purpose: Placeholder activity message.
	placeholder := obrimProgressResolvePlaceholder(
		fmt.Sprintf("%v", config["placeholder"]),
	)

	// Variable Purpose: Payload object.
	payload := map[string]any{
		"state":       state,
		"placeholder": placeholder,
	}

	payload["message"] = obrimProgressGenerateMessage("uncountable", payload)
	payload["visual"] = obrimProgressGenerateVisual("uncountable", payload)

	return obrimProgressBuildResponse(
		true,
		"SUCCESS_PROGRESS_UNCOUNTABLE",
		payload,
	)
}

// Function Name: obrimProgressResolvePlaceholder
// Function Purpose: Validate and prepare placeholder activity messages.
func obrimProgressResolvePlaceholder(placeholder string) string {
	return strings.TrimSpace(placeholder)
}