or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-js-sha256

A simple SHA-256 / SHA-224 hash function for JavaScript supports UTF-8 encoding.

Workspace: tessl
Visibility: Public
Created: 4 months ago
Last updated: 4 months ago
Describes: pkg:npm/js-sha256@0.11.x

To install, run

npx @tessl/cli install tessl/npm-js-sha256@0.11.0

js-sha256

js-sha256 is a simple SHA-256 / SHA-224 hash function library for JavaScript that supports UTF-8 encoding. It provides both direct hashing functions and streaming hash objects with update capabilities, supports HMAC authentication, and provides multiple output formats including hex strings, byte arrays, and ArrayBuffer.

Package Information

Package Name: js-sha256
Package Type: npm
Language: JavaScript
Installation: npm install js-sha256

Core Imports

// Main import - provides sha256 function directly, sha224 as property
const sha256 = require('js-sha256');
const sha224 = sha256.sha224;

// Named imports
const { sha256, sha224 } = require('js-sha256');

// Explicit property access
const sha256 = require('js-sha256').sha256;
const sha224 = require('js-sha256').sha224;

ES6 modules:

import { sha256, sha224 } from 'js-sha256';

Basic Usage

import { sha256, sha224 } from 'js-sha256';

// Direct hashing
const hash1 = sha256('Hello, World!');
const hash2 = sha224('Hello, World!');

// Incremental hashing
const hasher = sha256.create();
hasher.update('Hello, ');
hasher.update('World!');
const result = hasher.hex();

// HMAC authentication
const hmac = sha256.hmac('secret-key', 'message to authenticate');

Capabilities

SHA-256 Hashing

Core SHA-256 hash functionality with support for multiple input formats and output types.

/**
 * Hash a message and return hex string
 * @param message - Data to hash (string, Array, Uint8Array, ArrayBuffer)
 * @returns 64-character hex string
 */
function sha256(message: Message): string;

/**
 * Create a hash object for incremental hashing
 * @returns Hasher instance for chaining operations
 */
sha256.create(): Hasher;

/**
 * Create a hash object and add initial message
 * @param message - Initial data to hash
 * @returns Hasher instance for chaining operations
 */
sha256.update(message: Message): Hasher;

/**
 * Hash a message and return hex string
 * @param message - Data to hash
 * @returns 64-character hex string
 */
sha256.hex(message: Message): string;

/**
 * Hash a message and return byte array
 * @param message - Data to hash
 * @returns Array of 32 integers (0-255)
 */
sha256.array(message: Message): number[];

/**
 * Hash a message and return byte array (alias for array)
 * @param message - Data to hash
 * @returns Array of 32 integers (0-255)
 */
sha256.digest(message: Message): number[];

/**
 * Hash a message and return ArrayBuffer
 * @param message - Data to hash
 * @returns ArrayBuffer with 32 bytes
 */
sha256.arrayBuffer(message: Message): ArrayBuffer;

SHA-224 Hashing

Core SHA-224 hash functionality with identical API to SHA-256 but shorter output.

/**
 * Hash a message and return hex string
 * @param message - Data to hash (string, Array, Uint8Array, ArrayBuffer)
 * @returns 56-character hex string
 */
function sha224(message: Message): string;

/**
 * Create a hash object for incremental hashing
 * @returns Hasher instance for chaining operations
 */
sha224.create(): Hasher;

/**
 * Create a hash object and add initial message
 * @param message - Initial data to hash
 * @returns Hasher instance for chaining operations
 */
sha224.update(message: Message): Hasher;

/**
 * Hash a message and return hex string
 * @param message - Data to hash
 * @returns 56-character hex string
 */
sha224.hex(message: Message): string;

/**
 * Hash a message and return byte array
 * @param message - Data to hash
 * @returns Array of 28 integers (0-255)
 */
sha224.array(message: Message): number[];

/**
 * Hash a message and return byte array (alias for array)
 * @param message - Data to hash
 * @returns Array of 28 integers (0-255)
 */
sha224.digest(message: Message): number[];

