Firestore Timestamp: A Simple Guide To Deal With Date and Time (2022)

Dealing with dates, time, and timezones is one of the most painful experiences a developer can have: you need to take into account the user's timezone, daylight saving times, different encodings, datetime validation, misconfigured local times… and don't get me started on aggregating datetime data!

A backend solution like Google Firestore is a game-changer in this regard because it provides built-in best practices out of the box. In this article, we will cover everything you need to know to avoid complications with your timestamps down the road.

What’s a timestamp and why you need to use one

A timestamp is an encoded representation of a datetime object as an integer: the number of milliseconds since January the 1st, 1970, 12:00 PM UTC .

When you want to have a datetime in Javascript, you write the following:

const new_date = new Date()
// returns a date object

The best way to represent this information to store it in a database is using a timestamp, an integer:

new_date.getTime()
// returns a timestamp, e.g 1669386691734

As we already mentioned, timestamps represent the most efficient way to store datetime data. They are just integers so they take less space than text and you don’t need to parse or serialize them. Time is complex, so we might as well not make it more complicated.

How to configure timestamps for Firestore

1. Modifying a timestamp field in a document

If you want to set the property value of a given document to a timestamp, you’ll need to use the serverTimestamp helper function:

import { serverTimestamp } from 'firebase/firestore'

const updated_at_timestamp = serverTimestamp()
docRef.update({ updated_at: updated_at_timestamp })

A Firebase CMS like Rowy automatically appends and updates createdAt and updatedAt fields:

Untitled

2. Comparing timestamps

Whenever you encounter a use case when you need to compare two timestamps in your application, you can use the Timestamp.fromDate() function to convert a native Date object in Javascript to Firestore’s Timestamp object. Firestore’s timestamps use nanosecond precision, whereas Javascript datetimes use millisecond precision:

import { Timestamp } from 'firebase/firestore'

const current_timestamp = Timestamp.fromDate(new Date())

if(!my_data.updated_at.isEqual(current_timestamp)){ ... }

Since timestamps are integers, you can also simply use them in your where and orderBy clauses to perform comparisons inside database queries:

const res = await collection(firestore, "blog").orderBy('updated_at').get()

3. Dealing with timezones

import { getAuth, updateProfile } from "firebase/auth";
const auth = getAuth();

const user_timezone = "America/Los_Angeles"

updateProfile(auth.currentUser, {
  timezone: user_timezone
})

Assuming your user’s timezone based on browser data is often a bad practice―many users rely on firewalls and proxies to hide their location. Instead, offer the ability for users to define their timezone data themselves.

When you need to display a timestamp in the local timezone using Javascript, you can simply write:

const timezoned_date = new Date().toLocaleString('en', {
  timeZone: auth.currentUser.timezone
})

4. Timestamp processing using Rowy's derivative columns

With Rowy, you can use derivative columns to run scripts based on sibling columns. Say you are building a gardening app and you are measuring how many days it takes for a plant to grow. You can send a first request to register a start time, and a second request to register when the plant has fully matured. You can program a derivative column maturation to automatically calculate the time difference between the two points to get a duration:

const derivative:Derivative = async ({row, ref, db, storage, auth})=> {
        const beg_timestamp = row.begAt.toDate().getTime()
        const end_timestamp = row.endAt.toDate().getTime()
        const milliseconds_per_day = 1000 * 60 * 60 * 24

        const difference_in_days = (end_timestamp -  beg_timestamp) / milliseconds_per_day
    return difference_in_days
}

Subscribe to Rowy

That’s the bare minimum you need to know to deal with timestamp in Firestore! Hope you found it useful. Before you leave, do give Rowy a try. It only takes a few minutes to get started, and it’s completely free and open-source.

Share this post