Best practice for parsing multiple possible formats, like Date or ISO?

[patdx]

May I get some advice on how to parse dates that might come in one of several formats?

I tried searching but having trouble to find any advice or documentation about this case. Please let me know if I missed something or if it has already been asked.

There are two cases I have run across where I feel this is a little awkward in Luxon:

Case 1: Hybrid Node.js and Browser app (for example, using Next.js)

I run into an issue where a function could be getting Date or ISO string. For example, I have a User object that comes from the Node.js database adapter like this:

interface User {
  name: string;
  expiresAt: Date;
}

Sometimes this user object is served to the frontend as a serialized JSON blob.

As is well known, Date is serialized into an ISO string: console.log(JSON.stringify(new Date())); // "2022-03-01T02:53:42.510Z"

interface UserBrowser {
  name: string;
  /** ISO date string */
  expiresAt: string;
}

I want to write a function that checks if the user account is expired, but I also want it to be portable. In other words, the function does not know if it will run in the browser or server so I write something like:

// my version
function isExpired(expiredAt: string | Date): boolean {
  const dateTime =
    typeof time === 'string'
      ? DateTime.fromISO(time)
      : DateTime.fromJSDate(time);

  return DateTime.now() >= dateTime;
}

I feel like the my parsing strategy is little bit awkward, though overall I am quite happy writing code like this for myself, I like starting with the strictest API and being explicit about what formats can be accepted. And accepting Date and ISO string seems like a pretty good compromise too, with a low chance of parsing errors.

However, I noticed some people, when facing this kind of strict API, start short circuiting the parsing logic by wrapping it in nested new Date() etc so it becomes very very unstrict:

// my teammate's version
function isExpired(expiredAt: any): boolean {
  const dateTime = DateTime.fromJSDate(new Date(expiredAt));

  return DateTime.now() >= dateTime;
}

Actually, I feel like this case is especially difficult for a few reasons:

1. I want to advise that person to write something like my version above, but I'm not sure that they really understand the serialization issue, which is hard to explain in itself. Even if I say to check for ISO date string or Date, it can be very hard to understand why it needs to be used, or why this strategy needs to be used in Situation A but not in Situation B.
   • Also, does everyone have to think about these things? Is it possible to suggest a strategy that is reasonably safe and works in 99% of situations?
2. I feel like the code I wrote looks a little bit "silly", since many developers of this era have grown up with loose parsing APIs like new moment(...) where the source format was extremely flexible. So of course, when moment() is gone, they naturally want to reach for the next best thing, new Date(...).
3. Using raw new Date() with unknown input is especially "dangerous" because the system won't give any warnings if you use a weird format. If the code used some wrapper function that parsed the dates, it could generate warnings or more useful errors if a suspicious input is received.

Case 2: React Wrapper

I tried to create a React wrapper to show a formatted date. Depending on the source (server, recalculation on every form input, etc), I might be starting with a Date, DateTime or ISO string. As this is the final formatting step, not an internal calculation, I think seems like the most useful API is to just accept any of these and will have a low chance of showing incorrect data:

// Usage:
<FormattedDate date={new Date()} />
<FormattedDate date={DateTime.now()} />
<FormattedDate date="2022-01-01" />

// Component:
export function FormattedDate({
  date,
}: {
  date?: null | string | Date | DateTime;
}) {
  const parsed = parseDate(date);
  if (!parsed) return null;
  const formatted = parsed.toLocaleString();
  return <time dateTime={parsed.toJSON()}>{formatted}</time>;
}

function parseDate(
  date?: null | string | Date | DateTime
): DateTime | undefined {
  if (date == null) {
    return undefined; // date was null or undefined
  } else if (DateTime.isDateTime(date)) {
    return date;
  } else if (isDate(date)) {
    return DateTime.fromJSDate(date);
  } else if (typeof date === 'string') {
    return DateTime.fromISO(date);
  } else {
    console.warn(`Unknown date type`, date);
    return undefined;
  }
}

The awkward part here is I had to write my own quite long parseDate() function. And, I'm not quite sure if it is correct. For example, I'm not really sure if an invalid input will throw an error or generate an invalid DateTime (without reading the documentation carefully...), or if the error message generated by an invalid input will be enough information to debug it.

---

In both of these cases, I feel like there is a missing piece to parse from one of multiple formats. Should I be writing wrappers like parseDate() above in all of my projects? Is my strategy too loose thus I am not quite "getting it"?

While I'm not trying to make a feature request specifically, if Luxon had have some "parse multiple formats" function which looked like this:

DateTime.from(date, { formats: ['JSDate', 'ISO'] })

and that:

• could handle invalid input in a consistent way and with helpful debug info
• had a similar syntax to parsing a single format, so it is easy to suggest when reviewing a pull request, etc

I think i would have just used that function instead of wondering how to handle this case. Some kind of official documentation or code snippet could also serve to guide developers in how to handle this in an ideal way. Thanks!

[diesieben07]

Luxon already has a friendlyDateTime function internally, which could be exposed as DateTime.from like you proposed. However it only accepts unambiguous things, i.e. no strings. It accepts DateTime, Date or an object like DateTime.fromObject. One question to answer here is what about the options for fromObject and fromJSDate which are used under the hood. Does from accept them? It probably shouldn't, to avoid confusion in the case where a DateTime is passed and they would be ignored.
However I do think it does make sense to expose this function, as pretty much all places where Luxon accepts a DateTime in the options already run through this method anyways. I would accept a PR for this.

As for accepting strings: This is not something we can really do. You want ISO, but the next person might want a Unix timestamp (seconds or milliseconds or maybe even nanos?) or RFC 2822, etc. etc. This is something that needs to be solved in application logic. You know best which formats you have, you need to tell Luxon that. And I don't think DateTime.from(fooBar, { formats: ['ISO'] }) is a better API than DateTime.fromISO(fooBar).

Additionally, I don't understand how Luxon having a DateTime.from method like you described would prevent the "teammate version" you showed.