/**
 * @fileoverview CLI spinner utilities for long-running operations.
 * Provides animated progress indicators with CI environment detection.
 */
import type { Writable } from 'node:stream';
import type { ShimmerColorGradient, ShimmerConfig, ShimmerDirection, ShimmerState } from './effects/text-shimmer';
export type ColorName = 'black' | 'blue' | 'blueBright' | 'cyan' | 'cyanBright' | 'gray' | 'green' | 'greenBright' | 'magenta' | 'magentaBright' | 'red' | 'redBright' | 'white' | 'whiteBright' | 'yellow' | 'yellowBright';
export type ColorInherit = 'inherit';
export type ColorRgb = readonly [number, number, number];
export type ColorValue = ColorName | ColorRgb;
export type SymbolType = 'fail' | 'info' | 'success' | 'warn';
export type ProgressInfo = {
    current: number;
    total: number;
    unit?: string | undefined;
};
export type ShimmerInfo = ShimmerState & {
    color: ColorInherit | ColorValue | ShimmerColorGradient;
};
export type Spinner = {
    color: ColorRgb;
    spinner: SpinnerStyle;
    get isSpinning(): boolean;
    clear(): Spinner;
    debug(text?: string | undefined, ...extras: unknown[]): Spinner;
    debugAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    error(text?: string | undefined, ...extras: unknown[]): Spinner;
    errorAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    fail(text?: string | undefined, ...extras: unknown[]): Spinner;
    failAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    // text property returns a method via _textMethod override
    text(value: string): Spinner;
    text(): string;
    indent(spaces?: number | undefined): Spinner;
    dedent(spaces?: number | undefined): Spinner;
    info(text?: string | undefined, ...extras: unknown[]): Spinner;
    infoAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    log(text?: string | undefined, ...extras: unknown[]): Spinner;
    logAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    start(text?: string | undefined): Spinner;
    stop(text?: string | undefined): Spinner;
    stopAndPersist(text?: string | undefined): Spinner;
    step(text?: string | undefined, ...extras: unknown[]): Spinner;
    substep(text?: string | undefined, ...extras: unknown[]): Spinner;
    success(text?: string | undefined, ...extras: unknown[]): Spinner;
    successAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    done(text?: string | undefined, ...extras: unknown[]): Spinner;
    doneAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    progress(current: number, total: number, unit?: string | undefined): Spinner;
    progressStep(amount?: number): Spinner;
    shimmer(enabled: boolean): Spinner;
    shimmer(config: Partial<ShimmerConfig> | ShimmerDirection): Spinner;
    warn(text?: string | undefined, ...extras: unknown[]): Spinner;
    warnAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
};
export type SpinnerOptions = {
    readonly color?: ColorValue | undefined;
    readonly shimmer?: ShimmerConfig | ShimmerDirection | undefined;
    readonly spinner?: SpinnerStyle | undefined;
    readonly signal?: AbortSignal | undefined;
    readonly stream?: Writable | undefined;
    readonly text?: string | undefined;
};
export type SpinnerStyle = {
    readonly frames: string[];
    readonly interval?: number | undefined;
};
export declare const ciSpinner: SpinnerStyle;
/**
 * Get available CLI spinner styles or a specific style by name.
 * Extends the standard cli-spinners collection with Socket custom spinners.
 *
 * @see https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json
 *
 * Custom spinners:
 * - `socket` (default): Socket pulse animation with sparkles and lightning
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function getCliSpinners(styleName?: string | undefined): SpinnerStyle | Record<string, SpinnerStyle> | undefined;
/**
 * Create a spinner instance for displaying loading indicators.
 *
 * AUTO-CLEAR BEHAVIOR:
 * - All *AndStop() methods AUTO-CLEAR the spinner line via yocto-spinner.stop()
 *   Examples: doneAndStop(), successAndStop(), failAndStop(), etc.
 *
 * - Methods WITHOUT "AndStop" do NOT clear (spinner keeps spinning)
 *   Examples: done(), success(), fail(), etc.
 *
 * STREAM USAGE:
 * - Spinner animation: stderr (yocto-spinner default)
 * - Status methods (done, success, fail, info, warn, step, substep): stderr
 * - Data methods (log): stdout
 *
 * COMPARISON WITH LOGGER:
 * - logger.done() does NOT auto-clear (requires manual logger.clearLine())
 * - spinner.doneAndStop() DOES auto-clear (built into yocto-spinner.stop())
 * - Pattern: logger.clearLine().done() vs spinner.doneAndStop()
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function Spinner(options?: SpinnerOptions | undefined): Spinner;
/**
 * Get the default spinner instance.
 * Lazily creates the spinner to avoid circular dependencies during module initialization.
 */
