@atproto/syntax 0.4.2 → 0.5.0

package/src/recordkey.ts

@@ -17,32 +17,34 @@ const RECORD_KEY_REGEX = /^[a-zA-Z0-9_~.:-]{1,512}$/
 //   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 {
+export function ensureValidRecordKey<I extends string>(
+  input: I,
+): asserts input is I & RecordKeyString {
   if (
-    rkey.length > RECORD_KEY_MAX_LENGTH ||
-    rkey.length < RECORD_KEY_MIN_LENGTH
+    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(rkey)) {
+  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 (!RECORD_KEY_REGEX.test(rkey)) {
+  if (!RECORD_KEY_REGEX.test(input)) {
     throw new InvalidRecordKeyError('record key syntax not valid (regex)')
   }
 }
 
-export function isValidRecordKey(rkey: string): rkey is RecordKeyString {
+export function isValidRecordKey<I extends string>(
+  input: I,
+): input is I & 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)
+    input.length >= RECORD_KEY_MIN_LENGTH &&
+    input.length <= RECORD_KEY_MAX_LENGTH &&
+    RECORD_KEY_REGEX.test(input) &&
+    !RECORD_KEY_INVALID_VALUES.has(input)
   )
 }
 

package/src/tid.ts

@@ -3,18 +3,20 @@ export type TidString = string
 const TID_LENGTH = 13
 const TID_REGEX = /^[234567abcdefghij][234567abcdefghijklmnopqrstuvwxyz]{12}$/
 
