0
# Stream Processing
1

2
Efficient byte-level stream processing with zero-copy approach for optimal performance when parsing ASN.1 data.
3

4
## Capabilities
5

6
### Stream Class
7

8
The Stream class manages byte-level access to data with a zero-copy approach, supporting both binary arrays and strings.
9

10
```javascript { .api }
11
/**
12
 * Stream for efficient byte-level processing
13
 * @param enc - Source data (Stream, array, or string) - data will not be copied
14
 * @param pos - Starting position (required when enc is not a Stream)
15
 */
16
class Stream {
17
  constructor(enc: Stream | ArrayLike<number> | string, pos?: number);
18
  
19
  /** Source data (not copied) */
20
  enc: ArrayLike<number> | string;
21
  /** Current position in the stream */
22
  pos: number;
23
  
24
  /**
25
   * Get byte at current position (and increment) or specified position
26
   * @param pos - Read position if specified, else current position (and increment it)
27
   * @returns Byte value at the specified position
28
   * @throws Error if position exceeds stream length
29
   */
30
  get(pos?: number): number;
31
  
32
  /**
33
   * Hexadecimal dump of a specified region of the stream
34
   * @param start - Starting position (included)
35
   * @param end - Ending position (excluded)
36
   * @param type - Output format: 'raw', 'byte', or 'dump' (optional, defaults to 'raw')
37
   * @returns Hexadecimal representation of the region
38
   */
39
  hexDump(start: number, end: number, type?: 'raw' | 'byte' | 'dump'): string;
40
  
41
  /**
42
   * Base64 dump of a specified region of the stream
43
   * @param start - Starting position (included)
44
   * @param end - Ending position (excluded)  
45
   * @param type - Output format: 'url' (Base64url) or 'std' (standard Base64)
46
   * @returns Base64 representation of the region
47
   */
48
  b64Dump(start: number, end: number, type?: 'url' | 'std'): string;
49
  
50
  /**
51
   * Parse integer from stream region using ASN.1 INTEGER rules
52
   * @param start - Starting position
53
   * @param end - Ending position
54
   * @returns String representation of the integer (handles big integers)
55
   */
56
  parseInteger(start: number, end: number): string;
57
  
58
  /**
59
   * Parse Object Identifier from stream region
60
   * @param start - Starting position
61
   * @param end - Ending position
62
   * @param maxLength - Maximum length for output (optional)
63
   * @returns OID string in dotted notation (e.g., "1.2.840.113549.1.1.1")
64
   */
65
  parseOID(start: number, end: number, maxLength?: number): string;
66
  
67
  /**
68
   * Parse Relative Object Identifier from stream region
69
   * @param start - Starting position
70
   * @param end - Ending position
71
   * @param maxLength - Maximum length for output (optional)
72
   * @returns Relative OID string
73
   */
74
  parseRelativeOID(start: number, end: number, maxLength?: number): string;
75
  
76
  /**
77
   * Parse time value from stream region (UTCTime or GeneralizedTime)
78
   * @param start - Starting position
79
   * @param end - Ending position
80
   * @param shortYear - true for UTCTime (2-digit year), false for GeneralizedTime (4-digit year)
81
   * @returns Formatted time string
82
   */
83
  parseTime(start: number, end: number, shortYear: boolean): string;
84
  
85
  /**
86
   * Parse UTF-8 string from stream region
87
   * @param start - Starting position
88
   * @param end - Ending position
89
   * @param maxLength - Maximum length for output (optional)
90
   * @returns Object with str (parsed string) and size (byte count) properties
91
   */
92
  parseStringUTF(start: number, end: number, maxLength?: number): { str: string; size: number };
93
  
94
  /**
95
   * Parse ISO/ASCII string from stream region
96
   * @param start - Starting position
97
   * @param end - Ending position
98
   * @param maxLength - Maximum length for output (optional)
99
   * @returns Object with str (parsed string) and size (byte count) properties
100
   */
101
  parseStringISO(start: number, end: number, maxLength?: number): { str: string; size: number };
102
  
103
  /**
104
   * Parse BMP (Basic Multilingual Plane) string from stream region
105
   * @param start - Starting position
106
   * @param end - Ending position
107
   * @param maxLength - Maximum length for output (optional)
108
   * @returns Object with str (parsed string) and size (byte count) properties
109
   */
110
  parseStringBMP(start: number, end: number, maxLength?: number): { str: string; size: number };
111
  
112
  /**
113
   * Parse T.61 string from stream region
114
   * @param start - Starting position
115
   * @param end - Ending position
116
   * @param maxLength - Maximum length for output (optional)
117
   * @returns Object with str (parsed string) and size (byte count) properties
118
   */
119
  parseStringT61(start: number, end: number, maxLength?: number): { str: string; size: number };
120
  
121
  /**
122
   * Parse bit string from stream region
123
   * @param start - Starting position
124
   * @param end - Ending position
125
   * @param maxLength - Maximum length for output (optional)
126
   * @returns Object with str (bit string) and size (bit count) properties
127
   */
128
  parseBitString(start: number, end: number, maxLength?: number): { str: string; size: number };
129
  
130
  /**
131
   * Parse octet string from stream region
132
   * @param start - Starting position
133
   * @param end - Ending position
134
   * @param maxLength - Maximum length for output (optional)
135
   * @returns Object with str (hex representation) and size (byte count) properties
136
   */
137
  parseOctetString(start: number, end: number, maxLength?: number): { str: string; size: number };
138
}
139
```
140

