0
# Image Transformations
1

2
Comprehensive image processing operations including resizing, format conversion, metadata preservation, and custom transformations.
3

4
## Capabilities
5

6
### Image Resizing
7

8
Resize images using various methods including fit and cover modes.
9

10
```typescript { .api }
11
/**
12
 * Resize image with specified options
13
 * @param options - Resize configuration object
14
 * @returns New Source instance with resize transformation
15
 */
16
resize(options: ResizeOptions): Source;
17

18
interface ResizeOptions {
19
  /** Resize method determining how the image is fitted */
20
  method: "fit" | "cover";
21
  /** Target width in pixels */
22
  width?: number;
23
  /** Target height in pixels */
24
  height?: number;
25
}
26
```
27

28
**Resize Methods:**
29

30
- **fit**: Scale image to fit within dimensions (maintains aspect ratio, may leave empty space)
31
- **cover**: Scale and crop to cover entire area (maintains aspect ratio, may crop parts)
32

33
**Usage Examples:**
34

35
```typescript
36
const tinify = require("tinify");
37

38
tinify.key = "your-api-key";
39

40
// Fit within dimensions (no cropping)
41
await tinify.fromFile("large-image.jpg")
42
  .resize({ method: "fit", width: 800, height: 600 })
43
  .toFile("fitted.jpg");
44

45
// Cover area (may crop)  
46
await tinify.fromFile("photo.jpg")
47
  .resize({ method: "cover", width: 400, height: 400 })
48
  .toFile("square-thumbnail.jpg");
49

50
// Width only (maintain aspect ratio)
51
await tinify.fromFile("portrait.jpg")
52
  .resize({ method: "fit", width: 300 })
53
  .toFile("mobile-portrait.jpg");
54
```
55

56
### Format Conversion
57

58
Convert images between supported formats including AVIF, WebP, JPEG, and PNG.
59

60
```typescript { .api }
61
/**
62
 * Convert image to different format(s)
63
 * @param options - Conversion configuration object
64
 * @returns New Source instance with format conversion
65
 */
66
convert(options: ConvertOptions): Source;
67

68
interface ConvertOptions {
69
  /** Target format(s) - API will choose the most efficient */
70
  type: SupportedImageTypes | SupportedImageTypes[] | "*/*";
71
}
72

73
type SupportedImageTypes = 
74
  | "image/webp" 
75
  | "image/png" 
76
  | "image/jpg" 
77
  | "image/jpeg" 
78
  | "image/avif";
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
const tinify = require("tinify");
85

86
tinify.key = "your-api-key";
87

88
// Convert to specific format
89
await tinify.fromFile("photo.jpg")
90
  .convert({ type: "image/webp" })
91
  .toFile("photo.webp");
92

93
// Let API choose best format from options
94
const source = tinify.fromFile("image.png")
95
  .convert({ type: ["image/webp", "image/avif", "image/png"] });
96

97
// Get the chosen format
98
const result = source.result();
99
const extension = await result.extension();
100
await source.toFile(`optimized.${extension}`);
101

102
// Use wildcard for automatic format selection
103
await tinify.fromFile("large-file.png")
104
  .convert({ type: "*/*" })
105
  .toFile("smallest-format");
106
```
107

108
### Metadata Preservation
109

110
Preserve specific metadata fields including copyright, GPS location, and creation time.
111

112
```typescript { .api }
113
/**
114
 * Preserve metadata fields (array version)
115
 * @param options - Array of metadata fields to preserve
116
 * @returns New Source instance with metadata preservation
117
 */
118
preserve(options: string[]): Source;
119

120
/**
121
 * Preserve metadata fields (variadic version)
122
 * @param options - Metadata fields to preserve as separate arguments
123
 * @returns New Source instance with metadata preservation
124
 */
125
preserve(...options: string[]): Source;
126
```
127

128
**Supported Metadata Fields:**
129

130
- **copyright**: Copyright information
131
- **creation**: Creation date and time
132
- **location**: GPS coordinates and location data
133

134
**Usage Examples:**
135

136
```typescript
137
const tinify = require("tinify");
138

139
tinify.key = "your-api-key";
140

141
// Preserve specific metadata (array syntax)
142
await tinify.fromFile("photo-with-metadata.jpg")
143
  .preserve(["copyright", "location"])
144
  .toFile("compressed-with-metadata.jpg");
145

146
// Preserve metadata (variadic syntax)
147
await tinify.fromFile("photo.jpg")
148
  .preserve("copyright", "creation", "location")
149
  .toFile("preserved.jpg");
150

151
// Combine with other transformations
152
await tinify.fromFile("original.jpg")
153
  .resize({ method: "fit", width: 1200 })
154
  .preserve("copyright")
155
  .convert({ type: "image/webp" })
156
  .toFile("optimized.webp");
157
```
158

159
### Custom Transformations
160

161
Apply custom transformation options using the generic transform method.
162

163
```typescript { .api }
164
/**
165
 * Apply custom transformation options
166
 * @param options - Custom transformation configuration object
167
 * @returns New Source instance with custom transformation
168
 */
169
transform(options: object): Source;
170
```
171

172
**Usage Example:**
173

174
```typescript
175
const tinify = require("tinify");
176

177
tinify.key = "your-api-key";
178

179
// Custom transformation (API-specific options)
180
await tinify.fromFile("image.jpg")
181
  .transform({
182
    // Custom API options would go here
183
    // Refer to Tinify API documentation for available options
184
  })
185
  .toFile("custom-transformed.jpg");
186
```
187

188
### Chaining Transformations
189

190
All transformation methods return a new `Source` instance, allowing for fluent chaining of multiple operations.
191

192
**Usage Examples:**
193

194
```typescript
195
const tinify = require("tinify");
196

197
tinify.key = "your-api-key";
198

199
// Complex transformation chain
200
await tinify.fromFile("large-photo.jpg")
201
  .resize({ method: "cover", width: 800, height: 600 })
202
  .preserve("copyright", "location")
203
  .convert({ type: ["image/webp", "image/jpg"] })
204
  .toFile("processed-photo");
205

206
// Conditional transformations
207
let source = tinify.fromFile("image.png");
208

209
if (needsResize) {
210
  source = source.resize({ method: "fit", width: 1000 });
211
}
212

213
if (preserveMetadata) {
214
  source = source.preserve("copyright", "creation");
215
}
216

217
await source.toFile("final-image.png");
218
```
219

220
## Error Handling
221

222
Transformation methods can throw the following errors:
223

224
- **ClientError**: Invalid transformation options or unsupported format
225
- **AccountError**: Monthly compression limit exceeded
226
- **ServerError**: Temporary API processing issues
227

228
**Error Handling Example:**
229

230
```typescript
231
const tinify = require("tinify");
232

233
tinify.key = "your-api-key";
234

235
try {
236
  await tinify.fromFile("image.jpg")
237
    .resize({ method: "fit", width: 2000, height: 2000 })
238
    .convert({ type: "image/webp" })
239
    .toFile("processed.webp");
240
} catch (error) {
241
  if (error instanceof tinify.ClientError) {
242
    console.error("Invalid transformation options:", error.message);
243
  } else if (error instanceof tinify.AccountError) {
244
    console.error("Account limit exceeded:", error.message);
245
  }
246
}
247
```