@atproto/lex-data 0.0.2 → 0.0.4

package/dist/uint8array-to-base64.js.map

@@ -1 +1 @@
-{"version":3,"file":"uint8array-to-base64.js","sourceRoot":"","sources":["../src/uint8array-to-base64.ts"],"names":[],"mappings":";;;AA0CA,4CAEC;AA5CD,qDAAgD;AAChD,6DAAqD;AAErD,MAAM,MAAM,GAAG,+BAAY,CAAA;AAed,QAAA,cAAc,GACzB,OAAO,UAAU,CAAC,SAAS,CAAC,QAAQ,KAAK,UAAU;IACjD,CAAC,CAAC,SAAS,cAAc,CAAC,KAAiB;QACvC,OAAO,KAAK,CAAC,QAAS,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAA;IAC/C,CAAC;IACH,CAAC,CAAC,IAAI,CAAA;AAEG,QAAA,YAAY,GAAG,MAAM;IAChC,CAAC,CAAC,SAAS,YAAY,CAAC,KAAiB;QACrC,MAAM,GAAG,GAAG,CACV,KAAK,YAAY,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CACrD,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;QACpB,uDAAuD;QACvD,0EAA0E;QAC1E,sEAAsE;QACtE,6DAA6D;QAC7D,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI;YACtD,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI;gBACjD,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO;gBAC1B,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM;YAC3B,CAAC,CAAC,GAAG,CAAA;IACT,CAAC;IACH,CAAC,CAAC,IAAI,CAAA;AAER,SAAgB,gBAAgB,CAAC,KAAiB;IAChD,OAAO,IAAA,oBAAQ,EAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;AAClC,CAAC","sourcesContent":["import { toString } from 'uint8arrays/to-string'\nimport { NodeJSBuffer } from './lib/nodejs-buffer.js'\n\nconst Buffer = NodeJSBuffer\n\ndeclare global {\n  interface Uint8Array {\n    /**\n     * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array/toBase64 Uint8Array.prototype.toBase64()}\n     */\n    toBase64?: (options?: {\n      /** @default 'base64' */\n      alphabet?: 'base64' | 'base64url'\n      omitPadding?: boolean\n    }) => string\n  }\n}\n\nexport const toBase64Native =\n  typeof Uint8Array.prototype.toBase64 === 'function'\n    ? function toBase64Native(bytes: Uint8Array): string {\n        return bytes.toBase64!({ omitPadding: true })\n      }\n    : null\n\nexport const toBase64Node = Buffer\n  ? function toBase64Node(bytes: Uint8Array): string {\n      const b64 = (\n        bytes instanceof Buffer ? bytes : Buffer.from(bytes)\n      ).toString('base64')\n      // @NOTE We strip padding for strict compatibility with\n      // uint8arrays.toString behavior. Tests failing because of the presence of\n      // padding are not really synonymous with an actual error and we might\n      // (should?) actually want to keep the padding at some point.\n      return b64.charCodeAt(b64.length - 1) === /* '=' */ 0x3d\n        ? b64.charCodeAt(b64.length - 2) === /* '=' */ 0x3d\n          ? b64.slice(0, -2) // '=='\n          : b64.slice(0, -1) // '='\n        : b64\n    }\n  : null\n\nexport function toBase64Ponyfill(bytes: Uint8Array): string {\n  return toString(bytes, 'base64')\n}\n"]}
+{"version":3,"file":"uint8array-to-base64.js","sourceRoot":"","sources":["../src/uint8array-to-base64.ts"],"names":[],"mappings":";;;AAiDA,4CAKC;AAtDD,qDAAgD;AAChD,6DAAqD;AAGrD,MAAM,MAAM,GAAG,+BAAY,CAAA;AAed,QAAA,cAAc,GACzB,OAAO,UAAU,CAAC,SAAS,CAAC,QAAQ,KAAK,UAAU;IACjD,CAAC,CAAC,SAAS,cAAc,CACrB,KAAiB,EACjB,WAA2B,QAAQ;QAEnC,OAAO,KAAK,CAAC,QAAS,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAA;IACzD,CAAC;IACH,CAAC,CAAC,IAAI,CAAA;AAEG,QAAA,YAAY,GAAG,MAAM;IAChC,CAAC,CAAC,SAAS,YAAY,CACnB,KAAiB,EACjB,WAA2B,QAAQ;QAEnC,MAAM,MAAM,GAAG,KAAK,YAAY,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACnE,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;QAErC,uDAAuD;QACvD,0EAA0E;QAC1E,sEAAsE;QACtE,6DAA6D;QAC7D,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI;YACtD,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI;gBACjD,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO;gBAC1B,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM;YAC3B,CAAC,CAAC,GAAG,CAAA;IACT,CAAC;IACH,CAAC,CAAC,IAAI,CAAA;AAER,SAAgB,gBAAgB,CAC9B,KAAiB,EACjB,WAA2B,QAAQ;IAEnC,OAAO,IAAA,oBAAQ,EAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;AAClC,CAAC","sourcesContent":["import { toString } from 'uint8arrays/to-string'\nimport { NodeJSBuffer } from './lib/nodejs-buffer.js'\nimport { Base64Alphabet } from './uint8array-base64.js'\n\nconst Buffer = NodeJSBuffer\n\ndeclare global {\n  interface Uint8Array {\n    /**\n     * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array/toBase64 Uint8Array.prototype.toBase64()}\n     */\n    toBase64?: (options?: {\n      /** @default 'base64' */\n      alphabet?: 'base64' | 'base64url'\n      omitPadding?: boolean\n    }) => string\n  }\n}\n\nexport const toBase64Native =\n  typeof Uint8Array.prototype.toBase64 === 'function'\n    ? function toBase64Native(\n        bytes: Uint8Array,\n        alphabet: Base64Alphabet = 'base64',\n      ): string {\n        return bytes.toBase64!({ alphabet, omitPadding: true })\n      }\n    : null\n\nexport const toBase64Node = Buffer\n  ? function toBase64Node(\n      bytes: Uint8Array,\n      alphabet: Base64Alphabet = 'base64',\n    ): string {\n      const buffer = bytes instanceof Buffer ? bytes : Buffer.from(bytes)\n      const b64 = buffer.toString(alphabet)\n\n      // @NOTE We strip padding for strict compatibility with\n      // uint8arrays.toString behavior. Tests failing because of the presence of\n      // padding are not really synonymous with an actual error and we might\n      // (should?) actually want to keep the padding at some point.\n      return b64.charCodeAt(b64.length - 1) === /* '=' */ 0x3d\n        ? b64.charCodeAt(b64.length - 2) === /* '=' */ 0x3d\n          ? b64.slice(0, -2) // '=='\n          : b64.slice(0, -1) // '='\n        : b64\n    }\n  : null\n\nexport function toBase64Ponyfill(\n  bytes: Uint8Array,\n  alphabet: Base64Alphabet = 'base64',\n): string {\n  return toString(bytes, alphabet)\n}\n"]}

