Date API

toDate Convert

Converts and clones a valid date.

Signature

export function toDate(value: DateInput): Date;

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Required	Date, Unix millisecond timestamp, or runtime-parseable string.

Returns

Value	Type	Description
result	Date	New Date sharing no mutable state with the input.

isValidDate Validate

Checks whether an input can become a valid date.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
value	unknown	Required	Any value to check.

Returns

Value	Type	Description
result	value is DateInput	true 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

export function startOfDay(value: DateInput): Date;

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Required	Valid date input.

Returns

Value	Type	Description
result	Date	New 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

export function endOfDay(value: DateInput): Date;

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Required	Valid date input.

Returns

Value	Type	Description
result	Date	New end-of-day Date in the local time zone.

addDays Days

Adds integer local calendar days without mutating the input.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Required	Base date.
amount	number	Required	Safe integer number of days; may be negative.

Returns

Value	Type	Description
result	Date	New 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

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

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Required	Base date.
amount	number	Required	Safe integer number of months; may be negative.

Returns

Value	Type	Description
result	Date	New Date after month arithmetic.

addYears Years

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

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Required	Base date.
amount	number	Required	Safe integer number of years; may be negative.

Returns

Value	Type	Description
result	Date	New Date after year arithmetic.

isSameDay Compare

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

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
left	DateInput	Required	First date.
right	DateInput	Required	Second date.

Returns

Value	Type	Description
result	boolean	true when local year, month, and day match.

isFuture Future

Checks whether a time is later than the reference time.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Required	Time to compare.
now	DateInput	Optional; defaults to Date.now()	Reference time; defaults to the current time at invocation.

Returns

Value	Type	Description
result	boolean	true when value is strictly later than the reference.

getLocalDayBounds Bounds

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

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Optional; defaults to Date.now()	Reference date; defaults to the current date at invocation.

Returns

Value	Type	Description
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

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

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Required	Date to check.
start	DateInput	Required	Inclusive start.
end	DateInput	Required	Inclusive end.

Returns

Value	Type	Description
result	boolean	true when the timestamp lies in the closed interval.

formatRelativeTime Format

Creates readable relative-time text with Intl.RelativeTimeFormat.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
value	DateInput	Required	Target time.
options	RelativeTimeOptions	Optional; defaults to {}	Locale, style, and reference time.

Returns

Value	Type	Description
result	string	Localized text produced by Intl.RelativeTimeFormat.

formatChineseRelativeTime Format

Formats a date as fixed Chinese relative-time text.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
value	Date | number | string | null | undefined	Required	Date, timestamp, parseable string, or nullish value.

Returns

Value	Type	Description
result	string	Chinese 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

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

Example

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

const result = createOneMonthRangeFromToday(false);

Input

Input	Type	Required / default	Description
towardFuture	unknown	Optional; defaults to false	true selects today through one month later; otherwise one month earlier through today.

Returns

Value	Type	Description
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

export function isDateAfterNow(time: Date): boolean;

Example

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

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

Input

Input	Type	Required / default	Description
time	Date	Required	Date to compare.

Returns

Value	Type	Description
result	boolean	true when the timestamp is strictly later than Date.now().

getLocalTimeGreeting Greeting

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

Signature

export function getLocalTimeGreeting(): string;

Example

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

const result = getLocalTimeGreeting();

Input

This method has no input parameters.

Returns

Value	Type	Description
result	string	Chinese welcome text for the current time of day.

createDateRangeShortcuts Shortcuts

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

Signature

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

Example

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

const result = createDateRangeShortcuts(false);

Input

Input	Type	Required / default	Description
towardFuture	unknown	Optional; defaults to false	true creates future ranges; historical ranges by default.

Returns

Value	Type	Description
result	DateRangeShortcut[]	Range shortcuts that read the current time on every evaluation.

createDateShortcuts Shortcuts

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

Signature

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

Example

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

const result = createDateShortcuts(false);

Input

Input	Type	Required / default	Description
towardFuture	unknown	Optional; defaults to false	true creates future dates; historical dates by default.

Returns

Value	Type	Description
result	DateShortcut[]	Single-date shortcuts that read the current time on every evaluation.

getStartOfToday Start

Returns today's local midnight.

Signature

export function getStartOfToday(): Date;

Example

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

const result = getStartOfToday();

Input

This method has no input parameters.

Returns

Value	Type	Description
result	Date	New Date at 00:00:00.000.