0
# Read Chunk
1

2
Read Chunk is a Node.js utility library that provides both asynchronous and synchronous APIs for reading specific chunks of data from files. It eliminates the boilerplate code typically required with Node.js built-in fs methods by handling file descriptor management automatically and returning data as Uint8Array buffers.
3

4
## Package Information
5

6
- **Package Name**: read-chunk
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install read-chunk`
10

11
## Core Imports
12

13
```javascript
14
import { readChunk, readChunkSync } from "read-chunk";
15
```
16

17
For TypeScript projects:
18

19
```typescript
20
import { readChunk, readChunkSync, type Options } from "read-chunk";
21
```
22

23
## Basic Usage
24

25
```javascript
26
import { readChunk, readChunkSync } from "read-chunk";
27

28
// Asynchronous usage
29
const chunk = await readChunk('foo.txt', {
30
  length: 3,
31
  startPosition: 1
32
});
33
console.log(chunk); // Uint8Array containing the chunk data
34

35
// Synchronous usage  
36
const chunkSync = readChunkSync('foo.txt', {
37
  length: 3,
38
  startPosition: 1
39
});
40
console.log(chunkSync); // Uint8Array containing the chunk data
41
```
42

43
## Capabilities
44

45
### Asynchronous File Chunk Reading
46

47
Read a chunk from a file asynchronously using Node.js file descriptor operations.
48

49
```javascript { .api }
50
/**
51
 * Read a chunk from a file asynchronously
52
 * @param filePath - The path to the file
53
 * @param options - Configuration options for the read operation
54
 * @returns Promise resolving to the read chunk as Uint8Array
55
 */
56
function readChunk(filePath: string, options: Options): Promise<Uint8Array>;
57
```
58

59
**Usage:**
60

61
```javascript
62
import { readChunk } from "read-chunk";
63

64
// Read 10 bytes starting from position 5
65
const chunk = await readChunk('/path/to/file.txt', {
66
  length: 10,
67
  startPosition: 5
68
});
69

70
// Read from beginning of file (startPosition defaults to 0)
71
const header = await readChunk('/path/to/binary-file.bin', {
72
  length: 1024
73
});
74
```
75

76
### Synchronous File Chunk Reading
77

78
Read a chunk from a file synchronously using Node.js file descriptor operations.
79

80
```javascript { .api }
81
/**
82
 * Read a chunk from a file synchronously
83
 * @param filePath - The path to the file  
84
 * @param options - Configuration options for the read operation
85
 * @returns The read chunk as Uint8Array
86
 */
87
function readChunkSync(filePath: string, options: Options): Uint8Array;
88
```
89

90
**Usage:**
91

92
```javascript
93
import { readChunkSync } from "read-chunk";
94

95
// Read 10 bytes starting from position 5
96
const chunk = readChunkSync('/path/to/file.txt', {
97
  length: 10,
98
  startPosition: 5
99
});
100

101
// Read from beginning of file
102
const header = readChunkSync('/path/to/binary-file.bin', {
103
  length: 1024
104
});
105
```
106

107
## Types
108

109
```typescript { .api }
110
interface Options {
111
  /** The number of bytes to read */
112
  readonly length: number;
113
  /** 
114
   * The position to start reading from (defaults to 0)
115
   * Can be specified as number or bigint for large file positions
116
   */
117
  readonly startPosition?: number | bigint;
118
}
119
```
120

121
## Error Handling
122

123
Both functions handle file descriptor cleanup automatically using try/finally blocks. File system errors (such as file not found, permission denied, or invalid file paths) are propagated to the caller as native Node.js fs errors.
124

125
Common error scenarios:
126
- **ENOENT**: File does not exist
127
- **EACCES**: Permission denied
128
- **EISDIR**: Path is a directory, not a file
129
- **EMFILE**: Too many open files
130

131
## Buffer Management
132

133
- Returns `Uint8Array` for consistent binary data handling across all platforms
134
- Automatically trims the buffer if fewer bytes are read than requested (e.g., when reading near end of file)
135
- Uses native Node.js file descriptor operations for efficient reading without loading entire file into memory
136
- No external dependencies - uses only Node.js built-in modules (`node:fs`, `node:fs/promises`)
137

138
## Platform Requirements
139

140
- **Minimum Node.js version**: 18
141
- **Module type**: ES modules only (uses `import`/`export` syntax)
142
- **Platform support**: All platforms supported by Node.js