clock-reader
English | 中文
A lightweight, concise, unambiguous, high-performance, and extremely flexible next-generation time formatting tool.
Why clock-reader
Time formatting is a common requirement. Currently popular libraries include: moment.js, dayjs, date-fns.
Compared to these libraries, clock-reader uses JavaScript's native Date object and template literal syntax, with the following advantages:
- Small size: compressed size less than 3KB
- Concise and unambiguous: no need to learn complex template and escape syntax, directly use JavaScript's template literals
- Fast: about 4 times faster than
moment.js
and 10 times faster than date-fns
. Test it here - Flexible: functional design, easy to implement and use custom components
Installation
npm i clock-reader
Usage
Using templates
import {
compile, clockReader,
y_m_d, h_m_s, mss, iso8601_Shortest,
week_en_full, m_d_y_en,
y_m_d_cn, h_m_s_cn, week_cn_full,
} from 'clock-reader'
const iso = compile(clockReader`${y_m_d}T${h_m_s}.${mss}${iso8601_Shortest()}`)
const en = compile(clockReader`${week_en_full} ${m_d_y_en}, ${h_m_s}`, +0)
const cn = compile(clockReader`${y_m_d_cn} ${h_m_s_cn} ${week_cn_full}`, +8)
const now = Date.now()
console.log(iso(now))
console.log(en(now))
console.log(cn(now))
Basic Components
import {
y_m_d, m_d, h_m_s, h_m,
yyyy, mo, dd, hh, mm, ss, mss, hh12, yy,
year, month, date, hour, minute, sec, msec, hour12, week,
isAM,
} from 'clock-reader'
const o = new Date('1970-01-02T03:04:05.006Z')
console.log(y_m_d(o), m_d(o), h_m_s(o), h_m(o))
console.log(yyyy(o), mo(o), dd(o), hh(o), mm(o), ss(o), mss(o), hh12(o), yy(o))
console.log(year(o), month(o), date(o), hour(o), minute(o), sec(o), msec(o), hour12(o), week(o))
console.log(isAM(o))
English Components
import {
month_en, month_en_full,
m_d_y_en,
d_m_y_en,
week_en, week_en_full, am_pm_en
} from 'clock-reader'
const o = new Date('1970-01-02T03:04:05.006Z')
console.log(month_en(o), month_en_full(o))
console.log(m_d_y_en(o))
console.log(d_m_y_en(o))
console.log(week_en(o), week_en_full(o), am_pm_en(o))
Chinese Components
import {
year_cn, month_cn, date_cn,
month_cn_cc,
hour_cn, hour12_cn, minute_cn, sec_cn, msec_cn,
y_m_d_cn, h_m_s_cn,
week_cn, am_pm_cn,
} from 'clock-reader'
const o = new Date('1970-01-02T03:04:05.006Z')
console.log(year_cn(o), month_cn(o), date_cn(o))
console.log(month_cn_cc(o))
console.log(hour_cn(o), hour12_cn(o), minute_cn(o), sec_cn(o), msec_cn(o))
console.log(y_m_d_cn(o), h_m_s_cn(o))
console.log(week_cn(o), am_pm_cn(o))
Custom Components
Any function that takes a Date object as a parameter and returns a value convertible to string can be passed as a component into the template. Custom components should use methods with 'UTC' when processing Date objects, rather than methods related to the local timezone and no need to worry about the timezone.
import { compile, clockReader, y_m_d, month_en_full } from 'clock-reader'
function weekday_weekend(date) {
const day = date.getUTCDay()
return day === 0 || day === 6 ? 'weekend' : 'weekday'
}
function early_mid_late(date) {
const d = date.getUTCDate()
return d < 11 ? 'early ' : d < 21 ? 'mid-' : 'late '
}
const formatter =
compile(clockReader`${y_m_d} is a ${weekday_weekend} in ${early_mid_late}${month_en_full}.`)
console.log(formatter(new Date(2024, 9, 19)))
console.log(formatter(new Date(0)))
Timezone
import {
localZ,
parseZ,
sz, szzzz, szz_zz,
iso8601_Shortest,
zZeroOrNot, zIntOrNot
} from 'clock-reader'
console.log(localZ())
console.log(parseZ(-7.5))
console.log(sz(0), sz(+8), sz(-7.5))
console.log(szzzz(0), szzzz(+8), szzzz(-7.5))
console.log(iso8601_Shortest(0), iso8601_Shortest(+8), iso8601_Shortest(-7.5))
const fn1 = zZeroOrNot('Z', szzzz)
const fn2 = zIntOrNot(szz, szz_zz)
Attention
- When using dynamic templates, the timezone will always be the one given when compiling the template. If no timezone parameter is given when compiling the template, the local timezone is used by default.
import { compile, clockReader, hh } from 'clock-reader'
const h12 = 12 * 60 * 60 * 1000
console.log(compile(clockReader`${hh}`, 0)(h12))
console.log(compile(clockReader`${hh}`, +8)(h12))
console.log(compile(clockReader`${hh}`)(h12))
- When using components individually, components always ignore timezones. Regardless of the local timezone or the timezone of the Date object itself, components always process time according to UTC+0. Therefore, use dynamic templates when need to process time according to a specific timezone or local timezone.
import { compile, clockReader, hh } from '.'
const t = new Date('1970-01-01T12:00:00+0800')
console.log(hh(t))
console.log(compile(clockReader`${hh}`, +8)(t))
console.log(compile(clockReader`${hh}`)(t))
- Dynamic templates do not consider the timezone of the Date object itself. If timezone-related content is included in the template, the function should be called rather than directly passing the function.
import { compile, clockReader, szzzz } from 'clock-reader'
const tz = +8
console.log(compile(clockReader`Given timezone: ${szzzz(tz)}, Local timezone: ${szzzz()}`, tz)(0))