Tinytime ⏰

A straightforward date and time formatter in 770 bytes.

This fork

• Proper type definitions
• More correct code
• ESM-only
• Additional utilities

API

Tinytime exports a single function that returns a template object. This object has a single method, render, which takes a Date and returns a string with the rendered data.

import{tinytime}from'tinytime';consttemplate=tinytime('The time is {h}:{mm}:{ss}{a}.');template.render(newDate());// The time is 11:10:20PM.

Substitutions

• MMMM - Full Month (September)
• MM - Partial Month (Sep)
• Mo - Numeric Month (9) ^*
• YYYY - Full Year (1992)
• YY - Partial Year (92)
• dddd - Day of the Week (Monday)
• DD - Day of the Month (24) ^*
• Do - Day (24th)
• h - Hours - 12h format ^*
• H - Hours - 24h format ^*
• mm - Minutes (zero padded)
• ss - Seconds (zero padded)
• a - AM/PM

Note

^* you can pad them with zeroes (09 instead of 9) by passing in the padMonths, padDays, padHours option.

consttemplate=tinytime('{Mo}',{padMonth: true})

Utils

Tinytime now comes with two utility functions exported from tinytime/utils

Date parsing

The parseExact(string, string) function can be used to easily parse a date string according to a specified format.

import{parseExact}from"tinytime/parseExact";constdate=parseExact("05 21 1997 (at 06:37:00 PM)","MM dd yyyy (at hh:mm:ss aa)");console.assert(date===newDate("1997-05-21T18:37:00Z"));// assertion passes

The format tokens are as follows:

• y - year
• M - month
• d - date
• h - hours
• m - minutes
• s - seconds
• i - milliseconds
• a - AM/PM

Date manipulation

The addToDate(Date, DateDelta) function can be used to add a desired delta to a given date.

import{addToDate}from"tinytime/addToDate"constnow=Date.now();// 2025-05-17T15:08:00.000Zconstfuture=addToDate(now,{days: 3,years: 100,hours: 761});future.toISOString();// 2125-06-21T08:08:00.000Z

The DateDelta is defined as follows:

interfaceDateDelta{years?: number;months?: number;days?: number;hours?: number;minutes?: number;seconds?: number;milliseconds?: number;}

Efficiency

Tinytime takes an approach similar to a compiler and generates an AST representing your template. This AST is generated when you call the main tinytime function. This lets you efficiently re-render your template without Tinytime having to parse the template string again. That means it's important that you aren't recreating the template object frequently.

Here's an example showing the right and wrong way to use tinytime with React.

Don't do this:

functionTime({ date }){return(<div>{tinytime('{h}:{mm}:{ss}{a}').render(date)}</div>)}

Instead, only create the template object once and re-render it.

consttemplate=tinytime('{h}:{mm}:{ss}{a}');functionTime({ date }){return(<div>{template.render(date)}</div>)}

Current bundle size

dist\addToDate.js 402 bytes
dist\addToDate.js 246 bytes (GZIP)
dist\addToDate.js 228 bytes (DEFLATE)
dist\addToDate.min.js 270 bytes
dist\addToDate.min.js 195 bytes (GZIP)
dist\addToDate.min.js 177 bytes (DEFLATE)
dist\parseExact.js 1083 bytes
dist\parseExact.js 563 bytes (GZIP)
dist\parseExact.js 545 bytes (DEFLATE)
dist\parseExact.min.js 636 bytes
dist\parseExact.min.js 450 bytes (GZIP)
dist\parseExact.min.js 432 bytes (DEFLATE)
dist\tinytime.js 3674 bytes
dist\tinytime.js 1252 bytes (GZIP)
dist\tinytime.js 1234 bytes (DEFLATE)
dist\tinytime.min.js 1278 bytes
dist\tinytime.min.js 771 bytes (GZIP)
dist\tinytime.min.js 753 bytes (DEFLATE)

Babel Plugins

Using one of the plugins below, you can resolve this efficiency concern at compile time.

babel-plugin-transform-tinytime - Hoists tinytime calls out of the JSX render scope.

babel-plugin-tinytime - Hoists tinytime calls out of the current scope, regardless if its inside JSX or an ordinary function scope.