nhb-toolbox/dist/dts/converter/base.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { Numeric } from '../types/index';
import type { $Unit, Category, FormatToOptions, Units, UnitsTuple } from './types';
/**
 * @description Base class providing common mathematical and formatting utilities
 * for all unit converters (time, length, data, temperature, etc.).
 */
export declare class $BaseConverter<Unit extends $Unit> {
    protected readonly value: number;
    protected readonly unit: Unit;
    /**
     * Convert value to other units
     * @param value Number or numeric string value to convert.
     * @param unit Optional base unit for the provided value.
     */
    constructor(value: Numeric, unit?: Unit);
    /** @protected Returns a grammatically correct unit string, prefixed with the number value. */
    protected $withPluralUnit(value?: number, unit?: $Unit): string;
    /** @protected Rounds a numeric value to given decimal places. */
    protected $round(value: number, decimals?: number): number;
    /**
     * @protected Shared formatter for all converters.
     * @param value Converted value (already computed via `.to(target)`).
     * @param target Target unit name.
     * @param shortLabels Record of compact unit labels.
     * @param options Formatting options.
     * @returns Formatted string according to style (compact, plural, scientific).
     */
    protected $formatTo(value: number, target: Unit, shortLabels: Record<Unit, string>, options: FormatToOptions | undefined): string;
    /**
     * @instance Returns the numeric value.
     * @returns The raw numeric value without unit.
     */
    valueOf(): number;
    /**
     * @instance Returns the numeric value.
     * @returns The raw numeric value without unit.
     */
    getValue(): number;
    /**
     * @instance Returns the unit name.
     * @returns The current unit.
     */
    getUnit(): Unit;
    /**
     * @instance Returns the original value with formatted pluralized unit.
     * @returns A string like `"3 hours"` or `"1 minute"` or `"3"` if no unit is provided.
     *
     * @remarks
     * - This method is automatically called when the instance is used in a string context.
     * - For complex and versatile pluralization, please refer to {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/pluralizer pluralizer} or {@link https://toolbox.nazmul-nhb.dev/docs/classes/Pluralizer Pluralizer Class} instead.
     */
    toString(): string;
    /**
     * @instance Returns a plain object representation.
     * @returns An object with value and unit.
     */
    toObject(): {
        value: number;
        unit: Unit;
    };
    /**
     * @instance Converts to JSON representation.
     * @returns JSON string of `{ value, unit }`.
     */
    toJSON(): string;
    /** @instance Returns a new instance with the absolute value. */
    abs(): this;
    /**
     * @instance Adds a numeric value (same unit assumed).
     * @returns A new instance with updated value.
     */
    add(n: Numeric): this;
    /**
     * @instance Subtracts a numeric value (same unit assumed).
     * @returns A new instance with updated value.
     */
    subtract(n: Numeric): this;
    /**
     * @instance Multiplies the value.
     * @returns A new instance with updated value.
     */
    multiply(n: Numeric): this;
    /**
     * @instance Divides the value.
     * @returns A new instance with updated value.
     */
    divide(n: Numeric): this;
    /**
     * @instance Rounds to given decimal places.
     * @param decimals Number of decimal places to round. Default is `0`.
     * @returns A new instance with rounded value.
     */
    round(decimals?: number): this;
    /** @instance Returns whether this value is greater than another numeric value. */
    gt(n: Numeric): boolean;
    /** @instance Returns whether this value is less than another numeric value. */
    lt(n: Numeric): boolean;
    /** @instance Returns whether this value equals another numeric value. */
    eq(n: Numeric): boolean;
    /**
     * @instance Returns a human-friendly formatted string with fixed decimals (if the value is fraction).
     * @param decimals Number of decimal places for fractional value.
     * @returns Formatted string with proper unit pluralization.
     *
     * @remarks For complex and versatile pluralization, please refer to {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/pluralizer pluralizer} or {@link https://toolbox.nazmul-nhb.dev/docs/classes/Pluralizer Pluralizer Class} instead.
     */
    format(decimals?: number): string;
    /**
     * @instance Returns all supported units.
     * @returns Array of supported unit strings.
     */
    supportedUnits(): Units;
    /**
     * @instance Returns all supported units for a specific category.
     * @param category Category to filter units by.
     * @returns Tuple of supported units for the specified category.
     */
    supportedUnits<Cat extends Category>(category: Cat): UnitsTuple<Cat>;
}