0
# sha.js
1

2
Streaming SHA hash implementation in pure JavaScript providing SHA1 and SHA256 algorithms with incremental processing capabilities. Designed for both browser and Node.js environments with constant memory usage regardless of input size.
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
// Factory function (recommended)
15
const createHash = require('sha.js');
16

17
// Direct class imports  
18
const { sha, sha1, sha256 } = require('sha.js');
19
```
20

21
ES Modules:
22

23
```javascript
24
import createHash from 'sha.js';
25
import { sha, sha1, sha256 } from 'sha.js';
26
```
27

28
## Basic Usage
29

30
```javascript
31
const createHash = require('sha.js');
32

33
// Using factory function
34
const hash = createHash('sha1');
35
hash.update('hello world', 'utf8');
36
const digest = hash.digest('hex');
37
console.log(digest); // aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
38

39
// Using direct class constructor
40
const { sha1 } = require('sha.js');
41
const hashInstance = new sha1();
42
hashInstance.update('hello world', 'utf8');
43
const result = hashInstance.digest('hex');
44

45
// Using 'sha' alias (same as sha1)
46
const { sha } = require('sha.js');
47
const shaInstance = new sha();
48
shaInstance.update('hello world', 'utf8');
49
const shaResult = shaInstance.digest('hex');
50

51
// Streaming/incremental usage
52
const streamHash = createHash('sha256');
53
streamHash.update('part 1', 'utf8');
54
streamHash.update('part 2', 'utf8');
55
const finalHash = streamHash.digest('hex');
56
```
57

58
## Architecture
59

60
sha.js is built around several key components:
61

62
- **Factory Function**: `createHash()` provides a unified interface for creating hash instances supporting 'sha1', 'sha' (alias for sha1), and 'sha256'  
63
- **Algorithm Classes**: `Sha1` and `Sha256` classes implementing specific hash algorithms
64
- **Base Hash Class**: Abstract base class providing common functionality (update, digest methods)
65
- **Streaming Interface**: Incremental processing allowing data to be hashed in chunks
66
- **Encoding Support**: Multiple input encoding formats (utf8, hex, binary, ascii) and output formats (hex, binary, base64)
67

68
## Capabilities
69

70
### Hash Creation
71

72
Create hash instances using the factory function or direct class constructors.
73

74
```javascript { .api }
75
/**
76
 * Creates a hash instance for the specified algorithm
77
 * @param algorithm - Hash algorithm name ('sha1', 'sha', or 'sha256')
78
 * @returns Hash instance for the specified algorithm
79
 * @throws Error if algorithm is not supported
80
 */
81
function createHash(algorithm: 'sha1' | 'sha' | 'sha256'): Sha1Instance | Sha256Instance;
82

83
/**
84
 * SHA hash class constructor (alias for SHA1)
85
 * @returns SHA1 hash instance
86
 */
87
const sha: new() => Sha1Instance;
88

89
/**
90
 * SHA1 hash class constructor
91
 * @returns SHA1 hash instance
92
 */
93
const sha1: new() => Sha1Instance;
94

95
/**
96
 * SHA256 hash class constructor  
97
 * @returns SHA256 hash instance
98
 */
99
const sha256: new() => Sha256Instance;
100
```
101

102
### Data Processing
103

104
Update hash instances incrementally with data and generate final digest.
105

106
```javascript { .api }
107
/**
108
 * Updates the hash with new data
109
 * @param data - Data to hash (string, Buffer, or Uint8Array)
110
 * @param encoding - Input encoding when data is string ('utf8', 'ascii', 'binary', 'hex')
111
 * @returns Hash instance for method chaining
112
 */
113
update(data: string | Buffer | Uint8Array, encoding?: string): this;
114

115
/**
116
 * Computes and returns the final hash digest
117
 * @param encoding - Output encoding ('hex', 'binary', 'base64', or omit for Uint8Array)
118
 * @returns Final hash digest in specified format
119
 * @throws Error if called multiple times on same instance
120
 */
121
digest(encoding?: string): string | Uint8Array;
122
```
123

124
### Command Line Interface
125

126
Binary executable for hashing files or stdin from command line.
127

128
```bash { .api }
129
# Hash a file with default SHA1 (outputs: hash timestamp)
130
sha.js filename
131

132
# Hash a file with specific algorithm (outputs: hash timestamp)
133
sha.js sha256 filename
134

