@atproto/syntax

npm install @atproto/syntax

import { isValidDid, ensureValidDid } from '@atproto/syntax'

// Type guard - returns boolean
if (isValidDid('did:plc:abc123xyz')) {
  console.log('Valid DID')
}

// Assertion - throws on invalid
try {
  ensureValidDid('did:plc:abc123xyz')
  console.log('DID is valid')
} catch (err) {
  console.error('Invalid DID:', err.message)
}

type DidString<M extends string = string> = `did:${M}:${string}`

'did:plc:ewvi7nxzyoun6zhxrhs64oiz' // ✓ valid
'did:web:example.com'              // ✓ valid
'DID:plc:abc'                      // ✗ invalid (uppercase)
'did:plc:'                         // ✗ invalid (ends with :)

import { 
  isValidHandle, 
  ensureValidHandle,
  normalizeHandle,
  isValidTld
} from '@atproto/syntax'

// Validate handle
if (isValidHandle('alice.bsky.social')) {
  console.log('Valid handle')
}

// Normalize (lowercase)
const normalized = normalizeHandle('Alice.BSKY.Social')
console.log(normalized) // 'alice.bsky.social'

// Validate TLD
if (!isValidTld('alice.local')) {
  console.log('Disallowed TLD')
}

type HandleString = `${string}.${string}`

'alice.bsky.social'  // ✓ valid
'bob.com'            // ✓ valid
'charlie'            // ✗ invalid (no TLD)
'alice.local'        // ✗ invalid (disallowed TLD)
'-invalid.com'       // ✗ invalid (starts with hyphen)

import { NSID } from '@atproto/syntax'

// Parse NSID
const nsid = NSID.parse('com.example.song')
console.log(nsid.authority) // 'example.com'
console.log(nsid.name)      // 'song'
console.log(nsid.toString()) // 'com.example.song'

// Create from parts
const nsid2 = NSID.create('example.com', 'post')
console.log(nsid2.toString()) // 'com.example.post'

// Validate
if (NSID.isValid('com.atproto.repo.createRecord')) {
  console.log('Valid NSID')
}

import { isValidNsid, ensureValidNsid } from '@atproto/syntax'

if (isValidNsid('com.example.song')) {
  console.log('Valid NSID')
}

ensureValidNsid('com.example.song') // throws if invalid

type NsidString = `${string}.${string}.${string}`

'com.atproto.repo.createRecord' // ✓ valid
'com.example.song'              // ✓ valid
'example.song'                  // ✗ invalid (only 2 segments)
'com.example.my-song'           // ✗ invalid (hyphen in name)

import { AtUri } from '@atproto/syntax'

// Parse AT URI
const uri = new AtUri('at://bob.com/app.bsky.feed.post/3jzfcijpj2z2a')

console.log(uri.protocol)    // 'at:'
console.log(uri.host)        // 'bob.com'
console.log(uri.hostname)    // 'bob.com'
console.log(uri.collection)  // 'app.bsky.feed.post'
console.log(uri.rkey)        // '3jzfcijpj2z2a'
console.log(uri.pathname)    // '/app.bsky.feed.post/3jzfcijpj2z2a'

// Get DID (if host is DID)
const uri2 = new AtUri('at://did:plc:abc/app.bsky.feed.post/123')
console.log(uri2.did) // 'did:plc:abc'

// Construct from parts
const uri3 = AtUri.make('alice.bsky.social', 'app.bsky.feed.post', '3k2akjd')
console.log(uri3.toString()) 
// 'at://alice.bsky.social/app.bsky.feed.post/3k2akjd'

// With query params
const uri4 = new AtUri('at://bob.com/collection/rkey?param=value')
console.log(uri4.searchParams.get('param')) // 'value'

type AtUriString = `at://${string}`

at://authority/collection/rkey?query#fragment

'at://bob.com/app.bsky.feed.post/123'               // ✓ valid
'at://did:plc:abc/app.bsky.actor.profile/self'     // ✓ valid
'at://alice.com'                                    // ✓ valid (repo only)
'at://bob.com/app.bsky.feed.post/123?cursor=xyz'   // ✓ valid (with query)

import { isValidTid, ensureValidTid } from '@atproto/syntax'

if (isValidTid('3jzfcijpj2z2a')) {
  console.log('Valid TID')
}

ensureValidTid('3jzfcijpj2z2a') // throws if invalid

type TidString = string

'3jzfcijpj2z2a' // ✓ valid
'3k2akjd8fj3la' // ✓ valid
'1234567890123' // ✗ invalid (starts with 1)
'3jzfcijpj2z'   // ✗ invalid (too short)

import { isValidRecordKey, ensureValidRecordKey } from '@atproto/syntax'

if (isValidRecordKey('3jzfcijpj2z2a')) {
  console.log('Valid record key')
}

if (isValidRecordKey('self')) {
  console.log('Valid literal key')
}

ensureValidRecordKey('my-record-123') // throws if invalid

type RecordKeyString = string

'3jzfcijpj2z2a'     // ✓ valid (TID)
'self'              // ✓ valid (literal)
'my-record'         // ✓ valid
'2023-01-01'        // ✓ valid
'.'                 // ✗ invalid
'..'                // ✗ invalid
'invalid/key'       // ✗ invalid (slash not allowed)

import { isValidDatetime, ensureValidDatetime } from '@atproto/syntax'

const dt = new Date().toISOString()

if (isValidDatetime(dt)) {
  console.log('Valid datetime')
}

ensureValidDatetime('2024-01-15T12:30:00.000Z') // throws if invalid

import {
  isValidDid,
  isValidHandle,
  NSID,
  AtUri,
  isValidTid,
  isValidRecordKey
} from '@atproto/syntax'

// Validate identifiers
const did = 'did:plc:ewvi7nxzyoun6zhxrhs64oiz'
const handle = 'alice.bsky.social'

if (isValidDid(did) && isValidHandle(handle)) {
  console.log('Valid identifiers')
}

// Parse NSID
const nsid = NSID.parse('app.bsky.feed.post')
console.log(`Authority: ${nsid.authority}, Name: ${nsid.name}`)

// Parse AT URI
const uri = new AtUri(`at://${did}/${nsid.toString()}/3jzfcijpj2z2a`)
console.log('URI components:', {
  host: uri.host,
  collection: uri.collection,
  rkey: uri.rkey
})

// Validate record key
const rkey = uri.rkey
if (isValidTid(rkey)) {
  console.log('Record key is a TID')
} else if (isValidRecordKey(rkey)) {
  console.log('Record key is valid')
}

// Construct new URI
const newUri = AtUri.make(
  handle,
  'app.bsky.actor.profile',
  'self'
)
console.log('Profile URI:', newUri.toString())
// at://alice.bsky.social/app.bsky.actor.profile/self

// Work with query parameters
const queryUri = new AtUri(
  `at://${handle}/app.bsky.feed.post?cursor=abc&limit=50`
)
console.log('Cursor:', queryUri.searchParams.get('cursor'))
console.log('Limit:', queryUri.searchParams.get('limit'))

import { InvalidDidError, ensureValidDid } from '@atproto/syntax'

try {
  ensureValidDid('not-a-did')
} catch (err) {
  if (err instanceof InvalidDidError) {
    console.error('DID validation failed:', err.message)
  }
}