@atproto/lex-data 0.0.0

package/src/blob.ts

@@ -0,0 +1,99 @@
+import { CID, RAW_BIN_MULTICODEC, SHA2_256_MULTIHASH_CODE } from './cid.js'
+import { isPlainObject } from './object.js'
+
+export type BlobRef = {
+  $type: 'blob'
+  mimeType: string
+  ref: CID
+  size: number
+}
+
+export function isBlobRef(
+  input: unknown,
+  options?: { strict?: boolean },
+): input is BlobRef {
+  if (!isPlainObject(input)) {
+    return false
+  }
+
+  if (input?.$type !== 'blob') {
+    return false
+  }
+
+  const { mimeType, size, ref } = input
+  if (typeof mimeType !== 'string') {
+    return false
+  }
+
+  if (typeof size !== 'number' || size < 0 || !Number.isInteger(size)) {
+    return false
+  }
+
+  if (typeof ref !== 'object' || ref === null) {
+    return false
+  }
+
+  for (const key in input) {
+    if (
+      key !== '$type' &&
+      key !== 'mimeType' &&
+      key !== 'ref' &&
+      key !== 'size'
+    ) {
+      return false
+    }
+  }
+
+  const cid = CID.asCID(ref)
+  if (!cid) {
+    return false
+  }
+
+  if (options?.strict) {
+    if (cid.version !== 1) {
+      return false
+    }
+    if (cid.code !== RAW_BIN_MULTICODEC) {
+      return false
+    }
+    if (cid.multihash.code !== SHA2_256_MULTIHASH_CODE) {
+      return false
+    }
+  }
+
+  return true
+}
+
+export type LegacyBlobRef = {
+  cid: string
+  mimeType: string
+}
+
+export function isLegacyBlobRef(input: unknown): input is LegacyBlobRef {
+  if (!isPlainObject(input)) {
+    return false
+  }
+
+  const { cid, mimeType } = input
+  if (typeof cid !== 'string') {
+    return false
+  }
+
+  if (typeof mimeType !== 'string') {
+    return false
+  }
+
+  for (const key in input) {
+    if (key !== 'cid' && key !== 'mimeType') {
+      return false
+    }
+  }
+
+  try {
+    CID.parse(cid)
+  } catch {
+    return false
+  }
+
+  return true
+}

package/src/cid.ts

