diff --git a/src/crypto/sha256.ts b/src/crypto/sha256.ts index d56f306..de9a20f 100644 --- a/src/crypto/sha256.ts +++ b/src/crypto/sha256.ts @@ -32,6 +32,9 @@ const W: number[] = []; export class SHA256 extends Hasher { _hash = new WordArray([...H]); + /** + * Resets the internal state of the hash object to initial values. + */ reset() { super.reset(); this._hash = new WordArray([...H]); @@ -107,6 +110,12 @@ export class SHA256 extends Hasher { H[7] = (H[7] + h) | 0; } + /** + * Finishes the hash calculation and returns the hash as a WordArray. + * + * @param {string} messageUpdate - Additional message content to include in the hash. + * @returns {WordArray} The finalised hash as a WordArray. + */ finalize(messageUpdate: string): WordArray { super.finalize(messageUpdate); @@ -129,10 +138,22 @@ export class SHA256 extends Hasher { } } +/** + * Calculates the SHA-256 hash of the message provided. + * + * @param {string} message - The message to hash. + * @returns {string} The message hash as a hexadecimal string. + */ export function sha256(message: string) { return new SHA256().finalize(message).toString(); } +/** + * Calculates the SHA-256 hash of the given message and encodes it in Base64. + * + * @param {string} message - The message to hash. + * @returns {string} The base64 encoded hash of the message. + */ export function sha256base64(message: string) { return new SHA256().finalize(message).toString(Base64); } diff --git a/src/diff.ts b/src/diff.ts index ed53e66..d0dc7a8 100644 --- a/src/diff.ts +++ b/src/diff.ts @@ -1,5 +1,13 @@ import { objectHash, HashOptions } from "./object-hash"; +/** + * Calculates the difference between two objects and returns a list of differences. + * + * @param {any} obj1 - The first object to compare. + * @param {any} obj2 - The second object to compare. + * @param {HashOptions} [opts={}] - Configuration options for hashing the objects. See {@link HashOptions}. + * @returns {DiffEntry[]} An array with the differences between the two objects. + */ export function diff( obj1: any, obj2: any, diff --git a/src/hash.ts b/src/hash.ts index 2890b3f..b6a3186 100644 --- a/src/hash.ts +++ b/src/hash.ts @@ -4,7 +4,7 @@ import { sha256base64 } from "./crypto/sha256"; /** * Hash any JS value into a string * @param {object} object value to hash - * @param {HashOptions} options hashing options + * @param {HashOptions} options hashing options. See {@link HashOptions}. * @return {string} hash value * @api public */ diff --git a/src/object-hash.ts b/src/object-hash.ts index 078b838..b22f3db 100644 --- a/src/object-hash.ts +++ b/src/object-hash.ts @@ -2,43 +2,73 @@ export interface HashOptions { /** - * + * Function to determine if a key should be excluded from hashing. + * @optional + * @param key - The key to check for exclusion. + * @returns {boolean} - Returns true to exclude the key from hashing. */ excludeKeys?: ((key: string) => boolean) | undefined; + /** - * hash object keys, values ignored + * Specifies whether to exclude values from hashing, so that only the object keys are hashed. + * @optional */ excludeValues?: boolean | undefined; + /** - * ignore unknown object types + * Specifies whether to ignore objects of unknown type (not directly serialisable) when hashing. + * @optional + * @default false */ ignoreUnknown?: boolean | undefined; + /** - * optional function that replaces values before hashing + * A function that replaces values before they are hashed, which can be used to customise the hashing process. + * @optional + * @param value - The current value to be hashed. + * @returns {any} - The value to use for hashing instead. */ replacer?: ((value: any) => any) | undefined; + /** - * consider 'name' property of functions for hashing + * Specifies whether the 'name' property of functions should be taken into account when hashing. + * @optional + * @default false */ respectFunctionNames?: boolean | undefined; + /** - * consider function properties when hashing + * Specifies whether properties of functions should be taken into account when hashing. + * @optional + * @default false */ respectFunctionProperties?: boolean | undefined; + /** - * Respect special properties (prototype, letructor) when hashing to distinguish between types + * Specifies whether to include type-specific properties such as prototype or constructor in the hash to distinguish between types. + * @optional + * @default false */ respectType?: boolean | undefined; + /** - * Sort all arrays before hashing + * Specifies whether arrays should be sorted before hashing to ensure consistent order. + * @optional + * @default false */ unorderedArrays?: boolean | undefined; + /** - * Sort `Set` and `Map` instances before hashing + * Specifies whether Set and Map instances should be sorted by key before hashing to ensure consistent order. + * @optional + * @default true */ unorderedObjects?: boolean | undefined; + /** - * Sort `Set` and `Map` instances before hashing + * Specifies whether the elements of `Set' and keys of `Map' should be sorted before hashing to ensure consistent order. + * @optional + * @default false */ unorderedSets?: boolean | undefined; } @@ -60,7 +90,7 @@ const defaults: HashOptions = Object.freeze({ /** * Serialize any JS value into a stable, hashable string * @param {object} object value to hash - * @param {HashOptions} options hashing options + * @param {HashOptions} options hashing options. See {@link HashOptions}. * @return {string} serialized value * @api public */ diff --git a/src/utils.ts b/src/utils.ts index d6c2e58..00be2fc 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -3,7 +3,7 @@ import { objectHash, HashOptions } from "./object-hash"; * Compare two objects using reference equality and stable deep hashing. * @param {any} object1 First object * @param {any} object2 Second object - * @param {HashOptions} hash options + * @param {HashOptions} hashOptions. Configuration options for hashing the objects. See {@link HashOptions}. * @return {boolean} true if equal and false if not * @api public */