gg-json-hash/dist/gg-json-hash.d.ts

Add hashes to nested json objects.

/**
 * Number config for hashing.
 *
 * We need to make sure that the hashing of numbers is consistent
 * across different platforms. Especially rounding errors can lead to
 * different hashes although the numbers are considered equal. This
 * class provides a configuration for hashing numbers.
 */
export declare class NumberHashingConfig {
    precision: number;
    maxNum: number;
    minNum: number;
    throwOnRangeError: boolean;
    /**
     * Default configuration.
     *
     * @type {NumberHashingConfig}
     */
    static get default(): NumberHashingConfig;
}
/**
 * When writing hashes into a given JSON object, we have various options.
 */
export declare class ApplyJsonHashConfig {
    inPlace: boolean;
    updateExistingHashes: boolean;
    throwIfOnWrongHashes: boolean;
    /**
     * Constructor
     * @param {boolean} [inPlace=false] - Whether to modify the JSON object in place.
     * @param {boolean} [updateExistingHashes=true] - Whether to update existing hashes.
     * @param {boolean} [throwOnHashMismatch=true] - Whether to throw an error if existing hashes are wrong.
     */
    constructor(inPlace?: boolean, updateExistingHashes?: boolean, throwOnHashMismatch?: boolean);
    /**
     * Default configuration.
     *
     * @type {ApplyJsonHashConfig}
     */
    static get default(): ApplyJsonHashConfig;
}
/**
 * Options for the JSON hash.
 */
export declare class HashConfig {
    hashLength: number;
    hashAlgorithm: string;
    numberConfig: NumberHashingConfig;
    /**
     * Constructor
     * @param {number} [hashLength=22] - Length of the hash.
     * @param {string} [hashAlgorithm='SHA-256'] - Algorithm to use for hashing.
     * @param {NumberHashingConfig} [numberConfig=HashNumberHashingConfig.default] - Configuration for hashing numbers.
     */
    constructor(hashLength?: number, hashAlgorithm?: string, numberConfig?: NumberHashingConfig);
    /**
     * Default configuration.
     *
     * @type {HashConfig}
     */
    static get default(): HashConfig;
}
/**
 * Adds hashes to JSON object.
 */
export declare class JsonHash {
    config: HashConfig;
    /**
     * Constructor
     * @param {HashConfig} [config=HashConfig.default] - Configuration for the hash.
     */
    constructor(config?: HashConfig);
    /**
     * Default instance.
     *
     * @type {JsonHash}
     */
    static get default(): JsonHash;
    /**
     * Writes hashes into the JSON object.
     * @param {Record<string, any>} json - The JSON object to hash.
     * @param {ApplyJsonHashConfig} [applyConfig=HashApplyToConfig.default] - Options for the operation.
     * @returns {Record<string, any>} The JSON object with hashes added.
     */
    apply<T extends Record<string, any>>(json: T, applyConfig?: ApplyJsonHashConfig): T;
    applyInPlace<T extends Record<string, any>>(json: T, updateExistingHashes?: boolean, throwIfWrongHashes?: boolean): T;
    /**
     * Writes hashes into a JSON string.
     * @param {string} jsonString - The JSON string to hash.
     * @returns {string} The JSON string with hashes added.
     */
    applyToJsonString(jsonString: string): string;
    /**
     * Calculates a SHA-256 hash of a string with base64 url.
     * @param {string} value - The string to hash.
     * @returns {string} The calculated hash.
     */
    calcHash(value: string | Array<any> | Record<string, any>): string;
    /**
     * Throws if hashes are not correct.
     * @param {Record<string, any>} json - The JSON object to validate.
     */
    validate<T extends Record<string, any>>(json: T): T;
    /**
     * Copies the JSON object.
     */
    static copyJson: typeof JsonHash._copyJson;
    /**
     * Copies the list deeply
     */
    static copyList: typeof JsonHash._copyList;
    /**
     * Returns the value when it is a basic type. Otherwise throws an error.
     */
    static isBasicType: typeof JsonHash._isBasicType;
    /**
     * Converts a map to a JSON string.
     * @param {Record<string, any>} map - The map to convert.
     * @returns {string} The JSON string representation of the map.
     */
    static jsonString: typeof JsonHash._jsonString;
    /**
     * Checks an basic type. Throws an error if the type is not supported.
     */
    checkBasicType: (value: any) => any;
    /**
     * Validates the hashes of the JSON object.
     * @param {Record<string, any>} jsonIs - The JSON object to check.
     * @param {Record<string, any>} jsonShould - The JSON object with correct hashes.
     * @param {string} path - The current path in the JSON object.
     */
    private _validate;
    private _calcStringHash;
    private _calcArrayHash;
    /**
     * Recursively adds hashes to a nested object.
     * @param {Record<string, any>} obj - The object to add hashes to.
     * @param {ApplyJsonHashConfig} applyConfig - Whether to process recursively.
     */
    private _addHashesToObject;
    private _checkBasicType;
    /**
     * Builds a representation of a list for hashing.
     * @param {Array<any>} list - The list to flatten.
     * @returns {Array<any>} The flattened list.
     */
    private _flattenList;
    /**
     * Recursively processes a list, adding hashes to nested objects and lists.
     * @param {Array<any>} list - The list to process.
     * @param {ApplyJsonHashConfig} applyConfig - Whether to process recursively.
     */
    private _processList;
    /**
     * Copies the JSON object.
     * @param {Record<string, any>} json - The JSON object to copy.
     * @returns {Record<string, any>} The copied JSON object.
     */
    private static _copyJson;
    /**
     * Copies the list.
     * @param {Array<any>} list - The list to copy.
     * @returns {Array<any>} The copied list.
     */
    private static _copyList;
    /**
     * Checks if a value is a basic type.
     * @param {any} value - The value to check.
     * @returns {boolean} True if the value is a basic type, false otherwise.
     */
    private static _isBasicType;
    /**
     * Turns a number into a string with a given precision.
     * @param {number} value - The number to check.
     */
    private _checkNumber;
    /**
     * Checks if a number exceeds the defined range.
     * @param {number} value - The number to check.
     * @returns {boolean} True if the number exceeds the given range, false otherwise.
     */
    private _exceedsUpperRange;
    /**
     * Checks if a number exceeds the defined range.
     * @param {number} value - The number to check.
     * @returns {boolean} True if the number exceeds the given range, false otherwise.
     */
    private _exceedsLowerRange;
    /**
     * Checks if a number exceeds the precision.
     * @param {number} value - The number to check.
     * @returns {boolean} True if the number exceeds the precision, false otherwise.
     */
    private _exceedsPrecision;
    /**
     * Converts a map to a JSON string.
     * @param {Record<string, any>} map - The map to convert.
     * @returns {string} The JSON string representation of the map.
     */
    private static _jsonString;
}
/**
 * A shortcut to a default instance
 */
export declare const jh: JsonHash;