@@ -0,0 +1,50 @@
+import { CID } from 'multiformats/cid'
+
+export const DAG_CBOR_MULTICODEC = 0x71
+export const RAW_BIN_MULTICODEC = 0x55
+
+export const SHA2_256_MULTIHASH_CODE = 0x12
+
+export { CID }
+
+export function isCid(
+  value: unknown,
+  options?: { strict?: boolean },
+): value is CID {
+  const cid = CID.asCID(value)
+  if (!cid) {
+    return false
+  }
+
+  if (options?.strict) {
+    if (cid.version !== 1) {
+      return false
+    }
+    if (cid.code !== RAW_BIN_MULTICODEC && cid.code !== DAG_CBOR_MULTICODEC) {
+      return false
+    }
+    if (cid.multihash.code !== SHA2_256_MULTIHASH_CODE) {
+      return false
+    }
+  }
+
+  return true
+}
+
+export function validateCidString(input: string): boolean {
+  return parseCidString(input)?.toString() === input
+}
+
+export function parseCidString(input: string): CID | undefined {
+  try {
+    return CID.parse(input)
+  } catch {
+    return undefined
+  }
+}
+
+export function ensureValidCidString(input: string): void {
+  if (!validateCidString(input)) {
+    throw new Error(`Invalid CID string`)
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './blob.js'
+export * from './cid.js'
+export * from './language.js'
+export * from './lex-equals.js'
+export * from './lex.js'
+export * from './object.js'
+export * from './uint8array.js'
+export * from './utf8.js'

package/src/language.test.ts

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

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 parseLanguage(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 isLanguage(input: string): boolean {
+  return BCP47_REGEXP.test(input)
+}

package/src/lex-equals.test.ts

@@ -0,0 +1,153 @@
+import { CID } from './cid.js'
+import { lexEquals } from './lex-equals.js'
+import { LexValue } from './lex.js'
+
+function expectLexEqual(a: LexValue, b: LexValue, expected: boolean) {
+  expect(lexEquals(a, b)).toBe(expected)
+  expect(lexEquals(b, a)).toBe(expected)
+}
+
+describe('lexEquals', () => {
+  it('compares primitive values', () => {
+    expectLexEqual(null, null, true)
+    expectLexEqual(true, true, true)
+    expectLexEqual(false, false, true)
+    expectLexEqual(42, 42, true)
+    expectLexEqual('hello', 'hello', true)
+
+    expectLexEqual(null, false, false)
+    expectLexEqual(false, null, false)
+    expectLexEqual(true, false, false)
+    expectLexEqual(false, true, false)
+    expectLexEqual(42, 43, false)
+    expectLexEqual('hello', 'world', false)
+  })
+
+  it('compares NaN and Infinity correctly', () => {
+    expectLexEqual(NaN, NaN, true)
+    expectLexEqual(Infinity, Infinity, true)
+    expectLexEqual(-Infinity, -Infinity, true)
+
+    expectLexEqual(NaN, 0, false)
+    expectLexEqual(NaN, null, false)
+    expectLexEqual(Infinity, -Infinity, false)
+  })
+
+  it('compares arrays', () => {
+    expectLexEqual([1, 2, 3], [1, 2, 3], true)
+    expectLexEqual([1, 2, 3], [1, 2, 4], false)
+    expectLexEqual([1, 2, 3], [1, 2], false)
+    expectLexEqual([1, 2, 3], 'not an array', false)
+  })
+
+  it('compares Uint8Arrays', () => {
+    expectLexEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3]), true)
+    expectLexEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 4]), false)
+    expectLexEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2]), false)
+    expectLexEqual(new Uint8Array([1, 2, 3]), 'not a Uint8Array', false)
+  })
+
+  it('compares CIDs', () => {
+    const cid1 = CID.parse(
+      'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
+    )
+    const cid2 = CID.parse(cid1.toString())
+    const cid3 = CID.parse(cid1.toString())
+
+    expectLexEqual(cid1, cid2, true)
+    expectLexEqual(cid1, cid3, true)
+    expectLexEqual(cid2, cid3, true)
+
+    expectLexEqual(cid1, cid1.toString(), false)
+  })
+
+  it('compares objects', () => {
+    expectLexEqual({ a: 1, b: 2 }, { a: 1, b: 2 }, true)
+    expectLexEqual(
+      { a: 1, b: { unicode: 'a~öñ©⽘☎𓋓😀👨‍👩‍👧‍👧' } },
+      { a: 1, b: { unicode: 'a~öñ©⽘☎𓋓😀👨‍👩‍👧‍👧' } },
+      true,
+    )
+
+    expectLexEqual({ a: 1, b: 2 }, { a: 1, b: 3 }, false)
+    expectLexEqual({ a: 1, b: 2 }, { a: 1 }, false)
+    expectLexEqual({ a: 1, b: 2 }, 'not an object', false)
+    expectLexEqual({ a: 1, b: 2 }, null, false)
+  })
+
+  it('compares nested structures', () => {
+    const lex1 = {
+      foo: [1, 2, { bar: new Uint8Array([3, 4, 5]) }],
+      baz: CID.parse(
+        'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
+      ),
+    }
+    const lex2 = {
+      foo: [1, 2, { bar: new Uint8Array([3, 4, 5]) }],
+      baz: CID.parse(
+        'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
+      ),
+    }
+    const lex3 = {
+      foo: [1, 2, { bar: new Uint8Array([3, 4, 5 + 1]) }],
+      baz: CID.parse(
+        'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
+      ),
+    }
+
+    expectLexEqual(lex1, lex2, true)
+    expectLexEqual(lex1, lex3, false)
+    expectLexEqual(lex2, lex3, false)
+  })
+
+  it('allows comparing invalid numbers (floats, NaN, Infinity)', () => {
+    expectLexEqual(3.14, 2.71, false)
+    expectLexEqual(NaN, 0, false)
+    expectLexEqual(Infinity, -Infinity, false)
+  })
+
+  describe('reference equality', () => {
+    for (const value of [3.14, NaN, Infinity, -Infinity]) {
+      it(`returns true for identical references of ${String(value)}`, () => {
+        expectLexEqual(value, value, true)
+        expectLexEqual([value], [value], true)
+        expectLexEqual({ foo: value }, { foo: value }, true)
+        expectLexEqual([{ foo: value }], [{ foo: value }], true)
+      })
+    }
+  })
+
+  it('returns true for identical references', () => {
+    const arr = [1, 2, 3]
+    expectLexEqual(arr, arr, true)
+
+    const obj = { a: 1, b: 2 }
+    expectLexEqual(obj, obj, true)
+
+    const u8 = new Uint8Array([1, 2, 3])
+    expectLexEqual(u8, u8, true)
+
+    const cid = CID.parse(
+      'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
+    )
+    expectLexEqual(cid, cid, true)
+  })
+
+  it('throws when comparing plain object with non-allowed class instance', () => {
+    // @ts-expect-error
+    expect(() => lexEquals({}, new Map())).toThrow()
+    // @ts-expect-error
+    expect(() => lexEquals(new Map(), {})).toThrow()
+    // @ts-expect-error
+    expect(() => lexEquals({ foo: {} }, { foo: new Map() })).toThrow()
+    // @ts-expect-error
+    expect(() => lexEquals({ foo: new Map() }, { foo: {} })).toThrow()
+
+    expect(() => lexEquals({ foo: {} }, { foo: new (class {})() })).toThrow()
+    expect(() => lexEquals({ foo: new (class {})() }, { foo: {} })).toThrow()
+
+    expect(() =>
+      lexEquals({ foo: {} }, { foo: new (class Object {})() }),
+    ).toThrow()
+  })
+})

package/src/lex-equals.ts

