@atproto/syntax 0.4.0 → 0.4.2

package/src/nsid.ts

@@ -6,35 +6,42 @@ number    = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" / "0"
 delim     = "."
 segment   = alpha *( alpha / number / "-" )
 authority = segment *( delim segment )
-name      = alpha *( alpha )
+name      = alpha *( alpha / number )
 nsid      = authority delim name
 
 */
 
+export type NsidString = `${string}.${string}.${string}`
+
 export class NSID {
-  segments: string[] = []
+  readonly segments: readonly string[]
 
-  static parse(nsid: string): NSID {
-    return new NSID(nsid)
+  static parse(input: string): NSID {
+    return new NSID(input)
   }
 
   static create(authority: string, name: string): NSID {
-    const segments = [...authority.split('.').reverse(), name].join('.')
-    return new NSID(segments)
+    const input = [...authority.split('.').reverse(), name].join('.')
+    return new NSID(input)
+  }
+
+  static isValid(nsid: string) {
+    return isValidNsid(nsid)
   }
 
-  static isValid(nsid: string): boolean {
-    try {
-      NSID.parse(nsid)
-      return true
-    } catch (e) {
-      return false
+  static from(input: { toString: () => string }): NSID {
+    if (input instanceof NSID) {
+      // No need to clone, NSID is immutable
+      return input
     }
+    if (Array.isArray(input)) {
+      return new NSID((input as string[]).join('.'))
+    }
+    return new NSID(String(input))
   }
 
   constructor(nsid: string) {
-    ensureValidNsid(nsid)
-    this.segments = nsid.split('.')
+    this.segments = parseNsid(nsid)
   }
 
   get authority() {
@@ -53,60 +60,152 @@ export class NSID {
   }
 }
 
+export function ensureValidNsid(nsid: string): asserts nsid is NsidString {
+  const result = validateNsid(nsid)
+  if (!result.success) throw new InvalidNsidError(result.message)
+}
+
+export function parseNsid(nsid: string): string[] {
+  const result = validateNsid(nsid)
+  if (!result.success) throw new InvalidNsidError(result.message)
+  return result.value
+}
+
+export function isValidNsid(nsid: string): nsid is 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
+}
+
+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 const ensureValidNsid = (nsid: string): void => {
-  const toCheck = nsid
-
-  // check that all chars are boring ASCII
-  if (!/^[a-zA-Z0-9.-]*$/.test(toCheck)) {
-    throw new InvalidNsidError(
-      'Disallowed characters in NSID (ASCII letters, digits, dashes, periods only)',
-    )
+export function validateNsid(input: string): ValidateResult<string[]> {
+  if (input.length > 253 + 1 + 63) {
+    return {
+      success: false,
+      message: 'NSID is too long (317 chars max)',
+    }
   }
-
-  if (toCheck.length > 253 + 1 + 63) {
-    throw new InvalidNsidError('NSID is too long (317 chars max)')
+  if (hasDisallowedCharacters(input)) {
+    return {
+      success: false,
+      message:
+        'Disallowed characters in NSID (ASCII letters, digits, dashes, periods only)',
+    }
   }
-  const labels = toCheck.split('.')
-  if (labels.length < 3) {
-    throw new InvalidNsidError('NSID needs at least three parts')
+  const segments = input.split('.')
+  if (segments.length < 3) {
+    return {
+      success: false,
+      message: 'NSID needs at least three parts',
+    }
   }
-  for (let i = 0; i < labels.length; i++) {
-    const l = labels[i]
+  for (const l of segments) {
     if (l.length < 1) {
-      throw new InvalidNsidError('NSID parts can not be empty')
+      return {
+        success: false,
+        message: 'NSID parts can not be empty',
+      }
     }
     if (l.length > 63) {
-      throw new InvalidNsidError('NSID part too long (max 63 chars)')
+      return {
+        success: false,
+        message: 'NSID part too long (max 63 chars)',
+      }
     }
-    if (l.endsWith('-') || l.startsWith('-')) {
-      throw new InvalidNsidError('NSID parts can not start or end with hyphen')
+    if (startsWithHyphen(l) || endsWithHyphen(l)) {
+      return {
+        success: false,
+        message: 'NSID parts can not start or end with hyphen',
+      }
     }
-    if (/^[0-9]/.test(l) && i === 0) {
-      throw new InvalidNsidError('NSID first part may not start with a digit')
+  }
+  if (startsWithNumber(segments[0])) {
+    return {
+      success: false,
+      message: 'NSID first part may not start with a digit',
     }
-    if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(l) && i + 1 === labels.length) {
-      throw new InvalidNsidError(
+  }
+  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,
+  }
+}
+
+function hasDisallowedCharacters(v: string) {
+  return !/^[a-zA-Z0-9.-]*$/.test(v)
+}
+
+function startsWithNumber(v: string) {
+  const charCode = v.charCodeAt(0)
+  return charCode >= 48 && charCode <= 57
 }
 
-export const ensureValidNsidRegex = (nsid: string): void => {
-  // simple regex to enforce most constraints via just regex and length.
-  // hand wrote this regex based on above constraints
+function startsWithHyphen(v: string) {
+  return v.charCodeAt(0) === 45 /* - */
+}
+
+function endsWithHyphen(v: string) {
+  return v.charCodeAt(v.length - 1) === 45 /* - */
+}
+
+function isValidIdentifier(v: string) {
+  // Note, since we already know that "v" only contains [a-zA-Z0-9-], we can
+  // simplify the following regex by checking only the first char and presence
+  // of "-".
+
+  // return /^[a-zA-Z][a-zA-Z0-9]*$/.test(v)
+  return !startsWithNumber(v) && !v.includes('-')
+}
+
+/**
+ * @deprecated Use {@link ensureValidNsid} if you care about error details,
+ * {@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): asserts nsid is NsidString {
+  const result = validateNsidRegex(nsid)
+  if (!result.success) throw new InvalidNsidError(result.message)
+}
+
+/**
+ * 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> {
+  if (value.length > 253 + 1 + 63) {
+    return {
+      success: false,
+      message: 'NSID is too long (317 chars max)',
+    }
+  }
+
   if (
-    !/^[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(
-      nsid,
+    !/^[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,
     )
   ) {
-    throw new InvalidNsidError("NSID didn't validate via regex")
+    return {
+      success: false,
+      message: "NSID didn't validate via regex",
+    }
   }
-  if (nsid.length > 253 + 1 + 63) {
-    throw new InvalidNsidError('NSID is too long (317 chars max)')
+
+  return {
+    success: true,
+    value: value as NsidString,
   }
 }
 

package/src/recordkey.ts

@@ -1,26 +1,49 @@
-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(
+  rkey: string,
+): asserts rkey is RecordKeyString {
+  if (
+    rkey.length > RECORD_KEY_MAX_LENGTH ||
+    rkey.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(rkey)) {
+    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(rkey)) {
     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(rkey: string): rkey is RecordKeyString {
+  return (
+    rkey.length >= RECORD_KEY_MIN_LENGTH &&
+    rkey.length <= RECORD_KEY_MAX_LENGTH &&
+    RECORD_KEY_REGEX.test(rkey) &&
+    !RECORD_KEY_INVALID_VALUES.has(rkey)
+  )
 }
 
 export class InvalidRecordKeyError extends Error {}

package/src/tid.ts

@@ -1,7 +1,9 @@
+export type TidString = string
+
 const TID_LENGTH = 13
 const TID_REGEX = /^[234567abcdefghij][234567abcdefghijklmnopqrstuvwxyz]{12}$/
 
-export const ensureValidTid = (tid: string): void => {
+export function ensureValidTid(tid: string): asserts tid is TidString {
   if (tid.length !== TID_LENGTH) {
     throw new InvalidTidError(`TID must be ${TID_LENGTH} characters`)
   }
@@ -11,7 +13,7 @@ export const ensureValidTid = (tid: string): void => {
   }
 }
 
-export const isValidTid = (tid: string): boolean => {
+export function isValidTid(tid: string): tid is TidString {
   return tid.length === TID_LENGTH && TID_REGEX.test(tid)
 }
 

package/tests/nsid.test.ts

@@ -1,10 +1,12 @@
 import * as fs from 'node:fs'
-import * as readline from 'node:readline'
 import {
   InvalidNsidError,
   NSID,
   ensureValidNsid,
-  ensureValidNsidRegex,
+  isValidNsid,
+  parseNsid,
+  validateNsid,
+  validateNsidRegex,
 } from '../src'
 
 describe('NSID parsing & creation', () => {
@@ -39,12 +41,30 @@ describe('NSID parsing & creation', () => {
 
 describe('NSID validation', () => {
   const expectValid = (h: string) => {
+    expect(isValidNsid(h)).toBe(true)
     ensureValidNsid(h)
-    ensureValidNsidRegex(h)
+    expect(parseNsid(h)).toEqual(h.split('.'))
+    expect(validateNsidRegex(h)).toMatchObject({
+      success: true,
+      value: expect.any(String),
+    })
+    expect(validateNsid(h)).toMatchObject({
+      success: true,
+      value: expect.any(Array),
+    })
   }
   const expectInvalid = (h: string) => {
+    expect(isValidNsid(h)).toBe(false)
+    expect(() => parseNsid(h)).toThrow(InvalidNsidError)
     expect(() => ensureValidNsid(h)).toThrow(InvalidNsidError)
-    expect(() => ensureValidNsidRegex(h)).toThrow(InvalidNsidError)
+    expect(validateNsidRegex(h)).toMatchObject({
+      success: false,
+      message: expect.any(String),
+    })
+    expect(validateNsid(h)).toMatchObject({
+      success: false,
+      message: expect.any(String),
+    })
   }
 
   it('enforces spec details', () => {
@@ -68,91 +88,111 @@ describe('NSID validation', () => {
     const tooLongOverall = 'com.' + 'middle.'.repeat(50) + 'foo'
     expect(tooLongOverall.length).toBe(357)
     expectInvalid(tooLongOverall)
-
-    expectValid('com.example.fooBar')
-    expectValid('net.users.bob.ping')
-    expectValid('a.b.c')
-    expectValid('m.xn--masekowski-d0b.pl')
-    expectValid('one.two.three')
-    expectValid('one.two.three.four-and.FiVe')
-    expectValid('one.2.three')
-    expectValid('a-0.b-1.c')
-    expectValid('a0.b1.cc')
-    expectValid('cn.8.lex.stuff')
-    expectValid('test.12345.record')
-    expectValid('a01.thing.record')
-    expectValid('a.0.c')
-    expectValid('xn--fiqs8s.xn--fiqa61au8b7zsevnm8ak20mc4a87e.record.two')
-    expectValid('a0.b1.c3')
-    expectValid('com.example.f00')
-
-    expectInvalid('com.example.foo.*')
-    expectInvalid('com.example.foo.blah*')
-    expectInvalid('com.example.foo.*blah')
-    expectInvalid('com.exa💩ple.thing')
-    expectInvalid('a-0.b-1.c-3')
-    expectInvalid('a-0.b-1.c-o')
-    expectInvalid('1.0.0.127.record')
-    expectInvalid('0two.example.foo')
-    expectInvalid('example.com')
-    expectInvalid('com.example')
-    expectInvalid('a.')
-    expectInvalid('.one.two.three')
-    expectInvalid('one.two.three ')
-    expectInvalid('one.two..three')
-    expectInvalid('one .two.three')
-    expectInvalid(' one.two.three')
-    expectInvalid('com.exa💩ple.thing')
-    expectInvalid('com.atproto.feed.p@st')
-    expectInvalid('com.atproto.feed.p_st')
-    expectInvalid('com.atproto.feed.p*st')
-    expectInvalid('com.atproto.feed.po#t')
-    expectInvalid('com.atproto.feed.p!ot')
-    expectInvalid('com.example-.foo')
   })
 
-  it('allows onion (Tor) NSIDs', () => {
-    expectValid('onion.expyuzz4wqqyqhjn.spec.getThing')
-    expectValid(
+  describe('valid NSIDs', () => {
+    for (const validNsid of [
+      'com.example.foo',
+      'o'.repeat(63) + '.foo.bar',
+      'com.' + 'o'.repeat(63) + '.foo',
+      'com.example.' + 'o'.repeat(63),
+      'com.' + 'middle.'.repeat(40) + 'foo',
+
+      'a-0.b-1.c',
+      'a.0.c',
+      'a.b.c',
+      'a0.b1.c3',
+      'a0.b1.cc',
+      'a01.thing.record',
+      'cn.8.lex.stuff',
+      'com.example.f00',
+      'com.example.fooBar',
+      'm.xn--masekowski-d0b.pl',
+      'net.users.bob.ping',
+      'one.2.three',
+      'one.two.three',
+      'one.two.three.four-and.FiVe',
+      'onion.2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.lex.deleteThing',
+      'onion.expyuzz4wqqyqhjn.spec.getThing',
       'onion.g2zyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.lex.deleteThing',
-    )
+      'org.4chan.lex.getThing',
+      'test.12345.record',
+      'xn--fiqs8s.xn--fiqa61au8b7zsevnm8ak20mc4a87e.record.two',
+    ]) {
+      it(validNsid, () => {
+        expectValid(validNsid)
+      })
+    }
   })
 
-  it('allows starting-with-numeric segments (same as domains)', () => {
-    expectValid('org.4chan.lex.getThing')
-    expectValid('cn.8.lex.stuff')
-    expectValid(
-      'onion.2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.lex.deleteThing',
-    )
+  describe('invalid NSIDs', () => {
+    for (const invalidNsid of [
+      'o'.repeat(64) + '.foo.bar',
+      'com.' + 'o'.repeat(64) + '.foo',
+      'com.example.' + 'o'.repeat(64),
+      'com.' + 'middle.'.repeat(50) + 'foo',
+      'com.example.foo.*',
+      'com.example.foo.blah*',
+      'com.example.foo.*blah',
+      'com.exa💩ple.thing',
+      'a-0.b-1.c-3',
+      'a-0.b-1.c-o',
+      '1.0.0.127.record',
+      '0two.example.foo',
+      'example.com',
+      'com.example',
+      'a.',
+      '.one.two.three',
+      'one.two.three ',
+      'one.two..three',
+      'one .two.three',
+      ' one.two.three',
+      'com.atproto.feed.p@st',
+      'com.atproto.feed.p_st',
+      'com.atproto.feed.p*st',
+      'com.atproto.feed.po#t',
+      'com.atproto.feed.p!ot',
+      'com.example-.foo',
+      'com.-example.foo',
+      'com.example.0foo',
+      'com.example.f-o',
+    ]) {
+      it(invalidNsid, () => {
+        expect(validateNsid(invalidNsid)).toMatchObject({
+          success: false,
+          message: expect.any(String),
+        })
+      })
+    }
   })
 
-  it('conforms to interop valid NSIDs', () => {
-    const lineReader = readline.createInterface({
-      input: fs.createReadStream(
-        `${__dirname}/interop-files/nsid_syntax_valid.txt`,
-      ),
-      terminal: false,
-    })
-    lineReader.on('line', (line) => {
+  describe('conforms to interop valid NSIDs', () => {
+    for (const line of fs
+      .readFileSync(`${__dirname}/interop-files/nsid_syntax_valid.txt`)
+      .toString()
+      .split('\n')) {
       if (line.startsWith('#') || line.length === 0) {
-        return
+        continue
       }
-      expectValid(line)
-    })
+
+      it(line, () => {
+        expectValid(line)
+      })
+    }
   })
 
-  it('conforms to interop invalid NSIDs', () => {
-    const lineReader = readline.createInterface({
-      input: fs.createReadStream(
-        `${__dirname}/interop-files/nsid_syntax_invalid.txt`,
-      ),
-      terminal: false,
-    })
-    lineReader.on('line', (line) => {
+  describe('conforms to interop invalid NSIDs', () => {
+    for (const line of fs
+      .readFileSync(`${__dirname}/interop-files/nsid_syntax_invalid.txt`)
+      .toString()
+      .split('\n')) {
       if (line.startsWith('#') || line.length === 0) {
-        return
+        continue
       }
-      expectInvalid(line)
-    })
+
+      it(line, () => {
+        expectInvalid(line)
+      })
+    }
   })
 })

package/tsconfig.build.json

@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig/isomorphic.json",
   "compilerOptions": {
+    "noImplicitAny": true,
     "rootDir": "./src",
     "outDir": "./dist"
   },

package/tsconfig.build.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/aturi.ts","./src/aturi_validation.ts","./src/datetime.ts","./src/did.ts","./src/handle.ts","./src/index.ts","./src/nsid.ts","./src/recordkey.ts","./src/tid.ts"],"version":"5.6.3"}
+{"root":["./src/at-identifier.ts","./src/aturi.ts","./src/aturi_validation.ts","./src/datetime.ts","./src/did.ts","./src/handle.ts","./src/index.ts","./src/nsid.ts","./src/recordkey.ts","./src/tid.ts"],"version":"5.8.2"}

package/tsconfig.tests.tsbuildinfo

@@ -1 +1 @@
-{"root":["./tests/aturi.test.ts","./tests/datetime.test.ts","./tests/did.test.ts","./tests/handle.test.ts","./tests/nsid.test.ts","./tests/recordkey.test.ts","./tests/tid.test.ts"],"version":"5.6.3"}
+{"root":["./tests/aturi.test.ts","./tests/datetime.test.ts","./tests/did.test.ts","./tests/handle.test.ts","./tests/nsid.test.ts","./tests/recordkey.test.ts","./tests/tid.test.ts"],"version":"5.8.3"}