diff --git a/src/index.ts b/src/index.ts index 4af0900..49bbca7 100644 --- a/src/index.ts +++ b/src/index.ts @@ -97,6 +97,19 @@ export class IntegrityMetadata implements IntegrityMetadataLike { /** * Creates an instance of `IntegrityMetadata` from a given object or string. * @param integrity The integrity metadata input, which can be a string or object. + * @example + * ``` + * new IntegrityMetadata("sha256-MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM=") + * ``` + * + * or + * + * ``` + * new IntegrityMetadata({ + * alg: "sha256", + * val: "MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM=", + * }) + * ``` */ constructor(integrity: IntegrityMetadataLike | string | null | undefined) { const integrityString = @@ -121,6 +134,19 @@ export class IntegrityMetadata implements IntegrityMetadataLike { * Compares the current integrity metadata with another object or string. * @param integrity The integrity metadata to compare with. * @returns `true` if the integrity metadata matches, `false` otherwise. + * @example + * ``` + * integrityMetadata.match({ + * alg: "sha256", + * val: "MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM=", + * }) + * ``` + * + * or + * + * ``` + * integrityMetadata.match("sha256-MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM=") + * ``` */ match(integrity: IntegrityMetadataLike | string | null | undefined): boolean { const { alg, val } = new IntegrityMetadata(integrity); @@ -150,6 +176,13 @@ export class IntegrityMetadata implements IntegrityMetadataLike { * Static method to stringify an integrity metadata object. * @param integrity The integrity metadata object to stringify. * @returns The stringified integrity metadata. + * @example + * ``` + * IntegrityMetadata.stringify({ + * alg: "sha256", + * val: "MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM=", + * }) // "sha256-MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM=" + * ``` */ static stringify({ alg, val, opt = [] }: IntegrityMetadataLike): string { if (!alg) return ""; @@ -165,6 +198,12 @@ export class IntegrityMetadata implements IntegrityMetadataLike { * @param data The data to hash (in `ArrayBuffer` format). * @param opt Optional additional attributes. * @returns A promise that resolves to an `IntegrityMetadata` object. + * @example + * ``` + * const res = new Response("Hello, world!"); + * const data = await res.arrayBuffer(); + * const integrityMetadata = await createIntegrityMetadata("sha256", data); + * ``` */ export async function createIntegrityMetadata( hashAlgorithm: HashAlgorithm, @@ -211,6 +250,24 @@ export class IntegrityMetadataSet { * metadata. * @param integrity The integrity metadata or an array of integrity metadata. * @param options Optional configuration options for hash algorithm prioritization. + * @example + * ``` + * new IntegrityMetadataSet(` + * sha256-MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM= + * sha384-VbxVaw0v4Pzlgrpf4Huq//A1ZTY4x6wNVJTCpkwL6hzFczHHwSpFzbyn9MNKCJ7r + * sha512-wVJ82JPBJHc9gRkRlwyP5uhX1t9dySJr2KFgYUwM2WOk3eorlLt9NgIe+dhl1c6ilKgt1JoLsmn1H256V/eUIQ== + * `) + * ``` + * + * or + * + * ``` + * new IntegrityMetadataSet([ + * "sha256-MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM=", + * "sha384-VbxVaw0v4Pzlgrpf4Huq//A1ZTY4x6wNVJTCpkwL6hzFczHHwSpFzbyn9MNKCJ7r", + * "sha512-wVJ82JPBJHc9gRkRlwyP5uhX1t9dySJr2KFgYUwM2WOk3eorlLt9NgIe+dhl1c6ilKgt1JoLsmn1H256V/eUIQ==", + * ]) + * ``` */ constructor( integrity: @@ -263,6 +320,10 @@ export class IntegrityMetadataSet { /** * Enables iteration over the set of integrity metadata. * @returns A generator that yields each IntegrityMetadata object. + * @example + * ``` + * [...integrityMetadataSet] + * ``` */ *[Symbol.iterator](): Generator { for (const integrityMetadata of this.#set) { @@ -292,6 +353,19 @@ export class IntegrityMetadataSet { * Checks if a given integrity metadata object or string matches any in the set. * @param integrity The integrity metadata to match. * @returns `true` if the integrity metadata matches, `false` otherwise. + * @example + * ``` + * integrityMetadataSet.match({ + * alg: "sha256", + * val: "MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM=", + * }) + * ``` + * + * or + * + * ``` + * integrityMetadataSet.match("sha256-MV9b23bQeMQ7isAGTkoBZGErH853yGk0W/yUx1iU7dM=") + * ``` */ match(integrity: IntegrityMetadataLike | string | null | undefined): boolean { return this.#set.some((integrityMetadata) => @@ -332,6 +406,12 @@ export class IntegrityMetadataSet { * @param data The data to hash (in `ArrayBuffer` format). * @param options Optional configuration options for the metadata set. * @returns A promise that resolves to an `IntegrityMetadataSet` object. + * @example + * ``` + * const res = new Response("Hello, world!"); + * const data = await res.arrayBuffer(); + * const set = await createIntegrityMetadataSet(["sha256", "sha384", "sha512"], data); + * ``` */ export async function createIntegrityMetadataSet( hashAlgorithms: ReadonlyArray | HashAlgorithm,