0
# sha.js
1

2
sha.js provides pure JavaScript implementations of SHA (Secure Hash Algorithm) functions including SHA-0, SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512. It offers a Node.js-compatible API for creating streamable hash objects that can process data incrementally, making it suitable for hashing large amounts of data without loading everything into memory.
3

4
## Package Information
5

6
- **Package Name**: sha.js  
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install sha.js`
10

11
## Core Imports
12

13
```javascript
14
const shajs = require('sha.js');
15
// Or import specific algorithms
16
const { sha256, sha1, sha512 } = require('sha.js');
17
```
18

19
For ES modules:
20

21
```javascript
22
import shajs from 'sha.js';
23
// Or import specific algorithms
24
import { sha256, sha1, sha512 } from 'sha.js';
25
```
26

27
## Basic Usage
28

29
```javascript
30
const shajs = require('sha.js');
31

32
// Using factory function
33
const hash = shajs('sha256').update('hello world').digest('hex');
34
console.log(hash); // "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
35

36
// Using direct constructor
37
const sha256Hash = new shajs.sha256().update('hello world').digest('hex');
38

39
// Streaming usage
40
const stream = shajs('sha256');
41
stream.update('hello ');
42
stream.update('world');
43
const result = stream.digest('hex');
44
```
45

46
## Architecture
47

48
sha.js is built around several key components:
49

50
- **Factory Function**: Main export that creates hash instances based on algorithm name
51
- **Hash Base Class**: Common functionality for update(), digest(), and incremental processing
52
- **Algorithm Implementations**: Specific SHA variant classes (Sha, Sha1, Sha224, Sha256, Sha384, Sha512)
53
- **Inheritance Pattern**: All algorithms inherit from base Hash class using 'inherits' module
54
- **Incremental Processing**: Supports streaming/chunked data processing without memory limitations
55

56
## Capabilities
57

58
### Hash Factory Function
59

60
Creates hash instances for any supported SHA algorithm.
61

62
```javascript { .api }
63
/**
64
 * Creates a SHA hash instance for the specified algorithm
65
 * @param {string} algorithm - Algorithm name (case-insensitive): 'sha', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'
66
 * @returns {Hash} Hash instance for the specified algorithm
67
 * @throws {Error} If algorithm is not supported
68
 */
69
function shajs(algorithm);
70
```
71

72
**Usage Example:**
73

74
```javascript
75
// Create different hash types
76
const sha1Hash = shajs('sha1');
77
const sha256Hash = shajs('sha256');
78
const sha512Hash = shajs('SHA512'); // Case insensitive
79
```
80

81
### Algorithm Constructors
82

83
Direct access to specific SHA algorithm constructors.
84

85
```javascript { .api }
86
/**
87
 * SHA-0 hash constructor (legacy, deprecated)
88
 */
89
function Sha();
90

91
/**
92
 * SHA-1 hash constructor (legacy, deprecated for security)
93
 */
94
function Sha1();
95

96
/**
97
 * SHA-224 hash constructor
98
 */
99
function Sha224();
100

101
/**
102
 * SHA-256 hash constructor
103
 */
104
function Sha256();
105

106
/**
107
 * SHA-384 hash constructor
108
 */
109
function Sha384();
110

111
/**
112
 * SHA-512 hash constructor
113
 */
114
function Sha512();
115
```
116

117
**Usage Example:**
118

119
```javascript
120
const { sha256, sha1 } = require('sha.js');
121

122
// Direct instantiation
123
const hash1 = new sha256();
124
const hash2 = new sha1();
125
```
126

127
### Hash Instance Methods
128

129
All hash instances provide the same interface for incremental data processing.
130

131
```javascript { .api }
132
/**
133
 * Updates the hash with new data
134
 * @param {string|Buffer} data - Data to add to hash
135
 * @param {string} [encoding='utf8'] - Encoding for string data
136
 * @returns {Hash} this (for method chaining)
137
 */
138
update(data, encoding);
139

140
/**
141
 * Finalizes the hash computation and returns the result
142
 * @param {string} [encoding] - Output encoding ('hex', 'base64', etc.)
143
 * @returns {Buffer|string} Hash result as Buffer (no encoding) or string (with encoding)
144
 */
145
digest(encoding);
146

147
/**
148
 * Initializes/resets the hash state to start fresh
149
 * @returns {Hash} this
150
 */
151
init();
152
```
153

154
**Usage Examples:**
155

156
```javascript
157
const shajs = require('sha.js');
158

159
// Method chaining
160
const result = shajs('sha256')
161
  .update('hello')
162
  .update(' ')
163
  .update('world')
164
  .digest('hex');
165

166
// Step by step
167
const hash = shajs('sha256');
168
hash.update('data chunk 1');
169
hash.update('data chunk 2');
170
const hexResult = hash.digest('hex');
171
const bufferResult = hash.digest(); // Returns Buffer
172

173
// Reset and reuse
174
hash.init();
175
hash.update('new data');
176
const newResult = hash.digest('hex');
177
```
178

179
### Command Line Interface
180

181
sha.js includes a command-line tool for hashing files or stdin.
182

183
```bash
184
# Hash a file with SHA-256
185
sha.js sha256 filename.txt
186

187
# Hash stdin with SHA-1 (default)
188
echo "hello world" | sha.js
189

190
# Hash stdin with specific algorithm
191
echo "hello world" | sha.js sha512
192

193
# Show help
194
sha.js --help
195
```
196

197
## Supported Algorithms
198

199
```javascript { .api }
200
// Available algorithm names (case-insensitive)
201
type SupportedAlgorithm = 'sha' | 'sha1' | 'sha224' | 'sha256' | 'sha384' | 'sha512';
202
```
203

204
- **sha** / **sha-0**: SHA-0 (legacy, deprecated for security reasons)
205
- **sha1** / **sha-1**: SHA-1 (legacy, deprecated for security reasons)  
206
- **sha224** / **sha-224**: SHA-224 (28-byte output)
207
- **sha256** / **sha-256**: SHA-256 (32-byte output)
208
- **sha384** / **sha-384**: SHA-384 (48-byte output)
209
- **sha512** / **sha-512**: SHA-512 (64-byte output)
210

211
## Error Handling
212

213
```javascript
214
const shajs = require('sha.js');
215

216
try {
217
  const hash = shajs('unsupported-algorithm');
218
} catch (error) {
219
  console.log(error.message); // "unsupported-algorithm is not supported (we accept pull requests)"
220
}
221
```
222

223
## Types
224

225
```javascript { .api }
226
/**
227
 * Base hash class that all algorithm implementations extend
228
 */
229
interface Hash {
230
  /** Update hash with new data */
231
  update(data: string | Buffer, encoding?: string): Hash;
232
  /** Finalize and return hash result */
233
  digest(encoding?: string): Buffer | string;
234
  /** Reset hash state */
235
  init(): Hash;
236
}
237

238
/**
239
 * SHA-0 hash implementation (legacy)
240
 */
241
interface Sha extends Hash {}
242

243
/**
244
 * SHA-1 hash implementation (legacy)
245
 */
246
interface Sha1 extends Hash {}
247

248
/**
249
 * SHA-224 hash implementation
250
 */
251
interface Sha224 extends Hash {}
252

253
/**
254
 * SHA-256 hash implementation
255
 */
256
interface Sha256 extends Hash {}
257

258
/**
259
 * SHA-384 hash implementation
260
 */
261
interface Sha384 extends Hash {}
262

263
/**
264
 * SHA-512 hash implementation
265
 */
266
interface Sha512 extends Hash {}
267
```