@atproto/lex-data 0.0.10 → 0.0.12

package/src/blob.ts

@@ -3,7 +3,28 @@ import { LexValue } from './lex.js'
 import { isPlainObject, isPlainProto } from './object.js'
 
 /**
- * @note {@link BlobRef} is just a {@link LexMap} with a specific shape.
+ * Reference to binary data (like images, videos, etc.) in the AT Protocol data model.
+ *
+ * A BlobRef is a {@link LexMap} with a specific structure that identifies binary
+ * content by its content hash (CID), along with metadata about the content type
+ * and size.
+ *
+ * @typeParam Ref - The type of CID reference, defaults to any {@link Cid}
+ *
+ * @example
+ * ```typescript
+ * import type { BlobRef } from '@atproto/lex-data'
+ *
+ * const imageRef: BlobRef = {
+ *   $type: 'blob',
+ *   mimeType: 'image/jpeg',
+ *   ref: cid,  // CID of the blob content
+ *   size: 12345
+ * }
+ * ```
+ *
+ * @see {@link isBlobRef} to check if a value is a valid BlobRef
+ * @see {@link LegacyBlobRef} for the older blob reference format
  */
 export type BlobRef<Ref extends Cid = Cid> = {
   $type: 'blob'
@@ -12,17 +33,25 @@ export type BlobRef<Ref extends Cid = Cid> = {
   size: number
 }
 
+/**
+ * Options for validating a {@link BlobRef}.
+ */
 export type BlobRefCheckOptions = {
   /**
    * If `false`, skips strict CID validation of {@link BlobRef.ref}, allowing
    * any valid CID. Otherwise, validates that the CID is v1, uses the raw
    * multicodec, and has a sha256 multihash.
    *
-   * @defaults to `true`
+   * @default true
    */
   strict?: boolean
 }
 
+/**
+ * Infers the BlobRef type based on the check options.
+ *
+ * @typeParam TOptions - The options used for checking
+ */
 export type InferCheckedBlobRef<TOptions extends BlobRefCheckOptions> =
   TOptions extends { strict: false }
     ? BlobRef
@@ -30,6 +59,34 @@ export type InferCheckedBlobRef<TOptions extends BlobRefCheckOptions> =
       ? BlobRef
       : BlobRef<RawCid>
 
+/**
+ * Type guard to check if a value is a valid {@link BlobRef}.
+ *
+ * Validates the structure of the input including:
+ * - `$type` must be `'blob'`
+ * - `mimeType` must be a valid MIME type string (containing '/')
+ * - `size` must be a non-negative safe integer
+ * - `ref` must be a valid CID (strict validation by default)
+ *
+ * @param input - The value to check
+ * @param options - Optional validation options
+ * @returns `true` if the input is a valid BlobRef
+ *
+ * @example
+ * ```typescript
+ * import { isBlobRef } from '@atproto/lex-data'
+ *
+ * if (isBlobRef(data)) {
+ *   console.log(data.mimeType)  // e.g., 'image/jpeg'
+ *   console.log(data.size)      // e.g., 12345
+ * }
+ *
+ * // Allow any valid CID (not just raw CIDs)
+ * if (isBlobRef(data, { strict: false })) {
+ *   // ...
+ * }
+ * ```
+ */
 export function isBlobRef(input: unknown): input is BlobRef<RawCid>
 export function isBlobRef<TOptions extends BlobRefCheckOptions>(
   input: unknown,
@@ -89,13 +146,53 @@ export function isBlobRef(
 }
 
 /**
- * @note {@link LegacyBlobRef} is just a {@link LexMap} with a specific shape.
+ * Legacy format for blob references used in older AT Protocol data.
+ *
+ * This is the older format that stores the CID as a string rather than
+ * as a structured CID object. New code should use {@link BlobRef} instead.
+ *
+ * @example
+ * ```typescript
+ * import type { LegacyBlobRef } from '@atproto/lex-data'
+ *
+ * const legacyRef: LegacyBlobRef = {
+ *   cid: 'bafyreib...',
+ *   mimeType: 'image/jpeg'
+ * }
+ * ```
+ *
+ * @see {@link isLegacyBlobRef} to check if a value is a LegacyBlobRef
+ * @see {@link BlobRef} for the current blob reference format
+ * @deprecated Use {@link BlobRef} for new code
  */
 export type LegacyBlobRef = {
   cid: string
   mimeType: string
 }
 
+/**
+ * Type guard to check if a value is a valid {@link LegacyBlobRef}.
+ *
+ * Validates the structure of the input:
+ * - `cid` must be a valid CID string
+ * - `mimeType` must be a non-empty string
+ * - No additional properties allowed
+ *
+ * @param input - The value to check
+ * @returns `true` if the input is a valid LegacyBlobRef
+ *
+ * @example
+ * ```typescript
+ * import { isLegacyBlobRef } from '@atproto/lex-data'
+ *
+ * if (isLegacyBlobRef(data)) {
+ *   console.log(data.cid)       // CID as string
+ *   console.log(data.mimeType)  // e.g., 'image/jpeg'
+ * }
+ * ```
+ *
+ * @see {@link isBlobRef} for checking the current blob reference format
+ */
 export function isLegacyBlobRef(input: unknown): input is LegacyBlobRef {
   if (!isPlainObject(input)) {
     return false
@@ -123,13 +220,24 @@ export function isLegacyBlobRef(input: unknown): input is LegacyBlobRef {
   return true
 }
 
+/**
+ * Options for enumerating blob references within a {@link LexValue}.
+ */
 export type EnumBlobRefsOptions = BlobRefCheckOptions & {
   /**
-   * @defaults to `false`
+   * If `true`, also yields {@link LegacyBlobRef} objects in addition to
+   * {@link BlobRef} objects.
+   *
+   * @default false
    */
   allowLegacy?: boolean
 }
 
+/**
+ * Infers the yielded type of {@link enumBlobRefs} based on options.
+ *
+ * @typeParam TOptions - The options used for enumeration
+ */
 export type InferEnumBlobRefs<TOptions extends EnumBlobRefsOptions> =
   TOptions extends { allowLegacy: true }
     ? InferCheckedBlobRef<TOptions> | LegacyBlobRef
@@ -138,8 +246,37 @@ export type InferEnumBlobRefs<TOptions extends EnumBlobRefsOptions> =
       : InferCheckedBlobRef<TOptions>
 
 /**
- * Enumerates all {@link BlobRef}s (and, optionally, {@link LegacyBlobRef}s)
- * found within a {@link LexValue}.
+ * Generator that enumerates all {@link BlobRef}s (and, optionally,
+ * {@link LegacyBlobRef}s) found within a {@link LexValue}.
+ *
+ * Performs a deep traversal of the input value, yielding any blob references
+ * found. This is useful for extracting all media references from a record.
+ *
+ * @param input - The LexValue to search for blob references
+ * @param options - Optional configuration for the enumeration
+ * @yields Each blob reference found in the input
+ *
+ * @example
+ * ```typescript
+ * import { enumBlobRefs } from '@atproto/lex-data'
+ *
+ * const record = {
+ *   text: 'Hello',
+ *   images: [
+ *     { $type: 'blob', mimeType: 'image/jpeg', ref: cid1, size: 1000 },
+ *     { $type: 'blob', mimeType: 'image/png', ref: cid2, size: 2000 }
+ *   ]
+ * }
+ *
+ * for (const blobRef of enumBlobRefs(record)) {
+ *   console.log(blobRef.mimeType, blobRef.size)
+ * }
+ *
+ * // Include legacy blob references
+ * for (const ref of enumBlobRefs(record, { allowLegacy: true })) {
+ *   // ref may be BlobRef or LegacyBlobRef
+ * }
+ * ```
  */
 export function enumBlobRefs(
   input: LexValue,

package/src/cid-implementation.test.ts

@@ -73,25 +73,19 @@ describe(BytesCid, () => {
  */
 export function createCustomCid<
   TVersion extends 0 | 1,
-  TCode extends number,
-  TMultihashCode extends number,
+  TCodec extends number,
+  THashCode extends number,
 >(
   version: TVersion,
-  code: TCode,
-  multihashCode: TMultihashCode,
+  code: TCodec,
+  hashCode: THashCode,
   digest: Uint8Array,
-): Cid<TVersion, TCode, TMultihashCode> {
+): Cid<TVersion, TCodec, THashCode> {
   return {
     version,
     code,
-    multihash: { code: multihashCode, digest },
-    bytes: new Uint8Array([
-      version,
-      code,
-      multihashCode,
-      digest.length,
-      ...digest,
-    ]),
+    multihash: { code: hashCode, digest },
+    bytes: new Uint8Array([version, code, hashCode, digest.length, ...digest]),
     toString,
     equals,
   }

package/src/cid.test.ts

@@ -3,10 +3,10 @@ import { sha256, sha512 } from 'multiformats/hashes/sha2'
 import { describe, expect, it } from 'vitest'
 import { BytesCid, createCustomCid } from './cid-implementation.test.js'
 import {
+  CBOR_DATA_CODEC,
   Cid,
-  DAG_CBOR_MULTICODEC,
-  RAW_MULTICODEC,
-  SHA256_MULTIHASH,
+  RAW_DATA_CODEC,
+  SHA256_HASH_CODE,
   asMultiformatsCID,
   cidForRawHash,
   decodeCid,
@@ -28,8 +28,8 @@ const rawCid = parseCid(rawCidStr, { flavor: 'raw' })
 
 const rawCidLike: Cid = createCustomCid(
   1,
-  RAW_MULTICODEC,
-  SHA256_MULTIHASH,
+  RAW_DATA_CODEC,
+  SHA256_HASH_CODE,
   rawCid.multihash.digest,
 )
 const rawBytesCid = new BytesCid(rawCid.bytes)
@@ -49,7 +49,7 @@ describe(isCid, () => {
     it('returns true for CID v0 and v1', async () => {
       const digest = await sha256.digest(Buffer.from('hello world'))
       const cidV0 = CID.createV0(digest)
-      const cidV1 = CID.createV1(RAW_MULTICODEC, digest)
+      const cidV1 = CID.createV1(RAW_DATA_CODEC, digest)
       expect(isCid(cidV0)).toBe(true)
       expect(isCid(cidV1)).toBe(true)
     })
@@ -65,13 +65,13 @@ describe(isCid, () => {
     describe('raw', () => {
       it('validated "raw" cids', async () => {
         const digest = await sha256.digest(Buffer.from('hello world'))
-        const cid = CID.createV1(RAW_MULTICODEC, digest)
+        const cid = CID.createV1(RAW_DATA_CODEC, digest)
         expect(isCid(cid, { flavor: 'raw' })).toBe(true)
       })
 
       it('allows other hash algorithms', async () => {
         const digest = await sha512.digest(Buffer.from('hello world'))
-        const cid = CID.createV1(RAW_MULTICODEC, digest)
+        const cid = CID.createV1(RAW_DATA_CODEC, digest)
         expect(isCid(cid, { flavor: 'raw' })).toBe(true)
       })
 
@@ -91,13 +91,13 @@ describe(isCid, () => {
     describe('cbor', () => {
       it('validated "cbor" cids', async () => {
         const digest = await sha256.digest(Buffer.from('hello world'))
-        const cid = CID.createV1(DAG_CBOR_MULTICODEC, digest)
+        const cid = CID.createV1(CBOR_DATA_CODEC, digest)
         expect(isCid(cid, { flavor: 'cbor' })).toBe(true)
       })
 
       it('rejects CIDs with invalid hash algorithm', async () => {
         const digest = await sha512.digest(Buffer.from('hello world'))
-        const cid = CID.createV1(RAW_MULTICODEC, digest)
+        const cid = CID.createV1(RAW_DATA_CODEC, digest)
         expect(isCid(cid, { flavor: 'cbor' })).toBe(false)
       })
 
@@ -266,7 +266,7 @@ describe(isCidForBytes, () => {
       for (const hasher of [sha256, sha512]) {
         const data = new TextEncoder().encode('hello world')
         const digest = await hasher.digest(data)
-        const cid = CID.createV1(RAW_MULTICODEC, digest)
+        const cid = CID.createV1(RAW_DATA_CODEC, digest)
         expect(await isCidForBytes(cid, data)).toBe(true)
 
         data[0] = data[0] ^ 0xff
@@ -281,7 +281,7 @@ describe(isCidForBytes, () => {
         // @NOTE this is not valid CBOR, but sufficient for testing the hash
         const data = new TextEncoder().encode('hello world')
         const digest = await hasher.digest(data)
-        const cid = CID.createV1(DAG_CBOR_MULTICODEC, digest)
+        const cid = CID.createV1(CBOR_DATA_CODEC, digest)
         expect(await isCidForBytes(cid, data)).toBe(true)
 
         data[0] = data[0] ^ 0xff
@@ -318,8 +318,8 @@ describe(cidForRawHash, () => {
   it('creates a RawCid from a SHA-256 hash', () => {
     const hash = new Uint8Array(32)
     const cid = cidForRawHash(hash)
-    expect(cid.code).toBe(RAW_MULTICODEC)
-    expect(cid.multihash.code).toBe(SHA256_MULTIHASH)
+    expect(cid.code).toBe(RAW_DATA_CODEC)
+    expect(cid.multihash.code).toBe(SHA256_HASH_CODE)
     expect(ui8Equals(cid.multihash.digest, hash)).toBe(true)
   })