@httpx/stable-hash/dist/index.d.cts

Create keys or hashes from javascript values, useful for memoization or cache key generation.

type AsyncHashAlgorithms = 'SHA-256' | 'SHA-512';
type HashStrOptions = {
    /**
     * Hashing algorithm to use
     */
    algorithm: AsyncHashAlgorithms;
    /**
     * Encode the hash in hexadecimal
     */
    encoding: 'hexa';
};

type SupportedDataTypes = Record<string, unknown> | unknown[] | Date | string | number | boolean | bigint | null | undefined;
type SupportedDataTypesRW = SupportedDataTypes | Readonly<SupportedDataTypes>;
type CreateStableKeyOptions = {
    sortArrayValues?: boolean;
};
type CreateStableHashOptions = CreateStableKeyOptions & {
    /**
     * Hashing algorithm to use
     * @default 'SHA-256'
     */
    algorithm?: HashStrOptions['algorithm'];
    /**
     * Encode the hash in hexadecimal or base64
     * @default 'base64'
     */
    encoding?: HashStrOptions['encoding'];
};

type Result$1 = {
    success: true;
    hash: string;
} | {
    success: false;
    error: Error;
};
/**
 * Create a stable sha-256/hexadecimal hash from a value. Useful for caching
 * or memoization.
 *
 * Object keys are sorted to maintain equality between objects with
 * the same keys but in different order.
 *
 * @example
 * ```typescript
 * import { createStableHash } from '@httpx/stable-hash';
 *
 * const value = {
 *   key8: 'a string',
 *   key1: 1,
 *   key3: true,
 *   key2: [3, 2, 1],
 *   key7: {
 *     key2: true,
 *     key1: new Date('2025-02-11T08:58:32.075Z'),
 *   },
 * };
 *
 * const result = await createStableHash(value, {
 *   // By default SHA-256 is used (SHA-512 available)
 *   algorithm: 'SHA-256',
 *   // By default the hash is encoded in hexadecimal
 *   encoding: 'hexa',
 * });
 * if (!result.success) {
 *   throw result.error;
 * }
 * const hash = result.hash;
 * // -> 'fb17a6300efcf62ae80708e2a672aee581b7f0dd7c6a9a7a748218846c679394'
 * ```
 */
declare const createStableHash: <T extends SupportedDataTypesRW>(value: T, options?: CreateStableHashOptions) => Promise<Result$1>;

/**
 * Create a stable hash (sha-256) from a given value useful for caching or memoization.
 *
 * @example
 * ```typescript
 * import { createStableHashOrThrow } from '@httpx/stable-hash';
 *
 * const params = {
 *   key8: 'a string',
 *   key1: 1,
 *   key3: true,
 *   key2: [3, 2, 1],
 *   key7: {
 *     key2: true,
 *     key1: new Date('2025-02-11T08:58:32.075Z'),
 *   },
 * };
 *
 * try {
 *   const hash = await createStableHashOrThrow(params, {
 *     // By default SHA-256 is used (SHA-512 available)
 *     algorithm: 'SHA-256',
 *     // By default the hash is encoded in hexadecimal
 *     encoding: 'hexa',
 *   });
 *   // -> 'fb17a6300efcf62ae80708e2a672aee581b7f0dd7c6a9a7a748218846c679394'
 * } catch (e) {
 *   // TypeError in case of an unserializable data type
 * }
 * ```
 */
declare const createStableHashOrThrow: <T extends SupportedDataTypesRW>(value: T, options?: CreateStableHashOptions) => Promise<string>;

type Result = {
    success: true;
    key: string;
} | {
    success: false;
    error: Error;
};
/**
 * Create a stable key from a given value useful for caching or memoization.
 *
 * Object keys are sorted to maintain equality between objects with
 * the same keys but in different order.
 *
 * This function is
 * @example
 * ```typescript
 * import { createStableKey } from '@httpx/stable-hash';
 *
 * const params = {
 *   key8: 'a string',
 *   key1: 1,
 *   key3: true,
 *   key2: [3, 2, 1],
 *   key7: {
 *     key2: true,
 *     key1: new Date('2025-02-11T08:58:32.075Z'),
 *   },
 * };
 *
 * const result = createStableKey(params);
 * if (!result.success) {
 *   throw result.error;
 * }
 * const key = result.key;
 *
 * // Will return a string containing
 * // "{"key1":1,"key2":[1,2,3],"key3":true,"key7":{"key1":"2025-02-11T08:58:32.075Z","key2":true},"key8":"a string"}"
 * ```
 */
declare const createStableKey: <T extends SupportedDataTypesRW>(value: T, options?: CreateStableKeyOptions) => Result;

/**
 * Create a stable key from a given value useful for caching or memoization.
 *
 * Object keys are sorted to maintain equality between objects with
 * the same keys but in different order.
 *
 * This function is
 * @example
 * ```typescript
 * import { createStableKeyOrThrow } from '@httpx/stable-hash';
 *
 * const params = {
 *   key8: 'a string',
 *   key1: 1,
 *   key3: true,
 *   key2: [3, 2, 1],
 *   key7: {
 *     key2: true,
 *     key1: new Date('2025-02-11T08:58:32.075Z'),
 *   },
 * };
 *
 * try {
 *  const key = createStableKeyOrThrow(params);
 *  // Will return a string containing
 *  // "{"key1":1,"key2":[1,2,3],"key3":true,"key7":{"key1":"2025-02-11T08:58:32.075Z","key2":true},"key8":"a string"}"
 * } catch (e) {
 *  // TypeError in case of an unserializable data type
 * }
 * ```
 */
declare const createStableKeyOrThrow: <T extends SupportedDataTypesRW>(value: T, options?: CreateStableKeyOptions) => string;

export { createStableHash, createStableHashOrThrow, createStableKey, createStableKeyOrThrow };