@storm-stack/date-time/dist/storm-date-time.d.ts

This package includes a DateTime class, various utility functions for working with dates and times, and a number of formatting options.

import { Temporal } from "@js-temporal/polyfill";
import { type JsonValue } from "@storm-stack/serialization";
import { ValidationDetails } from "@storm-stack/types";
/**
 * The options to use when creating a new DateTime object
 */
export interface DateTimeOptions {
    /**
     * The time zone to use. If not specified, the default time zone for the runtime is used.
     */
    timeZone?: Temporal.TimeZoneLike;
    /**
     * The calendar to use. If not specified, the default calendar for the runtime is used.
     */
    calendar?: Temporal.CalendarLike;
    /**
     * If false, the current date and time is defaulted when undefined or null is passed. If true, the current date and time is not defaulted.
     *
     * @defaultValue false
     */
    defaultToNow?: boolean;
}
/**
 * The input types that can be used to create a DateTime object
 */
export type DateTimeInput = StormDateTime | Temporal.Instant | Date | string | number | bigint | null | undefined;
/**
 * Serializes a StormDateTime into a string
 *
 * @param dateTime - The dateTime to serialize
 * @returns The serialized dateTime
 */
export declare function serializeStormDateTime(dateTime: StormDateTime): string;
/**
 * Deserializes a string into a StormDateTime
 *
 * @param utcString - The dateTime to deserialize
 * @returns The deserialized dateTime
 */
export declare function deserializeStormDateTime(utcString: JsonValue): StormDateTime;
/**
 * A wrapper of the and Date class used by Storm Software to provide Date-Time values
 *
 * @decorator `@Serializable()`
 * @class StormDateTime
 */
