aweary / tinytime

⏰ A straightforward date and time formatter in <1kb

Tinytime ⏰

A straightforward date and time formatter in <800b.

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';
const template = tinytime('The time is {h}:{mm}:{ss}{a}.');
template.render(new Date());
// 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

¹ - you get padded months (09 instead of 9) by passing in the padMonth option.

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

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 its 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:

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

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

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

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 a ordinary function scope.

tinytime's Issues

TypeScript Support ?

Maybe need a definition file index.d.ts

Typo in description

Hey

Just wanted to let you know that the description says "time and time formatter" instead of "date and time formatter"

Feature request: Parsing time

Is there scope for something for parsing time passed as a string?
Something like

// TinyTime.parse :: String -> Date
tinytime('{H}:{mm}:{ss}').parse('13:43:28');

If yes, can I work on it?

Feature request: zero-padded month

A typical way to format dates in germany uses a zero-padded month.
Today, for example, is 23.04.2017.
Zero-padded month would be a welcome addition!

Dynamic page loading failed

When including tinytime in my webpack project, I'm given this runtime error (happens on import)

Feature request: fromNow() Relative Time

Would you consider adding a Relative Time feature such as moment's fromNow()?

The B.C. is not supported

const date = new Date();
date.setFullYear(-100);

Localization

Have you considered localization? My use case would be just to replace https://github.com/aweary/tinytime/blob/master/src/compiler.js#L29 and https://github.com/aweary/tinytime/blob/master/src/compiler.js#L44 with days/months in norwegian.

Basically just injecting two arrays to keep the code tiny.

Dates are being rendered one day behind

I'm not sure what's going on or if anyone else is having a similar issue but dates are being formatted one day behind.

const template = tinytime('{MMMM} {Do}');

const aprilTwentyNinth = new Date("2017-04-29");
const aprilThirtieth = new Date("2017-04-30");
const mayFirst = new Date("2017-05-01");

console.log(template.render(aprilTwentyNinth)); // renders April 28th
console.log(template.render(aprilThirtieth)); // renders April 29th
console.log(template.render(mayFirst)); // renders April 30th

What's LICENSE?