@atproto/lex-data 0.1.3 → 0.1.4

package/src/lex.test.ts

@@ -1,279 +0,0 @@
-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', () => {
-    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)
-      })
-    }
-  })
-})

package/src/lex.ts

@@ -1,253 +0,0 @@
-import { Cid, isCid } from './cid.js'
-import { isPlainObject } from './object.js'
-
-/**
- * Primitive values in the Lexicon data model.
- *
- * Represents the basic scalar types that can appear in AT Protocol data:
- * - `number` - Integer values only (no floats)
- * - `string` - UTF-8 text
- * - `boolean` - true or false
- * - `null` - Explicit null value
- * - `Cid` - Content Identifier (link by hash)
- * - `Uint8Array` - Binary data (bytes)
- *
- * @see {@link LexValue} for the complete recursive value type
- */
-export type LexScalar = number | string | boolean | null | Cid | Uint8Array
-
-/**
- * Any valid Lexicon value (recursive type).
- *
- * This is the union of all types that can appear in AT Protocol Lexicon data:
- * - {@link LexScalar} - Primitive values (number, string, boolean, null, Cid, Uint8Array)
- * - `LexValue[]` - Arrays of LexValues
- * - `{ [key: string]?: LexValue }` - Objects with string keys and LexValue values
- *
- * @example
- * ```typescript
- * import type { LexValue } from '@atproto/lex'
- *
- * const scalar: LexValue = 'hello'
- * const array: LexValue = [1, 2, 3]
- * const object: LexValue = { name: 'Alice', age: 30 }
- * ```
- *
- * @see {@link LexScalar} for primitive value types
- * @see {@link LexMap} for object types
- * @see {@link LexArray} for array types
- */
-export type LexValue = LexScalar | LexValue[] | { [_ in string]?: LexValue }
-
-/**
- * Object with string keys and LexValue values.
- *
- * Represents a plain object in the Lexicon data model where all values
- * must be valid {@link LexValue} types.
- *
- * @example
- * ```typescript
- * import type { LexMap } from '@atproto/lex'
- *
- * const user: LexMap = {
- *   name: 'Alice',
- *   age: 30,
- *   tags: ['admin', 'user']
- * }
- * ```
- *
- * @see {@link TypedLexMap} for objects with a required `$type` property
- */
-export type LexMap = { [_ in string]?: LexValue }
-
-/**
- * Array of {@link LexValue} elements.
- *
- * @example
- * ```typescript
- * import type { LexArray } from '@atproto/lex'
- *
- * const items: LexArray = [1, 'two', { three: 3 }]
- * ```
- */
-export type LexArray = LexValue[]
-
-/**
- * Type guard to check if a value is a valid {@link LexMap}.
- *
- * Returns true if the value is a plain object where all values are valid
- * {@link LexValue} types.
- *
- * @param value - The value to check
- * @returns `true` if the value is a valid LexMap
- *
- * @example
- * ```typescript
- * import { isLexMap } from '@atproto/lex'
- *
- * if (isLexMap(data)) {
- *   // data is narrowed to LexMap
- *   console.log(Object.keys(data))
- * }
- * ```
- */
-export function isLexMap(value: unknown): value is LexMap {
-  return isPlainObject(value) && Object.values(value).every(isLexValue)
-}
-
-/**
- * Type guard to check if a value is a valid {@link LexArray}.
- *
- * Returns true if the value is an array where all elements are valid
- * {@link LexValue} types.
- *
- * @param value - The value to check
- * @returns `true` if the value is a valid LexArray
- *
- * @example
- * ```typescript
- * import { isLexArray } from '@atproto/lex'
- *
- * if (isLexArray(data)) {
- *   // data is narrowed to LexArray
- *   data.forEach(item => console.log(item))
- * }
- * ```
- */
-export function isLexArray(value: unknown): value is LexArray {
-  return Array.isArray(value) && value.every(isLexValue)
-}
-
-/**
- * Type guard to check if a value is a valid {@link LexScalar}.
- *
- * Returns true if the value is one of the primitive Lexicon types:
- * number (integer only), string, boolean, null, Cid, or Uint8Array.
- *
- * @param value - The value to check
- * @returns `true` if the value is a valid LexScalar
- *
- * @example
- * ```typescript
- * import { isLexScalar } from '@atproto/lex'
- *
- * isLexScalar('hello')     // true
- * isLexScalar(42)          // true
- * isLexScalar(3.14)        // false (floats not allowed)
- * isLexScalar([1, 2])      // false (arrays are not scalars)
- * ```
- */
-export function isLexScalar(value: unknown): value is LexScalar {
-  switch (typeof value) {
-    case 'object':
-      return value === null || value instanceof Uint8Array || isCid(value)
-    case 'string':
-    case 'boolean':
-      return true
-    case 'number':
-      if (Number.isInteger(value)) return true
-    // fallthrough
-    default:
-      return false
-  }
-}
-
-/**
- * Type guard to check if a value is a valid {@link LexValue}.
- *
- * Performs a deep check to validate that the value (and all nested values)
- * conform to the Lexicon data model. This includes checking for:
- * - Valid scalar types (number, string, boolean, null, Cid, Uint8Array)
- * - Arrays containing only valid LexValues
- * - Plain objects with string keys and valid LexValue values
- * - No cyclic references (which cannot be serialized to JSON or CBOR)
- *
- * @param value - The value to check
- * @returns `true` if the value is a valid LexValue
- *
- * @example
- * ```typescript
- * import { isLexValue } from '@atproto/lex'
- *
- * isLexValue({ name: 'Alice', tags: ['admin'] })  // true
- * isLexValue(new Date())                           // false (not a plain object)
- * isLexValue({ fn: () => {} })                     // false (functions not allowed)
- * ```
- */
-export function isLexValue(value: unknown): value is LexValue {
-  // 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()!
-
-    if (isPlainObject(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 (!isLexScalar(value)) return false
-    }
-  } while (stack.length > 0)
-
-  // Optimization: ease GC's work
-  visited.clear()
-
-  return true
-}
-
-/**
- * A {@link LexMap} with a required `$type` property.
- *
- * Used to represent typed objects in the Lexicon data model, where the
- * `$type` property identifies the Lexicon schema that defines the object's
- * structure.
- *
- * @example
- * ```typescript
- * import type { TypedLexMap } from '@atproto/lex'
- *
- * const post: TypedLexMap = {
- *   $type: 'app.bsky.feed.post',
- *   text: 'Hello world!',
- *   createdAt: '2024-01-01T00:00:00Z'
- * }
- * ```
- *
- * @see {@link isTypedLexMap} to check if a value is a TypedLexMap
- */
-export type TypedLexMap<T extends string = string> = LexMap & { $type: T }
-
-/**
- * Type guard to check if a value is a {@link TypedLexMap}.
- *
- * Returns true if the value is a valid {@link LexMap} with a non-empty
- * `$type` string property.
- *
- * @param value - The LexValue to check
- * @returns `true` if the value is a TypedLexMap
- *
- * @example
- * ```typescript
- * import { isTypedLexMap } from '@atproto/lex'
- *
- * const data = { $type: 'app.bsky.feed.post', text: 'Hello' }
- *
- * if (isTypedLexMap(data)) {
- *   console.log(data.$type)  // 'app.bsky.feed.post'
- * }
- * ```
- */
-export function isTypedLexMap(value: LexValue): value is TypedLexMap {
-  return (
-    isLexMap(value) && typeof value.$type === 'string' && value.$type.length > 0
-  )
-}

