@reliverse/rempts 1.7.57 → 1.7.59

package/bin/libs/spinner/spinner-mod.d.ts

@@ -1,106 +1,261 @@
-interface SpinnerOptions {
-    cancelMessage?: string;
-    color?: string;
-    delay?: number;
-    errorMessage?: string;
-    failText?: string;
-    frames?: string[];
-    hideCursor?: boolean;
-    indicator?: "dots" | "timer";
-    onCancel?: () => void;
-    prefixText?: string;
-    signal?: AbortSignal;
-    silent?: boolean;
-    spinner?: string;
-    successText?: string;
-    text: string;
+/**
+ * Environment toggles:
+ * - Disable by setting CLI_NO_SPINNER=1 or CLI_NO_COLOR=1
+ * - Auto-disables in CI and when not a TTY; override with isEnabled: true
+ * - Respect env behavior can be bypassed with respectEnv: false
+ * Defaults:
+ * - spinner: "dots", color: "cyan", hideCursor: true, discardStdin: true, stream defaults to stderr.
+ */
+import { randomSpinner } from "cli-spinners";
+import prettyBytes from "pretty-bytes";
+import prettyMilliseconds from "pretty-ms";
+import { type Ora, type OraOptions, type OraPromiseOptions } from "./spinner-impl.js";
+export interface SpinnerOptions extends Omit<OraOptions, "text"> {
+    readonly respectEnv?: boolean;
+    readonly showTiming?: boolean;
+    readonly defaultSuccess?: string;
+    readonly defaultFail?: string;
+    text?: string;
+    readonly textColor?: string | ((text: string) => string);
+    readonly prefixColor?: string | ((text: string) => string);
+    readonly suffixColor?: string | ((text: string) => string);
+    readonly successColor?: string | ((text: string) => string);
+    readonly failColor?: string | ((text: string) => string);
+    readonly theme?: {
+        readonly info?: (text: string) => string;
+        readonly success?: (text: string) => string;
+        readonly error?: (text: string) => string;
+        readonly dim?: (text: string) => string;
+        readonly progress?: (text: string) => string;
+        readonly rate?: (text: string) => string;
+        readonly bytes?: (text: string) => string;
+        readonly percentage?: (text: string) => string;
+    };
 }
-interface ProgressOptions {
-    current: number;
-    total: number;
-    format?: "percentage" | "count" | "both";
+export interface SpinnerGroupOptions extends SpinnerOptions {
+    readonly items: readonly string[];
+    readonly concurrent?: boolean;
 }
-interface SpinnerControls {
-    start: (text?: string) => SpinnerControls;
-    stop: (text?: string, code?: number) => void;
-    setText: (text: string) => void;
-    setProgress: (progress: ProgressOptions) => void;
-    succeed: (text?: string) => void;
-    fail: (text?: string) => void;
-    warn: (text?: string) => void;
-    info: (text?: string) => void;
-    isSpinning: () => boolean;
-    clear: () => void;
-    getElapsedTime: () => number;
-    pause: () => void;
-    resume: () => void;
-    dispose: () => void;
-    isCancelled: boolean;
+export interface FileProgressOptions {
+    readonly totalBytes?: number;
+    readonly showBytes?: boolean;
+    readonly showRate?: boolean;
 }
+export type SimpleSpinner = Ora;
+export declare const defaultSpinnerOptions: Readonly<SpinnerOptions>;
+export declare function isSpinnerEnabled(options?: {
+    stream?: NodeJS.WriteStream;
+    respectEnv?: boolean;
+    isEnabled?: boolean;
+}): boolean;
+export declare function createSpinner(input?: string | SpinnerOptions): SimpleSpinner;
+export declare function withSpinnerPromise<T>(action: Promise<T> | ((spinner: Ora) => Promise<T>), options?: string | (OraPromiseOptions<T> & SpinnerOptions)): Promise<T>;
+export declare function withSpinner<T>(textOrOptions: string | SpinnerOptions, action: (spinner: Ora) => Promise<T>, onSuccessText?: string | ((result: T) => string), onFailText?: string | ((error: Error) => string)): Promise<T>;
 /**
- * Creates a terminal spinner with enhanced controls and styling options.
- *
- * @example
- * ```typescript
- * // Basic usage
- * const spinner = useSpinner({ text: "Loading..." }).start();
- * spinner.stop();
- *
- * // With progress tracking
- * const spinner = useSpinner({ text: "Processing files..." }).start();
- * for (let i = 0; i < files.length; i++) {
- *   spinner.setProgress({ current: i + 1, total: files.length });
- *   await processFile(files[i]);
- * }
- * spinner.succeed();
- *
- * // With custom color and spinner
- * const spinner = useSpinner({
- *   text: "Processing...",
- *   color: "cyan",
- *   spinner: "dots"
- * }).start();
- *
- * // With success/failure states
- * const spinner = useSpinner({
- *   text: "Uploading...",
- *   successText: "Upload complete!",
- *   failText: "Upload failed!"
- * }).start();
- * try {
- *   await uploadFile();
- *   spinner.succeed();
- * } catch (error) {
- *   spinner.fail();
- * }
- *
- * // Using the wrapper for async operations
- * await useSpinner.promise(
- *   async (spinner) => {
- *     await longOperation();
- *     spinner.setProgress({ current: 50, total: 100 });
- *   },
- *   {
- *     text: "Working...",
- *     successText: "Done!",
- *     failText: "Failed!"
- *   }
- * );
- * ```
+ * Update spinner text with optional prefix/suffix
  */
-export declare function useSpinner(options: SpinnerOptions): SpinnerControls;
-export declare namespace useSpinner {
-    var promise: <T>(operation: (spinner: SpinnerControls) => Promise<T>, options: SpinnerOptions) => Promise<T>;
-    var nested: (parentOptions: SpinnerOptions) => {
-        start: () => {
-            child: (childOptions: SpinnerOptions) => SpinnerControls;
-            finish: (success: boolean, text?: string) => void;
-            dispose: () => void;
-        };
-    };
-    var withTiming: <T>(operation: (spinner: SpinnerControls) => Promise<T>, options: SpinnerOptions) => Promise<{
-        result: T;
-        duration: number;
-    }>;
-}
-export {};
+export declare function updateSpinnerText(spinner: SimpleSpinner, text: string, options?: {
+    prefix?: string;
+    suffix?: string;
+}): void;
+/**
+ * Stop spinner and persist with custom symbol and text
+ */
+export declare function stopAndPersist(spinner: SimpleSpinner, options: {
+    symbol?: string;
+    text?: string;
+    prefixText?: string | (() => string);
+    suffixText?: string | (() => string);
+}): void;
+/**
+ * Create a spinner with timing that automatically shows elapsed time
+ */
+export declare function createTimedSpinner(input?: string | Omit<SpinnerOptions, "showTiming">): {
+    spinner: SimpleSpinner;
+    getElapsed: () => number;
+    succeedWithTiming: (text?: string) => void;
+    failWithTiming: (text?: string) => void;
+};
+/**
+ * Create multiple spinners for concurrent operations
+ */
+export declare function createSpinnerGroup(options: SpinnerGroupOptions): {
+    spinners: SimpleSpinner[];
+    updateAll: (text: string) => void;
+    succeedAll: (text?: string) => void;
+    failAll: (text?: string) => void;
+    stopAll: () => void;
+};
+/**
+ * Enhanced withSpinner that includes common patterns used in the codebase
+ */
+export declare function withEnhancedSpinner<T>(textOrOptions: string | (SpinnerOptions & {
+    successText?: string;
+    failText?: string;
+    showTiming?: boolean;
+}), action: (spinner: SimpleSpinner & {
+    updateText: (text: string, options?: {
+        prefix?: string;
+        suffix?: string;
+    }) => void;
+    setProgress: (current: number, total: number, text?: string) => void;
+}) => Promise<T>): Promise<T>;
+/**
+ * Check if a spinner is currently running
+ */
+export declare function isSpinnerRunning(spinner: SimpleSpinner): boolean;
+/**
+ * Safely stop a spinner if it's running
+ */
+export declare function safeStopSpinner(spinner: SimpleSpinner | null): void;
+/**
+ * Create a spinner that automatically handles common build/publish patterns
+ */
+export declare function createBuildSpinner(operation: string, options?: Omit<SpinnerOptions, "text">): {
+    spinner: SimpleSpinner;
+    complete: (message?: string) => void;
+    error: (error: Error | string) => void;
+    updateProgress: (step: string) => void;
+};
+/**
+ * Create a spinner with file progress tracking
+ */
+export declare function createFileProgressSpinner(operation: string, options?: SpinnerOptions & FileProgressOptions): {
+    spinner: SimpleSpinner;
+    updateProgress: (bytesProcessed: number, fileName?: string) => void;
+    updateRate: (bytesPerSecond: number) => void;
+    complete: (message?: string) => void;
+    error: (error: Error | string) => void;
+};
+/**
+ * Create a multi-step operation spinner with automatic timing
+ */
+export declare function createMultiStepSpinner(operationName: string, steps: readonly string[], options?: SpinnerOptions): {
+    spinner: SimpleSpinner;
+    nextStep: (stepIndex?: number) => void;
+    complete: (message?: string) => void;
+    error: (error: Error | string, stepIndex?: number) => void;
+    getCurrentStep: () => number;
+};
+/**
+ * Enhanced timing utility using pretty-ms
+ */
+export declare function formatSpinnerTiming(startTime: number, options?: {
+    verbose?: boolean;
+}): string;
+/**
+ * Format bytes for spinner display using pretty-bytes
+ */
+export declare function formatSpinnerBytes(bytes: number, options?: {
+    binary?: boolean;
+}): string;
+/**
+ * Format elapsed time for spinner display using pretty-ms
+ */
+export declare function formatSpinnerElapsed(elapsed: number, options?: {
+    verbose?: boolean;
+}): string;
+/**
+ * Create a spinner for download/upload operations with byte tracking
+ */
+export declare function createTransferSpinner(operation: string, options?: SpinnerOptions & {
+    totalBytes?: number;
+    showRate?: boolean;
+}): {
+    spinner: SimpleSpinner;
+    updateBytes: (bytesTransferred: number, fileName?: string) => void;
+    updateRate: (bytesPerSecond: number) => void;
+    complete: (message?: string, totalBytesTransferred?: number) => void;
+    error: (error: Error | string) => void;
+};
+export declare const spinners: {
+    readonly toggle: import("cli-spinners").Spinner;
+    readonly line: import("cli-spinners").Spinner;
+    readonly binary: import("cli-spinners").Spinner;
+    readonly dots: import("cli-spinners").Spinner;
+    readonly dots2: import("cli-spinners").Spinner;
+    readonly dots3: import("cli-spinners").Spinner;
+    readonly dots4: import("cli-spinners").Spinner;
+    readonly dots5: import("cli-spinners").Spinner;
+    readonly dots6: import("cli-spinners").Spinner;
+    readonly dots7: import("cli-spinners").Spinner;
+    readonly dots8: import("cli-spinners").Spinner;
+    readonly dots9: import("cli-spinners").Spinner;
+    readonly dots10: import("cli-spinners").Spinner;
+    readonly dots11: import("cli-spinners").Spinner;
+    readonly dots12: import("cli-spinners").Spinner;
+    readonly dots13: import("cli-spinners").Spinner;
+    readonly dots14: import("cli-spinners").Spinner;
+    readonly dots8Bit: import("cli-spinners").Spinner;
+    readonly dotsCircle: import("cli-spinners").Spinner;
+    readonly sand: import("cli-spinners").Spinner;
+    readonly line2: import("cli-spinners").Spinner;
+    readonly pipe: import("cli-spinners").Spinner;
+    readonly simpleDots: import("cli-spinners").Spinner;
+    readonly simpleDotsScrolling: import("cli-spinners").Spinner;
+    readonly star: import("cli-spinners").Spinner;
+    readonly star2: import("cli-spinners").Spinner;
+    readonly flip: import("cli-spinners").Spinner;
+    readonly hamburger: import("cli-spinners").Spinner;
+    readonly growVertical: import("cli-spinners").Spinner;
+    readonly growHorizontal: import("cli-spinners").Spinner;
+    readonly balloon: import("cli-spinners").Spinner;
+    readonly balloon2: import("cli-spinners").Spinner;
+    readonly noise: import("cli-spinners").Spinner;
+    readonly bounce: import("cli-spinners").Spinner;
+    readonly boxBounce: import("cli-spinners").Spinner;
+    readonly boxBounce2: import("cli-spinners").Spinner;
+    readonly triangle: import("cli-spinners").Spinner;
+    readonly arc: import("cli-spinners").Spinner;
+    readonly circle: import("cli-spinners").Spinner;
+    readonly squareCorners: import("cli-spinners").Spinner;
+    readonly circleQuarters: import("cli-spinners").Spinner;
+    readonly circleHalves: import("cli-spinners").Spinner;
+    readonly squish: import("cli-spinners").Spinner;
+    readonly toggle2: import("cli-spinners").Spinner;
+    readonly toggle3: import("cli-spinners").Spinner;
+    readonly toggle4: import("cli-spinners").Spinner;
+    readonly toggle5: import("cli-spinners").Spinner;
+    readonly toggle6: import("cli-spinners").Spinner;
+    readonly toggle7: import("cli-spinners").Spinner;
+    readonly toggle8: import("cli-spinners").Spinner;
+    readonly toggle9: import("cli-spinners").Spinner;
+    readonly toggle10: import("cli-spinners").Spinner;
+    readonly toggle11: import("cli-spinners").Spinner;
+    readonly toggle12: import("cli-spinners").Spinner;
+    readonly toggle13: import("cli-spinners").Spinner;
+    readonly arrow: import("cli-spinners").Spinner;
+    readonly arrow2: import("cli-spinners").Spinner;
+    readonly arrow3: import("cli-spinners").Spinner;
+    readonly bouncingBar: import("cli-spinners").Spinner;
+    readonly bouncingBall: import("cli-spinners").Spinner;
+    readonly smiley: import("cli-spinners").Spinner;
+    readonly monkey: import("cli-spinners").Spinner;
+    readonly hearts: import("cli-spinners").Spinner;
+    readonly clock: import("cli-spinners").Spinner;
+    readonly earth: import("cli-spinners").Spinner;
+    readonly material: import("cli-spinners").Spinner;
+    readonly moon: import("cli-spinners").Spinner;
+    readonly runner: import("cli-spinners").Spinner;
+    readonly pong: import("cli-spinners").Spinner;
+    readonly shark: import("cli-spinners").Spinner;
+    readonly dqpb: import("cli-spinners").Spinner;
+    readonly weather: import("cli-spinners").Spinner;
+    readonly christmas: import("cli-spinners").Spinner;
+    readonly grenade: import("cli-spinners").Spinner;
+    readonly point: import("cli-spinners").Spinner;
+    readonly layer: import("cli-spinners").Spinner;
+    readonly betaWave: import("cli-spinners").Spinner;
+    readonly fingerDance: import("cli-spinners").Spinner;
+    readonly fistBump: import("cli-spinners").Spinner;
+    readonly soccerHeader: import("cli-spinners").Spinner;
+    readonly mindblown: import("cli-spinners").Spinner;
+    readonly speaker: import("cli-spinners").Spinner;
+    readonly orangePulse: import("cli-spinners").Spinner;
+    readonly bluePulse: import("cli-spinners").Spinner;
+    readonly orangeBluePulse: import("cli-spinners").Spinner;
+    readonly timeTravel: import("cli-spinners").Spinner;
+    readonly aesthetic: import("cli-spinners").Spinner;
+    readonly dwarfFortress: import("cli-spinners").Spinner;
+};
+export { randomSpinner, prettyBytes, prettyMilliseconds };