@atcute/cid 2.2.5 → 2.3.0

package/README.md

@@ -1,18 +1,87 @@
 # @atcute/cid
 
-lightweight [DASL CID][dasl-cid] codec library for AT Protocol.
+content identifier (CID) codec for AT Protocol.
+
+```sh
+npm install @atcute/cid
+```
+
+this library implements DASL's [CID][dasl-cid] format used by AT Protocol to address resources by
+their contents.
 
 [dasl-cid]: https://dasl.ing/cid.html
 
+## usage
+
+### creating CIDs
+
 ```ts
 import * as CID from '@atcute/cid';
 
+// create a CID from DAG-CBOR data
+const cid = await CID.create(0x71, cborBytes);
+// -> { version: 1, codec: 113, digest: { ... }, bytes: Uint8Array(36) }
+
+// create from raw data
+const rawCid = await CID.create(0x55, rawBytes);
+
+// create an empty CID (zero-length digest)
+const empty = CID.createEmpty(0x71);
+```
+
+### parsing CIDs
+
+```ts
+import * as CID from '@atcute/cid';
+
+// parse from base32 string
 const cid = CID.fromString('bafyreihffx5a2e7k5uwrmmgofbvzujc5cmw5h4espouwuxt3liqoflx3ee');
-//    ^? { version: 1, codec: 113, digest: { ... }, bytes: Uint8Array(36) }
 
-// Creating a CID containing CBOR data
-const cid = await CID.create(0x71, buffer);
+// parse from binary (with 0x00 prefix)
+const cid = CID.fromBinary(bytes);
+
+// parse from raw CID bytes
+const cid = CID.decode(cidBytes);
+```
+
+### serializing CIDs
+
+```ts
+import * as CID from '@atcute/cid';
+
+// to base32 string
+CID.toString(cid);
+// -> "bafyreihffx5a2e7k5uwrmmgofbvzujc5cmw5h4espouwuxt3liqoflx3ee"
+
+// to binary (with 0x00 prefix)
+CID.toBinary(cid);
+// -> Uint8Array(37)
+```
+
+### comparing CIDs
+
+```ts
+import * as CID from '@atcute/cid';
+
+CID.equals(cidA, cidB); // true if same content hash
+```
+
+### CidLink wrapper
+
+for JSON serialization compatible with atproto's data model:
+
+```ts
+import { toCidLink, fromCidLink, isCidLink } from '@atcute/cid';
+
+// convert Cid to CidLink (has $link property)
+const link = toCidLink(cid);
+// -> { $link: "bafyrei..." }
+
+// convert back to Cid
+const cid = fromCidLink(link);
 
-// Serializing CID into string
-CID.toString(cid); // -> bafyrei...
+// type guard
+if (isCidLink(value)) {
+	console.log(value.$link);
+}
 ```

package/dist/cid-link.d.ts

@@ -4,7 +4,7 @@ export interface CidLink {
 }
 export declare class CidLinkWrapper implements CidLink {
     readonly bytes: Uint8Array;
-    constructor(bytes: Uint8Array, str?: string);
+    constructor(bytes: Uint8Array);
     get $link(): string;
     toJSON(): CidLink;
 }

package/dist/cid-link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cid-link.d.ts","sourceRoot":"","sources":["../lib/cid-link.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,GAAG,EAAE,MAAM,YAAY,CAAC;AAI1D,MAAM,WAAW,OAAO;IACvB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,cAAe,YAAW,OAAO;IAM7C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEf,KAAK,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,MAAM;IAK3C,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,MAAM,IAAI,OAAO;CAGjB;AAED,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAOnD,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,KAAK,GAAG,KAAG,OAEpC,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,KAAG,GAM3C,CAAC"}
+{"version":3,"file":"cid-link.d.ts","sourceRoot":"","sources":["../lib/cid-link.ts"],"names":[],"mappings":"AAEA,OAAO,EAA2C,KAAK,GAAG,EAAE,MAAM,YAAY,CAAC;AAO/E,MAAM,WAAW,OAAO;IACvB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,cAAe,YAAW,OAAO;IAI7C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAE3B,YAAY,KAAK,EAAE,UAAU,EAE5B;IAED,IAAI,KAAK,IAAI,MAAM,CASlB;IAED,MAAM,IAAI,OAAO,CAEhB;CACD;AAED,eAAO,MAAM,SAAS,sCAOrB,CAAC;AAEF,eAAO,MAAM,SAAS,uBASrB,CAAC;AAEF,eAAO,MAAM,WAAW,wBAMvB,CAAC"}

