dayjs

Postconditions — what we check

• dayjs · dayjs-invalid-date

  error
  Wheninput string is not a valid date format
  Required handlingCaller MUST check isValid() before using the Day.js object. Invalid Day.js objects can cause incorrect date calculations, display issues, or NaN values propagating through the application. Use pattern: const d = dayjs(input); if (!d.isValid()) { /* handle error */ }
  costmediumin proddegraded serviceusers seelost datavisibilitysilent
  Sources[1]
• utc · utc-invalid-date

  error
  Wheninput string is not a valid date format
  Required handlingCaller MUST check isValid() after parsing. Invalid UTC dates can cause timezone calculation errors and data corruption. Use pattern: const d = dayjs.utc(input); if (!d.isValid()) { /* handle error */ }
  costmediumin proddegraded serviceusers seelost datavisibilitysilent
  Sources[2]
• format · format-string-redos

  warning
  Whenformat string is user-controlled or very long
  Required handlingAvoid using user-controlled format strings directly. Vulnerable regex patterns in format parsing can cause quadratic time complexity, leading to CPU exhaustion and DoS. Validate and limit format string length. See GitHub PR #2908 for technical details.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• tz · tz-invalid-timezone-range-error

  error
  Whentimezone string is not a valid IANA timezone identifier
  ThrowsRangeError: Invalid time zone specified: <timezone>
  Required handlingCallers MUST wrap dayjs.tz() and Dayjs.tz() calls in try-catch when the timezone value comes from user input, database values, or external APIs. Valid IANA identifiers include "America/New_York", "UTC", "Europe/London". Invalid identifiers like "EST", "PST", or misspelled names throw RangeError. Use a validation step: check against Intl.supportedValuesOf('timeZone') or wrap in try-catch. Unlike other Day.js operations, this is a REAL exception, not a silent invalidity. Pattern: try { const d = dayjs.tz(input, timezone); } catch (e) { if (e instanceof RangeError) { /* invalid timezone */ } }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][5]
• tz · tz-setdefault-invalid-timezone

  warning
  Whendayjs.tz.setDefault() called with invalid IANA timezone string
  ThrowsRangeError propagated on next dayjs.tz() call
  Required handlingWhen setting a default timezone via dayjs.tz.setDefault(timezone), the timezone string is NOT validated at call time. The RangeError is thrown lazily on the next dayjs.tz() call that uses the default timezone. This makes the failure delayed and harder to trace. Validate the timezone before calling setDefault(): const isValid = (tz: string) => { try { Intl.DateTimeFormat(undefined, { timeZone: tz }); return true; } catch { return false; } }; if (isValid(tz)) { dayjs.tz.setDefault(tz); }
  costmediumin proddegraded serviceusers seeservice unavailablevisibilitysilent
  Sources[4]
• toISOString · toisostring-invalid-date-throws

  error
  Whencalled on a Day.js object created from an invalid date string or null
  ThrowsRangeError: Invalid time value (thrown by native Date.prototype.toISOString)
  Required handlingCallers MUST ensure the Day.js object is valid before calling toISOString(). Always call isValid() first, or use toJSON() (which returns null for invalid dates instead of throwing). Common pattern: const iso = d.isValid() ? d.toISOString() : null; Or use toJSON() as a safe alternative: const iso = d.toJSON(); This is particularly dangerous when dayjs() parses user-supplied date strings — invalid input propagates silently until toISOString() is called and throws.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• duration · duration-invalid-iso-string-silent-zero

  warning
  WhenISO 8601 duration string is malformed or does not match the expected format
  Required handlingCallers MUST validate ISO 8601 duration strings before passing to dayjs.duration(). Test the duration after creation: const d = dayjs.duration(str); if (d.asMilliseconds() === 0 && str !== 'P0D' && str !== 'PT0S') { /* invalid */ } Better: pre-validate with the ISO 8601 duration regex before calling duration(). Common invalid strings that silently produce zero-duration: - "1h30m" (not ISO format — should be "PT1H30M") - "1 day" (natural language — should be "P1D") - "90 minutes" (should be "PT90M") - "" (empty string) - "P" (bare P with no values)
  costmediumin proddegraded serviceusers seelost datavisibilitysilent
  Sources[7][8]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]day.js.org/docs/enhttps://day.js.org/docs/en/parse/string
2. [2]day.js.org/docs/enhttps://day.js.org/docs/en/plugin/utc
3. [3]github.com/iamkun/dayjshttps://github.com/iamkun/dayjs/pull/2908
4. [4]day.js.org/docs/enhttps://day.js.org/docs/en/plugin/timezone
5. [5]developer.mozilla.org/en-US/docshttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat
6. [6]developer.mozilla.org/en-US/docshttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString
7. [7]day.js.org/docs/enhttps://day.js.org/docs/en/plugin/duration
8. [8]en.wikipedia.org/wiki/ISO_8601https://en.wikipedia.org/wiki/ISO_8601#Durations