package/dist/uint8array.d.ts

@@ -1,16 +1,19 @@
+import { Base64Alphabet } from './uint8array-base64.js';
+export type { Base64Alphabet };
 /**
  * Encodes a Uint8Array into a base64 string.
  *
  * @returns The base64 encoded string
  */
-export declare const toBase64: (bytes: Uint8Array) => string;
+export declare const toBase64: (bytes: Uint8Array, alphabet?: Base64Alphabet) => string;
 /**
- * Decodes a base64 string into a Uint8Array.
+ * Decodes a base64 string into a Uint8Array. This function supports both padded
+ * and unpadded base64 strings.
  *
  * @returns The decoded {@link Uint8Array}
  * @throws If the input is not a valid base64 string
  */
-export declare const fromBase64: (b64: string) => Uint8Array;
+export declare const fromBase64: (b64: string, alphabet?: Base64Alphabet) => Uint8Array;
 /**
  * Coerces various binary data representations into a Uint8Array.
  *

package/dist/uint8array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uint8array.d.ts","sourceRoot":"","sources":["../src/uint8array.ts"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MACM,CAAA;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,UACgB,CAAA;AAS1D;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAkBnE;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAY/D"}
+{"version":3,"file":"uint8array.d.ts","sourceRoot":"","sources":["../src/uint8array.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAYvD,YAAY,EAAE,cAAc,EAAE,CAAA;AAO9B;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,CACrB,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,cAAc,KACtB,MAA2D,CAAA;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,CACvB,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,cAAc,KACtB,UAAqE,CAAA;AAS1E;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAkBnE;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAY/D"}

package/dist/uint8array.js

@@ -16,7 +16,8 @@ const uint8array_to_base64_js_1 = require("./uint8array-to-base64.js");
  */
 exports.toBase64 = uint8array_to_base64_js_1.toBase64Native ?? uint8array_to_base64_js_1.toBase64Node ?? uint8array_to_base64_js_1.toBase64Ponyfill;
 /**
- * Decodes a base64 string into a Uint8Array.
+ * Decodes a base64 string into a Uint8Array. This function supports both padded
+ * and unpadded base64 strings.
  *
  * @returns The decoded {@link Uint8Array}
  * @throws If the input is not a valid base64 string

package/dist/uint8array.js.map

@@ -1 +1 @@
-{"version":3,"file":"uint8array.js","sourceRoot":"","sources":["../src/uint8array.ts"],"names":[],"mappings":";;;AA6CA,oCAkBC;AAED,8BAYC;AA7ED,2EAIoC;AACpC,uEAIkC;AAElC,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,0CAA0C;AAE1C;;;;GAIG;AACU,QAAA,QAAQ,GACnB,wCAAc,IAAI,sCAAY,IAAI,0CAAgB,CAAA;AAEpD;;;;;GAKG;AACU,QAAA,UAAU,GACrB,4CAAgB,IAAI,0CAAc,IAAI,8CAAkB,CAAA;AAE1D,IAAI,gBAAQ,KAAK,0CAAgB,IAAI,kBAAU,KAAK,8CAAkB,EAAE,CAAC;IACvE,aAAa;IACb,OAAO,CAAC,IAAI,CACV,wJAAwJ,CACzJ,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,UAAU,CACnB,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC,iBAAiB,CAChD,CAAA;IACH,CAAC;IAED,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,SAAgB,SAAS,CAAC,CAAa,EAAE,CAAa;IACpD,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,EAAE,CAAC;QAClC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAClB,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC","sourcesContent":["import {\n  fromBase64Native,\n  fromBase64Node,\n  fromBase64Ponyfill,\n} from './uint8array-from-base64.js'\nimport {\n  toBase64Native,\n  toBase64Node,\n  toBase64Ponyfill,\n} from './uint8array-to-base64.js'\n\n// @TODO drop dependency on uint8arrays package once Uint8Array.fromBase64 /\n// Uint8Array.prototype.toBase64 is widely supported, and mark fromBase64 /\n// toBase64 as deprecated. We can also drop NodeJS specific implementations\n// once NodeJS <24 is no longer supported.\n\n/**\n * Encodes a Uint8Array into a base64 string.\n *\n * @returns The base64 encoded string\n */\nexport const toBase64: (bytes: Uint8Array) => string =\n  toBase64Native ?? toBase64Node ?? toBase64Ponyfill\n\n/**\n * Decodes a base64 string into a Uint8Array.\n *\n * @returns The decoded {@link Uint8Array}\n * @throws If the input is not a valid base64 string\n */\nexport const fromBase64: (b64: string) => Uint8Array =\n  fromBase64Native ?? fromBase64Node ?? fromBase64Ponyfill\n\nif (toBase64 === toBase64Ponyfill || fromBase64 === fromBase64Ponyfill) {\n  /*#__PURE__*/\n  console.warn(\n    '[@atproto/lex-data]: Uint8Array.fromBase64 / Uint8Array.prototype.toBase64 not available in this environment. Falling back to ponyfill implementation.',\n  )\n}\n\n/**\n * Coerces various binary data representations into a Uint8Array.\n *\n * @return `undefined` if the input could not be coerced into a {@link Uint8Array}.\n */\nexport function asUint8Array(input: unknown): Uint8Array | undefined {\n  if (input instanceof Uint8Array) {\n    return input\n  }\n\n  if (ArrayBuffer.isView(input)) {\n    return new Uint8Array(\n      input.buffer,\n      input.byteOffset,\n      input.byteLength / Uint8Array.BYTES_PER_ELEMENT,\n    )\n  }\n\n  if (input instanceof ArrayBuffer) {\n    return new Uint8Array(input)\n  }\n\n  return undefined\n}\n\nexport function ui8Equals(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.byteLength !== b.byteLength) {\n    return false\n  }\n\n  for (let i = 0; i < a.byteLength; i++) {\n    if (a[i] !== b[i]) {\n      return false\n    }\n  }\n\n  return true\n}\n"]}
+{"version":3,"file":"uint8array.js","sourceRoot":"","sources":["../src/uint8array.ts"],"names":[],"mappings":";;;AAqDA,oCAkBC;AAED,8BAYC;AApFD,2EAIoC;AACpC,uEAIkC;AAIlC,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,0CAA0C;AAE1C;;;;GAIG;AACU,QAAA,QAAQ,GAGP,wCAAc,IAAI,sCAAY,IAAI,0CAAgB,CAAA;AAEhE;;;;;;GAMG;AACU,QAAA,UAAU,GAGL,4CAAgB,IAAI,0CAAc,IAAI,8CAAkB,CAAA;AAE1E,IAAI,gBAAQ,KAAK,0CAAgB,IAAI,kBAAU,KAAK,8CAAkB,EAAE,CAAC;IACvE,aAAa;IACb,OAAO,CAAC,IAAI,CACV,wJAAwJ,CACzJ,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,UAAU,CACnB,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC,iBAAiB,CAChD,CAAA;IACH,CAAC;IAED,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,SAAgB,SAAS,CAAC,CAAa,EAAE,CAAa;IACpD,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,EAAE,CAAC;QAClC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAClB,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC","sourcesContent":["import { Base64Alphabet } from './uint8array-base64.js'\nimport {\n  fromBase64Native,\n  fromBase64Node,\n  fromBase64Ponyfill,\n} from './uint8array-from-base64.js'\nimport {\n  toBase64Native,\n  toBase64Node,\n  toBase64Ponyfill,\n} from './uint8array-to-base64.js'\n\nexport type { Base64Alphabet }\n\n// @TODO drop dependency on uint8arrays package once Uint8Array.fromBase64 /\n// Uint8Array.prototype.toBase64 is widely supported, and mark fromBase64 /\n// toBase64 as deprecated. We can also drop NodeJS specific implementations\n// once NodeJS <24 is no longer supported.\n\n/**\n * Encodes a Uint8Array into a base64 string.\n *\n * @returns The base64 encoded string\n */\nexport const toBase64: (\n  bytes: Uint8Array,\n  alphabet?: Base64Alphabet,\n) => string = toBase64Native ?? toBase64Node ?? toBase64Ponyfill\n\n/**\n * Decodes a base64 string into a Uint8Array. This function supports both padded\n * and unpadded base64 strings.\n *\n * @returns The decoded {@link Uint8Array}\n * @throws If the input is not a valid base64 string\n */\nexport const fromBase64: (\n  b64: string,\n  alphabet?: Base64Alphabet,\n) => Uint8Array = fromBase64Native ?? fromBase64Node ?? fromBase64Ponyfill\n\nif (toBase64 === toBase64Ponyfill || fromBase64 === fromBase64Ponyfill) {\n  /*#__PURE__*/\n  console.warn(\n    '[@atproto/lex-data]: Uint8Array.fromBase64 / Uint8Array.prototype.toBase64 not available in this environment. Falling back to ponyfill implementation.',\n  )\n}\n\n/**\n * Coerces various binary data representations into a Uint8Array.\n *\n * @return `undefined` if the input could not be coerced into a {@link Uint8Array}.\n */\nexport function asUint8Array(input: unknown): Uint8Array | undefined {\n  if (input instanceof Uint8Array) {\n    return input\n  }\n\n  if (ArrayBuffer.isView(input)) {\n    return new Uint8Array(\n      input.buffer,\n      input.byteOffset,\n      input.byteLength / Uint8Array.BYTES_PER_ELEMENT,\n    )\n  }\n\n  if (input instanceof ArrayBuffer) {\n    return new Uint8Array(input)\n  }\n\n  return undefined\n}\n\nexport function ui8Equals(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.byteLength !== b.byteLength) {\n    return false\n  }\n\n  for (let i = 0; i < a.byteLength; i++) {\n    if (a[i] !== b[i]) {\n      return false\n    }\n  }\n\n  return true\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-data",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "license": "MIT",
   "description": "Core utilities for AT Lexicons",
   "keywords": [

package/src/blob.ts

@@ -7,6 +7,9 @@ import {
 } from './cid.js'
 import { isPlainObject } from './object.js'
 
+/**
+ * @note {@link BlobRef} is just a {@link LexMap} with a specific shape.
+ */
 export type BlobRef = {
   $type: 'blob'
   mimeType: string
@@ -32,7 +35,12 @@ export function isBlobRef(
     return false
   }
 
-  if (typeof size !== 'number' || size < 0 || !Number.isInteger(size)) {
+  if (
+    typeof size !== 'number' ||
+    size < 0 ||
+    !Number.isInteger(size) ||
+    !Number.isSafeInteger(size)
+  ) {
     return false
   }
 
@@ -71,6 +79,9 @@ export function isBlobRef(
   return true
 }
 
+/**
+ * @note {@link LegacyBlobRef} is just a {@link LexMap} with a specific shape.
+ */
 export type LegacyBlobRef = {
   cid: string
   mimeType: string

package/src/cid.ts

@@ -22,21 +22,20 @@ declare module 'multiformats/cid' {
    * `multiformats/cid` in dependent packages, and instead have them rely on the
    * {@link Cid} interface from `@atproto/lex-data`. The {@link CID} class from
    * `multiformats` version <10 has compatibility issues with certain TypeScript
-   * module resolution strategies, which can lead to type errors in dependent
-   * packages.
+   * configuration, which can lead to type errors in dependent packages.
    *
    * We are stuck with version 9 because `@atproto` packages did not drop
    * CommonJS support yet, and multiformats version 10 only supports ES modules.
    *
    * In order to avoid compatibility issues, while preparing for future breaking
    * changes (CID in multiformats v10+ has a slightly different interface), as
-   * we update or swap out `multiformats`, we provide our own stable `Cid`
+   * we update or swap out `multiformats`, we provide our own stable {@link Cid}
    * interface.
    */
   interface CID {}
 }
 
-// CID form "multiformats" is not very portable because:
+// multiformats' CID class is not very portable because:
 //
 // - In dependent packages that use "moduleResolution" set to "node16",
 //   "nodenext" or "bundler", TypeScript fails to properly resolve the
@@ -46,14 +45,15 @@ declare module 'multiformats/cid' {
 //   uses "exports" field in package.json, which do not contain "types"
 //   entrypoints.
 //   https://www.npmjs.com/package/multiformats/v/9.9.0?activeTab=code
-// - By defining our own Cid interface and related functions, we can have more
-//   control over the API we expose to dependent packages.
+// - By defining our own interface and helper functions, we can have more
+//   control over the public API exposed by this package.
 // - It allow us to have a stable interface in case we need to swap out, or
 //   eventually update multiformats (should we choose to drop CommonJS support)
 //   in the future.
 
 // @NOTE Even though it is not portable, we still re-export CID here so that
-// dependent packages where it can be used, have access to it.
+// dependent packages where it can be used, have access to it (instead of
+// importing directly from "multiformats" or"multiformats/cid").
 export { CID }
 
 /**

package/src/language.test.ts

@@ -1,62 +1,62 @@
-import { isLanguage, parseLanguage } from './language'
+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 +64,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.test.ts

@@ -1,4 +1,107 @@
-import { isTypedLexMap } from './lex'
+import { isLexValue, isTypedLexMap } from './lex'
+
+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: { code: 1, version: 1, multihash: new Uint8Array([18, 32]) },
+      },
+      {
+        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: 'record with non-Lex value',
+        value: {
+          a: 123,
+          b: () => {},
+        },
+      },
+      {
+        note: 'list with non-Lex value',
+        value: [123, 'blah', () => {}],
+      },
+    ]) {
+      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/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 (

package/src/uint8array-base64.ts

@@ -0,0 +1,2 @@
+/** @default 'base64' */
+export type Base64Alphabet = 'base64' | 'base64url'

package/src/uint8array-from-base64.test.ts

@@ -40,34 +40,48 @@ for (const fromBase64 of [
         expect(ui8Equals(decoded, bytes)).toBe(true)
       })
 
-      for (const string of [
-        '',
-        '\0\0',
-        '\0\0\0',
-        '\0\0\0\0',
-        '__',
-        'é',
-        'àç',
-        '\0éàç',
-        '```',
-        'aaa',
-        'Hello, World!',
-        '😀😃😄😁😆😅😂🤣😊😇',
-        '👩‍💻👨‍💻👩‍🔬👨‍🔬👩‍🚀👨‍🚀',
-        '🌍🌎🌏🌐🪐🌟✨⚡🔥💧',
-      ] as const) {
-        const buffer = Buffer.from(string, 'utf8')
+      for (const buffer of [
+        Buffer.from(''),
+        Buffer.from('\0\0'),
+        Buffer.from('\0\0\0'),
+        Buffer.from('\0\0\0\0'),
+        Buffer.from('__'),
+        Buffer.from('é'),
+        Buffer.from('àç'),
+        Buffer.from('\0éàç'),
+        Buffer.from('```'),
+        Buffer.from('aaa'),
+        Buffer.from('Hello, World!'),
+        Buffer.from('😀😃😄😁😆😅😂🤣😊😇'),
+        Buffer.from('👩‍💻👨‍💻👩‍🔬👨‍🔬👩‍🚀👨‍🚀'),
+        Buffer.from('🌍🌎🌏🌐🪐🌟✨⚡🔥💧'),
+        Buffer.from(new Uint8Array([0xfb, 0xff, 0xbf])),
+        Buffer.from(new Uint8Array([0xfb, 0xff, 0xbf])),
+        Buffer.from(new Uint8Array([0x4d])),
+        Buffer.from(new Uint8Array([0x4d, 0x61])),
+        Buffer.from(new Uint8Array([0x4d, 0x61, 0x6e])),
+        Buffer.from(new Uint8Array([0x4d])),
+        Buffer.from(new Uint8Array([0x4d, 0x61])),
+        Buffer.from(new Uint8Array([0x00, 0x4d, 0x61, 0x6e, 0x00])),
+      ]) {
         const base64 = buffer.toString('base64')
         const base64Unpadded = base64.replace(/=+$/, '')
+        const base64url = buffer.toString('base64url') // No padding in base64url
 
-        it(`decodes ${JSON.stringify(string)}`, () => {
+        it(`decodes ${JSON.stringify(base64)}`, () => {
           const decoded = fromBase64(base64)
           expect(decoded).toBeInstanceOf(Uint8Array)
           expect(ui8Equals(decoded, buffer)).toBe(true)
         })
 
+        it(`decodes ${JSON.stringify(base64url)} (base64url)`, () => {
+          const decoded = fromBase64(base64url, 'base64url')
+          expect(decoded).toBeInstanceOf(Uint8Array)
+          expect(ui8Equals(decoded, buffer)).toBe(true)
+        })
+
         if (base64 !== base64Unpadded) {
-          it(`decodes ${JSON.stringify(string)} (unpadded)`, () => {
+          it(`decodes ${JSON.stringify(base64Unpadded)} (unpadded)`, () => {
             const decoded = fromBase64(base64Unpadded)
             expect(decoded).toBeInstanceOf(Uint8Array)
             expect(ui8Equals(decoded, buffer)).toBe(true)