-export function ensureValidTid(tid: string): asserts tid is TidString {
-  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 function isValidTid(tid: string): tid is TidString {
-  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 {}

package/src/uri.ts

@@ -0,0 +1,5 @@
+export type UriString = `${string}:${string}`
+
+export function isValidUri<I extends string>(input: I): input is I & UriString {
+  return /^\w+:(?:\/\/)?[^\s/][^\s]*$/.test(input)
+}

package/tests/aturi.test.ts

@@ -1,8 +1,9 @@
 import * as fs from 'node:fs'
 import * as readline from 'node:readline'
-import { AtUri, ensureValidAtUri, ensureValidAtUriRegex } from '../src/index'
+import { describe, expect, it } from 'vitest'
+import { AtUri, ensureValidAtUri, ensureValidAtUriRegex } from '../src'
 
-describe('At Uris', () => {
+describe(AtUri, () => {
   it('parses valid at uris', () => {
     //                 input   host    path    query   hash
     type AtUriTest = [string, string, string, string, string]
@@ -521,5 +522,52 @@ describe('AtUri validation', () => {
     })
   })
 
+  it('properly checks that the did property is a valid did', () => {
+    const urip = new AtUri('at://did:example:123')
+    expect(urip.did).toBe('did:example:123')
+    urip.host = 'did:example:456'
+    expect(urip.did).toBe('did:example:456')
+    urip.host = 'foo.com'
+    expect(() => urip.did).toThrow()
+  })
+
+  it('properly checks that the collection is a valid nsid', () => {
+    const urip = new AtUri('at://foo.com')
+    expect(urip.collection).toBe('')
+    expect(() => urip.collectionSafe).toThrow()
+
+    urip.collection = 'com.example.foo'
+    expect(urip.collection).toBe('com.example.foo')
+    expect(urip.collectionSafe).toBe('com.example.foo')
+
+    urip.collection = 'com.other.foo'
+    expect(urip.collection).toBe('com.other.foo')
+    expect(urip.collectionSafe).toBe('com.other.foo')
+
+    expect(() => (urip.collection = 'not a valid nsid')).toThrow()
+    expect(urip.collection).toBe('com.other.foo') // unchanged after failed set
+
+    urip.unsafelySetCollection('not-a-valid-nsid')
+    expect(urip.collection).toBe('not-a-valid-nsid')
+    expect(() => urip.collectionSafe).toThrow()
+  })
+
+  it('properly checks that the rkey is a valid record key', () => {
+    const urip = new AtUri('at://foo.com')
+    expect(urip.rkey).toBe('')
+    expect(() => urip.rkeySafe).toThrow()
+
+    urip.rkey = 'valid_rkey-123'
+    expect(urip.rkey).toBe('valid_rkey-123')
+    expect(urip.rkeySafe).toBe('valid_rkey-123')
+
+    expect(() => (urip.rkey = 'not a valid rkey')).toThrow()
+    expect(urip.rkey).toBe('valid_rkey-123') // unchanged after failed set
+
+    urip.unsafelySetRkey('not a valid rkey')
+    expect(urip.rkey).toBe('not a valid rkey')
+    expect(() => urip.rkeySafe).toThrow()
+  })
+
   // NOTE: this package is currently more permissive than spec about AT URIs, so invalid cases are not errors
 })

package/tests/datetime.test.ts

@@ -1,5 +1,5 @@
 import * as fs from 'node:fs'
-import * as readline from 'node:readline'
+import { describe, expect, it, test } from 'vitest'
 import {
   InvalidDatetimeError,
   ensureValidDatetime,
@@ -8,67 +8,111 @@ import {
   normalizeDatetimeAlways,
 } from '../src'
 
-describe('datetime validation', () => {
-  const expectValid = (h: string) => {
-    ensureValidDatetime(h)
-    normalizeDatetime(h)
-    normalizeDatetimeAlways(h)
-  }
-  const expectInvalid = (h: string) => {
-    expect(() => ensureValidDatetime(h)).toThrow(InvalidDatetimeError)
-  }
-
-  it('conforms to interop valid datetimes', () => {
-    const lineReader = readline.createInterface({
-      input: fs.createReadStream(
-        `${__dirname}/interop-files/datetime_syntax_valid.txt`,
-      ),
-      terminal: false,
-    })
-    lineReader.on('line', (line) => {
-      if (line.startsWith('#') || line.length === 0) {
-        return
-      }
-      if (!isValidDatetime(line)) {
-        console.log(line)
-      }
-      expectValid(line)
-    })
-  })
-
-  it('conforms to interop invalid datetimes', () => {
-    const lineReader = readline.createInterface({
-      input: fs.createReadStream(
-        `${__dirname}/interop-files/datetime_syntax_invalid.txt`,
-      ),
-      terminal: false,
-    })
-    lineReader.on('line', (line) => {
-      if (line.startsWith('#') || line.length === 0) {
-        return
-      }
-      expectInvalid(line)
-    })
-  })
-
-  it('conforms to interop invalid parse (semantics) datetimes', () => {
-    const lineReader = readline.createInterface({
-      input: fs.createReadStream(
-        `${__dirname}/interop-files/datetime_parse_invalid.txt`,
-      ),
-      terminal: false,
-    })
-    lineReader.on('line', (line) => {
-      if (line.startsWith('#') || line.length === 0) {
-        return
-      }
-      expectInvalid(line)
-    })
+const interopValid = readLines(
+  `${__dirname}/interop-files/datetime_syntax_valid.txt`,
+)
+const interopInvalidSyntax = readLines(
+  `${__dirname}/interop-files/datetime_syntax_invalid.txt`,
+)
+const interopInvalidParse = readLines(
+  `${__dirname}/interop-files/datetime_parse_invalid.txt`,
+)
+
+describe(ensureValidDatetime, () => {
+  describe('valid interop', () => {
+    for (const dt of interopValid) {
+      test(dt, () => {
+        expect(() => ensureValidDatetime(dt)).not.toThrow()
+      })
+    }
+  })
+
+  describe('fails on interop (invalid syntax)', () => {
+    for (const dt of interopInvalidSyntax) {
+      test(dt, () => {
+        expect(() => ensureValidDatetime(dt)).toThrow(InvalidDatetimeError)
+      })
+    }
+  })
+
+  describe('fails on interop (invalid parse)', () => {
+    for (const dt of interopInvalidParse) {
+      test(dt, () => {
+        expect(() => ensureValidDatetime(dt)).toThrow(InvalidDatetimeError)
+      })
+    }
+  })
+
+  it('rejects datetime that normalizes past year 9999 due to negative offset', () => {
+    // 9999-12-31T23:59:00-00:01 is syntactically valid, but normalizing to
+    // UTC advances it to 10000-01-01T00:00:00Z, which is out of range
+    expect(() => ensureValidDatetime('9999-12-31T23:59:00-00:01')).toThrow(
+      InvalidDatetimeError,
+    )
+  })
+})
+
+describe(isValidDatetime, () => {
+  describe('valid interop', () => {
+    for (const dt of interopValid) {
+      test(dt, () => {
+        expect(isValidDatetime(dt)).toBe(true)
+      })
+    }
+  })
+
+  describe('fails on interop (invalid syntax)', () => {
+    for (const dt of interopInvalidSyntax) {
+      test(dt, () => {
+        expect(isValidDatetime(dt)).toBe(false)
+      })
+    }
+  })
+
+  describe('fails on interop (invalid parse)', () => {
+    for (const dt of interopInvalidParse) {
+      test(dt, () => {
+        expect(isValidDatetime(dt)).toBe(false)
+      })
+    }
+  })
+
+  it('rejects datetime that normalizes past year 9999 due to negative offset', () => {
+    // 9999-12-31T23:59:00-00:01 is syntactically valid, but normalizing to
+    // UTC advances it to 10000-01-01T00:00:00Z, which is out of range
+    expect(isValidDatetime('9999-12-31T23:59:00-00:01')).toBe(false)
   })
 })
 
-describe('normalization', () => {
-  it('normalizes datetimes', () => {
+describe(normalizeDatetime, () => {
+  describe('valid interop', () => {
+    for (const dt of interopValid) {
+      test(dt, () => {
+        expect(() => normalizeDatetime(dt)).not.toThrow()
+      })
+    }
+  })
+
+  // @NOTE Normalize will actually succeed on some of the invalid syntax cases,
+  // because it is more lenient than the regex validation.
+
+  // describe('fails on interop (invalid syntax)', () => {
+  //   for (const dt of interopInvalidSyntax) {
+  //     test(dt, () => {
+  //       expect(() => normalizeDatetime(dt)).toThrow(InvalidDatetimeError)
+  //     })
+  //   }
+  // })
+
+  describe('fails on interop (invalid parse)', () => {
+    for (const dt of interopInvalidParse) {
+      test(dt, () => {
+        expect(() => normalizeDatetime(dt)).toThrow(InvalidDatetimeError)
+      })
+    }
+  })
+
+  it('normalizes valid input', () => {
     expect(normalizeDatetime('1234-04-12T23:20:50Z')).toEqual(
       '1234-04-12T23:20:50.000Z',
     )
@@ -89,7 +133,7 @@ describe('normalization', () => {
     )
   })
 
-  it('throws on invalid normalized datetimes', () => {
+  it('throws on invalid input', () => {
     expect(() => normalizeDatetime('')).toThrow(InvalidDatetimeError)
     expect(() => normalizeDatetime('blah')).toThrow(InvalidDatetimeError)
     expect(() => normalizeDatetime('1999-19-39T23:20:50.123Z')).toThrow(
@@ -104,15 +148,58 @@ describe('normalization', () => {
     expect(() => normalizeDatetime('0001-01-01T00:00:00+01:00')).toThrow(
       InvalidDatetimeError,
     )
+    // 9999-12-31T23:59:00-00:01 is syntactically valid, but normalizing to
+    // UTC advances it to 10000-01-01T00:00:00Z, which is out of range
+    expect(() => normalizeDatetime('9999-12-31T23:59:00-00:01')).toThrow(
+      InvalidDatetimeError,
+    )
   })
+})
 
-  it('normalizes datetimes always', () => {
+describe(normalizeDatetimeAlways, () => {
+  it('normalizes valid input', () => {
     expect(normalizeDatetimeAlways('1985-04-12T23:20:50Z')).toEqual(
       '1985-04-12T23:20:50.000Z',
     )
+  })
+
+  it('normalizes invalid input', () => {
     expect(normalizeDatetimeAlways('blah')).toEqual('1970-01-01T00:00:00.000Z')
     expect(normalizeDatetimeAlways('0000-01-01T00:00:00+01:00')).toEqual(
       '1970-01-01T00:00:00.000Z',
     )
   })
+
+  describe('valid interop', () => {
+    for (const dt of interopValid) {
+      test(dt, () => {
+        // @NOTE we can't test the returned value as some will normalize while others won't.
+        expect(() => normalizeDatetimeAlways(dt)).not.toThrow()
+      })
+    }
+  })
+
+  describe('succeeds on interop (invalid syntax)', () => {
+    for (const dt of interopInvalidSyntax) {
+      test(dt, () => {
+        // @NOTE we can't test the returned value as some will normalize while others won't.
+        expect(() => normalizeDatetimeAlways(dt)).not.toThrow()
+      })
+    }
+  })
+
+  describe('succeeds on interop invalid parse', () => {
+    for (const dt of interopInvalidParse) {
+      test(dt, () => {
+        expect(normalizeDatetimeAlways(dt)).toEqual('1970-01-01T00:00:00.000Z')
+      })
+    }
+  })
 })
+
+function readLines(filePath: string): string[] {
+  return fs
+    .readFileSync(filePath, 'utf-8')
+    .split(/\r?\n/)
+    .filter((line) => !line.startsWith('#') && line.length > 0)
+}

package/tests/did.test.ts

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs'
 import * as readline from 'node:readline'
+import { describe, expect, it } from 'vitest'
 import { InvalidDidError, ensureValidDid, ensureValidDidRegex } from '../src'
 
 describe('DID permissive validation', () => {

package/tests/handle.test.ts

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs'
 import * as readline from 'node:readline'
+import { describe, expect, it } from 'vitest'
 import {
   InvalidHandleError,
   ensureValidHandle,

package/tests/language.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import { isValidLanguage, parseLanguageString } from '../src'
+
+describe(isValidLanguage, () => {
+  it('validates BCP 47', () => {
+    // valid
+    expect(isValidLanguage('de')).toEqual(true)
+    expect(isValidLanguage('de-CH')).toEqual(true)
+    expect(isValidLanguage('de-DE-1901')).toEqual(true)
+    expect(isValidLanguage('es-419')).toEqual(true)
+    expect(isValidLanguage('sl-IT-nedis')).toEqual(true)
+    expect(isValidLanguage('mn-Cyrl-MN')).toEqual(true)
+    expect(isValidLanguage('x-fr-CH')).toEqual(true)
+    expect(
+      isValidLanguage('en-GB-boont-r-extended-sequence-x-private'),
+    ).toEqual(true)
+    expect(isValidLanguage('sr-Cyrl')).toEqual(true)
+    expect(isValidLanguage('hy-Latn-IT-arevela')).toEqual(true)
+    expect(isValidLanguage('i-klingon')).toEqual(true)
+    // invalid
+    expect(isValidLanguage('')).toEqual(false)
+    expect(isValidLanguage('x')).toEqual(false)
+    expect(isValidLanguage('de-CH-')).toEqual(false)
+    expect(isValidLanguage('i-bad-grandfathered')).toEqual(false)
+  })
+})
+
+describe(parseLanguageString, () => {
+  it('parses BCP 47', () => {
+    // valid
+    expect(parseLanguageString('de')).toEqual({
+      language: 'de',
+    })
+    expect(parseLanguageString('de-CH')).toEqual({
+      language: 'de',
+      region: 'CH',
+    })
+    expect(parseLanguageString('de-DE-1901')).toEqual({
+      language: 'de',
+      region: 'DE',
+      variant: '1901',
+    })
+    expect(parseLanguageString('es-419')).toEqual({
+      language: 'es',
+      region: '419',
+    })
+    expect(parseLanguageString('sl-IT-nedis')).toEqual({
+      language: 'sl',
+      region: 'IT',
+      variant: 'nedis',
+    })
+    expect(parseLanguageString('mn-Cyrl-MN')).toEqual({
+      language: 'mn',
+      script: 'Cyrl',
+      region: 'MN',
+    })
+    expect(parseLanguageString('x-fr-CH')).toEqual({
+      privateUse: 'x-fr-CH',
+    })
+    expect(
+      parseLanguageString('en-GB-boont-r-extended-sequence-x-private'),
+    ).toEqual({
+      language: 'en',
+      region: 'GB',
+      variant: 'boont',
+      extension: 'r-extended-sequence',
+      privateUse: 'x-private',
+    })
+    expect(parseLanguageString('sr-Cyrl')).toEqual({
+      language: 'sr',
+      script: 'Cyrl',
+    })
+    expect(parseLanguageString('hy-Latn-IT-arevela')).toEqual({
+      language: 'hy',
+      script: 'Latn',
+      region: 'IT',
+      variant: 'arevela',
+    })
+    expect(parseLanguageString('i-klingon')).toEqual({
+      grandfathered: 'i-klingon',
+    })
+    // invalid
+    expect(parseLanguageString('')).toEqual(null)
+    expect(parseLanguageString('x')).toEqual(null)
+    expect(parseLanguageString('de-CH-')).toEqual(null)
+    expect(parseLanguageString('i-bad-grandfathered')).toEqual(null)
+  })
+})

package/tests/nsid.test.ts

@@ -1,4 +1,5 @@
 import * as fs from 'node:fs'
+import { describe, expect, it } from 'vitest'
 import {
   InvalidNsidError,
   NSID,

package/tests/recordkey.test.ts

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs'
 import * as readline from 'node:readline'
+import { describe, expect, it } from 'vitest'
 import { InvalidRecordKeyError, ensureValidRecordKey } from '../src'
 
 describe('recordkey validation', () => {

package/tests/tid.test.ts

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs'
 import * as readline from 'node:readline'
+import { describe, expect, it } from 'vitest'
 import { InvalidTidError, ensureValidTid } from '../src'
 
 describe('tid validation', () => {

package/tsconfig.build.json

@@ -1,9 +1,12 @@
 {
   "extends": "../../tsconfig/isomorphic.json",
+  "include": ["./src"],
+  "exclude": ["**/*.test.ts"],
   "compilerOptions": {
     "noImplicitAny": true,
+    "importHelpers": true,
+    "target": "ES2023",
     "rootDir": "./src",
     "outDir": "./dist"
-  },
-  "include": ["./src"]
+  }
 }

package/tsconfig.build.tsbuildinfo

@@ -1 +1 @@
-{"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"}
+{"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/language.ts","./src/nsid.ts","./src/recordkey.ts","./src/tid.ts","./src/uri.ts"],"version":"5.8.2"}

package/tsconfig.tests.json

@@ -1,7 +1,9 @@
 {
-  "extends": "../../tsconfig/tests.json",
+  "extends": "../../tsconfig/vitest.json",
+  "include": ["./tests", "./src/**/*.test.ts"],
   "compilerOptions": {
-    "rootDir": "."
-  },
-  "include": ["./tests"]
+    "noImplicitAny": true,
+    "rootDir": "./",
+    "baseUrl": "./"
+  }
 }

package/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineProject } from 'vitest/config'
+
+export default defineProject({
+  test: {},
+})

package/jest.config.js

@@ -1,7 +0,0 @@
-/** @type {import('jest').Config} */
-module.exports = {
-  displayName: 'Syntax',
-  transform: { '^.+\\.(t|j)s$': '@swc/jest' },
-  setupFiles: ['<rootDir>/../../jest.setup.ts'],
-  moduleNameMapper: { '^(\\.\\.?\\/.+)\\.js$': ['$1.ts', '$1.js'] },
-}

package/tsconfig.tests.tsbuildinfo

@@ -1 +0,0 @@
-{"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"}