blockchain-helper-lib

A professional utility package for validating and working with SHA-256 hashes, designed for blockchain, cryptography, and data integrity applications in Node.js. Includes enhanced error handling and TypeScript support.

Installation

npm install blockchain-helper-lib

Features

• SHA-256 Hash Validation: Validate and compare SHA-256 hashes easily.
• Hash Generation: Generate SHA-256 hashes from content or files.
• File Hash Verification: Verify file contents against expected SHA-256 hashes.
• Synchronous & Asynchronous API: Choose between sync and async validation.
• TypeScript Support: Includes type definitions for seamless integration.
• Enhanced Error Handling: Clear, descriptive errors for invalid input.
• No External Dependencies: Lightweight and fast.

Usage

Importing

CommonJS

const Sha256Helper = require('blockchain-helper-lib');

ES Modules / TypeScript

import * as Sha256Helper from 'blockchain-helper-lib';

Validate a SHA-256 Hash (Format)

const { validateHashFormat } = require('blockchain-helper-lib');

console.log(validateHashFormat('a3f5...')); // true or false

Generate a SHA-256 Hash from Content

const { generateSha256 } = require('blockchain-helper-lib');

const hash = generateSha256('hello world');
console.log(hash); // prints SHA-256 hash string

Compare Two SHA-256 Hashes

const { compareSha256 } = require('blockchain-helper-lib');

const hash1 = '...';
const hash2 = '...';
console.log(compareSha256(hash1, hash2)); // true if equal, false otherwise

Synchronous File Hash Validation

const { syncSha256Validation } = require('blockchain-helper-lib');

try {
  const fileHash = syncSha256Validation({ encoding: 'utf8', resolveFromCwd: false });
  console.log('File hash:', fileHash);
} catch (err) {
  console.error('Validation error:', err.message);
}

Asynchronous File Hash Validation

const { asyncSha256Validation } = require('blockchain-helper-lib');

asyncSha256Validation({ encoding: 'utf8', resolveFromCwd: false })
  .then(hash => console.log('File hash:', hash))
  .catch(err => console.error('Validation error:', err.message));

Hash File Content Directly

const { hashFileContent } = require('blockchain-helper-lib');

const hash = hashFileContent('path/to/file.txt');
console.log(hash);

Verify File Hash Against Expected

const { verifyFileHash } = require('blockchain-helper-lib');

const isValid = verifyFileHash('path/to/file.txt', 'expected_sha256_hash');
console.log(isValid ? 'File is valid' : 'File is NOT valid');

API Reference

syncSha256Validation(options?)

Synchronously validates a file and returns its SHA-256 hash.

• options (object, optional):
  • encoding (string): File encoding (default: 'utf8')
  • resolveFromCwd (boolean): Resolve path from current working directory (default: false)
• Returns: string (SHA-256 hash)
• Throws: Error if validation fails

asyncSha256Validation(options?)

Asynchronously validates a file and returns its SHA-256 hash.

• options (object, optional): Same as above
• Returns: Promise<string>

generateSha256(content, options?)

Generates a SHA-256 hash from a string.

• content (string): The content to hash
• options (object, optional):
  • encoding (string): Content encoding (default: 'utf8')
• Returns: string (SHA-256 hash)

validateHashFormat(hash)

Checks if a string is a valid SHA-256 hash.

• hash (string): The hash to validate
• Returns: boolean

compareSha256(hash1, hash2)

Compares two SHA-256 hashes for equality.

• hash1 (string): First hash
• hash2 (string): Second hash
• Returns: boolean

hashFileContent(filePath, options?)

Generates a SHA-256 hash from the contents of a file.

• filePath (string): Path to the file
• options (object, optional):
  • encoding (string): File encoding (default: 'utf8')
  • resolveFromCwd (boolean): Resolve path from current working directory (default: false)
• Returns: string (SHA-256 hash)

verifyFileHash(filePath, expectedHash, options?)

Verifies that a file's contents match an expected SHA-256 hash.

• filePath (string): Path to the file
• expectedHash (string): The expected SHA-256 hash
• options (object, optional):
  • encoding (string): File encoding (default: 'utf8')
  • resolveFromCwd (boolean): Resolve path from current working directory (default: false)
• Returns: boolean

Requirements

• Node.js >= 16.0.0

License

MIT

Author

James Edward

Contributing

Contributions are welcome! Please open an issue or submit a pull request.