types

type Bar interface {
	// Inc increments the progress bar by n.
	// This is a convenience method that calls Inc64 with int64(n).
	Inc(n int)

	// Dec decrements the progress bar by n.
	// This is a convenience method that calls Dec64 with int64(n).
	Dec(n int)

	// Inc64 increments the progress bar by n (64-bit version).
	// Use this for large progress values or when n is already int64.
	Inc64(n int64)

	// Dec64 decrements the progress bar by n (64-bit version).
	// Implemented internally as Inc64(-n).
	Dec64(n int64)

	// Reset resets the progress bar to new total and current values.
	// This allows reusing the same bar for different operations.
	//
	// Parameters:
	//   - tot: New total/maximum value
	//   - current: New current progress value
	Reset(tot, current int64)

	// Complete marks the progress bar as complete.
	// If MPB is enabled, this triggers the completion animation.
	Complete()

	// Completed returns true if the progress bar has completed or was aborted.
	// Without MPB, this always returns true.
	Completed() bool

	// Current returns the current progress value.
	// Without MPB, returns the total value.
	Current() int64

	// Total returns the total/maximum value of the progress bar.
	Total() int64
}

type BarMPB interface {
	// GetMPB returns the underlying MPB bar instance.
	// Returns nil if progress bar is disabled.
	//
	// Use this for advanced MPB operations not covered by the Bar interface.
	GetMPB() *sdkmpb.Bar
}

type Progress interface {
	// BarBytes creates a progress bar for tracking byte quantities (files, downloads, etc.).
	// The bar displays sizes in human-readable format (KB, MB, GB, etc.).
	//
	// Parameters:
	//   - name: Display name for the bar
	//   - job: Job description to display
	//   - tot: Total number of bytes to process
	//   - drop: If true, removes the bar from display when complete
	//   - bar: Optional existing bar to queue after (for sequential display)
	//
	// Returns:
	//   - SemBar: A semaphore with progress bar configured for byte tracking
	BarBytes(name, job string, tot int64, drop bool, bar SemBar) SemBar

	// BarTime creates a progress bar for time-based operations.
	// Displays progress with time estimates (ETA, elapsed time).
	//
	// Parameters:
	//   - name: Display name for the bar
	//   - job: Job description to display
	//   - tot: Total number of time units
	//   - drop: If true, removes the bar from display when complete
	//   - bar: Optional existing bar to queue after
	//
	// Returns:
	//   - SemBar: A semaphore with progress bar configured for time tracking
	BarTime(name, job string, tot int64, drop bool, bar SemBar) SemBar

	// BarNumber creates a progress bar for tracking numeric quantities.
	// Displays progress as a simple counter (e.g., "45/100").
	//
	// Parameters:
	//   - name: Display name for the bar
	//   - job: Job description to display
	//   - tot: Total number of items to process
	//   - drop: If true, removes the bar from display when complete
	//   - bar: Optional existing bar to queue after
	//
	// Returns:
	//   - SemBar: A semaphore with progress bar configured for number tracking
	BarNumber(name, job string, tot int64, drop bool, bar SemBar) SemBar

	// BarOpts creates a progress bar with custom MPB options.
	// Use this for full control over bar appearance and behavior.
	//
	// Parameters:
	//   - tot: Total number of items to process
	//   - drop: If true, removes the bar from display when complete
	//   - opts: MPB bar options for customization
	//
	// Returns:
	//   - SemBar: A semaphore with custom progress bar
	//
	// See: github.com/vbauerster/mpb/v8 for available options
	BarOpts(tot int64, drop bool, opts ...sdkmpb.BarOption) SemBar
}

type ProgressMPB interface {
	// GetMPB returns the underlying MPB progress container.
	// Returns nil if progress tracking is disabled.
	//
	// Use this for:
	//   - Adding custom progress bars
	//   - Accessing MPB container-level operations
	//   - Coordinating multiple progress bars
	GetMPB() *sdkmpb.Progress
}

type Sem interface {
	context.Context // Inherits context functionality for cancellation and deadlines

	// NewWorker acquires a worker slot, blocking until one is available or context is cancelled.
	// Returns an error if the context is cancelled before acquiring a slot.
	//
	// Usage:
	//   if err := sem.NewWorker(); err != nil {
	//       return err
	//   }
	//   defer sem.DeferWorker()
	NewWorker() error

	// NewWorkerTry attempts to acquire a worker slot without blocking.
	// Returns true if successful, false if no slots are available.
	//
	// Usage:
	//   if sem.NewWorkerTry() {
	//       defer sem.DeferWorker()
	//       // process work
	//   }
	NewWorkerTry() bool

	// DeferWorker releases a previously acquired worker slot.
	// Should be called with defer immediately after NewWorker() or NewWorkerTry() succeeds.
	DeferWorker()

	// DeferMain cancels the semaphore's context and releases all resources.
	// Should be called with defer in the main goroutine that created the semaphore.
	DeferMain()

	// WaitAll blocks until all worker slots are available (all workers have completed).
	// Returns an error if the context is cancelled while waiting.
	//
	// Use this to wait for all spawned workers to complete before proceeding.
	WaitAll() error

	// Weighted returns the maximum number of concurrent workers allowed.
	// Returns -1 for unlimited concurrency (WaitGroup mode).
	// Returns the configured limit for weighted semaphore mode.
	Weighted() int64

	// New creates a new independent semaphore with the same concurrency limit.
	// The new semaphore inherits the parent's context but operates independently.
	New() Sem
}

type SemBar interface {
	Sem // Core semaphore functionality
	Bar // Progress bar operations
}

type SemPgb interface {
	Sem         // Core semaphore functionality
	ProgressMPB // Access to MPB progress container
}