package/src/lib/nodejs-buffer.ts

@@ -1,46 +0,0 @@
-type Encoding = 'utf8' | 'base64' | 'base64url'
-
-// Node's buffer module declares this type internally, but referencing it here
-// would couple this file to @types/node. Local copy keeps this module
-// standalone so it compiles in any environment (see tsconfig/isomorphic.json).
-type WithImplicitCoercion<T> = T | { valueOf(): T }
-
-interface NodeJSBuffer<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike>
-  extends Uint8Array<TArrayBuffer> {
-  byteLength: number
-  toString(encoding?: Encoding): string
-  slice(start?: number, end?: number): NodeJSBuffer<ArrayBuffer>
-  subarray(start?: number, end?: number): NodeJSBuffer<TArrayBuffer>
-}
-
-interface NodeJSBufferConstructor {
-  new (input: string, encoding?: Encoding): NodeJSBuffer
-  from(
-    string: WithImplicitCoercion<string>,
-    encoding?: BufferEncoding,
-  ): NodeJSBuffer<ArrayBuffer>
-  from(
-    arrayOrString: WithImplicitCoercion<ArrayLike<number> | string>,
-  ): NodeJSBuffer<ArrayBuffer>
-  from<TArrayBuffer extends ArrayBufferLike>(
-    arrayBuffer: WithImplicitCoercion<TArrayBuffer>,
-    byteOffset?: number,
-    length?: number,
-  ): NodeJSBuffer<TArrayBuffer>
-  concat(
-    list: readonly Uint8Array[],
-    totalLength?: number,
-  ): NodeJSBuffer<ArrayBuffer>
-  byteLength(input: string, encoding?: Encoding): number
-  prototype: NodeJSBuffer
-}
-
-// Avoids a direct reference to Node.js Buffer, which might not exist in some
-// environments (e.g. browsers, Deno, Bun) to prevent bundlers from trying to
-// include polyfills.
-const BUFFER = /*#__PURE__*/ (() => 'Bu' + 'f'.repeat(2) + 'er')() as 'Buffer'
-export const NodeJSBuffer: NodeJSBufferConstructor | null =
-  (globalThis as any)?.[BUFFER]?.prototype instanceof Uint8Array &&
-  'byteLength' in (globalThis as any)[BUFFER]
-    ? ((globalThis as any)[BUFFER] as NodeJSBufferConstructor)
-    : /* v8 ignore next -- @preserve */ null

