clock-reader

clock-reader

A modern way to stringlify time. It's fast, flexible, no ambiguity in template, and easy to use.

Installation

npm i clock-reader

Usage

Use Dynamic Template

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))   // 2024-10-25T00:09:23.929+08
console.log(en(now))    // Thursday Oct 24, 2024, 16:09:23
console.log(cn(now))    // 二〇二四年十月二十五日 零时九分二十三秒 星期五

Use Simple Function

import { YYYY, MM, DD } from 'clock-reader'

const originDate = new Date(0)
// 1970 01 01
console.log(YYYY(originDate), MM(originDate), DD(originDate))

Stringlify TimeZone

import { sz, szzzz, iso8601_Shortest } from 'clock-reader'

console.log(sz(0), sz(+8))          // +0 +8
console.log(szzzz(0), szzzz(+8))    // +0000 +0800
console.log(iso8601_Shortest(0))    // Z
console.log(iso8601_Shortest(+8))   // +08
console.log(iso8601_Shortest(-7.5)) // -0730

API

compile

(clockReader: DynTemplate<ClockPart>, timeZone?: number) => (time: Date | number) => string

Compile a clock reader template into a function which can stringlify time. The timeZone is in hours. If you don't provide the timeZone, it will be the local time zone offset.

clockReader

Make a dynamic clock reader template. See more at dyn-template.
You can use all the functions below as template parts, or write your own formatters.

Attention: When use these functions below in clockReader template, they always use the timezone offset provided by compile. When use all these functions below singly, they always ignore the timezone offset. That means the result is always in UTC+0. If you want to deal with the time not in UTC+0, you should use compile with a specific timezone offset or use compile with no timezone provided meaning the local time zone.

Functions: (time: Date) => number

• Y: year
• M: month, 1-12
• D: day
• h: hour
• m: minute
• s: second
• ms: millisecond
• w: week, 0-6

Functions: (time: Date) => string

• YYYY: 4-digit year
• YY: 2-digit year
• MM: 2-digit month
• DD: 2-digit day
• hh: 2-digit hour
• mm: 2-digit minute
• ss: 2-digit second
• mss: 3-digit millisecond
• Y_M_D: YYYY-MM-DD
• h_m_s: hh:mm:ss

Specific for English:

• M_EN: Jan, Feb, ..., Dec
• M_EN_Full: January, February, ..., December
• D_M_Y_EN: DD M_EN YYYY
• M_D_Y_EN: M_EN DD, YYYY
• week_EN: Sun, Mon, ..., Sat
• week_EN_Full: Sunday, Monday, ..., Saturday

Specific for Chinese:

• Y_CN: 汉字年份，如：二〇二四
• M_CN: 一，二，...，十二
• M_CN_CC: 同上，但一月返回正，十二月返回腊
• D_CN: 一，二，...，三十一
• h_CN: 零，一，二，...，二十三
• m_CN: 零，一，二，...，五十九
• s_CN: 零，一，二，...，五十九
• ms_CN: 零，一，二，...，九百九十九
• Y_M_D_CN: YYYY年MM月DD日
• h_m_s_CN: hh时mm分ss秒
• week_CN: 日, 一, 二, 三, 四, 五, 六
• week_CN_Full: 星期日, 星期一, 星期二, 星期三, 星期四, 星期五, 星期六

Timezone

Attention: These functions and Timezone Stringlify functions are not related to a time value. You should call them directly to stringlify time zone but not use them as template parts functions directly in clockReader template.

• localZ(): get the local time zone offset in hours
• parseZ(timeZone?: number): parse a time zone into { sign: '+' | '-', zHour: number, zMinute: number }. The timeZone is in hours. If you don't provide the input, it will be the local time zone offset.

Timezone Stringlify: (timeZone?: number) => string

The input is in hours, like +0, +8, -7.5, etc. If you don't provide the input, it will be the local time zone offset.

• sz: 1-digit, like +0, +8, -7
• szz: 2-digit, like +00, +08, -07
• szzzz: 4-digit, like +0000, +0800, -0730
• szz_zz: 5-digit with colon, like +00:00, +08:00, -07:30
• iso8601_Shortest: shortest in iso8601 format, like Z, +08, -0730

zZeroOrNot(whenIsZero: string, whenNot: (z?: number) => string):
return a Timezone Stringlify function, when input is 0, return whenIsZero, otherwise whenNot(z).

zIntOrNot(whenIsInt: (z?: number) => string, whenNot: (z?: number) => string):
return a Timezone Stringlify function, when input is an integer, return whenIsInt(z), otherwise whenNot(z).

So actually you can use zZeroOrNot and zIntOrNot to customize your own timezone stringlify function. The iso8601_Shortest is a example. It is zZeroOrNot('Z', zIntOrNot(szz, szzzz)).