@atproto/syntax 0.4.1 → 0.4.3

package/src/aturi_validation.ts

@@ -1,6 +1,12 @@
-import { ensureValidDid, ensureValidDidRegex } from './did'
-import { ensureValidHandle, ensureValidHandleRegex } from './handle'
-import { isValidNsid } 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,53 +21,78 @@ import { isValidNsid } 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<I extends string>(
+  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')
+    }
+
+    // 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',
       )
     }
-    if (!isValidNsid(parts[3])) {
+    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',
       )
@@ -69,37 +100,21 @@ 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<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 = uri.match(aturiRegex)
+  const rm = input.match(aturiRegex)
   if (!rm || !rm.groups) {
     throw new Error("ATURI didn't validate via regex")
   }
@@ -119,7 +134,19 @@ export const ensureValidAtUriRegex = (uri: string): void => {
     throw new Error('ATURI collection path segment must be a valid NSID')
   }
 
-  if (uri.length > 8 * 1024) {
+  if (input.length > 8 * 1024) {
     throw new Error('ATURI is far too long')
   }
 }
+
+export function isValidAtUri<I extends string>(
+  input: I,
+): input is I & AtUriString {
+  try {
+    ensureValidAtUriRegex(input)
+  } catch {
+    return false
+  }
+
+  return true
+}

package/src/datetime.ts

@@ -1,8 +1,21 @@
+/** 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 => {
-  const date = new Date(dtStr)
+export function ensureValidDatetime<I extends string>(
+  input: I,
+): asserts input is I & DatetimeString {
+  const date = new Date(input)
   // 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')
@@ -13,34 +26,33 @@ export const ensureValidDatetime = (dtStr: string): void => {
   // 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,
+      input,
     )
   ) {
     throw new InvalidDatetimeError("datetime didn't validate via regex")
   }
-  if (dtStr.length > 64) {
+  if (input.length > 64) {
     throw new InvalidDatetimeError('datetime is too long (64 chars max)')
   }
-  if (dtStr.endsWith('-00:00')) {
+  if (input.endsWith('-00:00')) {
     throw new InvalidDatetimeError(
       'datetime can not use "-00:00" for UTC timezone',
     )
   }
-  if (dtStr.startsWith('000')) {
+  if (input.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 => {
+export function isValidDatetime<I extends string>(
+  input: I,
+): input is I & DatetimeString {
   try {
-    ensureValidDatetime(dtStr)
+    ensureValidDatetime(input)
   } catch (err) {
-    if (err instanceof InvalidDatetimeError) {
-      return false
-    }
-    throw err
+    return false
   }
 
   return true
@@ -56,7 +68,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 +108,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,19 +11,32 @@
 //   - 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 => {
-  if (!did.startsWith('did:')) {
+
+export type DidString<M extends string = string> = `did:${M}:${string}`
+
+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',
@@ -33,26 +46,26 @@ export const ensureValidDid = (did: string): void => {
   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 const ensureValidDidRegex = (did: string): void => {
+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

@@ -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,18 +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 const ensureValidHandle = (handle: string): void => {
+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')
   }
@@ -74,46 +78,45 @@ 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")
-  }
-  if (handle.length > 253) {
+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<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(input)) {
+    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<I extends string>(
+  input: I,
+): input is I & HandleString {
+  return input.length <= 253 && HANDLE_REGEX.test(input)
+}
+
+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,10 @@
-export * from './handle'
-export * from './did'
-export * from './nsid'
-export * from './aturi'
-export * from './tid'
-export * from './recordkey'
-export * from './datetime'
+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 './language.js'
+export * from './recordkey.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

@@ -11,6 +11,8 @@ nsid      = authority delim name
 
 */
 
+export type NsidString = `${string}.${string}.${string}`
+
 export class NSID {
   readonly segments: readonly string[]
 
@@ -58,8 +60,10 @@ export class NSID {
   }
 }
 
-export function ensureValidNsid(nsid: string): void {
-  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)
 }
 
@@ -69,10 +73,12 @@ export function parseNsid(nsid: string): string[] {
   return result.value
 }
 
-export function isValidNsid(nsid: string): boolean {
+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> =
@@ -142,7 +148,7 @@ export function validateNsid(input: string): ValidateResult<string[]> {
   }
 }
 
