@atproto/lex-data 0.0.3 → 0.0.5

package/src/language.test.ts

@@ -1,62 +1,63 @@
-import { isLanguage, parseLanguage } from './language'
+import { describe, expect, it } from 'vitest'
+import { isLanguageString, parseLanguageString } 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)
+      expect(isLanguageString('de')).toEqual(true)
+      expect(isLanguageString('de-CH')).toEqual(true)
+      expect(isLanguageString('de-DE-1901')).toEqual(true)
+      expect(isLanguageString('es-419')).toEqual(true)
+      expect(isLanguageString('sl-IT-nedis')).toEqual(true)
+      expect(isLanguageString('mn-Cyrl-MN')).toEqual(true)
+      expect(isLanguageString('x-fr-CH')).toEqual(true)
+      expect(
+        isLanguageString('en-GB-boont-r-extended-sequence-x-private'),
+      ).toEqual(true)
+      expect(isLanguageString('sr-Cyrl')).toEqual(true)
+      expect(isLanguageString('hy-Latn-IT-arevela')).toEqual(true)
+      expect(isLanguageString('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)
+      expect(isLanguageString('')).toEqual(false)
+      expect(isLanguageString('x')).toEqual(false)
+      expect(isLanguageString('de-CH-')).toEqual(false)
+      expect(isLanguageString('i-bad-grandfathered')).toEqual(false)
     })
 
     it('parses BCP 47', () => {
       // valid
-      expect(parseLanguage('de')).toEqual({
+      expect(parseLanguageString('de')).toEqual({
         language: 'de',
       })
-      expect(parseLanguage('de-CH')).toEqual({
+      expect(parseLanguageString('de-CH')).toEqual({
         language: 'de',
         region: 'CH',
       })
-      expect(parseLanguage('de-DE-1901')).toEqual({
+      expect(parseLanguageString('de-DE-1901')).toEqual({
         language: 'de',
         region: 'DE',
         variant: '1901',
       })
-      expect(parseLanguage('es-419')).toEqual({
+      expect(parseLanguageString('es-419')).toEqual({
         language: 'es',
         region: '419',
       })
-      expect(parseLanguage('sl-IT-nedis')).toEqual({
+      expect(parseLanguageString('sl-IT-nedis')).toEqual({
         language: 'sl',
         region: 'IT',
         variant: 'nedis',
       })
-      expect(parseLanguage('mn-Cyrl-MN')).toEqual({
+      expect(parseLanguageString('mn-Cyrl-MN')).toEqual({
         language: 'mn',
         script: 'Cyrl',
         region: 'MN',
       })
-      expect(parseLanguage('x-fr-CH')).toEqual({
+      expect(parseLanguageString('x-fr-CH')).toEqual({
         privateUse: 'x-fr-CH',
       })
       expect(
-        parseLanguage('en-GB-boont-r-extended-sequence-x-private'),
+        parseLanguageString('en-GB-boont-r-extended-sequence-x-private'),
       ).toEqual({
         language: 'en',
         region: 'GB',
@@ -64,24 +65,24 @@ describe('string', () => {
         extension: 'r-extended-sequence',
         privateUse: 'x-private',
       })
-      expect(parseLanguage('sr-Cyrl')).toEqual({
+      expect(parseLanguageString('sr-Cyrl')).toEqual({
         language: 'sr',
         script: 'Cyrl',
       })
-      expect(parseLanguage('hy-Latn-IT-arevela')).toEqual({
+      expect(parseLanguageString('hy-Latn-IT-arevela')).toEqual({
         language: 'hy',
         script: 'Latn',
         region: 'IT',
         variant: 'arevela',
       })
-      expect(parseLanguage('i-klingon')).toEqual({
+      expect(parseLanguageString('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)
+      expect(parseLanguageString('')).toEqual(null)
+      expect(parseLanguageString('x')).toEqual(null)
+      expect(parseLanguageString('de-CH-')).toEqual(null)
+      expect(parseLanguageString('i-bad-grandfathered')).toEqual(null)
     })
   })
 })

package/src/language.ts

@@ -12,7 +12,7 @@ export type LanguageTag = {
   privateUse?: string
 }
 
-export function parseLanguage(input: string): LanguageTag | null {
+export function parseLanguageString(input: string): LanguageTag | null {
   const parsed = input.match(BCP47_REGEXP)
   if (!parsed?.groups) return null
 
@@ -34,6 +34,6 @@ export function parseLanguage(input: string): LanguageTag | null {
  *
  * @see {@link https://www.rfc-editor.org/rfc/rfc5646.html#section-2.1}
  */
-export function isLanguage(input: string): boolean {
+export function isLanguageString(input: string): boolean {
   return BCP47_REGEXP.test(input)
 }

package/src/lex-equals.test.ts

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest'
 import { parseCid } from './cid.js'
 import { lexEquals } from './lex-equals.js'
 import { LexValue } from './lex.js'
@@ -38,6 +39,7 @@ describe('lexEquals', () => {
     expectLexEqual([1, 2, 3], [1, 2, 4], false)
     expectLexEqual([1, 2, 3], [1, 2], false)
     expectLexEqual([1, 2, 3], 'not an array', false)
+    expectLexEqual([1, 2, 3], { 0: 1, 1: 2, 2: 3 }, false)
   })
 
   it('compares Uint8Arrays', () => {
@@ -59,10 +61,23 @@ describe('lexEquals', () => {
     expectLexEqual(cid2, cid3, true)
 
     expectLexEqual(cid1, cid1.toString(), false)
+    expectLexEqual(cid1, { not: 'a cid' }, false)
+    expectLexEqual(cid1, [], false)
+    expectLexEqual(cid1, cid1.bytes, false)
   })
 
   it('compares objects', () => {
     expectLexEqual({ a: 1, b: 2 }, { a: 1, b: 2 }, true)
+    expectLexEqual(
+      { a: 1, b: 2, c: undefined },
+      { a: 1, b: 2, c: undefined },
+      true,
+    )
+    expectLexEqual(
+      { a: 1, b: 2, c: { e: 1, d: undefined } },
+      { a: 1, b: 2, c: { d: undefined, e: 1 } },
+      true,
+    )
     expectLexEqual(
       { a: 1, b: { unicode: 'a~öñ©⽘☎𓋓😀👨‍👩‍👧‍👧' } },
       { a: 1, b: { unicode: 'a~öñ©⽘☎𓋓😀👨‍👩‍👧‍👧' } },
@@ -75,6 +90,21 @@ describe('lexEquals', () => {
     expectLexEqual({ a: 1, b: 2 }, null, false)
   })
 
+  it('accounts for undefined (but present) properties in objects', () => {
+    expectLexEqual({ a: 1, b: undefined }, { a: 1 }, false)
+    expectLexEqual(
+      { a: 1, b: { c: undefined, d: 2 } },
+      { a: 1, b: { d: 2 } },
+      false,
+    )
+
+    expectLexEqual(
+      { a: 1, b: { c: undefined, d: 2 } },
+      { a: 1, b: { c: 3, d: 2 } },
+      false,
+    )
+  })
+
   it('compares nested structures', () => {
     const lex1 = {
       foo: [1, 2, { bar: new Uint8Array([3, 4, 5]) }],

package/src/lex-error.ts

@@ -0,0 +1,34 @@
+export type LexErrorCode = string
+
+export type LexErrorData<N extends LexErrorCode = LexErrorCode> = {
+  error: N
+  message?: string
+}
+
+export class LexError<N extends LexErrorCode = LexErrorCode> extends Error {
+  name = 'LexError'
+
+  constructor(
+    readonly error: N,
+    message?: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+  }
+
+  toString(): string {
+    return `${this.name}: [${this.error}] ${this.message}`
+  }
+
+  toJSON(): LexErrorData<N> {
+    const { error, message } = this
+    return { error, message: message ?? undefined }
+  }
+
+  /**
+   * Translate into an HTTP response for downstream clients.
+   */
+  toResponse(): Response {
+    return Response.json(this.toJSON(), { status: 400 })
+  }
+}

package/src/lex.test.ts

@@ -1,4 +1,159 @@
-import { isTypedLexMap } from './lex'
+import { describe, expect, it } from 'vitest'
+import { parseCid } from './cid.js'
+import { isLexArray, isLexScalar, isLexValue, isTypedLexMap } from './lex.js'
+
+describe('isLexScalar', () => {
+  for (const { note, value, expected } of [
+    { note: 'string', value: 'hello', expected: true },
+    { note: 'boolean', value: true, expected: true },
+    { note: 'null', value: null, expected: true },
+    { note: 'Uint8Array', value: new Uint8Array([1, 2, 3]), expected: true },
+    {
+      note: 'Cid',
+      value: parseCid(
+        'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
+      ),
+      expected: true,
+    },
+    { note: 'number (integer)', value: 42, expected: true },
+    { note: 'number (float)', value: 3.14, expected: false },
+    { note: 'object', value: { a: 1 }, expected: false },
+    { note: 'array', value: [1, 2, 3], expected: false },
+    { note: 'undefined', value: undefined, expected: false },
+    { note: 'function', value: () => {}, expected: false },
+  ]) {
+    it(note, () => {
+      const result = isLexScalar(value)
+      expect(result).toBe(expected)
+    })
+  }
+})
+
+describe('isLexArray', () => {
+  it('returns true for valid LexArray', () => {
+    const list = [123, 'blah', true, null, new Uint8Array([1, 2, 3]), { a: 1 }]
+    expect(isLexArray(list)).toBe(true)
+  })
+
+  it('returns false for non-arrays', () => {
+    const values = [
+      123,
+      'blah',
+      true,
+      null,
+      new Uint8Array([1, 2, 3]),
+      { a: 1 },
+    ]
+    for (const value of values) {
+      expect(isLexArray(value)).toBe(false)
+    }
+  })
+
+  it('returns false for arrays with non-Lex values', () => {
+    expect(isLexArray([123, 'blah', () => {}])).toBe(false)
+    expect(isLexArray([123, 'blah', undefined])).toBe(false)
+  })
+})
+
+describe('isLexValue', () => {
+  describe('valid values', () => {
+    for (const { note, value } of [
+      { note: 'string', value: 'hello' },
+      { note: 'boolean', value: true },
+      { note: 'null', value: null },
+      { note: 'Uint8Array', value: new Uint8Array([1, 2, 3]) },
+      {
+        note: 'Cid',
+        value: parseCid(
+          'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
+        ),
+      },
+      {
+        note: 'record with Lex values',
+        value: {
+          a: 123,
+          b: 'blah',
+          c: true,
+          d: null,
+          e: new Uint8Array([1, 2, 3]),
+          f: {
+            nested: 'value',
+          },
+          g: [1, 2, 3],
+        },
+      },
+      {
+        note: 'list with Lex values',
+        value: [
+          123,
+          'blah',
+          true,
+          null,
+          new Uint8Array([1, 2, 3]),
+          {
+            nested: 'value',
+          },
+          [1, 2, 3],
+        ],
+      },
+    ]) {
+      it(note, () => {
+        expect(isLexValue(value)).toBe(true)
+      })
+    }
+  })
+
+  describe('invalid values', () => {
+    for (const { note, value } of [
+      { note: 'float', value: 123.456 },
+      { note: 'undefined', value: undefined },
+      { note: 'function', value: () => {} },
+      { note: 'obj with fn', value: { a: 123, b: () => {} } },
+      { note: 'list with non-Lex value', value: [123, 'blah', () => {}] },
+      { note: 'Date object', value: new Date() },
+      { note: 'Map object', value: new Map() },
+      { note: 'Set object', value: new Set() },
+      { note: 'class instance', value: new (class A {})() },
+    ]) {
+      it(note, () => {
+        expect(isLexValue(value)).toBe(false)
+      })
+    }
+  })
+
+  it('handles cyclic structures', () => {
+    const record: any = {
+      a: 123,
+      b: 'blah',
+    }
+    record.c = record
+
+    expect(isLexValue(record)).toBe(false)
+
+    const list: any[] = [123, 'blah']
+    list.push(list)
+
+    expect(isLexValue(list)).toBe(false)
+
+    const complex: any = {
+      a: {
+        b: [1, 2, 3],
+      },
+    }
+    complex.a.b.push(complex)
+
+    expect(isLexValue(complex)).toBe(false)
+  })
+
+  it('handles deeply nested structures', () => {
+    type Value = null | { nested: Value }
+    let value: Value = null
+    for (let i = 0; i < 1_000_000; i++) {
+      value = { nested: value }
+    }
+    expect(isLexValue(value)).toBe(true)
+  })
+})
 
 describe('isLexMap', () => {
   it('returns true for valid LexMap', () => {

package/src/lex.ts

@@ -1,7 +1,5 @@
 import { Cid, isCid } from './cid.js'
-import { isPlainObject } from './object.js'
-
-// @NOTE BlobRef is just a special case of LexMap.
+import { isPlainObject, isPlainProto } from './object.js'
 
 export type LexScalar = number | string | boolean | null | Cid | Uint8Array
 export type LexValue = LexScalar | LexValue[] | { [_ in string]?: LexValue }
@@ -9,65 +7,74 @@ export type LexMap = { [_ in string]?: LexValue }
 export type LexArray = LexValue[]
 
 export function isLexMap(value: unknown): value is LexMap {
-  if (!isPlainObject(value)) return false
-  for (const key in value) {
-    if (!isLexValue(value[key])) return false
-  }
-  return true
+  return isPlainObject(value) && Object.values(value).every(isLexValue)
 }
 
 export function isLexArray(value: unknown): value is LexArray {
-  if (!Array.isArray(value)) return false
-  for (let i = 0; i < value.length; i++) {
-    if (!isLexValue(value[i])) return false
-  }
-  return true
+  return Array.isArray(value) && value.every(isLexValue)
 }
 
 export function isLexScalar(value: unknown): value is LexScalar {
   switch (typeof value) {
     case 'object':
-      if (value === null) return true
-      return value instanceof Uint8Array || isCid(value)
+      return value === null || value instanceof Uint8Array || isCid(value)
     case 'string':
     case 'boolean':
       return true
     case 'number':
       if (Number.isInteger(value)) return true
-      throw new TypeError(`Invalid Lex value: ${value}`)
+    // fallthrough
     default:
-      throw new TypeError(`Invalid Lex value: ${typeof value}`)
+      return false
   }
 }
 
 export function isLexValue(value: unknown): value is LexValue {
-  switch (typeof value) {
-    case 'number':
-      if (!Number.isInteger(value)) return false
-    // fallthrough
-    case 'string':
-    case 'boolean':
-      return true
-    case 'object':
-      if (value === null) return true
-      if (Array.isArray(value)) {
-        for (let i = 0; i < value.length; i++) {
-          if (!isLexValue(value[i])) return false
-        }
-        return true
-      }
-      if (isPlainObject(value)) {
-        for (const key in value) {
-          if (!isLexValue(value[key])) return false
+  // Using a stack to avoid recursion depth issues.
+  const stack: unknown[] = [value]
+  // Cyclic structures are not valid LexValues as they cannot be serialized to
+  // JSON or CBOR. This also allows us to avoid infinite loops when traversing
+  // the structure.
+  const visited = new Set<object>()
+
+  do {
+    const value = stack.pop()!
+
+    // Optimization: we are not using `isLexScalar` here to avoid extra function
+    // calls, and to avoid computing `typeof value` multiple times.
+    switch (typeof value) {
+      case 'object':
+        if (value === null) {
+          // LexScalar
+        } else if (isPlainProto(value)) {
+          if (visited.has(value)) return false
+          visited.add(value)
+          stack.push(...Object.values(value))
+        } else if (Array.isArray(value)) {
+          if (visited.has(value)) return false
+          visited.add(value)
+          stack.push(...value)
+        } else if (value instanceof Uint8Array || isCid(value)) {
+          // LexScalar
+        } else {
+          return false
         }
-        return true
-      }
-      if (value instanceof Uint8Array) return true
-      if (isCid(value)) return true
-    // fallthrough
-    default:
-      return false
-  }
+        break
+      case 'string':
+      case 'boolean':
+        break
+      case 'number':
+        if (Number.isInteger(value)) break
+      // fallthrough
+      default:
+        return false
+    }
+  } while (stack.length > 0)
+
+  // Optimization: ease GC's work
+  visited.clear()
+
+  return true
 }
 
 export type TypedLexMap = LexMap & { $type: string }

package/src/lib/nodejs-buffer.ts

@@ -12,6 +12,7 @@ interface NodeJSBufferConstructor {
     input: Uint8Array | ArrayBuffer | ArrayBufferView,
   ): NodeJSBuffer<ArrayBuffer>
   from(input: string, encoding?: Encoding): NodeJSBuffer<ArrayBuffer>
+  concat(list: readonly Uint8Array[], totalLength?: number): NodeJSBuffer
   byteLength(input: string, encoding?: Encoding): number
   prototype: NodeJSBuffer
 }
@@ -24,4 +25,4 @@ export const NodeJSBuffer: NodeJSBufferConstructor | null =
   (globalThis as any)?.[BUFFER]?.prototype instanceof Uint8Array &&
   'byteLength' in (globalThis as any)[BUFFER]
     ? ((globalThis as any)[BUFFER] as NodeJSBufferConstructor)
-    : null
+    : /* v8 ignore next -- @preserve */ null

package/src/object.test.ts

@@ -1,5 +1,7 @@
+import { describe, expect, it } from 'vitest'
 import { parseCid } from './cid.js'
 import { isObject, isPlainObject } from './object.js'
+
 describe('isObject', () => {
   it('returns true for plain objects', () => {
     expect(isObject({})).toBe(true)

package/src/object.ts

@@ -1,3 +1,6 @@
+/**
+ * Checks whether the input is an object (not null).
+ */
 export function isObject(input: unknown): input is object {
   return input != null && typeof input === 'object'
 }
@@ -5,10 +8,19 @@ export function isObject(input: unknown): input is object {
 const ObjectProto = Object.prototype
 const ObjectToString = Object.prototype.toString
 
-export function isPlainObject(
-  input: unknown,
-): input is object & Record<string, unknown> {
-  if (!input || typeof input !== 'object') return false
+/**
+ * Checks whether the input is an object (not null) whose prototype is either
+ * null or `Object.prototype`.
+ */
+export function isPlainObject(input: unknown) {
+  return isObject(input) && isPlainProto(input)
+}
+
+/**
+ * Checks whether the prototype of the input object is either null or
+ * `Object.prototype`.
+ */
+export function isPlainProto(input: object): input is Record<string, unknown> {
   const proto = Object.getPrototypeOf(input)
   if (proto === null) return true
   return (