advanced-ms/dist/index.d.cts

An advanced millisecond conversion package

type CompactUnit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w' | 'mo' | 'y';

/**
 * Interface for options to customize the `toDuration` function behavior.
 */
interface Option {
    /**
     * Whether to use a leap year when calculating (default is false).
     */
    isLeapYear?: boolean;
    
    /**
     * Whether to return all units in the result, even if some of them have a value of 0 (default is false).
     */
    returnAllUnits?: boolean;
    
    /**
     * Whether to return the units in a compact format (e.g., `2h 30m` instead of `2 hours, 30 minutes`).
     * Default is false.
     */
    compactUnits?: boolean;
    
    /**
     * A list of unit short names (e.g., `'y'`, `'mo'`, `'w'`) to exclude from the result.
     * Default is undefined, meaning no units are avoided.
     */
    avoidUnits?: Array<CompactUnit>;
    
    /**
     * Can only be used with option `avoidUnits`. If true, it will return formatted time depending on what units were avoided.
     * when iterating over time units (default is false).
     */
    staticUnits?: boolean;
}

declare module 'advanced-ms' {
    /**
     * Converts a given string or number value into either milliseconds or a human-readable duration.
     * 
     * @param {string | number} value - The input value to convert. Can be a string (e.g., `"2h 30m"`) or a number (milliseconds).
     * @param {Option} option - An optional object containing various configuration options:
     *   - `isLeapYear` (optional) - A boolean to specify whether to use a leap year in calculations (default is false).
     *   - *Below options can only be used during the conversion of milliseconds to formatted time*
     *   - `returnAllUnits` (optional) - A boolean to specify whether to include all units, even those with a value of 0 (default is false).
     *   - `compactDuration` (optional) - A boolean to specify whether to return the duration in a compact format (e.g., `2h 30m` instead of `2 hours, 30 minutes`) (default is false).
     *   - `avoidUnits` (optional) - An array of time formats to exclude from the result (e.g., `['y', 'mo']`).
     *   - `staticUnits` (optional) - A boolean to specify whether to use static units. Can only be used with option `avoidUnits`. If true, it will return formatted time depending on what units were avoided. (default is false).
     * @returns {string | number} - Returns milliseconds if the input is a duration string, 
     *                              or a formatted string if the input is a number (milliseconds).
     * @throws {Error} If the input is neither a valid number nor a properly formatted duration string.
     */
    function AdvancedMS(value: string | number, option?: Option): string | number;
}

interface FlexOptions {
    isLeapYear?: boolean;
    returnAllUnits?: boolean;
    compactUnits?: boolean;
}
declare function AdvancedMS(value: string, option?: {
    isLeapYear?: boolean;
}): number;
declare function AdvancedMS(value: number, option?: FlexOptions): string;
declare function AdvancedMS(value: number, option: FlexOptions & {
    avoidUnits: Array<CompactUnit>;
    staticUnits?: boolean;
}): string;

export { AdvancedMS as default };