Temporal API Cheatsheet: Quick Guide to new JS API
Tags: javascript, webdev
Published: 2022-05-16 16:13:32

---
title: "Temporal API Cheatsheet: Quick Guide to new JS API"
published: "true"
description: "Temporal API Cheatsheet: a quick guide to new JavaScript Temporal API including code snippets and example use cases."
tags: "javascript, webdev"
canonical_url: "https://rodneylab.com/temporal-api-cheatsheet/"
cover_image: "https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3bkdt6d32hbnup007cwr.png"
---

## 🕚 Temporal API

The Temporal API Cheatsheet is a quick reference guide to help you when getting started with the API.  It is a **learn in public** project, where I have been adding methods I have discovered and found useful, rather than in-depth documentation on the Temporal API.  That said, the cheatsheet includes **links to the official documentation** for each method, for when you need a closer look.  The Temporal API itself is a new API which attempts to **address some of the shortcomings of the existing JavaScript Date** methods.  In this post we first take a look at this motivation for the Temporal API.  We then see the cheatsheet site and how you can use it.

The Temporal API is still a proposal and so not recommended for production use.  However, hopefully this post and the cheatsheet will help you try it out on your side projects. If that&rsquo;s something you will find useful, read on.

## 🤷🏽 Why do we need the Temporal API?

JavaScript already has a <a aria-label="Open M D N docs on Javs Script Date object" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date">Date object</a> and methods.  You can get the current date thus:

```javascript
const now = new Date();
```

Then there are methods to get and set the day, hour and so on for the the new date:

```javascript
const hour = now.getHours();

let newYearsDay = new Date();
newYearsDay.setFullYear(2023);
newYearsDay.setMonth(0);
newYearsDay.setDate(31);
```

You can set that date in a single step: `date.setFullYear(2023,0,31)`.  Manipulation is another story though.  Let&rsquo;s say you want an account to expire **at 23:59 a month from today**.  You can work out that date and time using these methods but it is messy and there are edge cases you need to watch out and test for.  The new Temporal API does the heavy lifting here and on top has ergonomic syntax:

```javascript
const result = Temporal.Now.plainDateTimeISO()
  .add({ months: 1 })
  .with({ hour: 23, minute: 59, second: 0 });
```

On top the API has methods which make working with time zones easier.

## 🐘 Temporal API Cheatsheet


![Temporal API Cheatsheet: Site: screenshot show close-up on polyfill section of the site and includes details of how to install and import the polyfill for the Temporal A P I](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8o1q2tirw29zdznf6jvd.png)

The idea of the Temporal API Cheatsheet was to keep a **quick reference** list of methods I found useful.  For more complex cases I would refer to the official docs.  As I discover more methods I will add to it.  In fact, it is an open-sourced <a aria-label="Open Astro posts" href="https://rodneylab.com/tags/astro/">Astro site</a>, so <a aria-label="Open a pull request on the Temporal API Cheatsheet" href="https://github.com/rodneylab/temporal-api-cheatsheet/pulls">you can add to it yourself</a>.

The temporal API is not net integrated into ECMA Script so you need to add a polyfill package to you project to use it.  TC39 give a couple of choices:

- <a href="https://www.npmjs.com/package/@js-temporal/polyfill">@js-temporal/polyfill</a>,
- <a href="https://www.npmjs.com/package/temporal-polyfill">temporal-polyfill</a>.

I tried the first one and have had no issues so included that in the cheatsheet. You just install it in your project like any other package and import it into you source JavaScript or TypeScript files.

Take a look at the <a aria-label="Open the temporal A P I cheatsheet" href="https://temporal-api-cheatsheet.rodneylab.com/">Temporal API Cheatsheet site</a> and try it out when you have a moment!

## 🙌🏽 Temporal API Cheatsheet: Wrapping Up

We have had an introduction to the Temporal API and the cheatsheet.  In particular, we saw:

- why the  **Temporal API exists**,
- how you can **start using the Temporal API** in projects and contribute to the cheatsheet,
- that the API is still a proposal and **not recommended for production** usage.

Open up the Temporal API cheatsheet to get start or <a aria-label="Open the Temporal A P I cheatsheet in the Rodney Lab Git Hub Repo" href="https://github.com/rodneylab/temporal-api-cheatsheet">contribute to the repo on GitHub</a>.  You can also <a aria-label="Open the Astro blog Markdown starter in Stack Blitz" href="https://stackblitz.com/github/rodneylab/temporal-api-cheatsheet">open the project up in Stackblitz</a>.

I hope you found this article useful and am keen to hear how you will the starter on your own projects as well as possible improvements.

## 🙏🏽 Temporal API Cheatsheet: Feedback

Have you found the post useful? Would you prefer to see posts on another topic instead? Get in touch with ideas for new posts. Also if you like my writing style, get in touch if I can write some posts for your company site on a consultancy basis. Read on to find ways to get in touch, further below. If you want to support posts similar to this one and can spare a few dollars, euros or pounds, please <a aria-label="Support Rodney Lab via Buy me a Coffee" href="https://rodneylab.com/giving/">consider supporting me through Buy me a Coffee</a>.

Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via <a aria-label="Reach out on Twitter" href="https://twitter.com/messages/compose?recipient_id=1323579817258831875">@askRodney</a> on Twitter and also <a aria-label="Contact Rodney Lab via Telegram" href="https://t.me/askRodney">askRodney on Telegram</a>. Also, see <a aria-label="Get in touch with Rodney Lab" href="https://rodneylab.com/contact">further ways to get in touch with Rodney Lab</a>. I post regularly on <a aria-label="See posts on Astro" href="https://rodneylab.com/tags/astro/">Astro</a> as well as <a aria-label="See posts on svelte kit" href="https://rodneylab.com/tags/sveltekit/">SvelteKit</a>. Also <a aria-label="Subscribe to the Rodney Lab newsletter" href="https://rodneylab.com/about/#newsletter">subscribe to the newsletter to keep up-to-date</a> with our latest projects.