shelving/util/date.d.ts

Toolkit for using data in JavaScript.

import type { AnyCaller } from "./function.js";
/** Values that can be converted to dates. */
export type PossibleDate = "now" | "today" | "tomorrow" | "yesterday" | Date | number | string;
/**
 * Is a value a valid date?
 * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `false`
 */
export declare function isDate(value: unknown): value is Date;
/** Assert that a value is a `Date` instance. */
export declare function assertDate(value: unknown, caller?: AnyCaller): asserts value is Date;
/**
 * Convert an unknown value to a valid `Date` instance, or return `undefined` if it couldn't be converted.
 * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `null`
 *
 * Conversion rules:
 * - `Date` instance returns unchanged (BUT if the date isn't valid, `undefined` is returned).
 * - `null` or `undefined` or `""` empty string returns `undefined`
 * - The string `"now"` returns the current date (e.g. `new Date()`).
 * - The string `"today"` returns the current date at midnight (e.g. `getMidnight()`).
 * - The string `"tomorrow"` returns tomorrow's date at midnight (e.g. `addDays(getMidnight(), 1)`).
 * - The string `"yesterday"` returns yesterday's date at midnight (e.g. `addDays(getMidnight(), 1)`).
 * - Strings (e.g. `"2003-09-12"` or `"2003 feb 20:09"`) return the corresponding date (using `new Date(string)`).
 * - Numbers are return the corresponding date (using `new Date(number)`, i.e. milliseconds since 01/01/1970).
 * - Anything else returns `undefined`
 *
 * @param value Any value that we want to parse as a valid date (defaults to `undefined`).
 * @returns `Date` instance if the value could be converted to a valid date, and `null` if not.
 */
export declare function getDate(value: unknown): Date | undefined;
/** Get a date representing this exact moment. */
export declare function getNow(): Date;
/** Get a date representing midnight of the previous day. */
export declare function getYesterday(): Date;
/** Get a date representing midnight of the current day. */
export declare function getToday(): Date;
/** Get a date representing midnight of the next day. */
export declare function getTomorrow(): Date;
/**
 * Convert a possible date to a `Date` instance, or throw `RequiredError` if it couldn't be converted.
 * @param value Any value that we want to parse as a valid date (defaults to `"now"`).
 */
export declare function requireDate(value?: PossibleDate, caller?: AnyCaller): Date;
/** Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `undefined` if it couldn't be converted. */
export declare function getTimestamp(value?: unknown): number | undefined;
/** Convert a possible date to a timestamp (milliseconds past Unix epoch), or throw `RequiredError` if it couldn't be converted. */
export declare function requireTimestamp(value?: PossibleDate): number;
/** Convert an unknown value to a YMD date string like "2015-09-12", or `undefined` if it couldn't be converted. */
export declare function getYMD(value?: unknown): string | undefined;
/** Convert a `Date` instance to a YMD string like "2015-09-12", or throw `RequiredError` if it couldn't be converted.  */
export declare function requireYMD(value?: PossibleDate, caller?: AnyCaller): string;
/** List of day-of-week strings. */
export declare const DAYS: readonly ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
/** Type listing day-of-week strings. */
export type Day = (typeof DAYS)[number];
/** Convert a `Date` instance to a day-of-week string like "monday" */
export declare function getDay(target?: PossibleDate): Day;
/** Get a Date representing exactly midnight of the specified date. */
export declare function getMidnight(target?: PossibleDate, caller?: AnyCaller): Date;
/** Get a Date representing midnight on Monday of the specified week. */
export declare function getMonday(target?: PossibleDate, caller?: AnyCaller): Date;
/** Return a new date that increase or decreases the number of days based on an input date. */
export declare function addDays(change: number, target?: PossibleDate): Date;
/** Return a new date that increase or decreases the number of hours based on an input date. */
export declare function addHours(change: number, target?: PossibleDate): Date;
/**
 * Get the duration (in milliseconds) between two dates.
 *
 * @param target The date when the thing will happen or did happen.
 * @param current Today's date (or a different date to measure from).
 */
export declare function getMillisecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/** Count the number of seconds until a date. */
export declare function getSecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/** Count the number of days ago a date was. */
export declare function getSecondsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/** Count the number of days until a date. */
export declare function getDaysUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/** Count the number of days ago a date was. */
export declare function getDaysAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/** Count the number of weeks until a date. */
export declare function getWeeksUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/** Count the number of weeks ago a date was. */
export declare function getWeeksAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/** Is a date in the past? */
export declare function isPast(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
/** Is a date in the future? */
export declare function isFuture(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
/** Is a date today (taking into account midnight). */
export declare function isToday(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
/** Compact when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now` */
export declare function formatWhen(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
export declare function formatUntil(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
export declare function formatAgo(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;