@atproto/lex-cbor 0.0.10 → 0.0.12

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @atproto/lex-cbor
 
+## 0.0.12
+
+### Patch Changes
+
+- Updated dependencies [[`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df)]:
+  - @atproto/lex-data@0.0.12
+
+## 0.0.11
+
+### Patch Changes
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fix `exports` field in package.json
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add JSDoc
+
+- Updated dependencies [[`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015)]:
+  - @atproto/lex-data@0.0.11
+
 ## 0.0.10
 
 ### Patch Changes

package/dist/encoding.d.ts

@@ -1,7 +1,100 @@
 import { LexValue } from '@atproto/lex-data';
+/**
+ * Configuration options for CBOR encoding that enforces AT Protocol data model
+ * constraints.
+ *
+ * This configuration ensures:
+ * - CIDs are encoded using CBOR tag 42 with a leading 0x00 byte prefix
+ * - Map keys must be strings (no numeric or other key types allowed)
+ * - `undefined` values are not permitted (undefined object properties will be stripped)
+ * - Only safe integer numbers are allowed (no floats or non-integer values)
+ */
 export declare const encodeOptions: Readonly<import("cborg/interface").EncodeOptions>;
+/**
+ * Configuration options for CBOR decoding that enforces AT Protocol data model
+ * constraints.
+ */
 export declare const decodeOptions: Readonly<import("cborg/interface").DecodeOptions>;
+/**
+ * Encodes a LexValue to CBOR bytes using the AT Protocol data model (DRISL format).
+ *
+ * @param data - The LexValue to encode
+ * @returns The CBOR-encoded bytes
+ * @throws {Error} If the data contains non-string map keys, undefined values, or non-integer numbers
+ *
+ * @example
+ * ```typescript
+ * import { encode } from '@atproto/lex-cbor'
+ *
+ * // Encode a simple object
+ * const bytes = encode({ text: 'Hello', count: 42 })
+ *
+ * // Encode an AT Protocol record
+ * const recordBytes = encode({
+ *   $type: 'app.bsky.feed.post',
+ *   text: 'Hello from AT Protocol!',
+ *   createdAt: new Date().toISOString(),
+ * })
+ * ```
+ */
 export declare function encode<T extends LexValue = LexValue>(data: T): Uint8Array;
+/**
+ * Decodes CBOR bytes to a LexValue using the AT Protocol data model (DRISL format).
+ *
+ * @typeParam T - Allows casting the decoded values to a specific LexValue subtype
+ * @param bytes - The CBOR bytes to decode
+ * @returns The decoded LexValue
+ * @throws {Error} If the bytes are not valid CBOR or violate AT Protocol constraints
+ *
+ * @example
+ * ```typescript
+ * import { encode, decode } from '@atproto/lex-cbor'
+ * import type { LexValue } from '@atproto/lex'
+ *
+ * // Round-trip encoding and decoding
+ * const original = { text: 'Hello', count: 42 }
+ * const bytes = encode(original)
+ * const decoded: LexValue = decode(bytes)
+ *
+ * // Decode with a specific type
+ * interface Post {
+ *   $type: string
+ *   text: string
+ *   createdAt: string
+ * }
+ * const post = decode<Post>(recordBytes)
+ * ```
+ */
 export declare function decode<T extends LexValue = LexValue>(bytes: Uint8Array): T;
+/**
+ * Generator that yields multiple decoded LexValues from a buffer containing
+ * concatenated CBOR-encoded values.
+ *
+ * This is useful for processing streams or files containing multiple
+ * CBOR-encoded records back-to-back (e.g., CAR file blocks or event streams).
+ *
+ * @typeParam T - Allows casting the decoded values to a specific LexValue subtype
+ * @param data - The buffer containing one or more CBOR-encoded values
+ * @yields Decoded LexValues one at a time
+ * @throws {Error} If any value in the buffer is not valid CBOR or violates AT Protocol constraints
+ *
+ * @example
+ * ```typescript
+ * import { encode, decodeAll } from '@atproto/lex-cbor'
+ *
+ * // Concatenate multiple encoded values
+ * const bytes1 = encode({ id: 1, text: 'First' })
+ * const bytes2 = encode({ id: 2, text: 'Second' })
+ * const combined = new Uint8Array([...bytes1, ...bytes2])
+ *
+ * // Decode all values from the combined buffer
+ * for (const value of decodeAll(combined)) {
+ *   console.log(value)
+ * }
+ * // Output:
+ * // { id: 1, text: 'First' }
+ * // { id: 2, text: 'Second' }
+ * ```
+ */
 export declare function decodeAll<T extends LexValue = LexValue>(data: Uint8Array): Generator<T, void, unknown>;
 //# sourceMappingURL=encoding.d.ts.map

