Dates and Timestamps serialization

ISO strings are the better choice

When interacting with Callable Functions, it's best to represent dates as ISO strings. The value and the type stay consistent when sending and receiving on the client and on Cloud functions.

In this article, we explain what happens when we send Date and Timestamp objects to Callable Functions or when we receive them from Callable Functions. Before being sent, both Date and Timestamp are serialized to JSON.

sending Date and Timestamp to Callable Functions (do not use)

Timestamp is a Firestore specific type and doesn't get a special treatment: it serializes to an object with seconds and nanoseconds (through toJSON()).

// on the Cloud function receiving end
type T = { seconds: number; nanoseconds: number }

Date fields serialize to an ISO string (through toJSON()):

date: "2023-10-08T07:54:47.527Z"

When receiving in Cloud functions, we have a type difference between RequestData on the client and RequestData in Cloud functions.

We could manually instantiate Timestamp or Date instances, but it requires manual processing:

new Date(date) // build a Date
new Timestamp(timestamp.seconds, timestamp.nanoseconds) // build a Timestamp

returning data from Callable functions

If we attempt to return a Date object, it serializes to an ISO string as well, through the same mechanism.

If we attempt to return a Timestamp object, it serializes to the internal representation specific to the admin SDK, which is different than the client SDK's Timestamp representation:

possible an object with _seconds and _nanoseconds. We should avoid this pattern:

// on the client SDK receiving end
type T = { _seconds: number; _nanoseconds: number }