@atproto/syntax 0.4.2 → 0.5.0

package/src/datetime.ts

@@ -1,125 +1,304 @@
-/** An ISO 8601 formatted datetime string (YYYY-MM-DDTHH:mm:ss.sssZ) */
-export type DatetimeString =
-  `${string}-${string}-${string}T${string}:${string}:${string}${'Z' | `+${string}` | `-${string}`}`
+/**
+ * Indicates a date or string is not a valid representation of a datetime
+ * according to the atproto
+ * {@link https://atproto.com/specs/lexicon#datetime specification}.
+ */
+export class InvalidDatetimeError extends Error {}
 
-// Allow date.toISOString() to be used where datetime format is expected
-declare global {
-  interface Date {
-    toISOString(): `${string}-${string}-${string}T${string}:${string}:${string}Z`
-  }
+/**
+ * A subset of {@link DatetimeString} that represent valid datetime strings with
+ * the format: `YYYY-MM-DDTHH:mm:ss.sssZ`, as returned by `Date.toISOString()
+ * for dates between the years 0000 and 9999.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString}
+ */
+export type ISODatetimeString =
+  // @TODO Switch to branded types for more accurate type safety.
+  `${string}-${string}-${string}T${string}:${string}:${string}.${string}Z`
+
+/**
+ * Represents a {@link Date} that can be safely stringified into a valid atproto
+ * {@link DatetimeString} using the {@link Date.toISOString toISOString()}
+ * method.
+ */
+export interface AtprotoDate extends Date {
+  toISOString(): ISODatetimeString
 }
 
-/* Validates datetime string against atproto Lexicon 'datetime' format.
- * Syntax is described at: https://atproto.com/specs/lexicon#datetime
+/**
+ * @see {@link AtprotoDate}
  */
-export function ensureValidDatetime(
-  dtStr: string,
-): asserts dtStr is DatetimeString {
-  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')
+export function assertAtprotoDate(date: Date): asserts date is AtprotoDate {
+  const res = parseDate(date)
+  if (!res.success) {
+    throw new InvalidDatetimeError(res.message)
   }
 }
 
-/* Same logic as ensureValidDatetime(), but returns a boolean instead of throwing an exception.
+/**
+ * @see {@link AtprotoDate}
  */
-export function isValidDatetime(dtStr: string): dtStr is DatetimeString {
-  try {
-    ensureValidDatetime(dtStr)
-  } catch (err) {
-    if (err instanceof InvalidDatetimeError) {
-      return false
-    }
-    throw err
+export function asAtprotoDate(date: Date): AtprotoDate {
+  assertAtprotoDate(date)
+  return date
+}
+
+/**
+ * @see {@link AtprotoDate}
+ */
+export function isAtprotoDate(date: Date): date is AtprotoDate {
+  return parseDate(date).success
+}
+
+/**
+ * @see {@link AtprotoDate}
+ */
+export function ifAtprotoDate(date: Date): AtprotoDate | undefined {
+  return isAtprotoDate(date) ? date : undefined
+}
+
+/**
+ * Datetime strings in atproto data structures and API calls should meet the
+ * {@link https://ijmacd.github.io/rfc3339-iso8601/ intersecting} requirements
+ * of the RFC 3339, ISO 8601, and WHATWG HTML datetime standards.
+ *
+ * @note This literal template type is not accurate enough to ensure that a
+ * string is a valid atproto datetime. The {@link DatetimeString} validation
+ * functions ({@link assertDatetimeString}, {@link isDatetimeString}, etc)
+ * should be used to validate that a string meets the atproto datetime
+ * requirements, and the {@link toDatetimeString} function should be used to
+ * convert a {@link Date} object into a valid {@link DatetimeString} string.
+ *
+ * @example "2024-01-15T12:30:00Z"
+ * @example "2024-01-15T12:30:00.000Z"
+ * @example "2024-01-15T12:30:00+00:00"
+ * @example "2024-01-15T11:30:00-01:00"
+ * @see {@link https://atproto.com/specs/lexicon#datetime atproto Lexicon datetime format}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc3339 RFC 3339}
+ * @see {@link https://www.iso.org/iso-8601-date-and-time-format.html ISO 8601}
+ */
+export type DatetimeString =
+  // @TODO Switch to branded types for more accurate type safety?
+  | `${string}-${string}-${string}T${string}:${string}:${string}Z`
+  | `${string}-${string}-${string}T${string}:${string}:${string}${'+' | '-'}${string}:${string}`
+
+/**
+ * Validates that a string is a valid {@link DatetimeString} format string,
+ * throwing an error if it is not.
+ *
+ * @throws InvalidDatetimeError if the input string does not meet the atproto 'datetime' format requirements.
+ * @see {@link DatetimeString}
+ */
+export function assertDatetimeString<I>(
+  input: I,
+): asserts input is I & DatetimeString {
+  const result = parseString(input)
+  if (!result.success) {
+    throw new InvalidDatetimeError(result.message)
   }
+}
 
-  return true
+/**
+ * Casts a string to a {@link DatetimeString} if it is a valid datetime format
+ * string, throwing an error if it is not.
+ *
+ * @throws InvalidDatetimeError if the input string does not meet the atproto 'datetime' format requirements.
+ * @see {@link DatetimeString}
+ */
+export function asDatetimeString<I>(input: I): I & DatetimeString {
+  assertDatetimeString(input)
+  return input
 }
 
-/* Takes a flexible datetime string and normalizes representation.
+/**
+ * Checks if a string is a valid {@link DatetimeString} format string.
  *
- * 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.
+ * @see {@link DatetimeString}
+ */
+export function isDatetimeString<I>(input: I): input is I & DatetimeString {
+  return parseString(input).success
+}
+
+/**
+ * Returns the input if it is a valid {@link DatetimeString} format string, or
+ * `undefined` if it is not.
  *
- * One use-case is a consistent, sortable string. Another is to work with older invalid createdAt datetimes.
+ * @see {@link DatetimeString}
+ */
+export function ifDatetimeString<I>(
+  input: I,
+): undefined | (I & DatetimeString) {
+  return isDatetimeString(input) ? input : undefined
+}
+
+/**
+ * Returns the current date and time as a {@link DatetimeString}.
  *
- * 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.
+ * @see {@link DatetimeString}
+ */
+export function currentDatetimeString(): DatetimeString {
+  return toDatetimeString(new Date())
+}
+
+/**
+ * Converts any {@link Date} into a {@link DatetimeString} if possible, throwing
+ * an error if the date is not a valid atproto datetime.
  *
- * Expected output format: YYYY-MM-DDTHH:mm:ss.sssZ
+ * This is short-hand for `asAtprotoDate(date).toISOString()`.
+ *
+ * @throws InvalidDatetimeError if the input date is not a valid atproto datetime (eg, it is too far in the future or past, or it normalizes to a negative year).
+ * @see {@link DatetimeString}
  */
-export function normalizeDatetime(dtStr: string): DatetimeString {
-  if (isValidDatetime(dtStr)) {
-    const outStr = new Date(dtStr).toISOString()
-    if (isValidDatetime(outStr)) {
-      return outStr
-    }
+export function toDatetimeString(date: Date): DatetimeString {
+  return asAtprotoDate(date).toISOString()
+}
+
+/**
+ * Takes a flexible datetime string and normalizes its representation.
+ *
+ * This function will work with any valid value that can be parsed as a date. It
+ * *additionally* is more flexible about accepting datetimes that are missing
+ * timezone information, and normalizing them to a valid atproto datetime.
+ *
+ * One use-case is a consistent, sortable string. Another is to work with older
+ * invalid createdAt datetimes.
+ *
+ * @returns ISODatetimeString - 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.
+ */
+export function normalizeDatetime(dtStr: string): ISODatetimeString {
+  // Parse the string as is
+  const date = new Date(dtStr)
+  if (isAtprotoDate(date)) {
+    return date.toISOString()
   }
 
-  // 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
-      }
+  // if dtStr is not a valid date, try parsing again with a timezone
+  if (isNaN(date.getTime()) && !/.*(([+-]\d\d:?\d\d)|[a-zA-Z])$/.test(dtStr)) {
+    const date = new Date(`${dtStr}Z`)
+    if (isAtprotoDate(date)) {
+      return date.toISOString()
     }
   }
 
-  // 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',
-    )
-  }
+  throw new InvalidDatetimeError(
+    'datetime did not parse as any timestamp format',
+  )
 }
 
-/* Variant of normalizeDatetime() which always returns a valid datetime strings.
+/**
+ * Variant of {@link normalizeDatetime} which always returns a valid datetime
+ * string.
+ *
+ * If a {@link InvalidDatetimeError} is encountered, returns the UNIX epoch time
+ * as a UTC datetime (`1970-01-01T00:00:00.000Z`).
  *
- * If a InvalidDatetimeError is encountered, returns the UNIX epoch time as a UTC datetime (1970-01-01T00:00:00.000Z).
+ * @see {@link normalizeDatetime}
  */
-export const normalizeDatetimeAlways = (dtStr: string): DatetimeString => {
+export function normalizeDatetimeAlways(dtStr: string): ISODatetimeString {
   try {
     return normalizeDatetime(dtStr)
   } catch (err) {
-    if (err instanceof InvalidDatetimeError) {
-      return new Date(0).toISOString()
-    }
-    throw err
+    return '1970-01-01T00:00:00.000Z'
+  }
+}
+
+// Legacy exports (should we deprecate these ?)
+export {
+  assertDatetimeString as ensureValidDatetime,
+  isDatetimeString as isValidDatetime,
+}
+
+// -----------------------------------------------------------------------------
+// ------------------------- Internal validation logic -------------------------
+// -----------------------------------------------------------------------------
+
+// Validation utils that allow avoiding try/catch for control flow (performance
+// optimization). Other syntax formats should also use this pattern to avoid
+// try/catch in their validation logic, at which point these utils can be moved
+// to a common internal utils.
+type FailureResult = { success: false; message: string }
+const failure = (m: string): FailureResult => ({ success: false, message: m })
+type SuccessResult<V> = { success: true; value: V }
+const success = <V>(v: V): SuccessResult<V> => ({ success: true, value: v })
+type Result<V> = FailureResult | SuccessResult<V>
+
+/**
+ * @see {@link https://www.rfc-editor.org/rfc/rfc3339#section-5.6 Internet Date/Time Format}
+ *
+ * @example
+ * ```abnf
+ * date-fullyear   = 4DIGIT
+ * date-month      = 2DIGIT  ; 01-12
+ * date-mday       = 2DIGIT  ; 01-28, 01-29, 01-30, 01-31 based on
+ *                           ; month/year
+ * time-hour       = 2DIGIT  ; 00-23
+ * time-minute     = 2DIGIT  ; 00-59
+ * time-second     = 2DIGIT  ; 00-58, 00-59, 00-60 based on leap second
+ *                           ; rules
+ * time-secfrac    = "." 1*DIGIT
+ * time-numoffset  = ("+" / "-") time-hour ":" time-minute
+ * time-offset     = "Z" / time-numoffset
+ * partial-time    = time-hour ":" time-minute ":" time-second
+ *                   [time-secfrac]
+ * full-date       = date-fullyear "-" date-month "-" date-mday
+ * full-time       = partial-time time-offset
+ * date-time       = full-date "T" full-time
+ * ```
+ */
+const DATETIME_REGEX =
+  /^(?<full_year>[0-9]{4})-(?<date_month>0[1-9]|1[012])-(?<date_mday>[0-2][0-9]|3[01])T(?<time_hour>[0-1][0-9]|2[0-3]):(?<time_minute>[0-5][0-9]):(?<time_second>[0-5][0-9]|60)(?<time_secfrac>\.[0-9]+)?(?<time_offset>Z|(?<time_numoffset>[+-](?:[0-1][0-9]|2[0-3]):[0-5][0-9]))$/
+
+/**
+ * Validates that the input is a datetime string according to atproto Lexicon
+ * rules, and parses it into a Date object.
+ */
+function parseString(input: unknown): Result<AtprotoDate> {
+  // @NOTE Performing cheap tests first
+  if (typeof input !== 'string') {
+    return failure('datetime must be a string')
+  }
+  if (input.length > 64) {
+    return failure('datetime is too long (64 chars max)')
+  }
+  if (input.endsWith('-00:00')) {
+    return failure('datetime can not use "-00:00" for UTC timezone')
   }
+  if (!DATETIME_REGEX.test(input)) {
+    return failure(
+      "datetime is not in a valid format (must match RFC 3339 & ISO 8601 with 'Z' or ±hh:mm timezone)",
+    )
+  }
+
+  // must parse as ISO 8601; this also verifies semantics like leap seconds and
+  // correct number of days in month, which the regex does not check for
+  const date = new Date(input)
+
+  return parseDate(date)
 }
 
-/* Indicates a datetime string did not pass full atproto Lexicon datetime string format checks.
+/**
+ * Ensures that a Date object represents a valid datetime according to atproto
+ * Lexicon rules. This ensures that `date.toISOString()` will produce a valid
+ * datetime string that can be used where {@link DatetimeString} is expected.
  */
-export class InvalidDatetimeError extends Error {}
+function parseDate(date: Date): Result<AtprotoDate> {
+  const fullYear = date.getUTCFullYear()
+  // Ensures that the date is valid. We could check isNaN(date.getTime()) here
+  // but since we'll check the year anyway, we just use that for the validity
+  // check since an invalid date will have NaN year.
+  if (Number.isNaN(fullYear)) {
+    return failure('datetime did not parse as ISO 8601')
+  }
+  // Ensure that the ISO string representation does not start with ±YYYYYY
+  if (fullYear < 0) {
+    return failure('datetime normalized to a negative time')
+  }
+  if (fullYear > 9999) {
+    return failure('datetime year is too far in the future')
+  }
+  if (fullYear < 10) {
+    return failure('datetime so close to year zero not allowed')
+  }
+  return success(date as AtprotoDate)
+}

package/src/did.ts

@@ -14,19 +14,29 @@
 
 export type DidString<M extends string = string> = `did:${M}:${string}`
 
-export function ensureValidDid(did: string): asserts did is DidString {
-  if (!did.startsWith('did:')) {
+export function ensureValidDid<I extends string>(
+  input: I,
+): asserts input is I & DidString {
+  if (!input.startsWith('did:')) {
     throw new InvalidDidError('DID requires "did:" prefix')
   }
 
+  if (input.length > 2048) {
+    throw new InvalidDidError('DID is too long (2048 chars max)')
+  }
+
+  if (input.endsWith(':') || input.endsWith('%')) {
+    throw new InvalidDidError('DID can not end with ":" or "%"')
+  }
+
   // check that all chars are boring ASCII
-  if (!/^[a-zA-Z0-9._:%-]*$/.test(did)) {
+  if (!/^[a-zA-Z0-9._:%-]*$/.test(input)) {
     throw new InvalidDidError(
       'Disallowed characters in DID (ASCII letters, digits, and a couple other characters only)',
     )
   }
 
-  const { length, 1: method } = did.split(':')
+  const { length, 1: method } = input.split(':')
   if (length < 3) {
     throw new InvalidDidError(
       'DID requires prefix, method, and method-specific content',
@@ -36,26 +46,26 @@ export function ensureValidDid(did: string): asserts did is DidString {
   if (!/^[a-z]+$/.test(method)) {
     throw new InvalidDidError('DID method must be lower-case letters')
   }
-
-  if (did.endsWith(':') || did.endsWith('%')) {
-    throw new InvalidDidError('DID can not end with ":" or "%"')
-  }
-
-  if (did.length > 2 * 1024) {
-    throw new InvalidDidError('DID is too long (2048 chars max)')
-  }
 }
 
-export function ensureValidDidRegex(did: string): asserts did is DidString {
+const DID_REGEX = /^did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-]$/
+
+export function ensureValidDidRegex<I extends string>(
+  input: I,
+): asserts input is I & DidString {
   // simple regex to enforce most constraints via just regex and length.
   // hand wrote this regex based on above constraints
-  if (!/^did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-]$/.test(did)) {
+  if (!DID_REGEX.test(input)) {
     throw new InvalidDidError("DID didn't validate via regex")
   }
 
-  if (did.length > 2 * 1024) {
+  if (input.length > 2048) {
     throw new InvalidDidError('DID is too long (2048 chars max)')
   }
 }
 
+export function isValidDid<I extends string>(input: I): input is I & DidString {
+  return input.length <= 2048 && DID_REGEX.test(input)
+}
+
 export class InvalidDidError extends Error {}

package/src/handle.ts

@@ -39,20 +39,20 @@ export const DISALLOWED_TLDS = [
 //  - does not validate whether domain or TLD exists, or is a reserved or
 //    special TLD (eg, .onion or .local)
 //  - does not validate punycode
-export function ensureValidHandle(
-  handle: string,
-): asserts handle is HandleString {
+export function ensureValidHandle<I extends string>(
+  input: I,
+): asserts input is I & HandleString {
   // check that all chars are boring ASCII
-  if (!/^[a-zA-Z0-9.-]*$/.test(handle)) {
+  if (!/^[a-zA-Z0-9.-]*$/.test(input)) {
     throw new InvalidHandleError(
       'Disallowed characters in handle (ASCII letters, digits, dashes, periods only)',
     )
   }
 
-  if (handle.length > 253) {
+  if (input.length > 253) {
     throw new InvalidHandleError('Handle is too long (253 chars max)')
   }
-  const labels = handle.split('.')
+  const labels = input.split('.')
   if (labels.length < 2) {
     throw new InvalidHandleError('Handle domain needs at least two parts')
   }
@@ -81,17 +81,19 @@ export function ensureValidHandle(
 const HANDLE_REGEX =
   /^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/
 
-export function ensureValidHandleRegex(
-  handle: string,
-): asserts handle is HandleString {
-  if (handle.length > 253) {
+export function ensureValidHandleRegex<I extends string>(
+  input: I,
+): asserts input is I & HandleString {
+  if (input.length > 253) {
     throw new InvalidHandleError('Handle is too long (253 chars max)')
   }
-  if (!HANDLE_REGEX.test(handle)) {
+  if (!HANDLE_REGEX.test(input)) {
     throw new InvalidHandleError("Handle didn't validate via regex")
   }
 }
 
+export function normalizeHandle(handle: HandleString): HandleString
+export function normalizeHandle(handle: string): string
 export function normalizeHandle(handle: string): string {
   return handle.toLowerCase()
 }
@@ -102,8 +104,10 @@ export function normalizeAndEnsureValidHandle(handle: string): HandleString {
   return normalized
 }
 
-export function isValidHandle(handle: string): handle is HandleString {
-  return handle.length <= 253 && HANDLE_REGEX.test(handle)
+export function isValidHandle<I extends string>(
+  input: I,
+): input is I & HandleString {
+  return input.length <= 253 && HANDLE_REGEX.test(input)
 }
 
 export function isValidTld(handle: string): boolean {

package/src/index.ts

@@ -1,8 +1,10 @@
-export * from './handle.js'
+export * from './at-identifier.js'
+export * from './aturi.js'
+export * from './datetime.js'
 export * from './did.js'
+export * from './handle.js'
 export * from './nsid.js'
-export * from './aturi.js'
-export * from './at-identifier.js'
-export * from './tid.js'
+export * from './language.js'
 export * from './recordkey.js'
-export * from './datetime.js'
+export * from './tid.js'
+export * from './uri.js'

package/src/language.ts

@@ -0,0 +1,39 @@
+const BCP47_REGEXP =
+  /^((?<grandfathered>(en-GB-oed|i-ami|i-bnn|i-default|i-enochian|i-hak|i-klingon|i-lux|i-mingo|i-navajo|i-pwn|i-tao|i-tay|i-tsu|sgn-BE-FR|sgn-BE-NL|sgn-CH-DE)|(art-lojban|cel-gaulish|no-bok|no-nyn|zh-guoyu|zh-hakka|zh-min|zh-min-nan|zh-xiang))|((?<language>([A-Za-z]{2,3}(-(?<extlang>[A-Za-z]{3}(-[A-Za-z]{3}){0,2}))?)|[A-Za-z]{4}|[A-Za-z]{5,8})(-(?<script>[A-Za-z]{4}))?(-(?<region>[A-Za-z]{2}|[0-9]{3}))?(-(?<variant>[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-(?<extension>[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+))*(-(?<privateUseA>x(-[A-Za-z0-9]{1,8})+))?)|(?<privateUseB>x(-[A-Za-z0-9]{1,8})+))$/
+
+export type LanguageTag = {
+  grandfathered?: string
+  language?: string
+  extlang?: string
+  script?: string
+  region?: string
+  variant?: string
+  extension?: string
+  privateUse?: string
+}
+
+export function parseLanguageString(input: string): LanguageTag | null {
+  const parsed = input.match(BCP47_REGEXP)
+  if (!parsed?.groups) return null
+
+  const { groups } = parsed
+  return {
+    grandfathered: groups.grandfathered,
+    language: groups.language,
+    extlang: groups.extlang,
+    script: groups.script,
+    region: groups.region,
+    variant: groups.variant,
+    extension: groups.extension,
+    privateUse: groups.privateUseA || groups.privateUseB,
+  }
+}
+
+/**
+ * Validates well-formed BCP 47 syntax
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc5646.html#section-2.1}
+ */
+export function isValidLanguage(input: string): boolean {
+  return BCP47_REGEXP.test(input)
+}

package/src/nsid.ts

@@ -48,20 +48,22 @@ export class NSID {
     return this.segments
       .slice(0, this.segments.length - 1)
       .reverse()
-      .join('.')
+      .join('.') as `${string}.${string}`
   }
 
   get name() {
     return this.segments.at(this.segments.length - 1)
   }
 
-  toString() {
-    return this.segments.join('.')
+  toString(): NsidString {
+    return this.segments.join('.') as NsidString
   }
 }
 
-export function ensureValidNsid(nsid: string): asserts nsid is NsidString {
-  const result = validateNsid(nsid)
+export function ensureValidNsid<I extends string>(
+  input: I,
+): asserts input is I & NsidString {
+  const result = validateNsid(input)
   if (!result.success) throw new InvalidNsidError(result.message)
 }
 
@@ -71,10 +73,12 @@ export function parseNsid(nsid: string): string[] {
   return result.value
 }
 
-export function isValidNsid(nsid: string): nsid is NsidString {
+export function isValidNsid<I extends string>(
+  input: I,
+): input is I & NsidString {
   // Since the regex version is more performant for valid NSIDs, we use it when
   // we don't care about error details.
-  return validateNsidRegex(nsid).success
+  return validateNsidRegex(input).success
 }
 
 type ValidateResult<T> =
@@ -193,6 +197,8 @@ export function validateNsidRegex(value: string): ValidateResult<NsidString> {
   }
 
   if (
+    // Fast check for small values
+    value.length < 5 ||
     !/^[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(?:\.[a-zA-Z](?:[a-zA-Z0-9]{0,62})?)$/.test(
       value,
     )