141
**Usage Examples:**
142

143
```javascript
144
import { Stream } from '@lapo/asn1js';
145

146
// Create stream from binary array
147
const data = [0x02, 0x03, 0x01, 0x00, 0xFF]; // INTEGER 65535
148
const stream = new Stream(data, 0);
149

150
// Read bytes manually
151
console.log(stream.get()); // 0x02 (INTEGER tag)
152
console.log(stream.get()); // 0x03 (length)
153
console.log(stream.pos); // 2
154

155
// Parse integer content
156
const intValue = stream.parseInteger(2, 5);
157
console.log(intValue); // "65535"
158

159
// Hex dump
160
const hexDump = stream.hexDump(0, 5, 'dump');
161
console.log(hexDump);
162
// Output formatted hex dump
163

164
// Create stream from string (for text data)
165
const textData = "Hello World";
166
const textStream = new Stream(textData, 0);
167
console.log(textStream.get()); // 72 (ASCII 'H')
168
```
169

170
### Static Methods
171

172
Utility methods for byte and stream operations.
173

174
```javascript { .api }
175
/**
176
 * Convert a single byte to hexadecimal string representation
177
 * @param b - Byte value (0-255)
178
 * @returns Two-character hexadecimal string (e.g., "A0", "FF")
179
 */
180
static Stream.hexByte(b: number): string;
181
```
182

183
**Usage Examples:**
184

185
```javascript
186
import { Stream } from '@lapo/asn1js';
187

188
// Convert bytes to hex
189
console.log(Stream.hexByte(255)); // "FF"
190
console.log(Stream.hexByte(0)); // "00"
191
console.log(Stream.hexByte(160)); // "A0"
192

193
// Use with stream data
194
const data = [0xDE, 0xAD, 0xBE, 0xEF];
195
const hexString = data.map(b => Stream.hexByte(b)).join('');
196
console.log(hexString); // "DEADBEEF"
197
```
198

199
### Parsing Examples
200

201
Complex examples showing how to use Stream for manual ASN.1 parsing.
202

203
```javascript
204
import { Stream, ASN1 } from '@lapo/asn1js';
205
import { Base64 } from '@lapo/asn1js/base64.js';
206

207
// Parse RSA public key manually
208
const rsaKeyPem = `-----BEGIN PUBLIC KEY-----
209
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3YkQOL4OqPlzJGPbhUKZ
210
...
211
-----END PUBLIC KEY-----`;
212

213
const keyData = Base64.unarmor(rsaKeyPem);
214
const stream = new Stream(keyData, 0);
215

216
// Manual parsing (normally you'd use ASN1.decode)
217
console.log(stream.get()); // 0x30 (SEQUENCE tag)
218
const length = stream.get(); // Length byte
219

220
// Or use ASN1 for full parsing
221
const publicKey = ASN1.decode(keyData);
222
console.log(publicKey.toPrettyString());
223

224
// Parse specific OID
225
const oidBytes = [0x2A, 0x86, 0x48, 0x86, 0xF7, 0x0D, 0x01, 0x01, 0x01];
226
const oidStream = new Stream(oidBytes, 0);
227
const oidString = oidStream.parseOID(0, oidBytes.length);
228
console.log(oidString); // "1.2.840.113549.1.1.1" (RSA encryption)
229

230
// Parse time values
231
const timeBytes = [0x31, 0x37, 0x30, 0x39, 0x31, 0x32, 0x31, 0x32, 0x33, 0x30, 0x30, 0x30, 0x5A];
232
const timeStream = new Stream(timeBytes, 0);
233
const timeString = timeStream.parseTime(0, timeBytes.length, true);
234
console.log(timeString); // Formatted time string
235
```