@bluesky-social/syntax/src/datetime.ts

Validation for atproto identifiers and formats: DID, handle, NSID, AT URI, etc

/* Validates datetime string against atproto Lexicon 'datetime' format.
 * Syntax is described at: https://atproto.com/specs/lexicon#datetime
 */
export const ensureValidDatetime = (dtStr: string): void => {
  const date = new Date(dtStr)
  // must parse as ISO 8601; this also verifies semantics like month is not 13 or 00
  if (isNaN(date.getTime())) {
    throw new InvalidDatetimeError('datetime did not parse as ISO 8601')
  }
  if (date.toISOString().startsWith('-')) {
    throw new InvalidDatetimeError('datetime normalized to a negative time')
  }
  // regex and other checks for RFC-3339
  if (
    !/^[0-9]{4}-[01][0-9]-[0-3][0-9]T[0-2][0-9]:[0-6][0-9]:[0-6][0-9](.[0-9]{1,20})?(Z|([+-][0-2][0-9]:[0-5][0-9]))$/.test(
      dtStr,
    )
  ) {
    throw new InvalidDatetimeError("datetime didn't validate via regex")
  }
  if (dtStr.length > 64) {
    throw new InvalidDatetimeError('datetime is too long (64 chars max)')
  }
  if (dtStr.endsWith('-00:00')) {
    throw new InvalidDatetimeError(
      'datetime can not use "-00:00" for UTC timezone',
    )
  }
  if (dtStr.startsWith('000')) {
    throw new InvalidDatetimeError('datetime so close to year zero not allowed')
  }
}

/* Same logic as ensureValidDatetime(), but returns a boolean instead of throwing an exception.
 */
export const isValidDatetime = (dtStr: string): boolean => {
  try {
    ensureValidDatetime(dtStr)
  } catch (err) {
    if (err instanceof InvalidDatetimeError) {
      return false
    }
    throw err
  }

  return true
}

/* Takes a flexible datetime string and normalizes representation.
 *
 * This function will work with any valid atproto datetime (eg, anything which isValidDatetime() is true for). It *additionally* is more flexible about accepting datetimes that don't comply to RFC 3339, or are missing timezone information, and normalizing them to a valid datetime.
 *
 * One use-case is a consistent, sortable string. Another is to work with older invalid createdAt datetimes.
 *
 * Successful output will be a valid atproto datetime with millisecond precision (3 sub-second digits) and UTC timezone with trailing 'Z' syntax. Throws `InvalidDatetimeError` if the input string could not be parsed as a datetime, even with permissive parsing.
 *
 * Expected output format: YYYY-MM-DDTHH:mm:ss.sssZ
 */
export const normalizeDatetime = (dtStr: string): string => {
  if (isValidDatetime(dtStr)) {
    const outStr = new Date(dtStr).toISOString()
    if (isValidDatetime(outStr)) {
      return outStr
    }
  }

  // check if this permissive datetime is missing a timezone
  if (!/.*(([+-]\d\d:?\d\d)|[a-zA-Z])$/.test(dtStr)) {
    const date = new Date(dtStr + 'Z')
    if (!isNaN(date.getTime())) {
      const tzStr = date.toISOString()
      if (isValidDatetime(tzStr)) {
        return tzStr
      }
    }
  }

  // finally try parsing as simple datetime
  const date = new Date(dtStr)
  if (isNaN(date.getTime())) {
    throw new InvalidDatetimeError(
      'datetime did not parse as any timestamp format',
    )
  }
  const isoStr = date.toISOString()
  if (isValidDatetime(isoStr)) {
    return isoStr
  } else {
    throw new InvalidDatetimeError(
      'datetime normalized to invalid timestamp string',
    )
  }
}

/* Variant of normalizeDatetime() which always returns a valid datetime strings.
 *
 * If a InvalidDatetimeError is encountered, returns the UNIX epoch time as a UTC datetime (1970-01-01T00:00:00.000Z).
 */
export const normalizeDatetimeAlways = (dtStr: string): string => {
  try {
    return normalizeDatetime(dtStr)
  } catch (err) {
    if (err instanceof InvalidDatetimeError) {
      return new Date(0).toISOString()
    }
    throw err
  }
}

/* Indicates a datetime string did not pass full atproto Lexicon datetime string format checks.
 */
export class InvalidDatetimeError extends Error {}