time

@tiny-libs/time

Tiny date/time formatting library. Inspired by Day.js and Moment.js.

Features

• No chaining
• Only practical APIs
• Minimal and fast
• Support Node.js and browser
• ESM support

Install

npm i @tiny-libs/time

Usage

import time from '@tiny-libs/time'

time.format(new Date(), 'YYYY/MM/DD HH:mm')

APIs

format

Format date/time.

• Type Signature:

  function format(date: Date, formatStr?: string): string

• Example Usage:

  time.format(new Date(2024, 3, 19), 'YYYY-MM-DD') // 2024-03-19

  List of formats

  Format	Output	Description
  YY	24	Two-digit year
  YYYY	2024	Four-digit year
  M	1-12	The month, beginning at 1
  MM	01-12	The month, 2-digits
  MMM	Jan-Dec	The abbreviated month name
  MMMM	January-December	The full month name
  D	1-31	The day of the month
  DD	01-31	The day of the month, 2-digits
  d	0-6	The day of the week, with Sunday as 0
  dd	Su-Sa	The min name of the day of the week
  ddd	Sun-Sat	The short name of the day of the week
  dddd	Sunday-Saturday	The name of the day of the week
  H	0-23	The hour
  HH	00-23	The hour, 2-digits
  h	1-12	The hour, 12-hour clock
  hh	01-12	The hour, 12-hour clock, 2-digits
  m	0-59	The minute
  mm	00-59	The minute, 2-digits
  s	0-59	The second
  ss	00-59	The second, 2-digits
  SSS	000-999	The millisecond, 3-digits
  Z	+05:00	The offset from UTC, ±HH:mm
  ZZ	+0500	The offset from UTC, ±HHmm
  A	AM PM
  a	am pm

add

Clone a date object with a specified amount of time added.

• Type Signature:

  function add(date: Date, num: number, unit: TimeUnit): Date

  Time Unit: second, minute, hour, day, week, month, year

• Example Usage:

  time.add(new Date(), -1, 'day')

startOf

Clone a date object and set it to the start of the time unit.

• Type Signature:

  function startOf(date: Date, unit?: TimeUnit): Date

• Example Usage:

  time.startOf(new Date(), 'day')

endOf

Clone a date object and set it to the end of the time unit.

• Type Signature:

  function endOf(date: Date, unit?: TimeUnit): Date

• Example Usage:

  time.endOf(new Date(), 'day')

isSame

Compares two dates for equality in specified exact units.

• Type Signature:

  function isSame(date1: Date, date2: Date, unit?: TimeUnit): boolean

• Example Usage:

  const date = time.add(new Date(), -1, 'minute')
  
  time.isSame(date, new Date(), 'hour') // true

clone

Clone for specified date object.

• Type Signature:

  function clone(date: Date | number): Date

from

Returns the string of relative time from now.

• Type Signature:

  function fromNow(date: number | Date, withoutAffix?: boolean, allowNow?: boolean): string

• Example Usage:

  const d1 = time.add(new Date(), -1, 'minute')
  const d2 = time.add(new Date(), 1, 'hour')
  
  time.fromNow(d1) // 1 minute ago
  time.fromNow(d2) // in 1 hour

  The base strings are localized by the current locale and can be customized with the relativeTime locale object.

socialize

Returns the social style date/time string of relative time from now.

• Type Signature:

  function socialize(date: Date | number, displayHourMinute?: boolean): string

• Example Usage:

  const d1 = new Date()
  const d2 = time.add(new Date(), 1, 'day')
  const d3 = time.add(new Date(), 2, 'day')
  
  time.socialize(d1) // 22:00
  time.socialize(d2) // Yesterday
  time.socialize(d3) // Monday 22:00

  Range	Key	Sample Output
  Today	LT	22:00
  Yesterday	Yesterday | Yesterday LT	Yesterday 22:00
  From this week to the day before yesterday	LW | LWT	wed 22:00
  This year	LDM | LDMT	11/12 22:00
  Before this year	LDMY | LDMYT	11/12/2024 22:00

  These strings are localized, and can be customized with the formats locale object.

I18n

Built-in en-US and zh-CN locales. You can customize the locale by following other locale object templates.

import time from '@tiny-libs/time'
import zh from '@tiny-libs/time/zh'

time.locale('zh-CN', zh)

License

MIT copyright © 2024-present alex wei