135
# Hash stdin with specific algorithm (outputs: hash timestamp)
136
echo "data" | sha.js sha1
137

138
# Display help
139
sha.js --help
140
```
141

142
## Types
143

144
```javascript { .api }
145
/**
146
 * Hash instance interface providing incremental hashing
147
 */
148
interface HashInstance {
149
  /**
150
   * Updates hash with new data
151
   * @param data - Input data
152
   * @param encoding - Input encoding for strings
153
   * @returns this for chaining
154
   */
155
  update(data: string | Buffer | Uint8Array, encoding?: InputEncoding): this;
156
  
157
  /**
158
   * Finalizes and returns hash digest
159
   * @param encoding - Output encoding
160
   * @returns Hash digest
161
   */
162
  digest(encoding?: OutputEncoding): string | Uint8Array;
163
}
164

165
/**
166
 * SHA1 hash instance (160-bit output)
167
 */
168
interface Sha1Instance extends HashInstance {}
169

170
/**
171
 * SHA256 hash instance (256-bit output) 
172
 */
173
interface Sha256Instance extends HashInstance {}
174

175
/**
176
 * Supported input encodings for string data
177
 */
178
type InputEncoding = 'utf8' | 'ascii' | 'binary' | 'hex';
179

180
/**
181
 * Supported output encodings for digest
182
 */
183
type OutputEncoding = 'hex' | 'binary' | 'base64';
184

185
/**
186
 * Supported hash algorithms ('sha' is an alias for 'sha1')
187
 */
188
type Algorithm = 'sha1' | 'sha' | 'sha256';
189
```
190

191
## Error Handling
192

193
```javascript { .api }
194
/**
195
 * Thrown when unsupported algorithm is requested
196
 */
197
class Error {
198
  message: string; // "[algorithm] is not supported (we accept pull requests)"
199
}
200

201
/**
202
 * Thrown when unsupported input encoding is used (only base64 currently unsupported)
203
 */
204
class Error {
205
  message: string; // "base64 encoding not yet supported" or "[encoding] encoding not yet supported"
206
}
207
```
208

209
## Usage Examples
210

211
### Incremental Hashing
212

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

216
// Hash large data incrementally
217
const hash = createHash('sha1');
218
const data = getLargeDataChunks(); // Array of data chunks
219

220
for (const chunk of data) {
221
  hash.update(chunk, 'utf8');
222
}
223

224
const finalDigest = hash.digest('hex');
225
```
226

227
### Multiple Encodings
228

229
```javascript
230
const { sha, sha256 } = require('sha.js');
231

232
// Using 'sha' alias (equivalent to sha1)
233
const hashSha = new sha();
234
hashSha.update('test with sha alias', 'utf8');
235
const shaResult = hashSha.digest('hex');
236

237
// Hash binary data with SHA256
238
const hash1 = new sha256();
239
const binaryData = new Uint8Array([1, 2, 3, 4, 5]);
240
hash1.update(binaryData);
241
const binaryResult = hash1.digest('hex');
242

243
// Hash hex-encoded data
244
const hash2 = new sha256();
245
hash2.update('48656c6c6f', 'hex'); // "Hello" in hex
246
const hexResult = hash2.digest('base64');
247

248
// Hash with different output formats
249
const hash3 = new sha256();
250
hash3.update('test data', 'utf8');
251
const hexDigest = hash3.digest('hex');     // Hex string
252

253
const hash4 = new sha256();
254
hash4.update('test data', 'utf8');
255
const rawDigest = hash4.digest();          // Uint8Array
256
```
257

258
### Command Line Usage
259

260
```bash
261
# Hash a file
262
sha.js sha1 myfile.txt
263

264
# Hash stdin
265
echo "hello world" | sha.js sha256
266

267
# Hash with timing information (outputs: hash milliseconds)
268
sha.js sha1 largefile.bin
269
# Output: aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d 1250
270

271
# Using 'sha' alias (equivalent to sha1)
272
sha.js sha myfile.txt
273
```
274

275
## Performance Characteristics
276

277
- **Constant Memory**: Uses fixed memory regardless of input size
278
- **Streaming**: Processes data incrementally without loading entire input
279
- **Pure JavaScript**: No native dependencies, works in browsers and Node.js
280
- **TypedArrays**: Uses Uint32Array and DataView for optimal performance
281
- **Algorithm Support**: SHA1 (160-bit) and SHA256 (256-bit) implementations