john-titor v0.0.3

John Titor

John Titor is a zero-dependency JavaScript library for handling date-time string formatting the PHP way. Named after time traveler TimeTravel_0, it has been designed to both make date string formatting easier in-general as well as make PHP developers feel more at-home in the JavaScript ecosystem.

Installation

This library can be installed via npm:

npm install john-titor

Once installed it can be used in your project via either ESM or CJS as-needed:

import titor from 'john-titor';

// OR

const titor = require('john-titor');

If you'd like to include this in a web page, you can download the source code here. Heck, in-a-pinch, you would be able to load it into your page with the following to start experimenting with it:

<!-- John Titor date formatter: -->
<script src="https://raw.githubusercontent.com/WarrenUhrich/john-titor/main/lib/titor.js"></script>

How to use John Titor

This library comes with a function called titor.

Parameters:

• format: a string containing special characters from the legend found below
• (optional) date: a JavaScript Date object that you'd like to format as a string—if no date is provided, it will use the present date and time instead

Return:

• string: the provided date as a formatted string

Example Usage

// By default it will format the current time:

const currentYear  = titor('Y');       // '2000'
const shortYear    = titor('y');       // '00'

const americanDate = titor('m/d/Y');   // '11/02/2000'
const betterDate   = titor('Y-m-d');   // '2000-11-02'

const wordDate     = titor('F jS, Y'); // 'November 2nd, 2000'

const dayAndTime   = titor('l g:i a'); // 'Thursday 3:04 am'

// If you'd like, you can pass in a specific time to format:

const date = new Date('2036-03-14 16:05'); // Date to try out!

const americanizeDate = titor('m/d/Y',             date); // '03/14/2036'
const unixTimestamp   = titor('U',                 date); // '2089145100'
const bigDateTime     = titor('l F jS, Y @ g:i A', date); // 'Friday March 14th, 2036 @ 4:05 PM'

// You can include words, phrases, and more in the output;
// be mindful that you escape any letters that overlap
// this library's legend characters! Use a backslash: \

const formattedOutput = titor(String.raw`

\H\e\l\l\o, \W\o\r\l\d!
=============

\D\a\t\e \I\n\f\o:
----------

\D\a\y:   l
\M\o\n\t\h: F
\Y\e\a\r:  Y
\U\n\ix:  U

`, date);

// formattedOutput would contain the following (sans comments):
/*


Hello, World!
=============

Date Info:
----------

Day:   Friday
Month: March
Year:  2036
Unix:  2089145100


*/

Quick Legend

Year

• Y: four-digit year number
• y: two-digit year number
• L: 1 if a leap year, 0 if not

Month

• m: month number (with leading zero)
• n: month number (without leading zero)
• F: full textual name of the month
• M: three-letter textual name of month
• t: number of days in the month

Day

• d: day of month (with leading zero)
• j: day of month (without leading zero)
• l: full textual day of the week
• D: three-letter textual day of the week

Hour

• h: 12-hour clock hour (with leading zero)
• g: 12-hour clock hour (without leading zero)
• a: lower-case am or pm
• A: upper-case AM or PM
• H: 24-hour clock hour (with leading zero)
• G: 24-hour clock hour (without leading zero)
• I: 1 if in daylight savings time, 0 if not

Minute

• i: minutes (with leading zero)

Second

• s: seconds (with leading zero)
• u: microseconds
• U: number of seconds since the Unix Epoch

Complete Legend

Incomplete Features

There are thirty-seven (37) internal methods required to match the formatting features supplied by PHP. Some features have not yet reached parity with its PHP counterpart:

• ❌ e
• ❌ O
• ❌ P
• ❌ T
• ❌ Z
• ❌ c
• ❌ r

Most of the above provide some reasonable output in the mean-time, but these will require more work to better handle timezone cases as well as behave more 1:1 with PHP date formatting.

Author

My name is Warren Uhrich! I'm a human person; instructor; and world wide web developer from Canada. Despite its potentially confusing syntax, I've always enjoyed the flexibility of PHP's date formatting. The ability to prepare a simple template out of a set of characters is powerful!

My goal when building john-titor was to develop a zero-dependancy library that is easy to use and brings the aforementioned power to JavaScript. Wield it wisely!