@@ -0,0 +1,85 @@
+import { CID, isCid } from './cid.js'
+import { LexValue } from './lex.js'
+import { isPlainObject } from './object.js'
+import { ui8Equals } from './uint8array.js'
+
+export function lexEquals(a: LexValue, b: LexValue): boolean {
+  if (Object.is(a, b)) {
+    return true
+  }
+
+  if (
+    a == null ||
+    b == null ||
+    typeof a !== 'object' ||
+    typeof b !== 'object'
+  ) {
+    return false
+  }
+
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) {
+      return false
+    }
+    if (a.length !== b.length) {
+      return false
+    }
+    for (let i = 0; i < a.length; i++) {
+      if (!lexEquals(a[i], b[i])) {
+        return false
+      }
+    }
+    return true
+  } else if (Array.isArray(b)) {
+    return false
+  }
+
+  if (ArrayBuffer.isView(a)) {
+    if (!ArrayBuffer.isView(b)) return false
+    return ui8Equals(a, b)
+  } else if (ArrayBuffer.isView(b)) {
+    return false
+  }
+
+  if (isCid(a)) {
+    // @NOTE CID.equals returns its argument when it is falsy (e.g. null or
+    // undefined) so we need to explicitly check that the output is "true".
+    return CID.asCID(a)!.equals(CID.asCID(b)) === true
+  } else if (isCid(b)) {
+    return false
+  }
+
+  if (!isPlainObject(a) || !isPlainObject(b)) {
+    // Foolproof (should never happen)
+    throw new TypeError(
+      'Invalid LexValue (expected CID, Uint8Array, or LexMap)',
+    )
+  }
+
+  const aKeys = Object.keys(a)
+  const bKeys = Object.keys(b)
+
+  if (aKeys.length !== bKeys.length) {
+    return false
+  }
+
+  for (const key of aKeys) {
+    const aVal = a[key]
+    const bVal = b[key]
+
+    // Needed because of the optional index signature in the Lex object type
+    // though, in practice, aVal should never be undefined here.
+    if (aVal === undefined) {
+      if (bVal === undefined && bKeys.includes(key)) continue
+      return false
+    } else if (bVal === undefined) {
+      return false
+    }
+
+    if (!lexEquals(aVal, bVal)) {
+      return false
+    }
+  }
+
+  return true
+}

package/src/lex.test.ts

@@ -0,0 +1,124 @@
+import { isTypedLexMap } from './lex'
+
+describe('isLexMap', () => {
+  it('returns true for valid LexMap', () => {
+    const record = {
+      a: 123,
+      b: 'blah',
+      c: true,
+      d: null,
+      e: new Uint8Array([1, 2, 3]),
+      f: {
+        nested: 'value',
+      },
+      g: [1, 2, 3],
+    }
+    expect(isTypedLexMap(record)).toBe(false)
+  })
+
+  it('returns false for non-records', () => {
+    const values = [
+      123,
+      'blah',
+      true,
+      null,
+      new Uint8Array([1, 2, 3]),
+      [1, 2, 3],
+    ]
+    for (const value of values) {
+      expect(isTypedLexMap(value)).toBe(false)
+    }
+  })
+
+  it('returns false for records with non-Lex values', () => {
+    expect(
+      // @ts-expect-error
+      isTypedLexMap({
+        a: 123,
+        b: () => {},
+      }),
+    ).toBe(false)
+    expect(
+      isTypedLexMap({
+        a: 123,
+        b: undefined,
+      }),
+    ).toBe(false)
+  })
+})
+
+describe('isTypedLexMap', () => {
+  describe('valid records', () => {
+    for (const { note, json } of [
+      {
+        note: 'trivial record',
+        json: {
+          $type: 'com.example.blah',
+          a: 123,
+          b: 'blah',
+        },
+      },
+      {
+        note: 'float, but integer-like',
+        json: {
+          $type: 'com.example.blah',
+          a: 123.0,
+          b: 'blah',
+        },
+      },
+      {
+        note: 'empty list and object',
+        json: {
+          $type: 'com.example.blah',
+          a: [],
+          b: {},
+        },
+      },
+    ]) {
+      it(note, () => {
+        expect(isTypedLexMap(json)).toBe(true)
+      })
+    }
+  })
+
+  describe('invalid records', () => {
+    for (const { note, json } of [
+      {
+        note: 'float',
+        json: {
+          $type: 'com.example.blah',
+          a: 123.456,
+          b: 'blah',
+        },
+      },
+      {
+        note: 'record with $type null',
+        json: {
+          $type: null,
+          a: 123,
+          b: 'blah',
+        },
+      },
+      {
+        note: 'record with $type wrong type',
+        json: {
+          $type: 123,
+          a: 123,
+          b: 'blah',
+        },
+      },
+      {
+        note: 'record with empty $type string',
+        json: {
+          $type: '',
+          a: 123,
+          b: 'blah',
+        },
+      },
+    ]) {
+      it(note, () => {
+        expect(isTypedLexMap(json)).toBe(false)
+      })
+    }
+  })
+})