/**
 * Hash a message and return ArrayBuffer
 * @param message - Data to hash
 * @returns ArrayBuffer with 28 bytes
 */
sha224.arrayBuffer(message: Message): ArrayBuffer;

Incremental Hashing

Hasher interface for streaming and incremental hash computation.

interface Hasher {
  /**
   * Add data to the hash computation
   * @param message - Data to add to hash
   * @returns this (for method chaining)
   */
  update(message: Message): Hasher;

  /**
   * Finalize hash and return hex string
   * @returns Hex string representation of hash
   */
  hex(): string;

  /**
   * Finalize hash and return hex string (alias for hex)
   * @returns Hex string representation of hash
   */
  toString(): string;

  /**
   * Finalize hash and return byte array
   * @returns Array of integers (0-255)
   */
  array(): number[];

  /**
   * Finalize hash and return byte array (alias for array)
   * @returns Array of integers (0-255)
   */
  digest(): number[];

  /**
   * Finalize hash and return ArrayBuffer
   * @returns ArrayBuffer with hash bytes
   */
  arrayBuffer(): ArrayBuffer;
}

Usage Examples:

import { sha256 } from 'js-sha256';

// Stream large data
const hasher = sha256.create();
hasher.update('chunk1');
hasher.update('chunk2');
hasher.update('chunk3');
const finalHash = hasher.hex();

// Method chaining
const hash = sha256.update('initial data')
  .update('more data')
  .hex();

// Different output formats
const hasher2 = sha256.create().update('test data');
const hexOutput = hasher2.hex();        // '...' (64 chars)
const arrayOutput = hasher2.array();    // [n1, n2, ..., n32]
const bufferOutput = hasher2.arrayBuffer(); // ArrayBuffer(32)

HMAC Authentication

Hash-based Message Authentication Code functionality for both SHA-256 and SHA-224.

/**
 * Compute HMAC-SHA256 and return hex string
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns 64-character hex string
 */
sha256.hmac(secretKey: Message, message: Message): string;

/**
 * Create HMAC hasher with secret key
 * @param secretKey - Secret key for authentication
 * @returns Hasher instance for incremental HMAC computation
 */
sha256.hmac.create(secretKey: Message): Hasher;

/**
 * Create HMAC hasher with secret key and initial message
 * @param secretKey - Secret key for authentication
 * @param message - Initial message to authenticate
 * @returns Hasher instance for chaining operations
 */
sha256.hmac.update(secretKey: Message, message: Message): Hasher;

/**
 * Compute HMAC-SHA256 and return hex string
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns 64-character hex string
 */
sha256.hmac.hex(secretKey: Message, message: Message): string;

/**
 * Compute HMAC-SHA256 and return byte array
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns Array of 32 integers (0-255)
 */
sha256.hmac.array(secretKey: Message, message: Message): number[];

/**
 * Compute HMAC-SHA256 and return byte array (alias for array)
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns Array of 32 integers (0-255)
 */
sha256.hmac.digest(secretKey: Message, message: Message): number[];

/**
 * Compute HMAC-SHA256 and return ArrayBuffer
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns ArrayBuffer with 32 bytes
 */
sha256.hmac.arrayBuffer(secretKey: Message, message: Message): ArrayBuffer;

/**
 * Compute HMAC-SHA224 and return hex string
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns 56-character hex string
 */
sha224.hmac(secretKey: Message, message: Message): string;

/**
 * Create HMAC-SHA224 hasher with secret key
 * @param secretKey - Secret key for authentication
 * @returns Hasher instance for incremental HMAC computation
 */
sha224.hmac.create(secretKey: Message): Hasher;

/**
 * Create HMAC-SHA224 hasher with secret key and initial message
 * @param secretKey - Secret key for authentication
 * @param message - Initial message to authenticate
 * @returns Hasher instance for chaining operations
 */
sha224.hmac.update(secretKey: Message, message: Message): Hasher;

/**
 * Compute HMAC-SHA224 and return hex string
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns 56-character hex string
 */
