@usefy/use-timer 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,275 @@
+/**
+ * Supported time format types for display
+ */
+type TimeFormat = "HH:MM:SS" | "HH:MM:SS.SSS" | "MM:SS" | "mm:ss.SSS" | "SS";
+/**
+ * Custom time formatter function type
+ */
+type TimeFormatter = (timeMs: number) => string;
+/**
+ * Timer status states
+ */
+type TimerStatus = "idle" | "running" | "paused" | "finished";
+/**
+ * Options for useTimer hook
+ */
+interface UseTimerOptions {
+    /**
+     * Update interval in milliseconds
+     * @default 100
+     */
+    interval?: number;
+    /**
+     * Time format preset or custom formatter function
+     * @default "MM:SS"
+     */
+    format?: TimeFormat | TimeFormatter;
+    /**
+     * Whether to start the timer automatically on mount
+     * @default false
+     */
+    autoStart?: boolean;
+    /**
+     * Whether to loop the timer when it completes
+     * @default false
+     */
+    loop?: boolean;
+    /**
+     * Whether to use requestAnimationFrame for smoother animations
+     * When true, ignores interval option and syncs with display refresh rate
+     * @default false
+     */
+    useRAF?: boolean;
+    /**
+     * Called when the timer completes (time reaches 0)
+     */
+    onComplete?: () => void;
+    /**
+     * Called on each tick with the remaining time in milliseconds
+     */
+    onTick?: (remainingMs: number) => void;
+    /**
+     * Called when the timer starts
+     */
+    onStart?: () => void;
+    /**
+     * Called when the timer pauses
+     */
+    onPause?: () => void;
+    /**
+     * Called when the timer resets
+     */
+    onReset?: () => void;
+    /**
+     * Called when the timer stops
+     */
+    onStop?: () => void;
+}
+/**
+ * Return type for useTimer hook
+ */
+interface UseTimerReturn {
+    /**
+     * Remaining time in milliseconds
+     */
+    time: number;
+    /**
+     * Initial time in milliseconds
+     */
+    initialTime: number;
+    /**
+     * Formatted time string based on format option
+     */
+    formattedTime: string;
+    /**
+     * Progress percentage (0-100)
+     * 0 at start, 100 when complete
+     */
+    progress: number;
+    /**
+     * Current timer status
+     */
+    status: TimerStatus;
+    /**
+     * Whether the timer is currently running
+     */
+    isRunning: boolean;
+    /**
+     * Whether the timer is paused
+     */
+    isPaused: boolean;
+    /**
+     * Whether the timer has finished (time = 0)
+     */
+    isFinished: boolean;
+    /**
+     * Whether the timer is idle (never started or after reset)
+     */
+    isIdle: boolean;
+    /**
+     * Hours component (0+)
+     */
+    hours: number;
+    /**
+     * Minutes component (0-59)
+     */
+    minutes: number;
+    /**
+     * Seconds component (0-59)
+     */
+    seconds: number;
+    /**
+     * Milliseconds component (0-999)
+     */
+    milliseconds: number;
+    /**
+     * Start or resume the timer
+     */
+    start: () => void;
+    /**
+     * Pause the timer (preserves remaining time)
+     */
+    pause: () => void;
+    /**
+     * Stop the timer (preserves remaining time, resets status to idle)
+     */
+    stop: () => void;
+    /**
+     * Reset the timer to initial time
+     */
+    reset: () => void;
+    /**
+     * Reset and start immediately
+     */
+    restart: () => void;
+    /**
+     * Toggle between running and paused states
+     */
+    toggle: () => void;
+    /**
+     * Add time in milliseconds
+     */
+    addTime: (ms: number) => void;
+    /**
+     * Subtract time in milliseconds (minimum 0)
+     */
+    subtractTime: (ms: number) => void;
+    /**
+     * Set time to a specific value in milliseconds
+     */
+    setTime: (ms: number) => void;
+}
+
+/**
+ * Helper object to create milliseconds from various time units
+ *
+ * @example
+ * ```tsx
+ * import { useTimer, ms } from "@usefy/use-timer";
+ *
+ * // 5 minute timer
+ * const timer = useTimer(ms.minutes(5));
+ *
+ * // 1 hour 30 minutes timer
+ * const timer = useTimer(ms.hours(1) + ms.minutes(30));
+ * ```
+ */
+declare const ms: {
+    /** Convert seconds to milliseconds */
+    readonly seconds: (n: number) => number;
+    /** Convert minutes to milliseconds */
+    readonly minutes: (n: number) => number;
+    /** Convert hours to milliseconds */
+    readonly hours: (n: number) => number;
+};
+/**
+ * A powerful countdown timer hook with comprehensive controls and features.
+ *
+ * @param initialTimeMs - Initial time in milliseconds
+ * @param options - Timer configuration options
+ * @returns Timer state and control functions
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * function Timer() {
+ *   const timer = useTimer(60000); // 60 seconds
+ *
+ *   return (
+ *     <div>
+ *       <p>{timer.formattedTime}</p>
+ *       <button onClick={timer.toggle}>
+ *         {timer.isRunning ? "Pause" : "Start"}
+ *       </button>
+ *       <button onClick={timer.reset}>Reset</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With callbacks and auto-start
+ * const timer = useTimer(30000, {
+ *   autoStart: true,
+ *   onComplete: () => alert("Time's up!"),
+ *   onTick: (remaining) => console.log(`${remaining}ms left`),
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With time helpers
+ * import { useTimer, ms } from "@usefy/use-timer";
+ *
+ * const timer = useTimer(ms.minutes(5), {
+ *   format: "MM:SS",
+ *   loop: true,
+ * });
+ * ```
+ */
+declare function useTimer(initialTimeMs: number, options?: UseTimerOptions): UseTimerReturn;
+
+/**
+ * Supported time units for utility functions
+ */
+type TimeUnit = "ms" | "seconds" | "minutes" | "hours";
+/**
+ * Convert a time value to milliseconds
+ * @param time - The time value to convert
+ * @param unit - The unit of the time value
+ * @returns Time in milliseconds (minimum 0)
+ */
+declare function toMs(time: number, unit: TimeUnit): number;
+/**
+ * Convert milliseconds to a specific time unit
+ * @param ms - Time in milliseconds
+ * @param unit - Target time unit
+ * @returns Time in the specified unit
+ */
+declare function fromMs(ms: number, unit: TimeUnit): number;
+/**
+ * Decomposed time object
+ */
+interface DecomposedTime {
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+}
+/**
+ * Decompose milliseconds into hours, minutes, seconds, and milliseconds
+ * @param ms - Time in milliseconds
+ * @returns Decomposed time object
+ */
+declare function decompose(ms: number): DecomposedTime;
+
+/**
+ * Format milliseconds into a time string
+ * @param ms - Time in milliseconds
+ * @param format - Desired format
+ * @returns Formatted time string
+ */
+declare function formatTime(ms: number, format: TimeFormat): string;
+
+export { type DecomposedTime, type TimeFormat, type TimeFormatter, type TimeUnit, type TimerStatus, type UseTimerOptions, type UseTimerReturn, decompose, formatTime, fromMs, ms, toMs, useTimer };