package/dist/cid-link.js

@@ -1,18 +1,22 @@
 import { toBase32 } from '@atcute/multibase';
-import { decode, fromString } from './codec.js';
+import { CID_STRINGIFY_CACHE, decode, fromString } from './codec.js';
 const CID_LINK_SYMBOL = Symbol.for('@atcute/cid-link-wrapper');
+/** @internal */
+export const CIDLINK_STRINGIFY_CACHE = new WeakMap();
 export class CidLinkWrapper {
     /** @internal */
     [CID_LINK_SYMBOL] = true;
-    /** @internal */
-    _str;
     bytes;
-    constructor(bytes, str) {
+    constructor(bytes) {
         this.bytes = bytes;
-        this._str = str;
     }
     get $link() {
-        return (this._str ??= `b${toBase32(this.bytes)}`);
+        let str = CIDLINK_STRINGIFY_CACHE.get(this);
+        if (str === undefined) {
+            str = `b${toBase32(this.bytes)}`;
+            CIDLINK_STRINGIFY_CACHE.set(this, str);
+        }
+        return str;
     }
     toJSON() {
         return { $link: this.$link };
@@ -24,7 +28,12 @@ export const isCidLink = (value) => {
         (val !== null && typeof val === 'object' && typeof val.$link === 'string'));
 };
 export const toCidLink = (cid) => {
-    return new CidLinkWrapper(cid.bytes, cid._str);
+    const inst = new CidLinkWrapper(cid.bytes);
+    const str = CID_STRINGIFY_CACHE.get(cid);
+    if (str !== undefined) {
+        CIDLINK_STRINGIFY_CACHE.set(inst, str);
+    }
+    return inst;
 };
 export const fromCidLink = (link) => {
     if (link instanceof CidLinkWrapper) {

package/dist/cid-link.js.map

@@ -1 +1 @@
-{"version":3,"file":"cid-link.js","sourceRoot":"","sources":["../lib/cid-link.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,EAAE,MAAM,EAAE,UAAU,EAAY,MAAM,YAAY,CAAC;AAE1D,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AAM/D,MAAM,OAAO,cAAc;IAC1B,gBAAgB;IACP,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC;IAClC,gBAAgB;IAChB,IAAI,CAAqB;IAEhB,KAAK,CAAa;IAE3B,YAAY,KAAiB,EAAE,GAAY;QAC1C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,IAAI,KAAK;QACR,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,MAAM;QACL,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;CACD;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAoB,EAAE;IAC7D,MAAM,GAAG,GAAG,KAAY,CAAC;IAEzB,OAAO,CACN,GAAG,YAAY,cAAc;QAC7B,CAAC,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAC1E,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAQ,EAAW,EAAE;IAC9C,OAAO,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;AAChD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAa,EAAO,EAAE;IACjD,IAAI,IAAI,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC,CAAC"}
+{"version":3,"file":"cid-link.js","sourceRoot":"","sources":["../lib/cid-link.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,UAAU,EAAY,MAAM,YAAY,CAAC;AAE/E,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AAE/D,gBAAgB;AAChB,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,OAAO,EAA0B,CAAC;AAM7E,MAAM,OAAO,cAAc;IAC1B,gBAAgB;IACP,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC;IAEzB,KAAK,CAAa;IAE3B,YAAY,KAAiB,EAAE;QAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IAAA,CACnB;IAED,IAAI,KAAK,GAAW;QACnB,IAAI,GAAG,GAAG,uBAAuB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACvB,GAAG,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAEjC,uBAAuB,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,GAAG,CAAC;IAAA,CACX;IAED,MAAM,GAAY;QACjB,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAAA,CAC7B;CACD;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAoB,EAAE,CAAC;IAC9D,MAAM,GAAG,GAAG,KAAY,CAAC;IAEzB,OAAO,CACN,GAAG,YAAY,cAAc;QAC7B,CAAC,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAC1E,CAAC;AAAA,CACF,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAQ,EAAW,EAAE,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEzC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACvB,uBAAuB,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,IAAI,CAAC;AAAA,CACZ,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAa,EAAO,EAAE,CAAC;IAClD,IAAI,IAAI,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAAA,CAC9B,CAAC"}

package/dist/codec.d.ts

@@ -1,6 +1,10 @@
+/** CID version, always `1` for CIDv1 */
 export declare const CID_VERSION = 1;
+/** multicodec for SHA-256 hash */
 export declare const HASH_SHA256 = 18;
+/** multicodec for raw binary data */
 export declare const CODEC_RAW = 85;
+/** multicodec for DAG-CBOR encoded data */
 export declare const CODEC_DCBOR = 113;
 /**
  * Represents a Content Identifier (CID), in particular, a limited subset of
@@ -22,13 +26,73 @@ export interface Cid {
     /** Raw CID bytes */
     readonly bytes: Uint8Array;
 }
-export declare const create: (codec: 85 | 113, data: Uint8Array) => Promise<Cid>;
+/**
+ * creates a CID from a pre-computed SHA-256 digest
+ * @param codec multicodec type for the data
+ * @param digest raw SHA-256 hash bytes (must be 32 bytes)
+ * @returns CID object
+ */
+export declare const fromDigest: (codec: 85 | 113, digest: Uint8Array<ArrayBufferLike>) => Cid;
+/**
+ * creates a CID by hashing the provided data with SHA-256
+ * @param codec multicodec type for the data
+ * @param data raw data to hash
+ * @returns CID object
+ */
+export declare const create: (codec: 85 | 113, data: Uint8Array<ArrayBufferLike>) => Promise<Cid>;
+/**
+ * creates an empty CID with a zero-length digest
+ * @param codec multicodec type for the data
+ * @returns CID object with empty digest
+ */
 export declare const createEmpty: (codec: 85 | 113) => Cid;
-export declare const decodeFirst: (bytes: Uint8Array) => [decoded: Cid, remainder: Uint8Array];
-export declare const decode: (bytes: Uint8Array) => Cid;
+/**
+ * decodes a CID from bytes, returning the CID and any remaining bytes
+ * @param bytes raw CID bytes
+ * @returns tuple of decoded CID and remainder bytes
+ * @throws {RangeError} if the bytes are too short or contain invalid values
+ */
+export declare const decodeFirst: (bytes: Uint8Array<ArrayBufferLike>) => [decoded: Cid, remainder: Uint8Array<ArrayBufferLike>];
+/**
+ * decodes a CID from bytes, expecting no remainder
+ * @param bytes raw CID bytes
+ * @returns decoded CID
+ * @throws {RangeError} if the bytes are invalid or contain extra data
+ */
+export declare const decode: (bytes: Uint8Array<ArrayBufferLike>) => Cid;
+/**
+ * parses a CID from a multibase base32 string
+ * @param input base32-encoded CID string (with 'b' prefix)
+ * @returns decoded CID
+ * @throws {SyntaxError} if the string is not a valid multibase base32 string
+ * @throws {RangeError} if the string length is invalid
+ */
 export declare const fromString: (input: string) => Cid;
+/**
+ * encodes a CID to a multibase base32 string
+ * @param cid CID to encode
+ * @returns base32-encoded string with 'b' prefix
+ */
 export declare const toString: (cid: Cid) => string;
-export declare const fromBinary: (input: Uint8Array) => Cid;
-export declare const toBinary: (cid: Cid) => Uint8Array;
+/**
+ * parses a CID from binary format (with 0x00 prefix)
+ * @param input binary CID bytes with 0x00 prefix
+ * @returns decoded CID
+ * @throws {RangeError} if the byte length is invalid
+ * @throws {SyntaxError} if the prefix byte is not 0x00
+ */
+export declare const fromBinary: (input: Uint8Array<ArrayBufferLike>) => Cid;
+/**
+ * encodes a CID to binary format (with 0x00 prefix)
+ * @param cid CID to encode
+ * @returns binary CID bytes with 0x00 prefix
+ */
+export declare const toBinary: (cid: Cid) => Uint8Array<ArrayBufferLike>;
+/**
+ * checks if two CIDs are equal
+ * @param a first CID
+ * @param b second CID
+ * @returns true if the CIDs have identical bytes
+ */
 export declare const equals: (a: Cid, b: Cid) => boolean;
 //# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../lib/codec.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,WAAW,KAAO,CAAC;AAEhC,eAAO,MAAM,SAAS,KAAO,CAAC;AAC9B,eAAO,MAAM,WAAW,MAAO,CAAC;AAEhC;;;;GAIG;AACH,MAAM,WAAW,GAAG;IACnB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE;QAChB,wEAAwE;QACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,qBAAqB;QACrB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;KAC9B,CAAC;IACF,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAI3B;AAKD,eAAO,MAAM,MAAM,GAAU,OAAO,EAAI,GAAG,GAAI,EAAE,MAAM,UAAU,KAAG,OAAO,CAAC,GAAG,CA2B9E,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,OAAO,EAAI,GAAG,GAAI,KAAG,GAgBhD,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,OAAO,UAAU,KAAG,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,CA4CnF,CAAC;AAEF,eAAO,MAAM,MAAM,GAAI,OAAO,UAAU,KAAG,GAQ1C,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,GAgB1C,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,KAAK,GAAG,KAAG,MAEnC,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,OAAO,UAAU,KAAG,GAa9C,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,KAAK,GAAG,KAAG,UAMnC,CAAC;AAEF,eAAO,MAAM,MAAM,GAAI,GAAG,GAAG,EAAE,GAAG,GAAG,KAAG,OAMvC,CAAC"}
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../lib/codec.ts"],"names":[],"mappings":"AAGA,wCAAwC;AACxC,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,kCAAkC;AAClC,eAAO,MAAM,WAAW,KAAO,CAAC;AAEhC,qCAAqC;AACrC,eAAO,MAAM,SAAS,KAAO,CAAC;AAC9B,2CAA2C;AAC3C,eAAO,MAAM,WAAW,MAAO,CAAC;AAKhC;;;;GAIG;AACH,MAAM,WAAW,GAAG;IACnB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE;QAChB,wEAAwE;QACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,qBAAqB;QACrB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;KAC9B,CAAC;IACF,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC3B;AAKD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,+DAuBtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,MAAM,sEAGlB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,0BAevB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,gGA2CvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,MAAM,6CAQlB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,wBAgBtB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,sBASpB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,6CAatB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,2CAMpB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,MAAM,6BAElB,CAAC"}

package/dist/codec.js

@@ -1,13 +1,24 @@
 import { fromBase32, toBase32 } from '@atcute/multibase';
 import { allocUnsafe, toSha256, equals as isBufferEqual } from '@atcute/uint8array';
+/** CID version, always `1` for CIDv1 */
 export const CID_VERSION = 1;
+/** multicodec for SHA-256 hash */
 export const HASH_SHA256 = 0x12;
+/** multicodec for raw binary data */
 export const CODEC_RAW = 0x55;
+/** multicodec for DAG-CBOR encoded data */
 export const CODEC_DCBOR = 0x71;
+/** @internal */
+export const CID_STRINGIFY_CACHE = new WeakMap();
 // a SHA-256 CIDv1 is always going to be 36 bytes, that's 4 bytes for the
 // header, and 32 bytes for the digest itself.
-export const create = async (codec, data) => {
-    const digest = await toSha256(data);
+/**
+ * creates a CID from a pre-computed SHA-256 digest
+ * @param codec multicodec type for the data
+ * @param digest raw SHA-256 hash bytes (must be 32 bytes)
+ * @returns CID object
+ */
+export const fromDigest = (codec, digest) => {
     if (digest.length !== 32) {
         throw new RangeError(`invalid digest length`);
     }
@@ -17,7 +28,7 @@ export const create = async (codec, data) => {
     bytes[2] = HASH_SHA256;
     bytes[3] = 32;
     bytes.set(digest, 4);
-    const cid = {
+    return {
         version: CID_VERSION,
         codec: codec,
         digest: {
@@ -25,10 +36,23 @@ export const create = async (codec, data) => {
             contents: bytes.subarray(4, 36),
         },
         bytes: bytes,
-        _str: undefined,
     };
-    return cid;
 };
+/**
+ * creates a CID by hashing the provided data with SHA-256
+ * @param codec multicodec type for the data
+ * @param data raw data to hash
+ * @returns CID object
+ */
+export const create = async (codec, data) => {
+    const digest = await toSha256(data);
+    return fromDigest(codec, digest);
+};
+/**
+ * creates an empty CID with a zero-length digest
+ * @param codec multicodec type for the data
+ * @returns CID object with empty digest
+ */
 export const createEmpty = (codec) => {
     const bytes = Uint8Array.from([CID_VERSION, codec, HASH_SHA256, 0]);
     const digest = bytes.subarray(4);
@@ -40,10 +64,15 @@ export const createEmpty = (codec) => {
             contents: digest,
         },
         bytes: bytes,
-        _str: undefined,
     };
     return cid;
 };
+/**
+ * decodes a CID from bytes, returning the CID and any remaining bytes
+ * @param bytes raw CID bytes
+ * @returns tuple of decoded CID and remainder bytes
+ * @throws {RangeError} if the bytes are too short or contain invalid values
+ */
 export const decodeFirst = (bytes) => {
     const length = bytes.length;
     if (length < 4) {
@@ -76,10 +105,15 @@ export const decodeFirst = (bytes) => {
             contents: bytes.subarray(4, 4 + digestSize),
         },
         bytes: bytes.subarray(0, 4 + digestSize),
-        _str: undefined,
     };
     return [cid, bytes.subarray(4 + digestSize)];
 };
+/**
+ * decodes a CID from bytes, expecting no remainder
+ * @param bytes raw CID bytes
+ * @returns decoded CID
+ * @throws {RangeError} if the bytes are invalid or contain extra data
+ */
 export const decode = (bytes) => {
     const [cid, remainder] = decodeFirst(bytes);
     if (remainder.length !== 0) {
@@ -87,6 +121,13 @@ export const decode = (bytes) => {
     }
     return cid;
 };
+/**
+ * parses a CID from a multibase base32 string
+ * @param input base32-encoded CID string (with 'b' prefix)
+ * @returns decoded CID
+ * @throws {SyntaxError} if the string is not a valid multibase base32 string
+ * @throws {RangeError} if the string length is invalid
+ */
 export const fromString = (input) => {
     if (input.length < 2 || input[0] !== 'b') {
         throw new SyntaxError(`not a multibase base32 string`);
@@ -98,12 +139,29 @@ export const fromString = (input) => {
     }
     const bytes = fromBase32(input.slice(1));
     const cid = decode(bytes);
-    cid._str = input;
+    CID_STRINGIFY_CACHE.set(cid, input);
     return cid;
 };
+/**
+ * encodes a CID to a multibase base32 string
+ * @param cid CID to encode
+ * @returns base32-encoded string with 'b' prefix
+ */
 export const toString = (cid) => {
-    return (cid._str ??= `b${toBase32(cid.bytes)}`);
+    let str = CID_STRINGIFY_CACHE.get(cid);
+    if (str === undefined) {
+        str = `b${toBase32(cid.bytes)}`;
+        CID_STRINGIFY_CACHE.set(cid, str);
+    }
+    return str;
 };
+/**
+ * parses a CID from binary format (with 0x00 prefix)
+ * @param input binary CID bytes with 0x00 prefix
+ * @returns decoded CID
+ * @throws {RangeError} if the byte length is invalid
+ * @throws {SyntaxError} if the prefix byte is not 0x00
+ */
 export const fromBinary = (input) => {
     // 4 bytes + 1 byte for the 0x00 prefix
     // 36 bytes + 1 byte for the 0x00 prefix
@@ -116,16 +174,24 @@ export const fromBinary = (input) => {
     const bytes = input.subarray(1);
     return decode(bytes);
 };
+/**
+ * encodes a CID to binary format (with 0x00 prefix)
+ * @param cid CID to encode
+ * @returns binary CID bytes with 0x00 prefix
+ */
 export const toBinary = (cid) => {
     const bytes = allocUnsafe(1 + cid.bytes.length);
     bytes[0] = 0;
     bytes.set(cid.bytes, 1);
     return bytes;
 };
+/**
+ * checks if two CIDs are equal
+ * @param a first CID
+ * @param b second CID
+ * @returns true if the CIDs have identical bytes
+ */
 export const equals = (a, b) => {
-    if (a._str !== undefined && b._str !== undefined) {
-        return a._str === b._str;
-    }
     return isBufferEqual(a.bytes, b.bytes);
 };
 //# sourceMappingURL=codec.js.map

package/dist/codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"codec.js","sourceRoot":"","sources":["../lib/codec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../lib/codec.ts"],"names":[],"mappings":"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"}

package/lib/cid-link.ts

@@ -1,9 +1,12 @@
 import { toBase32 } from '@atcute/multibase';
 
-import { decode, fromString, type Cid } from './codec.js';
+import { CID_STRINGIFY_CACHE, decode, fromString, type Cid } from './codec.js';
 
 const CID_LINK_SYMBOL = Symbol.for('@atcute/cid-link-wrapper');
 
+/** @internal */
+export const CIDLINK_STRINGIFY_CACHE = new WeakMap<CidLinkWrapper, string>();
+
 export interface CidLink {
 	$link: string;
 }
@@ -11,18 +14,22 @@ export interface CidLink {
 export class CidLinkWrapper implements CidLink {
 	/** @internal */
 	readonly [CID_LINK_SYMBOL] = true;
-	/** @internal */
-	_str: string | undefined;
 
 	readonly bytes: Uint8Array;
 
-	constructor(bytes: Uint8Array, str?: string) {
+	constructor(bytes: Uint8Array) {
 		this.bytes = bytes;
-		this._str = str;
 	}
 
 	get $link(): string {
-		return (this._str ??= `b${toBase32(this.bytes)}`);
+		let str = CIDLINK_STRINGIFY_CACHE.get(this);
+		if (str === undefined) {
+			str = `b${toBase32(this.bytes)}`;
+
+			CIDLINK_STRINGIFY_CACHE.set(this, str);
+		}
+
+		return str;
 	}
 
 	toJSON(): CidLink {
@@ -40,7 +47,14 @@ export const isCidLink = (value: unknown): value is CidLink => {
 };
 
 export const toCidLink = (cid: Cid): CidLink => {
-	return new CidLinkWrapper(cid.bytes, cid._str);
+	const inst = new CidLinkWrapper(cid.bytes);
+	const str = CID_STRINGIFY_CACHE.get(cid);
+
+	if (str !== undefined) {
+		CIDLINK_STRINGIFY_CACHE.set(inst, str);
+	}
+
+	return inst;
 };
 
 export const fromCidLink = (link: CidLink): Cid => {

package/lib/codec.ts

@@ -1,12 +1,19 @@
 import { fromBase32, toBase32 } from '@atcute/multibase';
 import { allocUnsafe, toSha256, equals as isBufferEqual } from '@atcute/uint8array';
 
+/** CID version, always `1` for CIDv1 */
 export const CID_VERSION = 1;
+/** multicodec for SHA-256 hash */
 export const HASH_SHA256 = 0x12;
 
+/** multicodec for raw binary data */
 export const CODEC_RAW = 0x55;
+/** multicodec for DAG-CBOR encoded data */
 export const CODEC_DCBOR = 0x71;
 
+/** @internal */
+export const CID_STRINGIFY_CACHE = new WeakMap<Cid, string>();
+
 /**
  * Represents a Content Identifier (CID), in particular, a limited subset of
  * CIDv1 as described by DASL specifications.
@@ -26,16 +33,18 @@ export interface Cid {
 	};
 	/** Raw CID bytes */
 	readonly bytes: Uint8Array;
-
-	/** @internal */
-	_str: string | undefined;
 }
 
 // a SHA-256 CIDv1 is always going to be 36 bytes, that's 4 bytes for the
 // header, and 32 bytes for the digest itself.
 
-export const create = async (codec: 0x55 | 0x71, data: Uint8Array): Promise<Cid> => {
-	const digest = await toSha256(data);
+/**
+ * creates a CID from a pre-computed SHA-256 digest
+ * @param codec multicodec type for the data
+ * @param digest raw SHA-256 hash bytes (must be 32 bytes)
+ * @returns CID object
+ */
+export const fromDigest = (codec: 0x55 | 0x71, digest: Uint8Array): Cid => {
 	if (digest.length !== 32) {
 		throw new RangeError(`invalid digest length`);
 	}
@@ -49,7 +58,7 @@ export const create = async (codec: 0x55 | 0x71, data: Uint8Array): Promise<Cid>
 
 	bytes.set(digest, 4);
 
-	const cid: Cid = {
+	return {
 		version: CID_VERSION,
 		codec: codec,
 		digest: {
@@ -57,12 +66,25 @@ export const create = async (codec: 0x55 | 0x71, data: Uint8Array): Promise<Cid>
 			contents: bytes.subarray(4, 36),
 		},
 		bytes: bytes,
-		_str: undefined,
 	};
+};
 
-	return cid;
+/**
+ * creates a CID by hashing the provided data with SHA-256
+ * @param codec multicodec type for the data
+ * @param data raw data to hash
+ * @returns CID object
+ */
+export const create = async (codec: 0x55 | 0x71, data: Uint8Array): Promise<Cid> => {
+	const digest = await toSha256(data);
+	return fromDigest(codec, digest);
 };
 
+/**
+ * creates an empty CID with a zero-length digest
+ * @param codec multicodec type for the data
+ * @returns CID object with empty digest
+ */
 export const createEmpty = (codec: 0x55 | 0x71): Cid => {
 	const bytes = Uint8Array.from([CID_VERSION, codec, HASH_SHA256, 0]);
 	const digest = bytes.subarray(4);
@@ -75,12 +97,17 @@ export const createEmpty = (codec: 0x55 | 0x71): Cid => {
 			contents: digest,
 		},
 		bytes: bytes,
-		_str: undefined,
 	};
 
 	return cid;
 };
 
+/**
+ * decodes a CID from bytes, returning the CID and any remaining bytes
+ * @param bytes raw CID bytes
+ * @returns tuple of decoded CID and remainder bytes
+ * @throws {RangeError} if the bytes are too short or contain invalid values
+ */
 export const decodeFirst = (bytes: Uint8Array): [decoded: Cid, remainder: Uint8Array] => {
 	const length = bytes.length;
 
@@ -121,12 +148,17 @@ export const decodeFirst = (bytes: Uint8Array): [decoded: Cid, remainder: Uint8A
 			contents: bytes.subarray(4, 4 + digestSize),
 		},
 		bytes: bytes.subarray(0, 4 + digestSize),
-		_str: undefined,
 	};
 
 	return [cid, bytes.subarray(4 + digestSize)];
 };
 
+/**
+ * decodes a CID from bytes, expecting no remainder
+ * @param bytes raw CID bytes
+ * @returns decoded CID
+ * @throws {RangeError} if the bytes are invalid or contain extra data
+ */
 export const decode = (bytes: Uint8Array): Cid => {
 	const [cid, remainder] = decodeFirst(bytes);
 
@@ -137,6 +169,13 @@ export const decode = (bytes: Uint8Array): Cid => {
 	return cid;
 };
 
+/**
+ * parses a CID from a multibase base32 string
+ * @param input base32-encoded CID string (with 'b' prefix)
+ * @returns decoded CID
+ * @throws {SyntaxError} if the string is not a valid multibase base32 string
+ * @throws {RangeError} if the string length is invalid
+ */
 export const fromString = (input: string): Cid => {
 	if (input.length < 2 || input[0] !== 'b') {
 		throw new SyntaxError(`not a multibase base32 string`);
@@ -151,14 +190,33 @@ export const fromString = (input: string): Cid => {
 	const bytes = fromBase32(input.slice(1));
 	const cid = decode(bytes);
 
-	cid._str = input;
+	CID_STRINGIFY_CACHE.set(cid, input);
 	return cid;
 };
 
+/**
+ * encodes a CID to a multibase base32 string
+ * @param cid CID to encode
+ * @returns base32-encoded string with 'b' prefix
+ */
 export const toString = (cid: Cid): string => {
-	return (cid._str ??= `b${toBase32(cid.bytes)}`);
+	let str = CID_STRINGIFY_CACHE.get(cid);
+	if (str === undefined) {
+		str = `b${toBase32(cid.bytes)}`;
+
+		CID_STRINGIFY_CACHE.set(cid, str);
+	}
+
+	return str;
 };
 
+/**
+ * parses a CID from binary format (with 0x00 prefix)
+ * @param input binary CID bytes with 0x00 prefix
+ * @returns decoded CID
+ * @throws {RangeError} if the byte length is invalid
+ * @throws {SyntaxError} if the prefix byte is not 0x00
+ */
 export const fromBinary = (input: Uint8Array): Cid => {
 	// 4 bytes + 1 byte for the 0x00 prefix
 	// 36 bytes + 1 byte for the 0x00 prefix
@@ -174,6 +232,11 @@ export const fromBinary = (input: Uint8Array): Cid => {
 	return decode(bytes);
 };
 
+/**
+ * encodes a CID to binary format (with 0x00 prefix)
+ * @param cid CID to encode
+ * @returns binary CID bytes with 0x00 prefix
+ */
 export const toBinary = (cid: Cid): Uint8Array => {
 	const bytes = allocUnsafe(1 + cid.bytes.length);
 	bytes[0] = 0;
@@ -182,10 +245,12 @@ export const toBinary = (cid: Cid): Uint8Array => {
 	return bytes;
 };
 
+/**
+ * checks if two CIDs are equal
+ * @param a first CID
+ * @param b second CID
+ * @returns true if the CIDs have identical bytes
+ */
 export const equals = (a: Cid, b: Cid): boolean => {
-	if (a._str !== undefined && b._str !== undefined) {
-		return a._str === b._str;
-	}
-
 	return isBufferEqual(a.bytes, b.bytes);
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@atcute/cid",
-  "version": "2.2.5",
+  "version": "2.3.0",
   "description": "lightweight DASL CID codec library for AT Protocol",
   "keywords": [
     "atproto",
@@ -13,6 +13,9 @@
     "url": "https://github.com/mary-ext/atcute",
     "directory": "packages/utilities/cid"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "dist/",
     "lib/",
@@ -25,15 +28,16 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@types/bun": "^1.2.21"
+    "@vitest/coverage-v8": "^4.0.16",
+    "vitest": "^4.0.16"
   },
   "dependencies": {
     "@atcute/multibase": "^1.1.6",
-    "@atcute/uint8array": "^1.0.5"
+    "@atcute/uint8array": "^1.0.6"
   },
   "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "test": "bun test --coverage",
+    "build": "tsgo --project tsconfig.build.json",
+    "test": "vitest",
     "prepublish": "rm -rf dist; pnpm run build"
   }
 }