helper-time-utils

Lightweight utilities for date parsing, countdown calculation, and Chinese-style time formatting.
轻量的时间工具包，适合做日期解析、倒计时计算和中文时间展示。

Features

• Safely parse string | number | Date inputs.

• Supports common iOS-safe date string normalization.

• Includes countdown text, countdown arrays, and day-hour-minute-second helpers.

• Includes Chinese display text such as 刚刚, 5分钟前, 今天12:30, and 明天09:00.

• Framework-agnostic and easy to publish as a standalone npm package.

• 安全解析 string | number | Date 输入。

• 兼容常见的 iOS 日期字符串解析问题。

• 提供倒计时文本、倒计时数组，以及天时分秒拆分能力。

• 提供 刚刚、5分钟前、今天12:30、明天09:00 这类中文展示格式。

• 无框架依赖，适合单独发布成 npm 包。

Install

npm install helper-time-utils

Usage

import {
  calculateTimeLeft,
  formatDate,
  formatTimeAgo,
  formatTimeDisplay,
  formatTimeRemaining,
  getCountdownDaysHMS,
  getTimeDiff,
  getTimeDiffArrayWithHours,
  isToday,
  parseSafeDate,
} from 'helper-time-utils';

parseSafeDate('2026-06-16 12:30:00');
formatDate('2026-06-16 12:30:00', 'YYYY/MM/DD HH:mm');
formatTimeAgo(Date.now() - 5 * 60 * 1000);
formatTimeDisplay(Date.now() + 2 * 60 * 60 * 1000);
formatTimeRemaining(Date.now() + 30 * 60 * 1000);
calculateTimeLeft(Date.now() + 90 * 1000);
getTimeDiffArrayWithHours(Date.now() + 5 * 60 * 60 * 1000);
getCountdownDaysHMS(Date.now() + 30 * 60 * 60 * 1000);
getTimeDiff(Date.now() + 90 * 1000);
isToday(new Date());

API

Parsing

Date parsing and validation helpers.
日期解析和校验相关方法。

• parseSafeDate(input) Safely parse input into a Date instance or return null. 安全地把输入解析成 Date，失败时返回 null。

• isValidDateInput(input) Check whether the input can be parsed into a valid date. 判断输入是否能被解析成合法日期。

Base Helpers

Core utilities for time difference and date formatting.
时间差计算和日期格式化的基础方法。

• getTimeDiff(input, { now? }) Returns a structured time difference object. 返回结构化的时间差对象。

• formatDate(input, template?) Formats a date using tokens like YYYY-MM-DD HH:mm:ss. 使用 YYYY-MM-DD HH:mm:ss 这类 token 模板格式化日期。

• isToday(input, { now? }) Checks whether the input falls on the same day as now. 判断输入时间是否和 now 是同一天。

• isTomorrow(input, { now? }) Checks whether the input is tomorrow relative to now. 判断输入时间是否是相对于 now 的明天。

• isYesterday(input, { now? }) Checks whether the input is yesterday relative to now. 判断输入时间是否是相对于 now 的昨天。

Countdown

Helpers for countdown display and breakdown.
倒计时展示和拆分相关方法。

• calculateTimeLeft(input, { now? }) Returns text like 2天3小时 or 15分08秒. 返回 2天3小时 或 15分08秒 这样的文本。

• getTimeDiffArray(input, { now? }) Returns [hours, minutes, seconds] capped at 24 hours. 返回 [小时, 分钟, 秒]，并在超过 24 小时时封顶。

• getTimeDiffArrayWithHours(input, { now? }) Returns [hours, minutes, seconds] without a 24-hour cap. 返回不封顶的 [小时, 分钟, 秒]。

• getCountdownDaysHMS(input, doubleNumDay?, { now? }) Returns either [day, hour, minute, second] or [hour, minute, second]. 返回 [天, 时, 分, 秒] 或 [时, 分, 秒]。

Display

Helpers for human-friendly Chinese time text.
面向中文场景的人类可读时间文本方法。

• formatTimeDisplay(input, { now? }) Returns text like 今天12:30, 明天09:00, or 2026-06-16 12:30. 返回 今天12:30、明天09:00 或 2026-06-16 12:30 这类文本。

• formatSecondsToHMS(seconds) Formats seconds into text like 1小时5分钟3秒. 把秒数格式化成 1小时5分钟3秒 这样的文本。

• formatTimeToChinese(input) Formats a date into text like 2026年6月16日 12:30. 把日期格式化成 2026年6月16日 12:30 这样的文本。

• formatTimeAgo(input, { now? }) Returns relative past text like 刚刚, 5分钟前, or 2天前. 返回 刚刚、5分钟前、2天前 这样的过去时间文本。

• formatTimeRemaining(input, { now? }) Returns future remaining text like 15分钟, 3小时, or 2天. 返回 15分钟、3小时、2天 这样的剩余时间文本。

Notes

• Numeric input is treated as a timestamp: 10 digits as seconds, 13 digits as milliseconds.

• Plain strings like 2026-06-16 12:30:00 are normalized when needed to improve iOS compatibility.

• Before publishing, consider changing the package name to your own npm scope, such as @your-scope/time-utils.

• 数字输入默认按时间戳处理：10 位按秒，13 位按毫秒。

• 类似 2026-06-16 12:30:00 的普通字符串会在需要时做兼容处理，以尽量避免 iOS 解析失败。

• 正式发布前，建议把包名改成你自己的 npm scope，比如 @your-scope/time-utils。