package/dist/index.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Supported time format types for display
+ */
+type TimeFormat = "HH:MM:SS" | "HH:MM:SS.SSS" | "MM:SS" | "mm:ss.SSS" | "SS";
+/**
+ * Custom time formatter function type
+ */
+type TimeFormatter = (timeMs: number) => string;
+/**
+ * Timer status states
+ */
+type TimerStatus = "idle" | "running" | "paused" | "finished";
+/**
+ * Options for useTimer hook
+ */
+interface UseTimerOptions {
+    /**
+     * Update interval in milliseconds
+     * @default 100
+     */
+    interval?: number;
+    /**
+     * Time format preset or custom formatter function
+     * @default "MM:SS"
+     */
+    format?: TimeFormat | TimeFormatter;
+    /**
+     * Whether to start the timer automatically on mount
+     * @default false
+     */
+    autoStart?: boolean;
+    /**
+     * Whether to loop the timer when it completes
+     * @default false
+     */
+    loop?: boolean;
+    /**
+     * Whether to use requestAnimationFrame for smoother animations
+     * When true, ignores interval option and syncs with display refresh rate
+     * @default false
+     */
+    useRAF?: boolean;
+    /**
+     * Called when the timer completes (time reaches 0)
+     */
+    onComplete?: () => void;
+    /**
+     * Called on each tick with the remaining time in milliseconds
+     */
+    onTick?: (remainingMs: number) => void;
+    /**
+     * Called when the timer starts
+     */
+    onStart?: () => void;
+    /**
+     * Called when the timer pauses
+     */
+    onPause?: () => void;
+    /**
+     * Called when the timer resets
+     */
+    onReset?: () => void;
+    /**
+     * Called when the timer stops
+     */
+    onStop?: () => void;
+}
+/**
+ * Return type for useTimer hook
+ */
+interface UseTimerReturn {
+    /**
+     * Remaining time in milliseconds
+     */
+    time: number;
+    /**
+     * Initial time in milliseconds
+     */
+    initialTime: number;
+    /**
+     * Formatted time string based on format option
+     */
+    formattedTime: string;
+    /**
+     * Progress percentage (0-100)
+     * 0 at start, 100 when complete
+     */
+    progress: number;
+    /**
+     * Current timer status
+     */
+    status: TimerStatus;
+    /**
+     * Whether the timer is currently running
+     */
+    isRunning: boolean;
+    /**
+     * Whether the timer is paused
+     */
+    isPaused: boolean;
+    /**
+     * Whether the timer has finished (time = 0)
+     */
+    isFinished: boolean;
+    /**
+     * Whether the timer is idle (never started or after reset)
+     */
+    isIdle: boolean;
+    /**
+     * Hours component (0+)
+     */
+    hours: number;
+    /**
+     * Minutes component (0-59)
+     */
+    minutes: number;
+    /**
+     * Seconds component (0-59)
+     */
+    seconds: number;
+    /**
+     * Milliseconds component (0-999)
+     */
+    milliseconds: number;
+    /**
+     * Start or resume the timer
+     */
+    start: () => void;
+    /**
+     * Pause the timer (preserves remaining time)
+     */
+    pause: () => void;
+    /**
+     * Stop the timer (preserves remaining time, resets status to idle)
+     */
+    stop: () => void;
+    /**
+     * Reset the timer to initial time
+     */
+    reset: () => void;
+    /**
+     * Reset and start immediately
+     */
+    restart: () => void;
+    /**
+     * Toggle between running and paused states
+     */
+    toggle: () => void;
+    /**
+     * Add time in milliseconds
+     */
+    addTime: (ms: number) => void;
+    /**
+     * Subtract time in milliseconds (minimum 0)
+     */
+    subtractTime: (ms: number) => void;
+    /**
+     * Set time to a specific value in milliseconds
+     */
+    setTime: (ms: number) => void;
+}
+
+/**
+ * Helper object to create milliseconds from various time units
+ *
+ * @example
+ * ```tsx
+ * import { useTimer, ms } from "@usefy/use-timer";
+ *
+ * // 5 minute timer
+ * const timer = useTimer(ms.minutes(5));
+ *
+ * // 1 hour 30 minutes timer
+ * const timer = useTimer(ms.hours(1) + ms.minutes(30));
+ * ```
+ */
+declare const ms: {
+    /** Convert seconds to milliseconds */
+    readonly seconds: (n: number) => number;
+    /** Convert minutes to milliseconds */
+    readonly minutes: (n: number) => number;
+    /** Convert hours to milliseconds */
+    readonly hours: (n: number) => number;
+};
+/**
+ * A powerful countdown timer hook with comprehensive controls and features.
+ *
+ * @param initialTimeMs - Initial time in milliseconds
+ * @param options - Timer configuration options
+ * @returns Timer state and control functions
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * function Timer() {
+ *   const timer = useTimer(60000); // 60 seconds
+ *
+ *   return (
+ *     <div>
+ *       <p>{timer.formattedTime}</p>
+ *       <button onClick={timer.toggle}>
+ *         {timer.isRunning ? "Pause" : "Start"}
+ *       </button>
+ *       <button onClick={timer.reset}>Reset</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With callbacks and auto-start
+ * const timer = useTimer(30000, {
+ *   autoStart: true,
+ *   onComplete: () => alert("Time's up!"),
+ *   onTick: (remaining) => console.log(`${remaining}ms left`),
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With time helpers
+ * import { useTimer, ms } from "@usefy/use-timer";
+ *
+ * const timer = useTimer(ms.minutes(5), {
+ *   format: "MM:SS",
+ *   loop: true,
+ * });
+ * ```
+ */
+declare function useTimer(initialTimeMs: number, options?: UseTimerOptions): UseTimerReturn;
+
+/**
+ * Supported time units for utility functions
+ */
+type TimeUnit = "ms" | "seconds" | "minutes" | "hours";
+/**
+ * Convert a time value to milliseconds
+ * @param time - The time value to convert
+ * @param unit - The unit of the time value
+ * @returns Time in milliseconds (minimum 0)
+ */
+declare function toMs(time: number, unit: TimeUnit): number;
+/**
+ * Convert milliseconds to a specific time unit
+ * @param ms - Time in milliseconds
+ * @param unit - Target time unit
+ * @returns Time in the specified unit
+ */
+declare function fromMs(ms: number, unit: TimeUnit): number;
+/**
+ * Decomposed time object
+ */
+interface DecomposedTime {
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+}
+/**
+ * Decompose milliseconds into hours, minutes, seconds, and milliseconds
+ * @param ms - Time in milliseconds
+ * @returns Decomposed time object
+ */
+declare function decompose(ms: number): DecomposedTime;
+
+/**
+ * Format milliseconds into a time string
+ * @param ms - Time in milliseconds
+ * @param format - Desired format
+ * @returns Formatted time string
+ */
+declare function formatTime(ms: number, format: TimeFormat): string;
+
+export { type DecomposedTime, type TimeFormat, type TimeFormatter, type TimeUnit, type TimerStatus, type UseTimerOptions, type UseTimerReturn, decompose, formatTime, fromMs, ms, toMs, useTimer };