declare class StormDateTime extends Date {
    #private;
    /**
     * A helper function to get the default time zone
     *
     * @returns The default time zone
     */
    static getDefaultTimeZone(): string;
    /**
     * Type-check to determine if `obj` is a `DateTime` object
     *
     * `isDateTime` returns true if the object passed to it has a `_symbol` property that is equal to
     * `DATE_TIME_SYMBOL`
     *
     * @param obj - the object to check
     * @returns The function isDateTime is returning a boolean value.
     */
    static isDateTime(obj: unknown): obj is StormDateTime;
    /**
     * The current function returns a new StormDateTime object with the current date and time
     *
     * @returns A new instance of StormDateTime with the current date and time.
     */
    static now(): number;
    /**
     * The current function returns a new StormDateTime object with the current date and time
     *
     * @returns A new instance of StormDateTime with the current date and time.
     */
    static current(): StormDateTime;
    /**
     * The maximum function returns a new StormDateTime object with the maximum date and time
     *
     * @returns A new instance of StormDateTime with the maximum date and time.
     */
    static minimum(): StormDateTime;
    /**
     * The maximum function returns a new StormDateTime object with the maximum date and time
     *
     * @returns A new instance of StormDateTime with the maximum date and time.
     */
    static maximum(): StormDateTime;
    /**
     * Get the month index from the month name
     *
     * @example
     * StormDateTime.getMonthIndex(""); // -1
     * StormDateTime.getMonthIndex("invalid"); // -1
     * StormDateTime.getMonthIndex("January"); // 0
     * StormDateTime.getMonthIndex("february"); // 1
     * StormDateTime.getMonthIndex("JUNE"); // 5
     *
     * @param month - The month name
     * @returns The month index
     */
    static getMonthIndex(month?: string): number;
    /**
     * Validate the input date value
     *
     * @param dateTime - The date value to validate
     * @returns A boolean representing whether the value is a valid *date-time*
     */
    static validate(value?: DateTimeInput): ValidationDetails | null;
    /**
     * Creates a new instance of StormDateTime from a string with a specified format.
     *
     * @param dateTime - The input value used to determine the current date and time
     * @param options - The options to use when creating the StormDateTime object
     * @returns A new instance of StormDateTime with the current date and time.
     */
    static create(dateTime?: DateTimeInput, options?: DateTimeOptions): StormDateTime;
    constructor(dateTime?: DateTimeInput, options?: DateTimeOptions);
    /**
     * An accessor that returns the epoch milliseconds of the DateTime object
     */
    get epochMilliseconds(): number;
    /**
     * An accessor that returns the `Temporal.Instant` object of the DateTime object
     */
    get instant(): Temporal.Instant;
    /**
     * An accessor that sets the `Temporal.Instant` object of the DateTime object
     */
    protected set instant(instant: Temporal.Instant);
    /**
     * An accessor that returns the `Temporal.ZonedDateTime` object of the DateTime object
     */
    get zonedDateTime(): Temporal.ZonedDateTime;
    /**
     * An accessor that sets the `Temporal.ZonedDateTime` object of the DateTime object
     */
    protected set zonedDateTime(zonedDateTime: Temporal.ZonedDateTime);
    /**
     * An accessor that returns the `calendarId` string of the DateTime object
     */
    get calendarId(): string;
    /**
     * An accessor that returns the `timeZoneId` string of the DateTime object
     */
    get timeZoneId(): string;
    /**
     * An accessor that returns the `valid` boolean of the DateTime object
     */
    get valid(): boolean;
    /**
     * An accessor that returns the `invalid` boolean of the DateTime object
     */
    get invalid(): boolean;
    /**
     * Returns the input value used to create the DateTime object
     */
    get input(): DateTimeInput;
    /**
     * Returns the options used to create the DateTime object
     */
    get options(): DateTimeOptions;
    /**
     * A function that validates the current DateTime object
     *
     * @returns A ValidationDetails object if the DateTime object is invalid, otherwise null
     */
    validate(): ValidationDetails | null;
    /**
     * Returns the stored time value in milliseconds since midnight, January 1, 1970 UTC.
     */
    getTime(): number;
    /**
     *  Gets the year, using local time.
     */
    getFullYear(): number;
    /**
     *  Gets the year using Universal Coordinated Time (UTC).
     */
    getUTCFullYear(): number;
    /**
     *  Gets the month, using local time.
     */
    getMonth(): number;
    /**
     *  Gets the month of a Date object using Universal Coordinated Time (UTC).
     */
    getUTCMonth(): number;
    /**
     *  Gets the day-of-the-month, using local time.
     */
    getDate(): number;
    /**
     *  Gets the day-of-the-month, using Universal Coordinated Time (UTC).
     */
    getUTCDate(): number;
    /**
     *  Gets the day of the week, using local time.
     */
    getDay(): number;
    /**
     *  Gets the day of the week using Universal Coordinated Time (UTC).
     */
    getUTCDay(): number;
    /**
     *  Gets the hours in a date, using local time.
     */
    getHours(): number;
    /**
     *  Gets the hours value in a Date object using Universal Coordinated Time (UTC).
     */
    getUTCHours(): number;
    /**
     *  Gets the minutes of a Date object, using local time.
     */
    getMinutes(): number;
    /**
     *  Gets the minutes of a Date object using Universal Coordinated Time (UTC).
     */
    getUTCMinutes(): number;
    /**
     *  Gets the seconds of a Date object, using local time.
     */
    getSeconds(): number;
    /**
     *  Gets the seconds of a Date object using Universal Coordinated Time (UTC).
     */
    getUTCSeconds(): number;
    /**
     *  Gets the milliseconds of a Date, using local time.
     */
    getMilliseconds(): number;
    /**
     *  Gets the milliseconds of a Date object using Universal Coordinated Time (UTC).
     */
    getUTCMilliseconds(): number;
    /**
     *  Gets the difference in minutes between the time on the local computer and Universal Coordinated Time (UTC).
     */
    getTimezoneOffset(): number;
    /**
     * Sets the date and time value in the Date object.
     * @param time - A numeric value representing the number of elapsed milliseconds since midnight, January 1, 1970 GMT.
     */
    setTime(time: number): number;
    /**
     * Sets the milliseconds value in the Date object using local time.
     * @param millisecond - A numeric value equal to the millisecond value.
     */
    setMilliseconds(millisecond: number): number;
    /**
     * Sets the milliseconds value in the Date object using Universal Coordinated Time (UTC).
     * @param millisecond - A numeric value equal to the millisecond value.
     */
    setUTCMilliseconds(millisecond: number): number;
    /**
     * Sets the seconds value in the Date object using local time.
     * @param second -  A numeric value equal to the seconds value.
     * @param millisecond - A numeric value equal to the milliseconds value.
     */
    setSeconds(second: number, millisecond?: number): number;
    /**
     * Sets the seconds value in the Date object using Universal Coordinated Time (UTC).
     * @param second - A numeric value equal to the seconds value.
     * @param millisecond - A numeric value equal to the milliseconds value.
     */
    setUTCSeconds(second: number, millisecond?: number): number;
    /**
     * Sets the minutes value in the Date object using local time.
     * @param minute - A numeric value equal to the minutes value.
     * @param second - A numeric value equal to the seconds value.
     * @param millisecond - A numeric value equal to the milliseconds value.
     */
    setMinutes(minute: number, second?: number, millisecond?: number): number;
    /**
     * Sets the minutes value in the Date object using Universal Coordinated Time (UTC).
     * @param minute - A numeric value equal to the minutes value.
     * @param second - A numeric value equal to the seconds value.
     * @param millisecond - A numeric value equal to the milliseconds value.
     */
    setUTCMinutes(minute: number, second?: number, millisecond?: number): number;
    /**
     * Sets the hour value in the Date object using local time.
     *
     * @param hour - A numeric value equal to the hours value.
     * @param minute - A numeric value equal to the minutes value.
     * @param second - A numeric value equal to the seconds value.
     * @param millisecond - A numeric value equal to the milliseconds value.
     */
    setHours(hour: number, minute: number, second?: number, millisecond?: number): number;
    /**
     * Sets the hours value in the Date object using Universal Coordinated Time (UTC).
     *
     * @param hour - A numeric value equal to the hours value.
     * @param minute - A numeric value equal to the minutes value.
     * @param second - A numeric value equal to the seconds value.
     * @param millisecond - A numeric value equal to the milliseconds value.
     */
    setUTCHours(hour: number, minute: number, second?: number, millisecond?: number): number;
    /**
     * Sets the numeric day-of-the-month value of the Date object using local time.
     *
     * @param day - A numeric value equal to the day of the month.
     */
    setDate(day: number): number;
    /**
     * Sets the numeric day of the month in the Date object using Universal Coordinated Time (UTC).
     *
     * @param day - A numeric value equal to the day of the month.
     */
    setUTCDate(day: number): number;
    /**
     * Sets the month value in the Date object using local time.
     *
     * @param month - A numeric value equal to the month. The value for January is 0, and other month values follow consecutively.
     * @param day - A numeric value representing the day of the month. If this value is not supplied, the value from a call to the getDate method is used.
     */
    setMonth(month: number, day?: number): number;
    /**
     * Sets the month value in the Date object using Universal Coordinated Time (UTC).
     *
     * @param month - A numeric value equal to the month. The value for January is 0, and other month values follow consecutively.
     * @param day - A numeric value representing the day of the month. If it is not supplied, the value from a call to the getUTCDate method is used.
     */
    setUTCMonth(month: number, day?: number): number;
    /**
     * Sets the year of the Date object using local time.
     * @param year - A numeric value for the year.
     * @param month - A zero-based numeric value for the month (0 for January, 11 for December). Must be specified if numDate is specified.
     * @param day - A numeric value equal for the day of the month.
     */
    setFullYear(year: number, month?: number, day?: number): number;
    /**
     * Sets the year value in the Date object using Universal Coordinated Time (UTC).
     *
     * @param year - A numeric value equal to the year.
     * @param month - A numeric value equal to the month. The value for January is 0, and other month values follow consecutively. Must be supplied if numDate is supplied.
     * @param day - A numeric value equal to the day of the month.
     */
    setUTCFullYear(year: number, month?: number, day?: number): number;
    /**
     * It returns a plain date object from a DateTime object
     *
     * @returns A PlainDate object.
     */
    getPlainDate(): StormDateTime;
    /**
     * `getPlainTime` returns a `PlainTime` object from a `DateTime` object
     *
     * @returns A PlainTime object.
     */
    getPlainTime(): StormDateTime;
    /**
     * It returns the duration between two dates.
     *
     * @param dateTimeTo - DateTime = DateTime.current
     * @returns A duration object.
     */
    since(dateTimeTo?: StormDateTime): Temporal.Duration;
    /**
     * It returns the duration between two date times.
     *
     * @param dateTimeTo - DateTime = DateTime.current
     * @returns A duration object.
     */
    getDuration(dateTimeTo?: StormDateTime): Temporal.Duration;
}
export { StormDateTime };