0
# Buffer Processing
1

2
Synchronous dimension extraction from image buffers and Uint8Array data. This approach is ideal for streams, network requests, memory-based operations, or when you already have image data loaded.
3

4
## Capabilities
5

6
### Image Size Extraction
7

8
Extracts dimensions from image buffer synchronously with automatic format detection.
9

10
```typescript { .api }
11
/**
12
 * Extract dimensions from image buffer
13
 * @param input - Image data as Uint8Array or Buffer
14
 * @returns Dimension data with width, height, type, and optional metadata
15
 * @throws TypeError if unsupported file type or disabled type
16
 */
17
function imageSize(input: Uint8Array): ISizeCalculationResult;
18

19
interface ISizeCalculationResult {
20
  /** Image width in pixels */
21
  width: number;
22
  /** Image height in pixels */
23
  height: number;
24
  /** JPEG EXIF orientation (1-8) if present */
25
  orientation?: number;
26
  /** Detected image format string */
27
  type?: string;
28
  /** Array of all sizes for multi-size formats (ICO, CUR, HEIF) */
29
  images?: ISize[];
30
}
31

32
interface ISize {
33
  width: number;
34
  height: number;
35
  orientation?: number;
36
  type?: string;
37
}
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import imageSize from "image-size"; // default export
44
// or
45
import { imageSize } from "image-size"; // named export
46
import { readFileSync } from "node:fs";
47

48
// Basic usage with file buffer
49
const buffer = readFileSync("photo.jpg");
50
const dimensions = imageSize(buffer);
51
console.log(`${dimensions.width}x${dimensions.height}`); // 1920x1080
52
console.log(`Format: ${dimensions.type}`); // Format: jpg
53

54
// Handle JPEG with orientation
55
const jpegBuffer = readFileSync("rotated-photo.jpg");
56
const jpegInfo = imageSize(jpegBuffer);
57
if (jpegInfo.orientation) {
58
  console.log(`Orientation: ${jpegInfo.orientation}`); // 1-8
59
}
60

61
// Multi-size formats (ICO, CUR, HEIF)
62
const icoBuffer = readFileSync("favicon.ico");
63
const icoInfo = imageSize(icoBuffer);
64
console.log(`Main size: ${icoInfo.width}x${icoInfo.height}`); // Largest image
65
if (icoInfo.images) {
66
  console.log("All sizes:");
67
  icoInfo.images.forEach(img => 
68
    console.log(`  ${img.width}x${img.height}`)
69
  );
70
}
71

72
// Handle network requests
73
import fetch from 'node-fetch';
74

75
const response = await fetch('https://example.com/image.png');
76
const arrayBuffer = await response.arrayBuffer();
77
const imageBuffer = new Uint8Array(arrayBuffer);
78
const netDimensions = imageSize(imageBuffer);
79

80
// Handle streams
81
import { Transform } from 'node:stream';
82

83
const imageStream = new Transform({
84
  transform(chunk, encoding, callback) {
85
    try {
86
      const dimensions = imageSize(chunk);
87
      console.log(`Stream image: ${dimensions.width}x${dimensions.height}`);
88
      callback(null, chunk);
89
    } catch (error) {
90
      // Might need more data for complete header
91
      callback(null, chunk);
92
    }
93
  }
94
});
95
```
96

97
### Type Management
98

99
Control which image formats are processed for performance optimization.
100

101
```typescript { .api }
102
/**
103
 * Globally disable specific image format detectors
104
 * @param types - Array of image format strings to disable
105
 * @returns void
106
 */
107
function disableTypes(types: imageType[]): void;
108

109
/**
110
 * Array of all supported image format strings
111
 */
112
const types: imageType[];
113

114
type imageType = 'bmp' | 'cur' | 'dds' | 'gif' | 'heif' | 'icns' | 'ico' | 'j2c' | 'jp2' | 'jpg' | 'jxl' | 'jxl-stream' | 'ktx' | 'png' | 'pnm' | 'psd' | 'svg' | 'tga' | 'tiff' | 'webp';
115
```
116

117
**Usage Examples:**
118

119
```typescript
120
import { disableTypes, types, imageSize } from "image-size";
121
import { readFileSync } from "node:fs";
122

123
// View all supported formats
124
console.log("Supported formats:", types);
125
// ['bmp', 'cur', 'dds', 'gif', 'heif', 'icns', 'ico', ...]
126

127
// Disable rarely used formats for performance
128
disableTypes(['tiff', 'psd', 'dds']);
129

130
// This will now throw TypeError for disabled formats
131
try {
132
  const tiffBuffer = readFileSync("document.tiff");
133
  const dimensions = imageSize(tiffBuffer);
134
} catch (error) {
135
  console.log(error.message); // "disabled file type: tiff"
136
}
137

138
// Common optimization: disable all but web formats
139
disableTypes(['bmp', 'cur', 'dds', 'icns', 'ico', 'j2c', 'jp2', 'jxl', 'jxl-stream', 'ktx', 'pnm', 'psd', 'tga', 'tiff']);
140
// Now only supports: gif, heif, jpg, png, svg, webp
141
```
142

143
## Error Handling
144

145
The buffer processing functions can throw the following errors:
146

147
```typescript
148
// Unsupported format
149
try {
150
  const result = imageSize(unknownBuffer);
151
} catch (error) {
152
  console.log(error.message); // "unsupported file type: undefined"
153
}
154

155
// Disabled format
156
disableTypes(['png']);
157
try {
158
  const result = imageSize(pngBuffer);
159
} catch (error) {
160
  console.log(error.message); // "disabled file type: png"
161
}
162
```
163

164
## Performance Notes
165

166
- Only reads image headers, not full files
167
- Zero memory copying for Uint8Array input
168
- Format detection optimized with header byte shortcuts
169
- Disabling unused formats improves detection speed
170
- Suitable for high-frequency operations and streaming