@thi.ng/date
Version:
Datetime types, relative dates, math, iterators, composable formatters, locales
243 lines • 7.03 kB
TypeScript
import { type FormatFn, type MaybeDate, type Precision } from "./api.js";
export declare const FORMATTERS: Record<string, FormatFn>;
/**
* Returns a new date formatter for given array of format strings (or
* functions). The returned function accepts timestamps (epoch), `Date` or
* `DateTime` instances and accepts an optional boolean arg to output UTC
* instead of local time (default).
*
* @remarks
* If no date is given to the returned formatter, `Date.now()` will be used by
* default.
*
* See {@link FORMATTERS} for available date component format IDs. To escape a
* formatter and use as a string literal, prefix the term with a backslash.
*
* @example
* ```ts tangle:../export/def-format.ts
* import { defFormat } from "@thi.ng/date";
*
* const fmt = defFormat(["yyyy", "-", "MM", "-", "dd"]);
*
* console.log(
* fmt(new Date(2015, 3, 23))
* );
* // "2015-04-23"
*
* console.log(
* defFormat(["\\yyyy"])(new Date(2015, 3, 23))
* );
* // "yyyy"
* ```
*
* @param fmt -
*/
export declare const defFormat: (fmt: (string | FormatFn)[]) => (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `2020-09-19`
*/
export declare const FMT_yyyyMMdd: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `20200919`
*/
export declare const FMT_yyyyMMdd_ALT: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `9/19/2020`
*/
export declare const FMT_Mdyyyy: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `Sep 19 2020`. Uses current `LOCALE`, see
* {@link setLocale}.
*/
export declare const FMT_MMMdyyyy: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `19.9.2020`
*/
export declare const FMT_dMyyyy: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `19 Sep 2020`
*/
export declare const FMT_dMMMyyyy: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `17:08`
*/
export declare const FMT_HHmm: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `5:08 PM`
*/
export declare const FMT_hm: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `17:08:01`
*/
export declare const FMT_HHmmss: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `170801`
*/
export declare const FMT_HHmmss_ALT: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `5:08:01 PM`
*/
export declare const FMT_hms: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, e.g. `20200919-170801`
*/
export declare const FMT_yyyyMMdd_HHmmss: (x?: MaybeDate, utc?: boolean) => string;
/**
* ISO8601 format preset (without millisecond term), e.g.
* `2020-09-19T17:08:01Z`
*/
export declare const FMT_ISO_SHORT: (x?: MaybeDate, utc?: boolean) => string;
/**
* ISO8601 format preset (with millisecond term), e.g.
* `2020-09-19T17:08:01.123Z`
*/
export declare const FMT_ISO: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, 4-digit year only
*/
export declare const FMT_yyyy: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, 2-digit month only
*/
export declare const FMT_MM: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, 2-digit week in year only
*/
export declare const FMT_ww: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, 2-digit day in month only
*/
export declare const FMT_dd: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, 2-digit hour only
*/
export declare const FMT_HH: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, 2-digit minute only
*/
export declare const FMT_mm: (x?: MaybeDate, utc?: boolean) => string;
/**
* Format preset, 2-digit second only
*/
export declare const FMT_ss: (x?: MaybeDate, utc?: boolean) => string;
/**
* Takes a `date` and optional reference `base` date and (also optional
* `prec`ision, i.e. number of fractional digits, default: 0). Computes the
* difference between given dates and returns it as formatted string.
*
* @remarks
* Returns {@link LOCALE.now} if absolute difference is < `eps` milliseconds
* (default: 100).
*
* See {@link formatRelativeParts} for alternative output.
*
*
* @example
* ```ts tangle:../export/format-relative.ts
* import { formatRelative } from "@thi.ng/date";
*
* console.log(
* formatRelative("2020-06-01", "2021-07-01")
* );
* // "1 year ago"
*
* console.log(
* formatRelative("2020-08-01", "2021-07-01")
* );
* // "11 months ago"
*
* console.log(
* formatRelative("2021-07-01 13:45", "2021-07-01 12:05")
* );
* // "in 2 hours"
*
* console.log(
* formatRelative("2021-07-01 12:23:24", "2021-07-01 12:05")
* );
* // "in 18 minutes"
* ```
*
* @param date -
* @param base -
* @param prec -
* @param eps -
*/
export declare const formatRelative: (date: MaybeDate, base?: MaybeDate, prec?: number, eps?: number) => string;
/**
* Similar to {@link formatRelative}, however precision is specified as
* {@link Precision} (default: seconds). The result will be formatted as a
* string made up of parts of increasing precision (years, months, days, hours,
* etc.). Only non-zero parts will be mentioned.
*
* @remarks
* Returns {@link LOCALE.now} if absolute difference is < `eps` milliseconds
* (default: 100). In all other cases uses {@link decomposeDifference} for
* given dates to extract parts for formatting.
*
* @example
* ```ts tangle:../export/format-relative-parts.ts
* import { formatRelativeParts, setLocale, EN_LONG } from "@thi.ng/date";
*
* setLocale(EN_LONG);
*
* // with default precision (seconds)
* console.log(
* formatRelativeParts("2022-09-01 12:23:24", "2021-07-01 12:05")
* );
* // "in 1 year, 2 months, 21 hours, 18 minutes, 24 seconds"
*
* // with day precision
* console.log(
* formatRelativeParts("2012-12-25 17:59", "2021-07-01 12:05", "d")
* );
* // "8 years, 6 months, 5 days ago"
*
* console.log(
* formatRelativeParts("2021-07-01 17:59", "2021-07-01 12:05", "d")
* );
* // "in less than a day"
* ```
*
* @param date -
* @param base -
* @param prec -
* @param eps -
*/
export declare const formatRelativeParts: (date: MaybeDate, base?: MaybeDate, prec?: Precision, eps?: number) => string;
/**
* Formats given duration (in ms) to given precision and using current
* {@link LOCALE}.
*
* @example
* ```ts tangle:../export/format-duration.ts
* import { formatDuration } from "@thi.ng/date";
*
* console.log(
* formatDuration(45296000)
* );
* // "12 h, 34 min, 56 s"
*
* console.log(
* formatDuration(45296000, "h")
* );
* // "13 h"
*
* console.log(
* formatDuration(45296000,"d")
* );
* // "< 1 d"
* ```
*
* @param dur
* @param prec
*/
export declare const formatDuration: (dur: number, prec?: Precision) => string;
/**
* Formats an already decomposed duration (in most case you'll want to use
* {@link formatDuration}).
*
* @param parts
* @param prec
*/
export declare const formatDurationParts: (parts: number[], prec?: Precision) => string;
//# sourceMappingURL=format.d.ts.map