Skip to content

Date API ​

toDate Convert ​

Converts and clones a valid date.

Signature ​

ts
export function toDate(value: DateInput): Date;

Example ​

ts
import { toDate } from "@fast-china/utils";

const result = toDate("2026-09-13T08:00:00+08:00");

Input ​

InputTypeRequired / defaultDescription
valueDateInputRequiredDate, Unix millisecond timestamp, or runtime-parseable string.

Returns ​

ValueTypeDescription
resultDateNew Date sharing no mutable state with the input.

isValidDate Validate ​

Checks whether an input can become a valid date.

Signature ​

ts
export function isValidDate(value: unknown): value is DateInput;

Example ​

ts
import { isValidDate } from "@fast-china/utils";

const result = isValidDate("2026-09-13");

Input ​

InputTypeRequired / defaultDescription
valueunknownRequiredAny value to check.

Returns ​

ValueTypeDescription
resultvalue is DateInputtrue only for Date, number, or string inputs with a finite timestamp.

startOfDay Start ​

Returns 00:00:00.000 on the input's local calendar day without mutation.

Signature ​

ts
export function startOfDay(value: DateInput): Date;

Example ​

ts
import { startOfDay } from "@fast-china/utils";

const result = startOfDay("2026-09-13T08:00:00+08:00");

Input ​

InputTypeRequired / defaultDescription
valueDateInputRequiredValid date input.

Returns ​

ValueTypeDescription
resultDateNew start-of-day Date in the local time zone.

endOfDay End ​

Returns 23:59:59.999 on the input's local calendar day without mutation.

Signature ​

ts
export function endOfDay(value: DateInput): Date;

Example ​

ts
import { endOfDay } from "@fast-china/utils";

const result = endOfDay("2026-09-13T08:00:00+08:00");

Input ​

InputTypeRequired / defaultDescription
valueDateInputRequiredValid date input.

Returns ​

ValueTypeDescription
resultDateNew end-of-day Date in the local time zone.

addDays Days ​

Adds integer local calendar days without mutating the input.

Signature ​

ts
export function addDays(value: DateInput, amount: number): Date;

Example ​

ts
import { addDays } from "@fast-china/utils";

const result = addDays("2026-09-13T08:00:00+08:00", 1);

Input ​

InputTypeRequired / defaultDescription
valueDateInputRequiredBase date.
amountnumberRequiredSafe integer number of days; may be negative.

Returns ​

ValueTypeDescription
resultDateNew Date after local calendar arithmetic; daylight-saving changes can make the elapsed duration differ from 24 hours.

addMonths Months ​

Adds integer local calendar months, clamping nonexistent dates to the target month's last day.

Signature ​

ts
export function addMonths(value: DateInput, amount: number): Date;

Example ​

ts
import { addMonths } from "@fast-china/utils";

const result = addMonths("2026-09-13T08:00:00+08:00", 1);

Input ​

InputTypeRequired / defaultDescription
valueDateInputRequiredBase date.
amountnumberRequiredSafe integer number of months; may be negative.

Returns ​

ValueTypeDescription
resultDateNew Date after month arithmetic.

addYears Years ​

Adds integer local calendar years using the same month-end clamping rule.

Signature ​

ts
export function addYears(value: DateInput, amount: number): Date;

Example ​

ts
import { addYears } from "@fast-china/utils";

const result = addYears("2026-09-13T08:00:00+08:00", 1);

Input ​

InputTypeRequired / defaultDescription
valueDateInputRequiredBase date.
amountnumberRequiredSafe integer number of years; may be negative.

Returns ​

ValueTypeDescription
resultDateNew Date after year arithmetic.

isSameDay Compare ​

Checks whether two inputs fall on the same local calendar day.

Signature ​

ts
export function isSameDay(left: DateInput, right: DateInput): boolean;

Example ​

ts
import { isSameDay } from "@fast-china/utils";

const result = isSameDay("2026-09-13", "2026-09-13T23:00:00");

Input ​

InputTypeRequired / defaultDescription
leftDateInputRequiredFirst date.
rightDateInputRequiredSecond date.

Returns ​

ValueTypeDescription
resultbooleantrue when local year, month, and day match.

isFuture Future ​

Checks whether a time is later than the reference time.

Signature ​

ts
export function isFuture(value: DateInput, now: DateInput = Date.now()): boolean;

Example ​

ts
import { isFuture } from "@fast-china/utils";

const result = isFuture("2026-09-13T08:00:00+08:00", Date.now());

Input ​

InputTypeRequired / defaultDescription
valueDateInputRequiredTime to compare.
nowDateInputOptional; defaults to Date.now()Reference time; defaults to the current time at invocation.

Returns ​

ValueTypeDescription
resultbooleantrue when value is strictly later than the reference.

getLocalDayBounds Bounds ​

Returns the complete inclusive interval of the reference's local calendar day.

Signature ​

ts
export function getLocalDayBounds(value: DateInput = Date.now()): [start: Date, end: Date];

Example ​

ts
import { getLocalDayBounds } from "@fast-china/utils";

const result = getLocalDayBounds(Date.now());

Input ​

InputTypeRequired / defaultDescription
valueDateInputOptional; defaults to Date.now()Reference date; defaults to the current date at invocation.

Returns ​

