Hash State Manager

Build a hash state manager that processes data in stages and properly handles errors when invalid operations are attempted on finalized hashes.

Requirements

Implement a HashStateManager class that manages the lifecycle of hash operations:

1. Multi-stage processing: Process data through multiple stages, where each stage adds data to the hash before finalization.

2. State lifecycle enforcement: Once a hash is finalized (digest computed), detect and handle attempts to update it with more data.

3. Error detection: Catch errors when trying to perform invalid operations (like updating a finalized hash) and track them for debugging.

4. Safe retry mechanism: Provide a way to safely attempt operations that might fail due to invalid state, returning success/failure status instead of throwing.

Implementation Notes

• Use try-catch blocks to detect when operations fail due to invalid state
• Track whether a hash has been finalized to prevent further updates
• Store error messages for debugging purposes
• Provide both throwing and non-throwing variants of operations where appropriate

Test Cases

• Processing data through multiple stages and finalizing produces correct hash @test
• Attempting to update a finalized hash is properly detected and handled @test
• Safe operation attempts return false when hash is finalized @test
• Error messages are captured and accessible for debugging @test

API

/**
 * Manages hash state lifecycle with proper error handling
 */
export class HashStateManager {
  /**
   * Creates a new hash state manager
   */
  constructor();

  /**
   * Adds data to the current hash state
   * @param data - Data to add to hash
   * @throws Error if hash is already finalized
   */
  addData(data: Uint8Array): void;

  /**
   * Finalizes the hash and returns the digest
   * @returns The computed hash digest
   */
  finalize(): Uint8Array;

  /**
   * Safely attempts to add data, catching any errors
   * @param data - Data to add
   * @returns true if successful, false if operation failed
   */
  tryAddData(data: Uint8Array): boolean;

  /**
   * Gets the last error message encountered
   * @returns Error message string or null if no error
   */
  getLastError(): string | null;

  /**
   * Resets to a fresh hash state
   */
  reset(): void;
}

Dependencies { .dependencies }

@stablelib/sha256 { .dependency }

Provides cryptographic hashing functionality with state management.