package/dist/encoding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"AAWA,OAAO,EAAO,QAAQ,EAAoB,MAAM,mBAAmB,CAAA;AASnE,eAAO,MAAM,aAAa,mDAsCxB,CAAA;AAEF,eAAO,MAAM,aAAa,mDAoBxB,CAAA;AAEF,wBAAgB,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,UAAU,CAEzE;AAED,wBAAgB,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,KAAK,EAAE,UAAU,GAAG,CAAC,CAE1E;AAED,wBAAiB,SAAS,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EACtD,IAAI,EAAE,UAAU,GACf,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAM7B"}
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"AAWA,OAAO,EAAO,QAAQ,EAAoB,MAAM,mBAAmB,CAAA;AASnE;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,mDAsCxB,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,mDAoBxB,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,UAAU,CAEzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,KAAK,EAAE,UAAU,GAAG,CAAC,CAE1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAiB,SAAS,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EACtD,IAAI,EAAE,UAAU,GACf,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAM7B"}

package/dist/index.d.ts

@@ -3,5 +3,29 @@ export type { Cid } from '@atproto/lex-data';
 export type { CborCid, LexValue };
 export { decode, decodeAll, encode } from './encoding.js';
 export { decode as cborDecode, decodeAll as cborDecodeAll, decodeOptions, encode as cborEncode, encodeOptions, } from './encoding.js';
+/**
+ * Computes a CID (Content Identifier) for a given LexValue.
+ *
+ * This function first encodes the value to CBOR bytes using the AT Protocol
+ * data model constraints, then computes the CID hash of those bytes. The
+ * resulting CID can be used to uniquely identify and reference the content.
+ *
+ * @param value - The LexValue to compute a CID for
+ * @returns A promise that resolves to the CID for the CBOR-encoded value
+ *
+ * @example
+ * ```typescript
+ * import { cidForLex } from '@atproto/lex-cbor'
+ *
+ * const record = {
+ *   $type: 'app.bsky.feed.post',
+ *   text: 'Hello, AT Protocol!',
+ *   createdAt: new Date().toISOString(),
+ * }
+ *
+ * const cid = await cidForLex(record)
+ * console.log(cid.toString()) // e.g., 'bafyreih...'
+ * ```
+ */
 export declare function cidForLex(value: LexValue): Promise<CborCid>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAc,MAAM,mBAAmB,CAAA;AAGjE,YAAY,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AAC5C,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAA;AAEjC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAEzD,OAAO,EACL,MAAM,IAAI,UAAU,EACpB,SAAS,IAAI,aAAa,EAC1B,aAAa,EACb,MAAM,IAAI,UAAU,EACpB,aAAa,GACd,MAAM,eAAe,CAAA;AAEtB,wBAAsB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAEjE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAc,MAAM,mBAAmB,CAAA;AAGjE,YAAY,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AAC5C,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAA;AAEjC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAEzD,OAAO,EACL,MAAM,IAAI,UAAU,EACpB,SAAS,IAAI,aAAa,EAC1B,aAAa,EACb,MAAM,IAAI,UAAU,EACpB,aAAa,GACd,MAAM,eAAe,CAAA;AAEtB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAEjE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-cbor",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "license": "MIT",
   "description": "Lexicon encoding utilities for AT Lexicon data in CBOR format",
   "keywords": [
@@ -26,25 +26,27 @@
     "./CHANGELOG.md"
   ],
   "sideEffects": false,