ValueTypeDescription
result[start: Date, end: Date]New tuple containing local start-of-day and end-of-day Dates.

isWithinInterval Range ​

Checks whether a date lies within an inclusive interval.

Signature ​

ts
export function isWithinInterval(value: DateInput, start: DateInput, end: DateInput): boolean;

Example ​

ts
import { isWithinInterval } from "@fast-china/utils";

const result = isWithinInterval("2026-09-13T08:00:00+08:00", "2026-09-01", "2026-09-30");

Input ​

InputTypeRequired / defaultDescription
valueDateInputRequiredDate to check.
startDateInputRequiredInclusive start.
endDateInputRequiredInclusive end.

Returns ​

ValueTypeDescription
resultbooleantrue when the timestamp lies in the closed interval.

formatRelativeTime Format ​

Default Simplified Chinese relative-time text uses an internal implementation without Intl. Explicit locale options use Intl.RelativeTimeFormat and retain arbitrary locale support. The numeric, style, fixed-duration thresholds, and rounding rules are unchanged.

Signature ​

ts
export function formatRelativeTime(value: DateInput, options: RelativeTimeOptions = {}): string;

Example ​

ts
import { formatRelativeTime } from "@fast-china/utils";

const result = formatRelativeTime("2026-09-13T08:00:00+08:00", {});

Input ​

InputTypeRequired / defaultDescription
valueDateInputRequiredTarget time.
optionsRelativeTimeOptionsOptional; defaults to {}Locale, style, and reference time.

Returns ​

ValueTypeDescription
resultstringRelative-time text.

formatChineseRelativeTime Format ​

Formats a date as fixed Chinese relative-time text.

Signature ​

ts
export function formatChineseRelativeTime(value: Date | number | string | null | undefined): string;

Example ​

ts
import { formatChineseRelativeTime } from "@fast-china/utils";

const result = formatChineseRelativeTime("2026-09-13T08:00:00+08:00");

Input ​

InputTypeRequired / defaultDescription
valueDate | number | string | null | undefinedRequiredDate, timestamp, parseable string, or nullish value.

Returns ​

ValueTypeDescription
resultstringChinese text meaning, for example, three minutes ago or six months later; invalid or empty input returns an empty string.

createOneMonthRangeFromToday Month ​

Creates a complete local-day range between today and one month before or after.

Signature ​

ts
export function createOneMonthRangeFromToday(towardFuture = false): [start: Date, end: Date];

Example ​

ts
import { createOneMonthRangeFromToday } from "@fast-china/utils";

const result = createOneMonthRangeFromToday(false);

Input ​

InputTypeRequired / defaultDescription
towardFutureunknownOptional; defaults to falsetrue selects today through one month later; otherwise one month earlier through today.

Returns ​

ValueTypeDescription
result[start: Date, end: Date]New local start/end-of-day boundaries on every call.

isDateAfterNow Future ​

Checks whether a date is later than the current time at invocation.

Signature ​

ts
export function isDateAfterNow(time: Date): boolean;

Example ​

ts
import { isDateAfterNow } from "@fast-china/utils";

const result = isDateAfterNow(new Date(Date.now() + 60_000));

Input ​

InputTypeRequired / defaultDescription
timeDateRequiredDate to compare.

Returns ​

ValueTypeDescription
resultbooleantrue when the timestamp is strictly later than Date.now().

getLocalTimeGreeting Greeting ​

Returns a fixed Chinese greeting based on the browser's local hour.

Signature ​

ts
export function getLocalTimeGreeting(): string;

Example ​

ts
import { getLocalTimeGreeting } from "@fast-china/utils";

const result = getLocalTimeGreeting();

Input ​

This method has no input parameters.

Returns ​

ValueTypeDescription
resultstringChinese welcome text for the current time of day.

createDateRangeShortcuts Shortcuts ​

Creates common full-date-range shortcuts for the past or future.

Signature ​

ts
export function createDateRangeShortcuts(towardFuture = false): DateRangeShortcut[];

Example ​

ts
import { createDateRangeShortcuts } from "@fast-china/utils";

const result = createDateRangeShortcuts(false);

Input ​

InputTypeRequired / defaultDescription
towardFutureunknownOptional; defaults to falsetrue creates future ranges; historical ranges by default.

Returns ​

ValueTypeDescription
resultDateRangeShortcut[]Range shortcuts that read the current time on every evaluation.

createDateShortcuts Shortcuts ​

Creates common single-date shortcuts for the past or future.

Signature ​

ts
export function createDateShortcuts(towardFuture = false): DateShortcut[];

Example ​

ts
import { createDateShortcuts } from "@fast-china/utils";

const result = createDateShortcuts(false);

Input ​

InputTypeRequired / defaultDescription
towardFutureunknownOptional; defaults to falsetrue creates future dates; historical dates by default.

Returns ​

ValueTypeDescription
resultDateShortcut[]Single-date shortcuts that read the current time on every evaluation.

getStartOfToday Start ​

Returns today's local midnight.

Signature ​

ts
export function getStartOfToday(): Date;

Example ​

ts
import { getStartOfToday } from "@fast-china/utils";

const result = getStartOfToday();

Input ​

This method has no input parameters.

Returns ​

ValueTypeDescription
resultDateNew Date at 00:00:00.000.