shelving/util/time.d.ts

Toolkit for using data in JavaScript.

import type { AnyCaller } from "./function.js";
/** Class representing a time in the day in 24 hour format in the user's current locale. */
export declare class Time {
    /** Make a new `Time` instance from a time string. */
    static from(value: unknown): Time | undefined;
    readonly time: number;
    constructor(time: number);
    /** Get the number of hours in this time. */
    get h(): number;
    /** Get the number of minutes in this time. */
    get m(): number;
    /** Get the number of seconds in this time. */
    get s(): number;
    /** Get the number of seconds in this time. */
    get ms(): number;
    /** Get the time as in `hh:mm` format (hours, minutes), e.g. `13.59` */
    get short(): string;
    /** Get the time in `hh:mm:ss` format (hours, minutes seconds), e.g. `13.16.19.123` */
    get medium(): string;
    /** Get this time in `hh:mm:ss.fff` format (ISO 8601 compatible, hours, minutes, seconds, milliseconds), e.g. `13:16:19.123` */
    get long(): string;
    /** Get a date corresponding to this time. */
    get date(): Date;
    /**
     * Format this time using the browser locale settings with a specified amount of precision.
     * @param precision Reveal additional parts of the time, e.g. `2` shows hours and minutes, `3` also shows seconds, and `4 | 5 | 6` show mlliseconds at increasing precision.
     */
    format(precision?: 2 | 3 | 4 | 5 | 6): string;
    valueOf(): number;
    toString(): string;
}
/** Values that can be converted to times. */
export type PossibleTime = Time | Date | number | string;
/** Is an unknown value a `Time` instance. */
export declare function isTime(value: unknown): value is Time;
/**
 * Convert a value to a `Time` instance, or return `undefined` if it couldn't be converted.
 * - Works with possible dates, e.g. `now` or `Date` or `2022-09-12 18:32` or `19827263567`
 * - Works with time strings, e.g. `18:32` or `23:59:59.999`
 *
 * @param value Any value that we want to parse as a valid time (defaults to `undefined`).
 */
export declare function getTime(value: unknown): Time | undefined;
/**
 * Convert a possible date to a `Time` instance, or throw `ValueError` if it couldn't be converted (defaults to `"now"`).
 * @param value Any value that we want to parse as a valid time (defaults to `"now"`).
 */
export declare function requireTime(value?: PossibleTime, caller?: AnyCaller): Time;