@atproto/syntax 0.5.2 → 0.5.4

package/src/aturi_validation.ts

@@ -1,152 +1,321 @@
-import { AtIdentifierString, ensureValidAtIdentifier } from './at-identifier.js'
-import { ensureValidDidRegex } from './did.js'
-import { ensureValidHandleRegex } from './handle.js'
+import { AtIdentifierString, isAtIdentifierString } from './at-identifier.js'
+import { Result, failure, success } from './lib/result.js'
 import { NsidString, isValidNsid } from './nsid.js'
+import { isValidRecordKey } from './recordkey.js'
 
-export type AtUriString =
+export type AtUriStringBase =
   | `at://${AtIdentifierString}`
   | `at://${AtIdentifierString}/${NsidString}`
   | `at://${AtIdentifierString}/${NsidString}/${string}`
 
-// Human-readable constraints on ATURI:
-//   - following regular URLs, a 8KByte hard total length limit
-//   - follows ATURI docs on website
-//      - all ASCII characters, no whitespace. non-ASCII could be URL-encoded
-//      - starts "at://"
-//      - "authority" is a valid DID or a valid handle
-//      - optionally, follow "authority" with "/" and valid NSID as start of path
-//      - optionally, if NSID given, follow that with "/" and rkey
-//      - rkey path component can include URL-encoded ("percent encoded"), or:
-//          ALPHA / DIGIT / "-" / "." / "_" / "~" / ":" / "@" / "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
-//          [a-zA-Z0-9._~:@!$&'\(\)*+,;=-]
-//      - rkey must have at least one char
-//      - regardless of path component, a fragment can follow  as "#" and then a JSON pointer (RFC-6901)
-
-export function ensureValidAtUri<I extends string>(
+export type AtUriStringFragment = `#/${string}`
+
+/**
+ * A URI string as used to point at resources in the AT Protocol
+ *
+ * The full, general structure of an AT URI is:
+ *
+ * ```bnf
+ * AT-URI = "at://" AUTHORITY [ PATH ] [ "?" QUERY ] [ "#" FRAGMENT ]
+ * ```
+ *
+ * The authority part of the URI can be either a handle or a DID, indicating the
+ * identity associated with the repository. In current atproto Lexicon use, the
+ * query and fragment parts are not yet supported, and only a fixed pattern of
+ * paths are allowed:
+ *
+ * ```bnf
+ * AT-URI     = "at://" AUTHORITY [ "/" COLLECTION [ "/" RKEY ] ]
+ *
+ * AUTHORITY  = HANDLE | DID
+ * COLLECTION = NSID
+ * RKEY       = RECORD-KEY
+ * ```
+ *
+ * The authority section is required, and should be normalized.
+ *
+ * AT URI strings must respect the following syntax (as prescribed by the AT
+ * protocol specification):
+ *
+ * - The overall URI is restricted to a subset of ASCII characters
+ * - For reference below, the set of unreserved characters, as defined in [RFC-3986](https://www.rfc-editor.org/rfc/rfc3986), includes alphanumeric (`A-Za-z0-9`), period, hyphen, underscore, and tilde (`.-_~`)
+ * - Maximum overall length is 8 kilobytes (which may be shortened in the future)
+ * - Hex-encoding of characters is permitted (but in practice not necessary and should be avoided to keep the URI normalized and human-readable)
+ * - The URI scheme is `at`, and an authority part preceded with double slashes is always required. AT URIs always start with `at://`.
+ * - An authority section is required and must be non-empty. the authority can be either an atproto Handle, or a DID meeting the restrictions for use with atproto. The authority part can *not* be interpreted as a host:port pair, because of the use of colon characters (`:`) in DIDs. Colons and unreserved characters should not be escaped in DIDs, but other reserved characters (including `#`, `/`, `$`, `&`, `@`) must be escaped.
+ *     - Note that none of the current "blessed" DID methods for atproto allow these characters in DID identifiers
+ * - An optional path section may follow the authority. The path may contain multiple segments separated by a single slash (`/`). Generic URI path normalization rules may be used.
+ * - An optional query part is allowed, following generic URI syntax restrictions
+ * - An optional fragment part is allowed, using JSON Path syntax
+ *
+ * @example "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.actor.profile/self"
+ *
+ * @see {@link https://atproto.com/specs/at-uri-scheme AT protocol - AT URI Scheme}
+ */
+export type AtUriString =
+  | AtUriStringBase
+  | `${AtUriStringBase}${AtUriStringFragment}`
+
+/**
+ * Type guard that checks if a value is a valid {@link AtUriString}
+ *
+ * @see {@link AtUriString}
+ */
+export function isAtUriString<I>(
   input: I,
-): asserts input is I & AtUriString {
-  const fragmentIndex = input.indexOf('#')
-  if (fragmentIndex !== -1) {
-    if (input.charCodeAt(fragmentIndex + 1) !== 47) {
-      throw new Error('ATURI fragment must be non-empty and start with slash')
-    }
-    if (input.includes('#', fragmentIndex + 1)) {
-      throw new Error('ATURI can have at most one "#", separating fragment out')
-    }
+  options?: Omit<ParseAtUriStringOptions, 'detailed'>,
+): input is I & AtUriString {
+  return parseAtUriString(input, options).success
+}
 
-    // NOTE: enforcing *some* checks here for sanity. Eg, at least no whitespace
-    const fragment = input.slice(fragmentIndex + 1)
-    if (!/^\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\]/-]*$/.test(fragment)) {
-      throw new Error('Disallowed characters in ATURI fragment (ASCII)')
-    }
-  }
+/**
+ * Returns the input if it is a valid {@link AtUriString} format string, or
+ * `undefined` if it is not.
+ *
+ * @see {@link AtUriString}
+ */
+export function ifAtUriString<I>(
+  input: I,
+  options?: Omit<ParseAtUriStringOptions, 'detailed'>,
+): undefined | (I & AtUriString) {
+  return isAtUriString(input, options) ? input : undefined
+}
 
