0
# Tinify
1

2
Tinify is a Node.js client library for the Tinify API (TinyPNG/TinyJPG) that provides intelligent image compression, resizing, format conversion, and cloud storage integration. It supports AVIF, WebP, JPEG, and PNG formats with advanced features like metadata preservation and direct cloud storage uploads.
3

4
## Package Information
5

6
- **Package Name**: tinify
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tinify`
10

11
## Core Imports
12

13
```javascript
14
const tinify = require("tinify");
15
```
16

17
For TypeScript:
18

19
```typescript
20
import tinify = require("tinify");
21
```
22

23
## Basic Usage
24

25
```javascript
26
const tinify = require("tinify");
27

28
// Set API key
29
tinify.key = "YOUR_API_KEY";
30

31
// Basic compression from file
32
await tinify.fromFile("input.png").toFile("output.png");
33

34
// From URL with resizing  
35
await tinify.fromUrl("https://example.com/image.jpg")
36
  .resize({ method: "fit", width: 150, height: 100 })
37
  .toFile("thumbnail.jpg");
38

39
// Format conversion
40
const source = tinify.fromFile("image.jpg")
41
  .convert({ type: ["image/webp", "image/png"] });
42
const result = source.result();
43
const extension = await result.extension();
44
await source.toFile(`converted.${extension}`);
45
```
46

47
## Architecture
48

49
Tinify uses a fluent API design centered around these core components:
50

51
- **Main Module**: Configuration and factory methods for creating sources
52
- **Source Class**: Represents an image for processing with chainable transformation methods
53
- **Result Classes**: Handle processed image data and metadata
54
- **Client**: Internal HTTP client for API communication
55
- **Error Handling**: Comprehensive error types for different failure scenarios
56

57
## Capabilities
58

59
### Configuration and Authentication
60

61
Core configuration settings including API key authentication, proxy settings, and application identification.
62

63
```typescript { .api }
64
// Configuration properties
65
let key: string;
66
let appIdentifier: string;
67
let proxy: string;
68
let compressionCount?: number;
69

70
// Validation method
71
function validate(): Promise<void>;
72
function validate(callback: (err: Error | null) => void): void;
73
```
74

75
[Configuration](./configuration.md)
76

77
### Image Source Creation
78

79
Factory methods for creating image sources from files, buffers, or URLs for processing.
80

81
```typescript { .api }
82
function fromFile(path: string): Source;
83
function fromBuffer(data: string | Uint8Array): Source;
84
function fromUrl(url: string): Source;
85
```
86

87
[Image Sources](./image-sources.md)
88

89
### Image Transformations
90

91
Comprehensive image processing operations including resizing, format conversion, and metadata preservation.
92

93
```typescript { .api }
94
class Source {
95
  resize(options: ResizeOptions): Source;
96
  convert(options: ConvertOptions): Source;
97
  preserve(options: string[]): Source;
98
  preserve(...options: string[]): Source;
99
  transform(options: object): Source;
100
}
101

102
interface ResizeOptions {
103
  method: "fit" | "cover";
104
  width?: number;
105
  height?: number;
106
}
107

108
interface ConvertOptions {
109
  type: SupportedImageTypes | SupportedImageTypes[] | "*/*";
110
}
111

112
type SupportedImageTypes = "image/webp" | "image/png" | "image/jpg" | "image/jpeg" | "image/avif";
113
```
114

115
[Image Transformations](./transformations.md)
116

117
### Results and Output
118

119
Methods for retrieving processed images as files, buffers, or metadata, with both Promise and callback support.
120

121
```typescript { .api }
122
class Source {
123
  result(): Result;
124
  toFile(path: string): Promise<void>;
125
  toFile(path: string, callback: (err: Error | null) => void): void;
126
  toBuffer(): Promise<Uint8Array>;
127
  toBuffer(callback: (err: Error | null, data?: Uint8Array) => void): void;
128
}
129

130
class Result {
131
  toFile(path: string): Promise<void>;
132
  toBuffer(): Promise<Uint8Array>;
133
  size(): Promise<number>;
134
  mediaType(): Promise<string | void>;
135
  extension(): Promise<string | void>;
136
}
137
```
138

139
[Results and Output](./results.md)
140

141
### Cloud Storage Integration
142

143
Direct upload integration with Amazon S3, Google Cloud Storage, and other S3-compatible services.
144

145
```typescript { .api }
146
class Source {
147
  store(options: StoreOptions): ResultMeta;
148
}
149

150
interface StoreOptions {
151
  service: "s3" | "gcs";
152
  aws_access_key_id?: string;
153
  aws_secret_access_key?: string;
154
  region?: string;
155
  path: string;
156
  // Additional S3/GCS options
157
}
158
```
159

160
[Cloud Storage](./cloud-storage.md)
161

162
### Error Handling
163

164
Comprehensive error types for different failure scenarios including authentication, client, server, and connection errors.
165

166
```typescript { .api }
167
class Error extends globalThis.Error {
168
  status?: number;
169
  constructor(message: string, type?: string, status?: number);
170
  static create(message: string, type: string, status?: number): Error;
171
}
172

173
class AccountError extends Error {} // 401, 429 errors
174
class ClientError extends Error {}  // 400-499 errors  
175
class ServerError extends Error {}  // 500-599 errors
176
class ConnectionError extends Error {} // Network errors
177
```
178

179
[Error Handling](./error-handling.md)
180

181
## Types
182

183
```typescript { .api }
184
type Callback<T = void> = (err: Error | null, data?: T) => void;
185

186
interface ResultMeta {
187
  width(): Promise<number>;
188
  height(): Promise<number>;
189
  location(): Promise<string>;
190
}
191
```