package/src/lib/util.test.ts

@@ -1,49 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { isUint8, toHexString } from './util.js'
-
-describe(toHexString, () => {
-  it('converts 0 to 0x00', () => {
-    expect(toHexString(0)).toBe('0x00')
-  })
-
-  it('converts single-digit hex values with padding', () => {
-    expect(toHexString(1)).toBe('0x01')
-    expect(toHexString(15)).toBe('0x0f')
-  })
-
-  it('converts two-digit hex values without extra padding', () => {
-    expect(toHexString(16)).toBe('0x10')
-    expect(toHexString(255)).toBe('0xff')
-  })
-
-  it('converts larger numbers', () => {
-    expect(toHexString(256)).toBe('0x100')
-    expect(toHexString(4096)).toBe('0x1000')
-  })
-})
-
-describe(isUint8, () => {
-  it('returns true for valid uint8 values', () => {
-    expect(isUint8(0)).toBe(true)
-    expect(isUint8(1)).toBe(true)
-    expect(isUint8(127)).toBe(true)
-    expect(isUint8(255)).toBe(true)
-  })
-
-  it('returns false for values outside uint8 range', () => {
-    expect(isUint8(-1)).toBe(false)
-    expect(isUint8(256)).toBe(false)
-  })
-
-  it('returns false for non-integer numbers', () => {
-    expect(isUint8(1.5)).toBe(false)
-    expect(isUint8(0.1)).toBe(false)
-  })
-
-  it('returns false for non-number types', () => {
-    expect(isUint8('0')).toBe(false)
-    expect(isUint8(null)).toBe(false)
-    expect(isUint8(undefined)).toBe(false)
-    expect(isUint8(true)).toBe(false)
-  })
-})

package/src/lib/util.ts

@@ -1,7 +0,0 @@
-export function toHexString(number: number): string {
-  return `0x${number.toString(16).padStart(2, '0')}`
-}
-
-export function isUint8(val: unknown): val is number {
-  return Number.isInteger(val) && (val as number) >= 0 && (val as number) < 256
-}

package/src/object.test.ts

@@ -1,80 +0,0 @@
-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)
-    expect(isObject({ a: 1 })).toBe(true)
-  })
-
-  it('returns true for CIDs', () => {
-    const cid = parseCid(
-      'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
-    )
-    expect(isObject(cid)).toBe(true)
-  })
-
-  it('returns true for class instances', () => {
-    class MyClass {}
-    expect(isObject(new MyClass())).toBe(true)
-  })
-
-  it('returns true for arrays', () => {
-    expect(isObject([])).toBe(true)
-    expect(isObject([1, 2, 3])).toBe(true)
-  })
-
-  it('returns false for null', () => {
-    expect(isObject(null)).toBe(false)
-  })
-
-  it('returns false for non-objects', () => {
-    expect(isObject(42)).toBe(false)
-    expect(isObject('string')).toBe(false)
-    expect(isObject(undefined)).toBe(false)
-    expect(isObject(true)).toBe(false)
-  })
-})
-
-describe('isPlainObject', () => {
-  it('returns true for plain objects', () => {
-    expect(isPlainObject({})).toBe(true)
-    expect(isPlainObject({ a: 1 })).toBe(true)
-  })
-
-  it('returns true for objects with null prototype', () => {
-    const obj = Object.create(null)
-    obj.a = 1
-    expect(isPlainObject(obj)).toBe(true)
-    expect(isPlainObject({ __proto__: null, foo: 'bar' })).toBe(true)
-  })
-
-  it('returns false for class instances', () => {
-    class MyClass {}
-    expect(isPlainObject(new MyClass())).toBe(false)
-  })
-
-  it('returns false for CIDs', () => {
-    const cid = parseCid(
-      'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
-    )
-    expect(isPlainObject(cid)).toBe(false)
-  })
-
-  it('returns false for arrays', () => {
-    expect(isPlainObject([])).toBe(false)
-    expect(isPlainObject([1, 2, 3])).toBe(false)
-  })
-
-  it('returns false for null', () => {
-    expect(isPlainObject(null)).toBe(false)
-  })
-
-  it('returns false for non-objects', () => {
-    expect(isPlainObject(42)).toBe(false)
-    expect(isPlainObject('string')).toBe(false)
-    expect(isPlainObject(undefined)).toBe(false)
-    expect(isPlainObject(true)).toBe(false)
-  })
-})