🕚 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’s something you will find useful, read on.
🤷🏽 Why do we need the Temporal API?
JavaScript already has a Date object and methods. You can get the current date thus:
const now = new Date();
Then there are methods to get and set the day, hour and so on for the the new date:
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’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:
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
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 Astro site, so you can add to it yourself.
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:
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 Temporal API Cheatsheet site 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 contribute to the repo on GitHub. You can also open the project up in Stackblitz.
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 consider supporting me through Buy me a Coffee.
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 @askRodney on Twitter and also askRodney on Telegram. Also, see further ways to get in touch with Rodney Lab. I post regularly on Astro as well as SvelteKit. Also subscribe to the newsletter to keep up-to-date with our latest projects.
Top comments (1)
So without giving a try just yet, there's 1 thing that I'm really interested but I could find any info anywhere (neither in your article). How do we format dates with Temporal? That was easy to do with MomentJS with the
format()function (or Moment 2nd argument), it would be helpful if you could add a section detailing this. For examplemoment().format('YYYY-MM-DD hh:mm:ss a').My project is allowing the user to use multiple formats and I'm wondering if I will need to create a parser or if Temporal already has a built-in formatter? Thanks for the great article