@toreda/time/dist/time/data.d.ts

Simple, small footprint library for common time operations and converting between units of time.

import type { LogLike } from '../log/like';
import type { Time } from '../time';
import type { TimeUnit } from './unit';
/**
 * Internal state data created and wrapped by Time instances. All mutators
 * are silent no-ops on bad input: the failure is logged and `caller` is
 * returned unchanged.
 */
export declare class TimeData {
    private _units;
    private value;
    private readonly initialUnits;
    private readonly initialValue;
    readonly log: LogLike;
    constructor(units: TimeUnit, value: number, log?: LogLike | null);
    /**
     * Get the instance's current native time unit.
     */
    units(): TimeUnit;
    /**
     * Convert the current value into the target time unit and update the
     * instance's native time unit to match. Used by in-place conversion
     * methods on the wrapping Time instance.
     *
     * @returns		`caller` for chaining. The conversion is a no-op when the
     *				target is unsupported, the conversion fails, or `target`
     *				already matches the current unit.
     */
    setUnits(caller: Time, target: TimeUnit): Time;
    /**
     * Get the current time value in instance's native time unit.
     */
    get(): number;
    /**
     * Replace the current value with `input`.
     * @returns		`caller` for chaining. State is left unchanged when `input`
     *				is missing, not a finite number in safe range, or a Time
     *				instance whose conversion fails.
     */
    set(caller: Time, input?: number | Time | null): Time;
    /**
     * Add number input to current value.
     * @param caller		Time instance calling this method.
     * @param input			number value to be added.
     * @returns				`caller` for chaining. State is left unchanged when
     *						`input` is not a finite number in safe range or the
     *						resulting sum overflows the safe range.
     */
    addNumber(caller: Time, input?: number | null): Time;
    /**
     * Subtract number input from the current value.
     * @param caller		Time instance calling this method.
     * @param input			number value to be subtracted.
     * @returns				`caller` for chaining. State is left unchanged when
     *						`input` is not a finite number in safe range or the
     *						resulting difference overflows the safe range.
     */
    subNumber(caller: Time, input?: number | null): Time;
    /**
     * Get numeric unit value from a Time or number input.
     *
     * @param convertTo		TimeUnit the result should be expressed in. Used only
     *						when `input` is a Time instance; raw numbers pass through
     *						unchanged.
     * @param input			A Time instance (its value is converted from its native
     *						unit into `convertTo`), a finite number in safe range
     *						(returned as-is), or `null`/`undefined`.
     * @returns				The unit value as a number, or `null` if `input` is
     *						missing, a non-finite or out-of-range number, not a
     *						valid Time instance, or fails conversion.
     */
    getUnitValue(convertTo: TimeUnit, input?: Time | number | null): number | null;
    /**
     * Convert value from specified units into instance's native time units, then
     * subtract it from the current value.
     * @param caller		Time instance calling this method.
     * @param units			TimeUnit of the provided value.
     * @param value			number value to be converted and subtracted.
     * @param decimals		Optional precision (decimals) for the conversion.
     */
    subUnit(caller: Time, units: TimeUnit, value?: number | null, decimals?: number): Time;
    /**
     * Convert value from provided unit type into instance's native time units and
     * add it to the current value.
     * @param caller		Time instance calling this function to be returned by function.
     * @param units			TimeUnit of the provided value.
     * @param value			Value to be converted and added to current time.
     * @param decimals		Number of decimals to include in final added value.
     */
    addUnit(caller: Time, units: TimeUnit, value?: number | null, decimals?: number): Time;
    /**
     * Invert the current value's sign in place.
     * @param caller		Time instance calling this method.
     * @param positivesOnly	When true, only positive values are inverted.
     *						Negative values are left unchanged.
     */
    invert(caller: Time, positivesOnly?: boolean): Time;
    /**
     * Get a Time object representing the elapsed time between the instance's
     * current value and a target Time. Returns a negative value when the target
     * is in the future. The returned Time uses the instance's native unit.
     * @param target
     */
    timeSinceTime(target?: Time | null): Time | null;
    timeSinceNumber(target?: number | null): Time | null;
    /**
     * Get time object containing time left until target time. May return
     * negative value when target time is in the past. The returned time
     * object's time left value uses the same time units as the calling instance.
     * @param time
     */
    timeUntilTime(time?: Time | null): Time | null;
    /**
     * Get time remaining until target unix timestamp.
     * @param target
     */
    timeUntilNumber(target?: number | null): Time | null;
    /**
     * Reset internal state variables to their initial values.
     * @param caller
     */
    reset(caller: Time): Time;
}