-  const uri = fragmentIndex === -1 ? input : input.slice(0, fragmentIndex)
+/**
+ * Casts a string to an {@link AtUriString} if it is a valid AT URI format
+ * string, throwing an error if it is not.
+ *
+ * @throws InvalidAtUriError if the input string does not meet the atproto AT URI format requirements.
+ * @see {@link AtUriString}
+ */
+export function asAtUriString<I>(
+  input: I,
+  options?: ParseAtUriStringOptions,
+): I & AtUriString {
+  assertAtUriString(input, options)
+  return input
+}
 
-  if (uri.length > 8 * 1024) {
-    throw new Error('ATURI is far too long')
+/**
+ * Assert the validity of an {@link AtUriString}, throwing an error if the
+ * {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ */
+export function assertAtUriString<I>(
+  input: I,
+  options?: ParseAtUriStringOptions,
+): asserts input is I & AtUriString {
+  // Optimistically use faster isAtUriString(), throwing a detailed error only
+  // in case of failure. This check, and the fact that the code after it always
+  // throws, also ensures that isAtUriString() and assertAtUriString()'s
+  // behavior are always consistent.
+  const result = parseAtUriString(input, options)
+  if (!result.success) {
+    throw new InvalidAtUriError(result.message)
   }
+}
+
+/**
+ * Assert the **non-strict** validity of an {@link AtUriString}, throwing a
+ * detailed error if the {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead
+ */
+export function ensureValidAtUri<I>(
+  input: I,
+): asserts input is I & AtUriString {
+  assertAtUriString(input, { strict: false, detailed: true })
+}
+
+/**
+ * Assert the (non-strict!) validity of an {@link AtUriString}, throwing an
+ * error if the {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead
+ */
+export function ensureValidAtUriRegex<I>(
+  input: I,
+): asserts input is I & AtUriString {
+  assertAtUriString(input, { strict: false, detailed: false })
+}
+
+/**
+ * Type guard that checks if a value is a valid {@link AtUriString} format
+ * string, without enforcing strict record key validation. This is useful for
+ * cases where you want to allow a wider range of valid ATURIs, such as when
+ * validating user input or when the record key is not relevant.
+ *
+ * @deprecated use {@link isAtUriString} with `{ strict: false }` option instead
+ */
+export function isValidAtUri<I>(input: I): input is I & AtUriString {
+  return isAtUriString(input, { strict: false })
+}
+
+export class InvalidAtUriError extends Error {}
 
-  if (!uri.startsWith('at://')) {
-    throw new Error('ATURI must start with "at://"')
+export type ParseAtUriStringOptions = {
+  /**
+   * If true, the parser will enforce that the record key (rkey) part of the URI
+   * is a valid record key (validated by {@link isValidRecordKey}). If false,
+   * any non-empty string of allowed chars will be accepted as a record key.
+   *
+   * @default true
+   */
+  strict?: boolean
+
+  /**
+   * If true, the parser will return detailed error messages for why a string is
+   * not a valid AT URI. This option has no effect on the behavior of
+   * {@link isAtUriString}, which will always return false for invalid strings
+   * regardless of this option.
+   *
+   * @default false
+   */
+  detailed?: boolean
+}
+
+export type AtUriParts = {
+  authority: AtIdentifierString
+  query?: string
+  hash?: string
+} & (
+  | { collection?: NsidString; rkey?: undefined }
+  | { collection: NsidString; rkey?: string }
+)
+
+const INVALID_CHAR_REGEXP = /[^a-zA-Z0-9._~:@!$&'()*+,;=%/\\[\]#?-]/
+const AT_URI_REGEXP =
+  /^(?<uri>at:\/\/(?<authority>[^/?#\s]+)(?:\/(?<collection>[^/?#\s]+)(?:\/(?<rkey>[^/?#\s]+))?)?(?<trailingSlash>\/)?)(?:\?(?<query>[^#\s]*))?(?:#(?<hash>[^\s]*))?$/
+
+/**
+ * Parses a valid {@link AtUriString} into a {@link AtUriParts} object, or
+ * returns a failure with a detailed error message if the string is not a valid
+ * {@link AtUriString}.
+ */
+export function parseAtUriString(
+  input: unknown,
+  options?: ParseAtUriStringOptions,
+): Result<AtUriParts> {
+  if (typeof input !== 'string') {
+    return failure('ATURI must be a string')
   }
 
-  // check that all chars are boring ASCII
-  if (!/^[a-zA-Z0-9._~:@!$&')(*+,;=%/-]*$/.test(uri)) {
-    throw new Error('Disallowed characters in ATURI (ASCII)')
+  if (input.length > 8192) {
+    return failure('ATURI exceeds maximum length')
   }
 
-  const authorityEnd = uri.indexOf('/', 5)
-  const authority =
-    authorityEnd === -1 ? uri.slice(5) : uri.slice(5, authorityEnd)
-  try {
-    ensureValidAtIdentifier(authority)
-  } catch (cause) {
-    throw new Error('ATURI authority must be a valid handle or DID', { cause })
+  const invalidChar = input.match(INVALID_CHAR_REGEXP)
+  if (invalidChar) {
+    return failure('Disallowed characters in ATURI (ASCII)')
   }
 
-  const collectionStart = authorityEnd === -1 ? -1 : authorityEnd + 1
-  const collectionEnd =
-    collectionStart === -1 ? -1 : uri.indexOf('/', collectionStart)
+  const match = input.match(AT_URI_REGEXP)
+  const groups = match?.groups
+  if (!groups) {
+    // Regex validation failed, but we don't know exactly why. Provide more
+    // detailed error messages if the "detailed" option is set, falling back to
+    // a generic error.
+    if (options?.detailed) {
+      if (!input.startsWith('at://')) {
+        return failure('ATURI must start with "at://"')
+      }
 
-  if (collectionStart !== -1) {
-    const collection =
-      collectionEnd === -1
-        ? uri.slice(collectionStart)
-        : uri.slice(collectionStart, collectionEnd)
+      if (input.includes(' ')) {
+        return failure('ATURI can not contain spaces')
+      }
 
-    if (collection.length === 0) {
-      throw new Error(
-        'ATURI can not have a slash after authority without a path segment',
-      )
-    }
-    if (!isValidNsid(collection)) {
-      throw new Error(
-        'ATURI requires first path segment (if supplied) to be valid NSID',
-      )
+      if (input.includes('//', 5)) {
+        return failure('ATURI can not have empty path segments')
+      }
+
+      const pathStart = input.indexOf('/', 5) // after "at://"
+      if (pathStart !== -1) {
+        const fragmentIndex = input.indexOf('#')
+        const pathEnd = fragmentIndex !== -1 ? fragmentIndex : input.length
+        const secondSlash = input.indexOf('/', pathStart + 1)
+        if (secondSlash !== -1 && secondSlash !== pathEnd - 1) {
+          return failure('ATURI can not have more than two path segments')
+        }
+      }
     }
+
+    return failure('ATURI does not match expected format')
   }
 
-  const recordKeyStart = collectionEnd === -1 ? -1 : collectionEnd + 1
-  const recordKeyEnd =
-    recordKeyStart === -1 ? -1 : uri.indexOf('/', recordKeyStart)
+  // @NOTE Percent-encoding is allowed by the AT URI specification, but any
+  // percent-encoded characters appearing in the collection NSID or record key
+  // will effectively be rejected by the isValidNsid and isValidRecordKey
+  // validators. Since these values are defined to be plain ASCII identifiers,
+  // this legacy behavior is beneficial: it ensures that normalized
+  // (non-percent-encoded) values are always used, as prescribed by the spec.
 
-  if (recordKeyStart !== -1) {
-    if (recordKeyStart === uri.length) {
-      throw new Error(
-        'ATURI can not have a slash after collection, unless record key is provided',
-      )
-    }
-    // would validate rkey here, but there are basically no constraints!
+  if (!isAtIdentifierString(groups.authority)) {
+    return failure('ATURI has invalid authority')
   }
 
-  if (recordKeyEnd !== -1) {
-    throw new Error(
-      'ATURI path can have at most two parts, and no trailing slash',
-    )
+  if (groups.collection != null && !isValidNsid(groups.collection)) {
+    return failure('ATURI has invalid collection')
   }
-}
 
-export function ensureValidAtUriRegex<I extends string>(
-  input: I,
-): asserts input is I & AtUriString {
-  // simple regex to enforce most constraints via just regex and length.
-  // hand wrote this regex based on above constraints. whew!
-  const aturiRegex =
-    /^at:\/\/(?<authority>[a-zA-Z0-9._:%-]+)(\/(?<collection>[a-zA-Z0-9-.]+)(\/(?<rkey>[a-zA-Z0-9._~:@!$&%')(*+,;=-]+))?)?(#(?<fragment>\/[a-zA-Z0-9._~:@!$&%')(*+,;=\-[\]/\\]*))?$/
-  const rm = input.match(aturiRegex)
-  if (!rm || !rm.groups) {
-    throw new Error("ATURI didn't validate via regex")
+  if (groups.hash != null) {
+    const result = parseJsonPointer(groups.hash, options)
+    if (result.success) {
+      groups.hash = result.value
+    } else {
+      return failure(`ATURI has invalid fragment (${result.message})`)
+    }
   }
-  const groups = rm.groups
 
-  try {
-    ensureValidHandleRegex(groups.authority)
-  } catch {
-    try {
-      ensureValidDidRegex(groups.authority)
-    } catch {
-      throw new Error('ATURI authority must be a valid handle or DID')
+  if (options?.strict !== false) {
+    if (groups.trailingSlash != null) {
+      return failure('ATURI can not have a trailing slash')
+    }
+
+    if (groups.query != null) {
+      return failure('ATURI query part is not allowed')
+    }
+
+    if (groups.rkey != null && !isValidRecordKey(groups.rkey)) {
+      return failure('ATURI has invalid record key')
     }
   }
 
-  if (groups.collection && !isValidNsid(groups.collection)) {
-    throw new Error('ATURI collection path segment must be a valid NSID')
+  return success(groups as AtUriParts)
+}
+
+const BASIC_JSON_POINTER_REGEXP = /^\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\]/-]*$/
+
+/**
+ * Checks if a string is a valid JSON pointer (RFC-6901) with the allowed chars
+ * for ATURI fragments. This is a very loose validation that only checks the
+ * basic syntax and charset.
+ */
+function parseJsonPointer(
+  value: string,
+  options?: { strict?: boolean },
+): Result<string> {
+  if (!BASIC_JSON_POINTER_REGEXP.test(value)) {
+    return failure('Invalid JSON pointer')
   }
 
-  if (input.length > 8 * 1024) {
-    throw new Error('ATURI is far too long')
+  const result = parsePercentEncoding(value)
+
+  // In non-strict mode, we allow invalid percent-encoding in the fragment
+  if (!result.success && options?.strict === false) {
+    return success(value)
   }
+
+  return result
 }
 
-export function isValidAtUri<I extends string>(
-  input: I,
-): input is I & AtUriString {
+function parsePercentEncoding(value: string): Result<string> {
   try {
-    ensureValidAtUri(input)
+    return success(decodeURIComponent(value))
   } catch {
-    return false
+    // decodeURIComponent throws if the percent-encoding is invalid (e.g. "%FF")
+    return failure('Invalid percent-encoding')
   }
-
-  return true
 }

package/src/datetime.ts

@@ -163,19 +163,52 @@ export function toDatetimeString(date: Date): DatetimeString {
  * One use-case is a consistent, sortable string. Another is to work with older
  * invalid createdAt datetimes.
  *
+ * @note This function might return different normalized strings for the same
+ * input depending on the timezone of the machine it is run on, since it will
+ * attempt to parse the input "as is" if it fails to parse with an explicit
+ * timezone.
+ *
  * @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()
-  }
+  if (
+    // Explicit timezone offset
+    /[+-]\d\d:?\d\d/.test(dtStr) ||
+    // 'Z' timezone designator
+    /\dZ\b/.test(dtStr) ||
+    // Timezone abbreviation (eg. "EST", "PST", "UTC", "GMT", etc), as in:
+    // > Tue Mar 17 2026 16:38:44 PST (Pacific Standard Time)
+    /\b[A-Z]{3,4}\b/.test(dtStr)
+  ) {
+    // Since we do have a timezone designator, we can try parsing "as is" and
+    // should get consistent results regardless of local timezone.
+
+    // @NOTE NodeJS will reject dates with an un-recognized timezone designator
+    // (like "AFT"), even if we add a well-known timezone abbreviation like
+    // "UTC" or "Z".
+    const date = new Date(dtStr)
+    if (isAtprotoDate(date)) {
+      return date.toISOString()
+    }
+  } else {
+    // If there is no timezone information, try parsing as UTC using two
+    // different syntaxes, falling back to parsing "as is".
+
+    const dateZ = new Date(`${dtStr}Z`)
+    if (isAtprotoDate(dateZ)) {
+      return dateZ.toISOString()
+    }
+
+    const dateUTC = new Date(`${dtStr} UTC`)
+    if (isAtprotoDate(dateUTC)) {
+      return dateUTC.toISOString()
+    }
 
-  // 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`)
+    // Despite our best efforts to parse as a consistent value, appending "Z" or
+    // " UTC" did not work, so we will try parsing "as is", which may yield
+    // different results depending on the local timezone of the machine.
+    const date = new Date(dtStr)
     if (isAtprotoDate(date)) {
       return date.toISOString()
     }

package/src/lib/result.ts

@@ -0,0 +1,11 @@
+export type Result<T> = Success<T> | Failure
+
+export type Success<T> = { success: true; value: T }
+export function success<T>(value: T): Success<T> {
+  return { success: true, value }
+}
+
+export type Failure = { success: false; message: string }
+export function failure(message: string): Failure {
+  return { success: false, message }
+}

package/src/nsid.ts

@@ -1,3 +1,5 @@
+import { Result, failure, success } from './lib/result.js'
+
 /*
 Grammar:
 
@@ -81,71 +83,42 @@ export function isValidNsid<I extends string>(
   return validateNsidRegex(input).success
 }
 
-type ValidateResult<T> =
-  | { success: true; value: T }
-  | { success: false; message: string }
-
 // Human readable constraints on NSID:
 // - a valid domain in reversed notation
 // - followed by an additional period-separated name, which is camel-case letters
-export function validateNsid(input: string): ValidateResult<string[]> {
+export function validateNsid(input: string): Result<string[]> {
   if (input.length > 253 + 1 + 63) {
-    return {
-      success: false,
-      message: 'NSID is too long (317 chars max)',
-    }
+    return failure('NSID is too long (317 chars max)')
   }
   if (hasDisallowedCharacters(input)) {
-    return {
-      success: false,
-      message:
-        'Disallowed characters in NSID (ASCII letters, digits, dashes, periods only)',
-    }
+    return failure(
+      'Disallowed characters in NSID (ASCII letters, digits, dashes, periods only)',
+    )
   }
   const segments = input.split('.')
   if (segments.length < 3) {
-    return {
-      success: false,
-      message: 'NSID needs at least three parts',
-    }
+    return failure('NSID needs at least three parts')
   }
   for (const l of segments) {
     if (l.length < 1) {
-      return {
-        success: false,
-        message: 'NSID parts can not be empty',
-      }
+      return failure('NSID parts can not be empty')
     }
     if (l.length > 63) {
-      return {
-        success: false,
-        message: 'NSID part too long (max 63 chars)',
-      }
+      return failure('NSID part too long (max 63 chars)')
     }
     if (startsWithHyphen(l) || endsWithHyphen(l)) {
-      return {
-        success: false,
-        message: 'NSID parts can not start or end with hyphen',
-      }
+      return failure('NSID parts can not start or end with hyphen')
     }
   }
   if (startsWithNumber(segments[0])) {
-    return {
-      success: false,
-      message: 'NSID first part may not start with a digit',
-    }
+    return failure('NSID first part may not start with a digit')
   }
   if (!isValidIdentifier(segments[segments.length - 1])) {
-    return {
-      success: false,
-      message:
-        'NSID name part must be only letters and digits (and no leading digit)',
-    }
-  }
-  return {
-    success: true,
-    value: segments,
+    return failure(
+      'NSID name part must be only letters and digits (and no leading digit)',
+    )
   }
+  return success(segments)
 }
 
 function hasDisallowedCharacters(v: string) {
@@ -188,12 +161,9 @@ export function ensureValidNsidRegex(nsid: string): asserts nsid is NsidString {
  * Regexp based validation that behaves identically to the previous code but
  * provides less detailed error messages (while being 20% to 50% faster).
  */
-export function validateNsidRegex(value: string): ValidateResult<NsidString> {
+export function validateNsidRegex(value: string): Result<NsidString> {
   if (value.length > 253 + 1 + 63) {
-    return {
-      success: false,
-      message: 'NSID is too long (317 chars max)',
-    }
+    return failure('NSID is too long (317 chars max)')
   }
 
   if (
@@ -203,16 +173,10 @@ export function validateNsidRegex(value: string): ValidateResult<NsidString> {
       value,
     )
   ) {
-    return {
-      success: false,
-      message: "NSID didn't validate via regex",
-    }
+    return failure("NSID didn't validate via regex")
   }
 
-  return {
-    success: true,
-    value: value as NsidString,
-  }
+  return success(value as NsidString)
 }
 
 export class InvalidNsidError extends Error {}