sha224.hmac.hex(secretKey: Message, message: Message): string;

/**
 * Compute HMAC-SHA224 and return byte array
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns Array of 28 integers (0-255)
 */
sha224.hmac.array(secretKey: Message, message: Message): number[];

/**
 * Compute HMAC-SHA224 and return byte array (alias for array)
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns Array of 28 integers (0-255)
 */
sha224.hmac.digest(secretKey: Message, message: Message): number[];

/**
 * Compute HMAC-SHA224 and return ArrayBuffer
 * @param secretKey - Secret key for authentication
 * @param message - Message to authenticate
 * @returns ArrayBuffer with 28 bytes
 */
sha224.hmac.arrayBuffer(secretKey: Message, message: Message): ArrayBuffer;

Usage Examples:

import { sha256, sha224 } from 'js-sha256';

// Direct HMAC computation
const hmac256 = sha256.hmac('my-secret-key', 'data to authenticate');
const hmac224 = sha224.hmac('my-secret-key', 'data to authenticate');

// Incremental HMAC computation
const hmacHasher = sha256.hmac.create('my-secret-key');
hmacHasher.update('chunk 1');
hmacHasher.update('chunk 2');
const authenticatedHash = hmacHasher.hex();

// Different output formats
const hmacHex = sha256.hmac.hex('key', 'message');      // hex string
const hmacArray = sha256.hmac.array('key', 'message');  // byte array
const hmacBuffer = sha256.hmac.arrayBuffer('key', 'message'); // ArrayBuffer

Types

/**
 * Supported message input types
 */
type Message = string | number[] | ArrayBuffer | Uint8Array;

/**
 * Hash computation interface for incremental operations
 */
interface Hasher {
  update(message: Message): Hasher;
  hex(): string;
  toString(): string;
  array(): number[];
  digest(): number[];
  arrayBuffer(): ArrayBuffer;
}

/**
 * Hash function interface with multiple output methods
 */
interface Hash {
  (message: Message): string;
  create(): Hasher;
  update(message: Message): Hasher;
  hex(message: Message): string;
  array(message: Message): number[];
  digest(message: Message): number[];
  arrayBuffer(message: Message): ArrayBuffer;
  hmac: Hmac;
}

/**
 * HMAC function interface
 */
interface Hmac {
  (secretKey: Message, message: Message): string;
  create(secretKey: Message): Hasher;
  update(secretKey: Message, message: Message): Hasher;
  hex(secretKey: Message, message: Message): string;
  array(secretKey: Message, message: Message): number[];
  digest(secretKey: Message, message: Message): number[];
  arrayBuffer(secretKey: Message, message: Message): ArrayBuffer;
}

Error Handling

The library throws an Error with the message "input is invalid type" when:

Input is null or undefined
Input is an invalid object type (not array, ArrayBuffer, or typed array)
Input is a non-string, non-object primitive type

Valid input types:

Strings: UTF-8 encoded JavaScript strings including Unicode characters
Arrays: Regular JavaScript arrays containing integers 0-255
Uint8Array: Typed arrays for binary data
Int8Array: Signed byte arrays (when ArrayBuffer support is available)
ArrayBuffer: Raw binary data buffers
Other typed arrays: Any ArrayBuffer view when available

Platform Compatibility

The library automatically detects and optimizes for different JavaScript environments:

Browser: Provides window.sha256 and window.sha224 global variables
Node.js: Uses native crypto module optimizations when available
Web Workers: Provides self.sha256 and self.sha224 global variables
AMD/RequireJS: Supports AMD module definition
CommonJS: Standard module.exports support

Output Formats

Hex String Format

SHA-256: 64-character lowercase hexadecimal string
SHA-224: 56-character lowercase hexadecimal string

Array Format

SHA-256: Array of 32 integers (0-255)
SHA-224: Array of 28 integers (0-255)

ArrayBuffer Format

SHA-256: ArrayBuffer containing 32 bytes
SHA-224: ArrayBuffer containing 28 bytes
Uses DataView for cross-platform compatibility