-function hasDisallowedCharacters(v) {
+function hasDisallowedCharacters(v: string) {
   return !/^[a-zA-Z0-9.-]*$/.test(v)
 }
 
@@ -173,7 +179,7 @@ function isValidIdentifier(v: string) {
  * {@link parseNsid}/{@link NSID.parse} if you need the parsed segments, or
  * {@link isValidNsid} if you just want a boolean.
  */
-export function ensureValidNsidRegex(nsid: string): void {
+export function ensureValidNsidRegex(nsid: string): asserts nsid is NsidString {
   const result = validateNsidRegex(nsid)
   if (!result.success) throw new InvalidNsidError(result.message)
 }
@@ -182,7 +188,7 @@ export function ensureValidNsidRegex(nsid: string): void {
  * 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<string> {
+export function validateNsidRegex(value: string): ValidateResult<NsidString> {
   if (value.length > 253 + 1 + 63) {
     return {
       success: false,
@@ -203,7 +209,7 @@ export function validateNsidRegex(value: string): ValidateResult<string> {
 
   return {
     success: true,
-    value,
+    value: value as NsidString,
   }
 }
 

package/src/recordkey.ts

@@ -1,26 +1,51 @@
-export const ensureValidRecordKey = (rkey: string): void => {
-  if (rkey.length > 512 || rkey.length < 1) {
-    throw new InvalidRecordKeyError('record key must be 1 to 512 characters')
+export type RecordKeyString = string
+
+const RECORD_KEY_MAX_LENGTH = 512
+const RECORD_KEY_MIN_LENGTH = 1
+const RECORD_KEY_INVALID_VALUES = new Set(['.', '..'])
+const RECORD_KEY_REGEX = /^[a-zA-Z0-9_~.:-]{1,512}$/
+
+// https://atproto.com/specs/record-key#record-key-syntax
+// Regardless of the type, Record Keys must fulfill some baseline syntax constraints:
+// - restricted to a subset of ASCII characters -- the allowed characters are
+//   alphanumeric (A-Za-z0-9), period, dash, underscore, colon, or tilde (.-_:~)
+// - must have at least 1 and at most 512 characters
+// - the specific record key values . and .. are not allowed
+// - must be a permissible part of repository MST path string (the above
+//   constraints satisfy this condition)
+// - must be permissible to include in a path component of a URI (following
+//   RFC-3986, section 3.3). The above constraints satisfy this condition, by
+//   matching the "unreserved" characters allowed in generic URI paths.
+
+export function ensureValidRecordKey<I extends string>(
+  input: I,
+): asserts input is I & RecordKeyString {
+  if (
+    input.length > RECORD_KEY_MAX_LENGTH ||
+    input.length < RECORD_KEY_MIN_LENGTH
+  ) {
+    throw new InvalidRecordKeyError(
+      `record key must be ${RECORD_KEY_MIN_LENGTH} to ${RECORD_KEY_MAX_LENGTH} characters`,
+    )
+  }
+  if (RECORD_KEY_INVALID_VALUES.has(input)) {
+    throw new InvalidRecordKeyError('record key can not be "." or ".."')
   }
   // simple regex to enforce most constraints via just regex and length.
-  if (!/^[a-zA-Z0-9_~.:-]{1,512}$/.test(rkey)) {
+  if (!RECORD_KEY_REGEX.test(input)) {
     throw new InvalidRecordKeyError('record key syntax not valid (regex)')
   }
-  if (rkey === '.' || rkey === '..')
-    throw new InvalidRecordKeyError('record key can not be "." or ".."')
 }
 
-export const isValidRecordKey = (rkey: string): boolean => {
-  try {
-    ensureValidRecordKey(rkey)
-  } catch (err) {
-    if (err instanceof InvalidRecordKeyError) {
-      return false
-    }
-    throw err
-  }
-
-  return true
+export function isValidRecordKey<I extends string>(
+  input: I,
+): input is I & RecordKeyString {
+  return (
+    input.length >= RECORD_KEY_MIN_LENGTH &&
+    input.length <= RECORD_KEY_MAX_LENGTH &&
+    RECORD_KEY_REGEX.test(input) &&
+    !RECORD_KEY_INVALID_VALUES.has(input)
+  )
 }
 
 export class InvalidRecordKeyError extends Error {}

package/src/tid.ts

@@ -1,18 +1,22 @@
+export type TidString = string
+
 const TID_LENGTH = 13
 const TID_REGEX = /^[234567abcdefghij][234567abcdefghijklmnopqrstuvwxyz]{12}$/
 
-export const ensureValidTid = (tid: string): void => {
-  if (tid.length !== TID_LENGTH) {
+export function ensureValidTid<I extends string>(
+  input: I,
+): asserts input is I & TidString {
+  if (input.length !== TID_LENGTH) {
     throw new InvalidTidError(`TID must be ${TID_LENGTH} characters`)
   }
   // simple regex to enforce most constraints via just regex and length.
-  if (!TID_REGEX.test(tid)) {
+  if (!TID_REGEX.test(input)) {
     throw new InvalidTidError('TID syntax not valid (regex)')
   }
 }
 
-export const isValidTid = (tid: string): boolean => {
-  return tid.length === TID_LENGTH && TID_REGEX.test(tid)
+export function isValidTid<I extends string>(input: I): input is I & TidString {
+  return input.length === TID_LENGTH && TID_REGEX.test(input)
 }
 
 export class InvalidTidError extends Error {}