@atproto/syntax 0.4.0 → 0.4.2

package/src/aturi.ts

@@ -1,4 +1,8 @@
-export * from './aturi_validation'
+import { AtIdentifierString, ensureValidAtIdentifier } from './at-identifier.js'
+import { AtUriString } from './aturi_validation.js'
+import { ensureValidNsid } from './nsid.js'
+
+export * from './aturi_validation.js'
 
 export const ATP_URI_REGEX =
   // proto-    --did--------------   --name----------------   --path----   --query--   --hash--
@@ -8,32 +12,23 @@ const RELATIVE_REGEX = /^(\/[^?#\s]*)?(\?[^#\s]+)?(#[^\s]+)?$/i
 
 export class AtUri {
   hash: string
-  host: string
+  host: AtIdentifierString
   pathname: string
   searchParams: URLSearchParams
 
-  constructor(uri: string, base?: string) {
-    let parsed
-    if (base) {
-      parsed = parse(base)
-      if (!parsed) {
-        throw new Error(`Invalid at uri: ${base}`)
-      }
-      const relativep = parseRelative(uri)
-      if (!relativep) {
-        throw new Error(`Invalid path: ${uri}`)
-      }
-      Object.assign(parsed, relativep)
-    } else {
-      parsed = parse(uri)
-      if (!parsed) {
-        throw new Error(`Invalid at uri: ${uri}`)
-      }
-    }
+  constructor(uri: string, base?: string | AtUri) {
+    const parsed =
+      base !== undefined
+        ? typeof base === 'string'
+          ? Object.assign(parse(base), parseRelative(uri))
+          : Object.assign({ host: base.host }, parseRelative(uri))
+        : parse(uri)
 
-    this.hash = parsed.hash
+    ensureValidAtIdentifier(parsed.host)
+
+    this.hash = parsed.hash ?? ''
     this.host = parsed.host
-    this.pathname = parsed.pathname
+    this.pathname = parsed.pathname ?? ''
     this.searchParams = parsed.searchParams
   }
 
@@ -49,7 +44,7 @@ export class AtUri {
   }
 
   get origin() {
-    return `at://${this.host}`
+    return `at://${this.host}` as const
   }
 
   get hostname() {
@@ -57,6 +52,7 @@ export class AtUri {
   }
 
   set hostname(v: string) {
+    ensureValidAtIdentifier(v)
     this.host = v
   }
 
@@ -73,6 +69,7 @@ export class AtUri {
   }
 
   set collection(v: string) {
+    ensureValidNsid(v)
     const parts = this.pathname.split('/').filter(Boolean)
     parts[0] = v
     this.pathname = parts.join('/')
@@ -84,7 +81,7 @@ export class AtUri {
 
   set rkey(v: string) {
     const parts = this.pathname.split('/').filter(Boolean)
-    if (!parts[0]) parts[0] = 'undefined'
+    parts[0] ||= 'undefined'
     parts[1] = v
     this.pathname = parts.join('/')
   }
@@ -93,44 +90,60 @@ export class AtUri {
     return this.toString()
   }
 
-  toString() {
+  toString(): AtUriString {
     let path = this.pathname || '/'
     if (!path.startsWith('/')) {
       path = `/${path}`
     }
-    let qs = this.searchParams.toString()
-    if (qs && !qs.startsWith('?')) {
-      qs = `?${qs}`
+    let qs = ''
+    if (this.searchParams.size) {
+      qs = `?${this.searchParams.toString()}`
     }
     let hash = this.hash
     if (hash && !hash.startsWith('#')) {
       hash = `#${hash}`
     }
-    return `at://${this.host}${path}${qs}${hash}`
+    return `at://${this.host}${path}${qs}${hash}` as AtUriString
   }
 }
 
 function parse(str: string) {
-  const match = ATP_URI_REGEX.exec(str)
-  if (match) {
-    return {
-      hash: match[5] || '',
-      host: match[2] || '',
-      pathname: match[3] || '',
-      searchParams: new URLSearchParams(match[4] || ''),
-    }
+  const match = str.match(ATP_URI_REGEX) as null | {
+    0: string
+    1: string | undefined // proto
+    2: string // host
+    3: string | undefined // path
+    4: string | undefined // query
+    5: string | undefined // hash
+  }
+
+  if (!match) {
+    throw new Error(`Invalid AT uri: ${str}`)
+  }
+
+  return {
+    host: match[2],
+    hash: match[5],
+    pathname: match[3],
+    searchParams: new URLSearchParams(match[4]),
   }
-  return undefined
 }
 
 function parseRelative(str: string) {
-  const match = RELATIVE_REGEX.exec(str)
-  if (match) {
-    return {
-      hash: match[3] || '',
-      pathname: match[1] || '',
-      searchParams: new URLSearchParams(match[2] || ''),
-    }
+  const match = str.match(RELATIVE_REGEX) as null | {
+    0: string
+    1: string | undefined // path
+    2: string | undefined // query
+    3: string | undefined // hash
+  }
+
+  if (!match) {
+    throw new Error(`Invalid path: ${str}`)
+  }
+
+  return {
+    hash: match[3],
+    pathname: match[1],
+    searchParams: new URLSearchParams(match[2]),
   }
-  return undefined
 }

package/src/aturi_validation.ts

@@ -1,6 +1,12 @@
-import { ensureValidDid, ensureValidDidRegex } from './did'
-import { ensureValidHandle, ensureValidHandleRegex } from './handle'
-import { ensureValidNsid, ensureValidNsidRegex } from './nsid'
+import { AtIdentifierString, ensureValidAtIdentifier } from './at-identifier.js'
+import { ensureValidDidRegex } from './did.js'
+import { ensureValidHandleRegex } from './handle.js'
+import { NsidString, isValidNsid } from './nsid.js'
+
+export type AtUriString =
+  | `at://${AtIdentifierString}`
+  | `at://${AtIdentifierString}/${NsidString}`
+  | `at://${AtIdentifierString}/${NsidString}/${string}`
 
 // Human-readable constraints on ATURI:
 //   - following regular URLs, a 8KByte hard total length limit
@@ -15,55 +21,76 @@ import { ensureValidNsid, ensureValidNsidRegex } from './nsid'
 //          [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 const ensureValidAtUri = (uri: string) => {
-  // JSON pointer is pretty different from rest of URI, so split that out first
-  const uriParts = uri.split('#')
-  if (uriParts.length > 2) {
-    throw new Error('ATURI can have at most one "#", separating fragment out')
+
+export function ensureValidAtUri(input: string): asserts input is 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')
+    }
+
+    // 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)')
+    }
   }
-  const fragmentPart = uriParts[1] || null
-  uri = uriParts[0]
 
-  // check that all chars are boring ASCII
-  if (!/^[a-zA-Z0-9._~:@!$&')(*+,;=%/-]*$/.test(uri)) {
-    throw new Error('Disallowed characters in ATURI (ASCII)')
+  const uri = fragmentIndex === -1 ? input : input.slice(0, fragmentIndex)
+
+  if (uri.length > 8 * 1024) {
+    throw new Error('ATURI is far too long')
   }
 
-  const parts = uri.split('/')
-  if (parts.length >= 3 && (parts[0] !== 'at:' || parts[1].length !== 0)) {
+  if (!uri.startsWith('at://')) {
     throw new Error('ATURI must start with "at://"')
   }
-  if (parts.length < 3) {
-    throw new Error('ATURI requires at least method and authority sections')
+
+  // check that all chars are boring ASCII
+  if (!/^[a-zA-Z0-9._~:@!$&')(*+,;=%/-]*$/.test(uri)) {
+    throw new Error('Disallowed characters in ATURI (ASCII)')
   }
 
+  const authorityEnd = uri.indexOf('/', 5)
+  const authority =
+    authorityEnd === -1 ? uri.slice(5) : uri.slice(5, authorityEnd)
   try {
-    if (parts[2].startsWith('did:')) {
-      ensureValidDid(parts[2])
-    } else {
-      ensureValidHandle(parts[2])
-    }
-  } catch {
-    throw new Error('ATURI authority must be a valid handle or DID')
+    ensureValidAtIdentifier(authority)
+  } catch (cause) {
+    throw new Error('ATURI authority must be a valid handle or DID', { cause })
   }
 
-  if (parts.length >= 4) {
-    if (parts[3].length === 0) {
+  const collectionStart = authorityEnd === -1 ? -1 : authorityEnd + 1
+  const collectionEnd =
+    collectionStart === -1 ? -1 : uri.indexOf('/', collectionStart)
+
+  if (collectionStart !== -1) {
+    const collection =
+      collectionEnd === -1
+        ? uri.slice(collectionStart)
+        : uri.slice(collectionStart, collectionEnd)
+
+    if (collection.length === 0) {
       throw new Error(
         'ATURI can not have a slash after authority without a path segment',
       )
     }
-    try {
-      ensureValidNsid(parts[3])
-    } catch {
+    if (!isValidNsid(collection)) {
       throw new Error(
         'ATURI requires first path segment (if supplied) to be valid NSID',
       )
     }
   }
 
-  if (parts.length >= 5) {
-    if (parts[4].length === 0) {
+  const recordKeyStart = collectionEnd === -1 ? -1 : collectionEnd + 1
+  const recordKeyEnd =
+    recordKeyStart === -1 ? -1 : uri.indexOf('/', recordKeyStart)
+
+  if (recordKeyStart !== -1) {
+    if (recordKeyStart === uri.length) {
       throw new Error(
         'ATURI can not have a slash after collection, unless record key is provided',
       )
@@ -71,32 +98,14 @@ export const ensureValidAtUri = (uri: string) => {
     // would validate rkey here, but there are basically no constraints!
   }
 
-  if (parts.length >= 6) {
+  if (recordKeyEnd !== -1) {
     throw new Error(
       'ATURI path can have at most two parts, and no trailing slash',
     )
   }
-
-  if (uriParts.length >= 2 && fragmentPart == null) {
-    throw new Error('ATURI fragment must be non-empty and start with slash')
-  }
-
-  if (fragmentPart != null) {
-    if (fragmentPart.length === 0 || fragmentPart[0] !== '/') {
-      throw new Error('ATURI fragment must be non-empty and start with slash')
-    }
-    // NOTE: enforcing *some* checks here for sanity. Eg, at least no whitespace
-    if (!/^\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\]/-]*$/.test(fragmentPart)) {
-      throw new Error('Disallowed characters in ATURI fragment (ASCII)')
-    }
-  }
-
-  if (uri.length > 8 * 1024) {
-    throw new Error('ATURI is far too long')
-  }
 }
 
-export const ensureValidAtUriRegex = (uri: string): void => {
+export function ensureValidAtUriRegex(uri: string): asserts uri is AtUriString {
   // simple regex to enforce most constraints via just regex and length.
   // hand wrote this regex based on above constraints. whew!
   const aturiRegex =
@@ -117,12 +126,8 @@ export const ensureValidAtUriRegex = (uri: string): void => {
     }
   }
 
-  if (groups.collection) {
-    try {
-      ensureValidNsidRegex(groups.collection)
-    } catch {
-      throw new Error('ATURI collection path segment must be a valid NSID')
-    }
+  if (groups.collection && !isValidNsid(groups.collection)) {
+    throw new Error('ATURI collection path segment must be a valid NSID')
   }
 
   if (uri.length > 8 * 1024) {

package/src/datetime.ts

@@ -1,7 +1,20 @@
+/** 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}`}`
+
+// Allow date.toISOString() to be used where datetime format is expected
+declare global {
+  interface Date {
+    toISOString(): `${string}-${string}-${string}T${string}:${string}:${string}Z`
+  }
+}
+
 /* Validates datetime string against atproto Lexicon 'datetime' format.
  * Syntax is described at: https://atproto.com/specs/lexicon#datetime
  */
-export const ensureValidDatetime = (dtStr: string): void => {
+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())) {
@@ -33,7 +46,7 @@ export const ensureValidDatetime = (dtStr: string): void => {
 
 /* Same logic as ensureValidDatetime(), but returns a boolean instead of throwing an exception.
  */
-export const isValidDatetime = (dtStr: string): boolean => {
+export function isValidDatetime(dtStr: string): dtStr is DatetimeString {
   try {
     ensureValidDatetime(dtStr)
   } catch (err) {
@@ -56,7 +69,7 @@ export const isValidDatetime = (dtStr: string): boolean => {
  *
  * Expected output format: YYYY-MM-DDTHH:mm:ss.sssZ
  */
-export const normalizeDatetime = (dtStr: string): string => {
+export function normalizeDatetime(dtStr: string): DatetimeString {
   if (isValidDatetime(dtStr)) {
     const outStr = new Date(dtStr).toISOString()
     if (isValidDatetime(outStr)) {
@@ -96,7 +109,7 @@ export const normalizeDatetime = (dtStr: string): string => {
  *
  * 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 => {
+export const normalizeDatetimeAlways = (dtStr: string): DatetimeString => {
   try {
     return normalizeDatetime(dtStr)
   } catch (err) {

package/src/did.ts

@@ -11,7 +11,10 @@
 //   - in current atproto, only allowing did:plc and did:web. But not *forcing* this at lexicon layer
 //   - hard length limit of 8KBytes
 //   - not going to validate "percent encoding" here
-export const ensureValidDid = (did: string): void => {
+
+export type DidString<M extends string = string> = `did:${M}:${string}`
+
+export function ensureValidDid(did: string): asserts did is DidString {
   if (!did.startsWith('did:')) {
     throw new InvalidDidError('DID requires "did:" prefix')
   }
@@ -43,7 +46,7 @@ export const ensureValidDid = (did: string): void => {
   }
 }
 
-export const ensureValidDidRegex = (did: string): void => {
+export function ensureValidDidRegex(did: string): asserts did is 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)) {

package/src/handle.ts

@@ -1,5 +1,7 @@
 export const INVALID_HANDLE = 'handle.invalid'
 
+export type HandleString = `${string}.${string}`
+
 // Currently these are registration-time restrictions, not protocol-level
 // restrictions. We have a couple accounts in the wild that we need to clean up
 // before hard-disallow.
@@ -37,7 +39,9 @@ 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 const ensureValidHandle = (handle: string): void => {
+export function ensureValidHandle(
+  handle: string,
+): asserts handle is HandleString {
   // check that all chars are boring ASCII
   if (!/^[a-zA-Z0-9.-]*$/.test(handle)) {
     throw new InvalidHandleError(
@@ -74,46 +78,43 @@ export const ensureValidHandle = (handle: string): void => {
 }
 
 // simple regex translation of above constraints
-export const ensureValidHandleRegex = (handle: string): void => {
-  if (
-    !/^([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])?$/.test(
-      handle,
-    )
-  ) {
-    throw new InvalidHandleError("Handle didn't validate via regex")
-  }
+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) {
     throw new InvalidHandleError('Handle is too long (253 chars max)')
   }
+  if (!HANDLE_REGEX.test(handle)) {
+    throw new InvalidHandleError("Handle didn't validate via regex")
+  }
 }
 
-export const normalizeHandle = (handle: string): string => {
+export function normalizeHandle(handle: string): string {
   return handle.toLowerCase()
 }
 
-export const normalizeAndEnsureValidHandle = (handle: string): string => {
+export function normalizeAndEnsureValidHandle(handle: string): HandleString {
   const normalized = normalizeHandle(handle)
   ensureValidHandle(normalized)
   return normalized
 }
 
-export const isValidHandle = (handle: string): boolean => {
-  try {
-    ensureValidHandle(handle)
-  } catch (err) {
-    if (err instanceof InvalidHandleError) {
+export function isValidHandle(handle: string): handle is HandleString {
+  return handle.length <= 253 && HANDLE_REGEX.test(handle)
+}
+
+export function isValidTld(handle: string): boolean {
+  for (const tld of DISALLOWED_TLDS) {
+    if (handle.endsWith(tld)) {
       return false
     }
-    throw err
   }
-
   return true
 }
 
-export const isValidTld = (handle: string): boolean => {
-  return !DISALLOWED_TLDS.some((domain) => handle.endsWith(domain))
-}
-
 export class InvalidHandleError extends Error {}
 /** @deprecated Never used */
 export class ReservedHandleError extends Error {}

package/src/index.ts

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