export declare function getDefaultSpinner(): ReturnType<typeof Spinner>;
/**
 * @deprecated Use `getDefaultSpinner()` function instead for better tree-shaking and to avoid circular dependencies.
 */
export declare const spinner: Spinner;
export type WithSpinnerOptions<T> = {
    message: string;
    operation: () => Promise<T>;
    spinner?: Spinner | undefined;
};
/**
 * Execute an async operation with spinner lifecycle management.
 * Ensures spinner.stop() is always called via try/finally, even if the operation throws.
 *
 * @param options - Configuration object
 * @param options.message - Message to display while spinner is running
 * @param options.operation - Async function to execute
 * @param options.spinner - Optional spinner instance (if not provided, no spinner is used)
 * @returns Result of the operation
 * @throws Re-throws any error from operation after stopping spinner
 *
 * @example
 * import { spinner, withSpinner } from '@socketsecurity/registry/lib/spinner'
 *
 * // With spinner instance
 * await withSpinner({
 *   message: 'Processing…',
 *   operation: async () => {
 *     return await processData()
 *   },
 *   spinner
 * })
 *
 * // Without spinner instance (no-op)
 * await withSpinner({
 *   message: 'Processing…',
 *   operation: async () => {
 *     return await processData()
 *   }
 * })
 */
export declare function withSpinner<T>(options: WithSpinnerOptions<T>): Promise<T>;
export type WithSpinnerRestoreOptions<T> = {
    operation: () => Promise<T>;
    spinner?: Spinner | undefined;
    wasSpinning: boolean;
};
/**
 * Execute an async operation with conditional spinner restart.
 * Useful when you need to temporarily stop a spinner for an operation,
 * then restore it to its previous state.
 *
 * @param options - Configuration object
 * @param options.operation - Async function to execute
 * @param options.spinner - Optional spinner instance to manage
 * @param options.wasSpinning - Whether spinner was spinning before
 * @returns Result of the operation
 * @throws Re-throws any error from operation after restoring spinner state
 *
 * @example
 * import { spinner, withSpinnerRestore } from '@socketsecurity/registry/lib/spinner'
 *
 * const wasSpinning = spinner.isSpinning
 * spinner.stop()
 *
 * const result = await withSpinnerRestore({
 *   operation: async () => {
 *     // Do work without spinner
 *     return await someOperation()
 *   },
 *   spinner,
 *   wasSpinning
 * })
 */
export declare function withSpinnerRestore<T>(options: WithSpinnerRestoreOptions<T>): Promise<T>;
export type WithSpinnerSyncOptions<T> = {
    message: string;
    operation: () => T;
    spinner?: Spinner | undefined;
};
/**
 * Execute a synchronous operation with spinner lifecycle management.
 * Ensures spinner.stop() is always called via try/finally, even if the operation throws.
 *
 * @param options - Configuration object
 * @param options.message - Message to display while spinner is running
 * @param options.operation - Function to execute
 * @param options.spinner - Optional spinner instance (if not provided, no spinner is used)
 * @returns Result of the operation
 * @throws Re-throws any error from operation after stopping spinner
 *
 * @example
 * import { spinner, withSpinnerSync} from '@socketsecurity/registry/lib/spinner'
 *
 * const result = withSpinnerSync({
 *   message: 'Processing…',
 *   operation: () => {
 *     return processDataSync()
 *   },
 *   spinner
 * })
 */
export declare function withSpinnerSync<T>(options: WithSpinnerSyncOptions<T>): T;