+  "type": "commonjs",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/index.mjs",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "default": "./dist/index.cjs"
     }
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/lex-data": "^0.0.10"
+    "@atproto/lex-data": "^0.0.12"
   },
   "devDependencies": {
     "cborg": "^4.5.8",
     "vite": "^6.2.0",
     "vitest": "^4.0.16",
-    "@atproto/lex-json": "^0.0.10"
+    "@atproto/lex-json": "^0.0.12"
   },
   "scripts": {
     "dev": "vite build --watch",

package/src/encoding.ts

@@ -18,6 +18,16 @@ import { Cid, LexValue, decodeCid, ifCid } from '@atproto/lex-data'
 
 const CID_CBOR_TAG = 42
 
+/**
+ * Configuration options for CBOR encoding that enforces AT Protocol data model
+ * constraints.
+ *
+ * This configuration ensures:
+ * - CIDs are encoded using CBOR tag 42 with a leading 0x00 byte prefix
+ * - Map keys must be strings (no numeric or other key types allowed)
+ * - `undefined` values are not permitted (undefined object properties will be stripped)
+ * - Only safe integer numbers are allowed (no floats or non-integer values)
+ */
 export const encodeOptions = Object.freeze<EncodeOptions>({
   float64: true,
   ignoreUndefinedProperties: true,
@@ -58,6 +68,10 @@ export const encodeOptions = Object.freeze<EncodeOptions>({
   }),
 })
 
+/**
+ * Configuration options for CBOR decoding that enforces AT Protocol data model
+ * constraints.
+ */
 export const decodeOptions = /*#__PURE__*/ Object.freeze<DecodeOptions>({
   allowIndefinite: false,
   coerceUndefinedToNull: true,
@@ -80,14 +94,93 @@ export const decodeOptions = /*#__PURE__*/ Object.freeze<DecodeOptions>({
   ) as TagDecoder[],
 })
 
+/**
+ * Encodes a LexValue to CBOR bytes using the AT Protocol data model (DRISL format).
+ *
+ * @param data - The LexValue to encode
+ * @returns The CBOR-encoded bytes
+ * @throws {Error} If the data contains non-string map keys, undefined values, or non-integer numbers
+ *
+ * @example
+ * ```typescript
+ * import { encode } from '@atproto/lex-cbor'
+ *
+ * // Encode a simple object
+ * const bytes = encode({ text: 'Hello', count: 42 })
+ *
+ * // Encode an AT Protocol record
+ * const recordBytes = encode({
+ *   $type: 'app.bsky.feed.post',
+ *   text: 'Hello from AT Protocol!',
+ *   createdAt: new Date().toISOString(),
+ * })
+ * ```
+ */
 export function encode<T extends LexValue = LexValue>(data: T): Uint8Array {
   return cborgEncode(data, encodeOptions)
 }
 
+/**
+ * Decodes CBOR bytes to a LexValue using the AT Protocol data model (DRISL format).
+ *
+ * @typeParam T - Allows casting the decoded values to a specific LexValue subtype
+ * @param bytes - The CBOR bytes to decode
+ * @returns The decoded LexValue
+ * @throws {Error} If the bytes are not valid CBOR or violate AT Protocol constraints
+ *
+ * @example
+ * ```typescript
+ * import { encode, decode } from '@atproto/lex-cbor'
+ * import type { LexValue } from '@atproto/lex'
+ *
+ * // Round-trip encoding and decoding
+ * const original = { text: 'Hello', count: 42 }
+ * const bytes = encode(original)
+ * const decoded: LexValue = decode(bytes)
+ *
+ * // Decode with a specific type
+ * interface Post {
+ *   $type: string
+ *   text: string
+ *   createdAt: string
+ * }
+ * const post = decode<Post>(recordBytes)
+ * ```
+ */
 export function decode<T extends LexValue = LexValue>(bytes: Uint8Array): T {
   return cborgDecode(bytes, decodeOptions)
 }
 
+/**
+ * Generator that yields multiple decoded LexValues from a buffer containing
+ * concatenated CBOR-encoded values.
+ *
+ * This is useful for processing streams or files containing multiple
+ * CBOR-encoded records back-to-back (e.g., CAR file blocks or event streams).
+ *
+ * @typeParam T - Allows casting the decoded values to a specific LexValue subtype
+ * @param data - The buffer containing one or more CBOR-encoded values
+ * @yields Decoded LexValues one at a time
+ * @throws {Error} If any value in the buffer is not valid CBOR or violates AT Protocol constraints
+ *
+ * @example
+ * ```typescript
+ * import { encode, decodeAll } from '@atproto/lex-cbor'
+ *
+ * // Concatenate multiple encoded values
+ * const bytes1 = encode({ id: 1, text: 'First' })
+ * const bytes2 = encode({ id: 2, text: 'Second' })
+ * const combined = new Uint8Array([...bytes1, ...bytes2])
+ *
+ * // Decode all values from the combined buffer
+ * for (const value of decodeAll(combined)) {
+ *   console.log(value)
+ * }
+ * // Output:
+ * // { id: 1, text: 'First' }
+ * // { id: 2, text: 'Second' }
+ * ```
+ */
 export function* decodeAll<T extends LexValue = LexValue>(
   data: Uint8Array,
 ): Generator<T, void, unknown> {

package/src/index.ts

@@ -14,6 +14,30 @@ export {
   encodeOptions,
 } from './encoding.js'
 
+/**
+ * Computes a CID (Content Identifier) for a given LexValue.
+ *
+ * This function first encodes the value to CBOR bytes using the AT Protocol
+ * data model constraints, then computes the CID hash of those bytes. The
+ * resulting CID can be used to uniquely identify and reference the content.
+ *
+ * @param value - The LexValue to compute a CID for
+ * @returns A promise that resolves to the CID for the CBOR-encoded value
+ *
+ * @example
+ * ```typescript
+ * import { cidForLex } from '@atproto/lex-cbor'
+ *
+ * const record = {
+ *   $type: 'app.bsky.feed.post',
+ *   text: 'Hello, AT Protocol!',
+ *   createdAt: new Date().toISOString(),
+ * }
+ *
+ * const cid = await cidForLex(record)
+ * console.log(cid.toString()) // e.g., 'bafyreih...'
+ * ```
+ */
 export async function cidForLex(value: LexValue): Promise<CborCid> {
   return cidForCbor(encode(value))
 }