convertit 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +85 -0
- package/README.md +503 -0
- package/dist/converters/base.d.ts +27 -0
- package/dist/converters/base.d.ts.map +1 -0
- package/dist/converters/csv.d.ts +67 -0
- package/dist/converters/csv.d.ts.map +1 -0
- package/dist/converters/excel-styles.d.ts +51 -0
- package/dist/converters/excel-styles.d.ts.map +1 -0
- package/dist/converters/excel.d.ts +40 -0
- package/dist/converters/excel.d.ts.map +1 -0
- package/dist/converters/html.d.ts +21 -0
- package/dist/converters/html.d.ts.map +1 -0
- package/dist/converters/image.d.ts +80 -0
- package/dist/converters/image.d.ts.map +1 -0
- package/dist/converters/index.d.ts +10 -0
- package/dist/converters/index.d.ts.map +1 -0
- package/dist/converters/pdf.d.ts +68 -0
- package/dist/converters/pdf.d.ts.map +1 -0
- package/dist/converters/text.d.ts +36 -0
- package/dist/converters/text.d.ts.map +1 -0
- package/dist/converters/word.d.ts +24 -0
- package/dist/converters/word.d.ts.map +1 -0
- package/dist/core/converter.d.ts +65 -0
- package/dist/core/converter.d.ts.map +1 -0
- package/dist/core/errors.d.ts +64 -0
- package/dist/core/errors.d.ts.map +1 -0
- package/dist/core/index.d.ts +8 -0
- package/dist/core/index.d.ts.map +1 -0
- package/dist/core/template-engine.d.ts +57 -0
- package/dist/core/template-engine.d.ts.map +1 -0
- package/dist/core/types.d.ts +702 -0
- package/dist/core/types.d.ts.map +1 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +270420 -0
- package/dist/transformers/index.d.ts +61 -0
- package/dist/transformers/index.d.ts.map +1 -0
- package/dist/utils/helpers.d.ts +55 -0
- package/dist/utils/helpers.d.ts.map +1 -0
- package/dist/utils/index.d.ts +7 -0
- package/dist/utils/index.d.ts.map +1 -0
- package/dist/utils/validator.d.ts +26 -0
- package/dist/utils/validator.d.ts.map +1 -0
- package/package.json +129 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
### Added
|
|
9
|
+
|
|
10
|
+
#### Core Features
|
|
11
|
+
- **File Conversion**: Support for PDF, Word (DOCX), Excel (XLSX), CSV, HTML, JSON, XML, Markdown, and image formats
|
|
12
|
+
- **Builder Pattern**: Fluent API for chaining conversion operations
|
|
13
|
+
- **Batch Processing**: Convert multiple files with configurable concurrency
|
|
14
|
+
- **Progress Tracking**: Monitor conversion progress with callbacks
|
|
15
|
+
|
|
16
|
+
#### Excel Conditional Formatting (NEW)
|
|
17
|
+
- **Row Styles**: Color entire rows based on conditions
|
|
18
|
+
- Even/odd row styling (zebra stripes)
|
|
19
|
+
- Column value conditions (equal, greater than, less than, etc.)
|
|
20
|
+
- Custom expression-based conditions
|
|
21
|
+
- **Cell Styles**: Apply styles to specific cells, columns, or ranges
|
|
22
|
+
- Number formatting (currency, percentage, dates)
|
|
23
|
+
- Font styling (bold, italic, color, size)
|
|
24
|
+
- Fill colors and patterns
|
|
25
|
+
- Border styles
|
|
26
|
+
- Alignment options
|
|
27
|
+
- **Style Presets**: Pre-built styles for common scenarios
|
|
28
|
+
- `positiveHighlight`, `negativeHighlight`, `warningHighlight`
|
|
29
|
+
- `headerStyle`, `totalRow`
|
|
30
|
+
- `currencyFormat`, `percentFormat`
|
|
31
|
+
- **Native Excel Conditional Formatting**
|
|
32
|
+
- Data bars
|
|
33
|
+
- Color scales
|
|
34
|
+
- Icon sets
|
|
35
|
+
|
|
36
|
+
#### Template Engine (NEW)
|
|
37
|
+
- Simple yet powerful template processing
|
|
38
|
+
- Variable substitution with dot notation
|
|
39
|
+
- Conditionals (`#if`, `#unless`, `#else`)
|
|
40
|
+
- Loops (`#each`)
|
|
41
|
+
- Context blocks (`#with`)
|
|
42
|
+
- Partial templates
|
|
43
|
+
- Built-in helpers:
|
|
44
|
+
- `formatDate`, `formatNumber`, `formatCurrency`, `formatPercent`
|
|
45
|
+
- `upper`, `lower`, `capitalize`, `titleCase`, `truncate`
|
|
46
|
+
- `add`, `subtract`, `multiply`, `divide`, `round`
|
|
47
|
+
- `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `not`
|
|
48
|
+
- `json`, `join`, `length`, `default`
|
|
49
|
+
|
|
50
|
+
#### Transformers
|
|
51
|
+
- **Watermark**: Add text watermarks to PDFs
|
|
52
|
+
- **Encryption**: Password protect PDF files
|
|
53
|
+
- **Compression**: Reduce file sizes
|
|
54
|
+
- **Page Numbers**: Add page numbering to PDFs
|
|
55
|
+
- **Headers/Footers**: Add custom headers and footers
|
|
56
|
+
- **Merge**: Combine multiple files
|
|
57
|
+
- **Split**: Split files into parts
|
|
58
|
+
- **Rotation**: Rotate PDF pages
|
|
59
|
+
|
|
60
|
+
#### Developer Experience
|
|
61
|
+
- **ESLint**: Code linting with TypeScript support
|
|
62
|
+
- **Husky**: Git hooks for pre-commit and pre-push
|
|
63
|
+
- **lint-staged**: Run linters on staged files
|
|
64
|
+
- **GitHub Actions CI**: Automated testing, linting, and builds
|
|
65
|
+
- **TypeScript**: Full type definitions for all APIs
|
|
66
|
+
|
|
67
|
+
#### Utilities
|
|
68
|
+
- File format detection and validation
|
|
69
|
+
- MIME type utilities
|
|
70
|
+
- Color parsing and conversion
|
|
71
|
+
- File size formatting
|
|
72
|
+
- Environment detection (Node.js, Bun, Browser)
|
|
73
|
+
- Async utilities (delay, retry, timeout)
|
|
74
|
+
|
|
75
|
+
### Technical Details
|
|
76
|
+
- Built with Bun for fast development
|
|
77
|
+
- ESM and CJS dual module support
|
|
78
|
+
- Comprehensive test coverage
|
|
79
|
+
- Type-safe error handling with custom error classes
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## [0.x.x] - Previous Development
|
|
84
|
+
|
|
85
|
+
Initial development and internal releases.
|
package/README.md
ADDED
|
@@ -0,0 +1,503 @@
|
|
|
1
|
+
# convertit
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<strong>A powerful, type-safe file conversion library for Node.js and Bun</strong>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
Convert between PDF, Word, Excel, CSV, HTML, images, and more with a simple, intuitive API.
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="#features">Features</a> •
|
|
13
|
+
<a href="#installation">Installation</a> •
|
|
14
|
+
<a href="#quick-start">Quick Start</a> •
|
|
15
|
+
<a href="#excel-styling">Excel Styling</a> •
|
|
16
|
+
<a href="#api-reference">API</a> •
|
|
17
|
+
<a href="#examples">Examples</a>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Features
|
|
23
|
+
|
|
24
|
+
- **Multiple Format Support**: PDF, Word (DOCX), Excel (XLSX), CSV, HTML, JSON, XML, Markdown, and various image formats
|
|
25
|
+
- **Simple API**: Convert files with just one line of code
|
|
26
|
+
- **Builder Pattern**: Fluent API for complex conversions
|
|
27
|
+
- **Excel Conditional Formatting**: Row colors, cell styles, data bars, color scales
|
|
28
|
+
- **Template Engine**: Built-in template processing for document generation
|
|
29
|
+
- **Transformers**: Built-in support for compression, watermarks, merging, splitting, and rotation
|
|
30
|
+
- **Type-Safe**: Full TypeScript support with comprehensive type definitions
|
|
31
|
+
- **Extensible**: Plugin system for custom converters
|
|
32
|
+
- **Batch Processing**: Convert multiple files efficiently
|
|
33
|
+
- **Progress Tracking**: Monitor conversion progress with callbacks
|
|
34
|
+
|
|
35
|
+
## Installation
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# Using bun
|
|
39
|
+
bun add convertit
|
|
40
|
+
|
|
41
|
+
# Using npm
|
|
42
|
+
npm install convertit
|
|
43
|
+
|
|
44
|
+
# Using yarn
|
|
45
|
+
yarn add convertit
|
|
46
|
+
|
|
47
|
+
# Using pnpm
|
|
48
|
+
pnpm add convertit
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Quick Start
|
|
52
|
+
|
|
53
|
+
### Basic Usage
|
|
54
|
+
|
|
55
|
+
```typescript
|
|
56
|
+
import convertit from 'convertit';
|
|
57
|
+
|
|
58
|
+
// Convert data to PDF
|
|
59
|
+
const result = await convertit.from(data).toPdf().toBuffer();
|
|
60
|
+
|
|
61
|
+
// Save directly to file
|
|
62
|
+
await convertit.from(data).toPdf().toFile('output.pdf');
|
|
63
|
+
|
|
64
|
+
// Get as Base64
|
|
65
|
+
const base64 = await convertit.from(data).toPdf().toBase64();
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Builder Pattern (Fluent API)
|
|
69
|
+
|
|
70
|
+
```typescript
|
|
71
|
+
import convertit from 'convertit';
|
|
72
|
+
|
|
73
|
+
// Convert JSON to PDF with options
|
|
74
|
+
const buffer = await convertit.from(jsonData)
|
|
75
|
+
.toPdf({ pageSize: 'A4', orientation: 'landscape' })
|
|
76
|
+
.withWatermark({ text: 'DRAFT', opacity: 0.3 })
|
|
77
|
+
.withCompression({ level: 'medium' })
|
|
78
|
+
.toBuffer();
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Excel Styling
|
|
82
|
+
|
|
83
|
+
### Conditional Row Formatting
|
|
84
|
+
|
|
85
|
+
convertit supports powerful Excel conditional formatting. Color entire rows based on values:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
import convertit, { StylePresets } from 'convertit';
|
|
89
|
+
|
|
90
|
+
const salesData = [
|
|
91
|
+
{ name: 'Suraj', amount: 15000, status: 'Achieved' },
|
|
92
|
+
{ name: 'Sathya', amount: 0, status: 'Pending' },
|
|
93
|
+
{ name: 'Pruthvi', amount: -500, status: 'Deficit' },
|
|
94
|
+
];
|
|
95
|
+
|
|
96
|
+
// Create Excel with conditional row colors
|
|
97
|
+
const excel = await convertit.from(salesData)
|
|
98
|
+
.toExcel({
|
|
99
|
+
sheetName: 'Sales Report',
|
|
100
|
+
rowStyles: [
|
|
101
|
+
// Zebra striping - blue for even rows
|
|
102
|
+
{
|
|
103
|
+
condition: { type: 'even' },
|
|
104
|
+
style: { fill: { color: '#E3F2FD' } },
|
|
105
|
+
},
|
|
106
|
+
// Red row if amount is 0
|
|
107
|
+
{
|
|
108
|
+
condition: {
|
|
109
|
+
type: 'columnValue',
|
|
110
|
+
column: 'amount',
|
|
111
|
+
operator: 'equal',
|
|
112
|
+
value: 0,
|
|
113
|
+
},
|
|
114
|
+
style: {
|
|
115
|
+
fill: { color: '#FFCDD2' },
|
|
116
|
+
font: { color: '#C62828', bold: true },
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
// Green row if amount is positive
|
|
120
|
+
{
|
|
121
|
+
condition: {
|
|
122
|
+
type: 'columnValue',
|
|
123
|
+
column: 'amount',
|
|
124
|
+
operator: 'greaterThan',
|
|
125
|
+
value: 0,
|
|
126
|
+
},
|
|
127
|
+
style: StylePresets.positiveHighlight,
|
|
128
|
+
},
|
|
129
|
+
// Custom expression-based styling
|
|
130
|
+
{
|
|
131
|
+
condition: {
|
|
132
|
+
type: 'expression',
|
|
133
|
+
expression: (row) => row.status === 'Deficit',
|
|
134
|
+
},
|
|
135
|
+
style: StylePresets.negativeHighlight,
|
|
136
|
+
},
|
|
137
|
+
],
|
|
138
|
+
})
|
|
139
|
+
.toFile('styled-report.xlsx');
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Row Style Conditions
|
|
143
|
+
|
|
144
|
+
| Condition Type | Description | Example |
|
|
145
|
+
|---------------|-------------|---------|
|
|
146
|
+
| `even` | Style even-numbered rows | `{ type: 'even' }` |
|
|
147
|
+
| `odd` | Style odd-numbered rows | `{ type: 'odd' }` |
|
|
148
|
+
| `columnValue` | Based on column value | `{ type: 'columnValue', column: 'amount', operator: 'equal', value: 0 }` |
|
|
149
|
+
| `expression` | Custom JavaScript logic | `{ type: 'expression', expression: (row) => row.amount < 0 }` |
|
|
150
|
+
|
|
151
|
+
### Cell Styles
|
|
152
|
+
|
|
153
|
+
Style specific cells, columns, or ranges:
|
|
154
|
+
|
|
155
|
+
```typescript
|
|
156
|
+
await convertit.from(data).toExcel({
|
|
157
|
+
cellStyles: [
|
|
158
|
+
// Style entire column
|
|
159
|
+
{
|
|
160
|
+
target: 'D', // Column D (amount)
|
|
161
|
+
style: {
|
|
162
|
+
numFmt: '$#,##0.00',
|
|
163
|
+
alignment: { horizontal: 'right' },
|
|
164
|
+
},
|
|
165
|
+
},
|
|
166
|
+
// Style header row
|
|
167
|
+
{
|
|
168
|
+
target: 'A1:F1',
|
|
169
|
+
style: {
|
|
170
|
+
font: { bold: true, color: '#FFFFFF' },
|
|
171
|
+
fill: { color: '#1976D2' },
|
|
172
|
+
},
|
|
173
|
+
},
|
|
174
|
+
// Style specific cell
|
|
175
|
+
{
|
|
176
|
+
target: 'A10',
|
|
177
|
+
style: {
|
|
178
|
+
font: { bold: true, size: 14 },
|
|
179
|
+
border: { bottom: { style: 'thick' } },
|
|
180
|
+
},
|
|
181
|
+
},
|
|
182
|
+
],
|
|
183
|
+
}).toFile('styled-cells.xlsx');
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Style Presets
|
|
187
|
+
|
|
188
|
+
Use built-in presets for common styling scenarios:
|
|
189
|
+
|
|
190
|
+
```typescript
|
|
191
|
+
import { StylePresets } from 'convertit';
|
|
192
|
+
|
|
193
|
+
// Available presets:
|
|
194
|
+
StylePresets.positiveHighlight // Green background
|
|
195
|
+
StylePresets.negativeHighlight // Red background
|
|
196
|
+
StylePresets.warningHighlight // Yellow/amber background
|
|
197
|
+
StylePresets.headerStyle // Bold white text on blue
|
|
198
|
+
StylePresets.totalRow // Bold with top border
|
|
199
|
+
StylePresets.currencyFormat // Currency number format
|
|
200
|
+
StylePresets.percentFormat // Percentage format
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Native Excel Conditional Formatting
|
|
204
|
+
|
|
205
|
+
Apply Excel's built-in conditional formatting rules:
|
|
206
|
+
|
|
207
|
+
```typescript
|
|
208
|
+
await convertit.from(data).toExcel({
|
|
209
|
+
conditionalFormatting: [
|
|
210
|
+
// Data bars
|
|
211
|
+
{
|
|
212
|
+
type: 'dataBar',
|
|
213
|
+
ref: 'D2:D100',
|
|
214
|
+
rules: { color: '4CAF50' },
|
|
215
|
+
},
|
|
216
|
+
// Color scale (heat map)
|
|
217
|
+
{
|
|
218
|
+
type: 'colorScale',
|
|
219
|
+
ref: 'E2:E100',
|
|
220
|
+
rules: { color: 'F44336' },
|
|
221
|
+
},
|
|
222
|
+
// Icon sets
|
|
223
|
+
{
|
|
224
|
+
type: 'iconSet',
|
|
225
|
+
ref: 'F2:F100',
|
|
226
|
+
rules: { iconSet: '3TrafficLights' },
|
|
227
|
+
},
|
|
228
|
+
],
|
|
229
|
+
}).toFile('conditional-formatting.xlsx');
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Supported Conversions
|
|
233
|
+
|
|
234
|
+
### Documents
|
|
235
|
+
- **PDF**: Create PDFs from text, JSON, arrays, or other data
|
|
236
|
+
- **Word (DOCX)**: Generate Word documents with formatting
|
|
237
|
+
- **HTML**: Convert to HTML with templates and styling
|
|
238
|
+
- **Markdown**: Generate Markdown from various sources
|
|
239
|
+
- **Plain Text**: Extract or convert to plain text
|
|
240
|
+
|
|
241
|
+
### Spreadsheets
|
|
242
|
+
- **Excel (XLSX)**: Create spreadsheets with multiple sheets, formulas, conditional formatting, and styling
|
|
243
|
+
- **CSV**: Generate CSV with custom delimiters
|
|
244
|
+
|
|
245
|
+
### Data Formats
|
|
246
|
+
- **JSON**: Convert to/from JSON
|
|
247
|
+
- **XML**: Generate XML from data
|
|
248
|
+
|
|
249
|
+
### Images
|
|
250
|
+
- **PNG, JPG, JPEG, WebP, GIF, BMP, TIFF**: Convert between image formats
|
|
251
|
+
- **Resize, crop, rotate, and apply filters**
|
|
252
|
+
|
|
253
|
+
## API Reference
|
|
254
|
+
|
|
255
|
+
### Convertit Class
|
|
256
|
+
|
|
257
|
+
```typescript
|
|
258
|
+
// Static Methods (Recommended)
|
|
259
|
+
convertit.from(data): ConvertitBuilder
|
|
260
|
+
convertit.batch(items, concurrency): Promise<BatchConversionResult>
|
|
261
|
+
convertit.merge(files, format): Promise<Buffer>
|
|
262
|
+
convertit.split(data, format, config): Promise<Buffer[]>
|
|
263
|
+
|
|
264
|
+
// Instance Methods
|
|
265
|
+
convert(): Promise<ConversionResult>
|
|
266
|
+
toBuffer(): Promise<Buffer>
|
|
267
|
+
toBase64(): Promise<string>
|
|
268
|
+
toFile(path: string): Promise<string>
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
### Builder Methods
|
|
272
|
+
|
|
273
|
+
```typescript
|
|
274
|
+
// Format converters
|
|
275
|
+
.toPdf(options?: PDFOptions)
|
|
276
|
+
.toWord(options?: WordOptions)
|
|
277
|
+
.toExcel(options?: ExcelOptions)
|
|
278
|
+
.toCsv(options?: CSVOptions)
|
|
279
|
+
.toHtml(options?: HTMLOptions)
|
|
280
|
+
.toImage(format?, options?: ImageOptions)
|
|
281
|
+
.toJson()
|
|
282
|
+
.toText()
|
|
283
|
+
.toMarkdown()
|
|
284
|
+
.toXml()
|
|
285
|
+
|
|
286
|
+
// Transformers
|
|
287
|
+
.withWatermark(config: WatermarkConfig)
|
|
288
|
+
.withEncryption(config: EncryptionConfig)
|
|
289
|
+
.withCompression(config: CompressionConfig)
|
|
290
|
+
.withPageNumbers(config: PageNumberConfig)
|
|
291
|
+
|
|
292
|
+
// Layout
|
|
293
|
+
.landscape()
|
|
294
|
+
.pageSize(size: 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal')
|
|
295
|
+
|
|
296
|
+
// Output
|
|
297
|
+
.toBuffer(): Promise<Buffer>
|
|
298
|
+
.toBase64(): Promise<string>
|
|
299
|
+
.toFile(path: string): Promise<string>
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
## Examples
|
|
303
|
+
|
|
304
|
+
### Convert JSON Array to Excel with Styling
|
|
305
|
+
|
|
306
|
+
```typescript
|
|
307
|
+
const data = [
|
|
308
|
+
{ name: 'Suraj', email: 'surajlohit42@example.com', salary: 85000 },
|
|
309
|
+
{ name: 'Sathya', email: 'sathya@example.com', salary: 95000 },
|
|
310
|
+
{ name: 'Karthik', email: 'karthik@example.com', salary: 79000 },
|
|
311
|
+
{ name: 'Charan', email: 'charan@example.com', salary: 91000 },
|
|
312
|
+
{ name: 'Sid', email: 'sid@example.com', salary: 75000 },
|
|
313
|
+
{ name: 'pruthvi', email: 'pruthvi@example.com', salary: 95000 },
|
|
314
|
+
];
|
|
315
|
+
|
|
316
|
+
const buffer = await convertit.from(data)
|
|
317
|
+
.toExcel({
|
|
318
|
+
sheetName: 'Employees',
|
|
319
|
+
autoFilter: true,
|
|
320
|
+
freezePane: { row: 1 },
|
|
321
|
+
autoWidth: true,
|
|
322
|
+
rowStyles: [
|
|
323
|
+
{ condition: { type: 'even' }, style: { fill: { color: '#F5F5F5' } } },
|
|
324
|
+
],
|
|
325
|
+
cellStyles: [
|
|
326
|
+
{
|
|
327
|
+
target: 'C', // Salary column
|
|
328
|
+
style: { numFmt: '$#,##0.00' },
|
|
329
|
+
},
|
|
330
|
+
],
|
|
331
|
+
})
|
|
332
|
+
.toBuffer();
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
### Create PDF with Headers and Footers
|
|
336
|
+
|
|
337
|
+
```typescript
|
|
338
|
+
const buffer = await convertit.from(content)
|
|
339
|
+
.toPdf({
|
|
340
|
+
pageSize: 'A4',
|
|
341
|
+
margins: { top: 72, bottom: 72, left: 72, right: 72 },
|
|
342
|
+
header: {
|
|
343
|
+
enabled: true,
|
|
344
|
+
content: 'Company Report',
|
|
345
|
+
alignment: 'center',
|
|
346
|
+
},
|
|
347
|
+
footer: {
|
|
348
|
+
enabled: true,
|
|
349
|
+
includePageNumber: true,
|
|
350
|
+
},
|
|
351
|
+
})
|
|
352
|
+
.toBuffer();
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
### Add Watermark to PDF
|
|
356
|
+
|
|
357
|
+
```typescript
|
|
358
|
+
const watermarkedPdf = await convertit.from(pdfBuffer)
|
|
359
|
+
.toPdf()
|
|
360
|
+
.withWatermark({
|
|
361
|
+
text: 'CONFIDENTIAL',
|
|
362
|
+
opacity: 0.3,
|
|
363
|
+
rotation: -45,
|
|
364
|
+
font: { size: 50, color: '#FF0000' },
|
|
365
|
+
})
|
|
366
|
+
.toBuffer();
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
### Batch Convert Multiple Files
|
|
370
|
+
|
|
371
|
+
```typescript
|
|
372
|
+
const items = [
|
|
373
|
+
{ data: data1, options: { type: 'pdf' } },
|
|
374
|
+
{ data: data2, options: { type: 'xlsx' } },
|
|
375
|
+
{ data: data3, options: { type: 'docx' } },
|
|
376
|
+
];
|
|
377
|
+
|
|
378
|
+
const result = await convertit.batch(items, 3);
|
|
379
|
+
console.log(`Converted ${result.successCount}/${result.totalFiles} files`);
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
## Direct Converter Usage
|
|
383
|
+
|
|
384
|
+
For advanced use cases, use converters directly:
|
|
385
|
+
|
|
386
|
+
```typescript
|
|
387
|
+
import {
|
|
388
|
+
PDFManipulator,
|
|
389
|
+
ExcelUtils,
|
|
390
|
+
ExcelStyleEngine,
|
|
391
|
+
ImageUtils
|
|
392
|
+
} from 'convertit';
|
|
393
|
+
|
|
394
|
+
// PDF manipulation
|
|
395
|
+
const pageCount = await PDFManipulator.getPageCount(pdfBuffer);
|
|
396
|
+
const rotated = await PDFManipulator.rotatePages(pdfBuffer, 90);
|
|
397
|
+
|
|
398
|
+
// Excel utilities
|
|
399
|
+
const data = await ExcelUtils.readAsJson(excelBuffer);
|
|
400
|
+
const sheetNames = await ExcelUtils.getSheetNames(excelBuffer);
|
|
401
|
+
|
|
402
|
+
// Image utilities
|
|
403
|
+
const metadata = await ImageUtils.getMetadata(imageBuffer);
|
|
404
|
+
const thumbnail = await ImageUtils.createThumbnail(imageBuffer, 150, 150);
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
## Template Engine
|
|
408
|
+
|
|
409
|
+
Built-in template engine for document generation:
|
|
410
|
+
|
|
411
|
+
```typescript
|
|
412
|
+
import { TemplateEngine } from 'convertit';
|
|
413
|
+
|
|
414
|
+
const engine = new TemplateEngine();
|
|
415
|
+
|
|
416
|
+
const template = `
|
|
417
|
+
Hello {{name}}!
|
|
418
|
+
|
|
419
|
+
{{#if premium}}
|
|
420
|
+
Thank you for being a premium member!
|
|
421
|
+
{{else}}
|
|
422
|
+
Consider upgrading to premium.
|
|
423
|
+
{{/if}}
|
|
424
|
+
|
|
425
|
+
Your orders:
|
|
426
|
+
{{#each orders}}
|
|
427
|
+
- {{description}}: {{formatCurrency total}}
|
|
428
|
+
{{/each}}
|
|
429
|
+
|
|
430
|
+
Total: {{formatCurrency grandTotal}}
|
|
431
|
+
`;
|
|
432
|
+
|
|
433
|
+
const html = engine.render(template, {
|
|
434
|
+
name: 'Suraj',
|
|
435
|
+
premium: true,
|
|
436
|
+
orders: [
|
|
437
|
+
{ description: 'Widget', total: 29.99 },
|
|
438
|
+
{ description: 'Gadget', total: 49.99 },
|
|
439
|
+
],
|
|
440
|
+
grandTotal: 79.98,
|
|
441
|
+
});
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
## Error Handling
|
|
445
|
+
|
|
446
|
+
```typescript
|
|
447
|
+
import { isConvertFileError, ErrorCode } from 'convertit';
|
|
448
|
+
|
|
449
|
+
try {
|
|
450
|
+
const result = await convertit.from(data).toPdf().toBuffer();
|
|
451
|
+
} catch (error) {
|
|
452
|
+
if (isConvertFileError(error)) {
|
|
453
|
+
console.error(`Error [${error.code}]: ${error.message}`);
|
|
454
|
+
if (error.recoverable) {
|
|
455
|
+
// Implement retry logic
|
|
456
|
+
}
|
|
457
|
+
}
|
|
458
|
+
}
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
## TypeScript Support
|
|
462
|
+
|
|
463
|
+
Full TypeScript support with comprehensive type definitions:
|
|
464
|
+
|
|
465
|
+
```typescript
|
|
466
|
+
import type {
|
|
467
|
+
FileFormat,
|
|
468
|
+
ConvertFileOptions,
|
|
469
|
+
ExcelOptions,
|
|
470
|
+
RowStyleRule,
|
|
471
|
+
CellStyleRule,
|
|
472
|
+
CellStyle,
|
|
473
|
+
} from 'convertit';
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
## Development
|
|
477
|
+
|
|
478
|
+
```bash
|
|
479
|
+
# Install dependencies
|
|
480
|
+
bun install
|
|
481
|
+
|
|
482
|
+
# Run tests
|
|
483
|
+
bun test
|
|
484
|
+
|
|
485
|
+
# Build
|
|
486
|
+
bun run build
|
|
487
|
+
|
|
488
|
+
# Lint
|
|
489
|
+
bun run lint
|
|
490
|
+
|
|
491
|
+
# Type check
|
|
492
|
+
bun run typecheck
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
## Contributing
|
|
496
|
+
|
|
497
|
+
Contributions are welcome! This project uses:
|
|
498
|
+
- ESLint for linting
|
|
499
|
+
- Husky for git hooks
|
|
500
|
+
- lint-staged for pre-commit checks
|
|
501
|
+
- GitHub Actions for CI/CD
|
|
502
|
+
|
|
503
|
+
Please ensure your PR passes all checks before submitting.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Base converter class and converter registry.
|
|
3
|
+
*/
|
|
4
|
+
import type { InputDataType, ConvertFileOptions, ConversionResult, FileFormat, ProgressInfo } from '../core/types';
|
|
5
|
+
export declare abstract class BaseConverter {
|
|
6
|
+
protected readonly format: FileFormat;
|
|
7
|
+
constructor(format: FileFormat);
|
|
8
|
+
abstract convert(data: InputDataType, options: ConvertFileOptions): Promise<Buffer>;
|
|
9
|
+
abstract getSupportedInputFormats(): FileFormat[];
|
|
10
|
+
canConvert(inputFormat?: FileFormat): boolean;
|
|
11
|
+
execute(data: InputDataType, options: ConvertFileOptions): Promise<ConversionResult>;
|
|
12
|
+
protected emitProgress(options: ConvertFileOptions, progress: ProgressInfo): void;
|
|
13
|
+
getDefaultOptions(): Partial<ConvertFileOptions>;
|
|
14
|
+
}
|
|
15
|
+
export declare class ConverterRegistry {
|
|
16
|
+
private static instance;
|
|
17
|
+
private converters;
|
|
18
|
+
private constructor();
|
|
19
|
+
static getInstance(): ConverterRegistry;
|
|
20
|
+
register(format: FileFormat, converter: BaseConverter): void;
|
|
21
|
+
get(format: FileFormat): BaseConverter | undefined;
|
|
22
|
+
has(format: FileFormat): boolean;
|
|
23
|
+
getFormats(): FileFormat[];
|
|
24
|
+
unregister(format: FileFormat): boolean;
|
|
25
|
+
clear(): void;
|
|
26
|
+
}
|
|
27
|
+
//# sourceMappingURL=base.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/converters/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,YAAY,EACb,MAAM,eAAe,CAAC;AAIvB,8BAAsB,aAAa;IACjC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;gBAE1B,MAAM,EAAE,UAAU;IAI9B,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAEnF,QAAQ,CAAC,wBAAwB,IAAI,UAAU,EAAE;IAEjD,UAAU,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO;IAKvC,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+D1F,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI;IAIjF,iBAAiB,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAKjD;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAoB;IAC3C,OAAO,CAAC,UAAU,CAA6C;IAE/D,OAAO;IAEP,MAAM,CAAC,WAAW,IAAI,iBAAiB;IAOvC,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,GAAG,IAAI;IAI5D,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS;IAIlD,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO;IAIhC,UAAU,IAAI,UAAU,EAAE;IAI1B,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO;IAIvC,KAAK,IAAI,IAAI;CAGd"}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* CSV converter for arrays, objects, and tabular data.
|
|
3
|
+
*/
|
|
4
|
+
import { BaseConverter } from './base';
|
|
5
|
+
import type { InputDataType, ConvertFileOptions, FileFormat } from '../core/types';
|
|
6
|
+
export declare class CSVConverter extends BaseConverter {
|
|
7
|
+
constructor();
|
|
8
|
+
getSupportedInputFormats(): FileFormat[];
|
|
9
|
+
convert(data: InputDataType, options: ConvertFileOptions): Promise<Buffer>;
|
|
10
|
+
private createFromArray;
|
|
11
|
+
private createFromObject;
|
|
12
|
+
private createFromString;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* CSV Utilities
|
|
16
|
+
*/
|
|
17
|
+
export declare class CSVUtils {
|
|
18
|
+
/**
|
|
19
|
+
* Parse CSV string to array of objects
|
|
20
|
+
*/
|
|
21
|
+
static parse(content: string | Buffer, options?: {
|
|
22
|
+
delimiter?: string;
|
|
23
|
+
headers?: boolean | string[];
|
|
24
|
+
skipEmptyLines?: boolean;
|
|
25
|
+
trim?: boolean;
|
|
26
|
+
}): Record<string, any>[];
|
|
27
|
+
/**
|
|
28
|
+
* Parse CSV to array of arrays
|
|
29
|
+
*/
|
|
30
|
+
static parseToArrays(content: string | Buffer, options?: {
|
|
31
|
+
delimiter?: string;
|
|
32
|
+
skipEmptyLines?: boolean;
|
|
33
|
+
trim?: boolean;
|
|
34
|
+
}): any[][];
|
|
35
|
+
/**
|
|
36
|
+
* Get column headers from CSV
|
|
37
|
+
*/
|
|
38
|
+
static getHeaders(content: string | Buffer, delimiter?: string): string[];
|
|
39
|
+
/**
|
|
40
|
+
* Convert CSV to JSON
|
|
41
|
+
*/
|
|
42
|
+
static toJson(content: string | Buffer, options?: {
|
|
43
|
+
delimiter?: string;
|
|
44
|
+
headers?: string[];
|
|
45
|
+
}): Record<string, any>[];
|
|
46
|
+
/**
|
|
47
|
+
* Merge multiple CSV contents
|
|
48
|
+
*/
|
|
49
|
+
static merge(csvContents: (string | Buffer)[], options?: {
|
|
50
|
+
delimiter?: string;
|
|
51
|
+
includeHeaders?: boolean;
|
|
52
|
+
}): string;
|
|
53
|
+
/**
|
|
54
|
+
* Filter CSV by column value
|
|
55
|
+
*/
|
|
56
|
+
static filter(content: string | Buffer, column: string, predicate: (value: any) => boolean, options?: {
|
|
57
|
+
delimiter?: string;
|
|
58
|
+
}): Record<string, any>[];
|
|
59
|
+
/**
|
|
60
|
+
* Sort CSV by column
|
|
61
|
+
*/
|
|
62
|
+
static sort(content: string | Buffer, column: string, order?: 'asc' | 'desc', options?: {
|
|
63
|
+
delimiter?: string;
|
|
64
|
+
}): Record<string, any>[];
|
|
65
|
+
}
|
|
66
|
+
export default CSVConverter;
|
|
67
|
+
//# sourceMappingURL=csv.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/converters/csv.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAc,MAAM,eAAe,CAAC;AAG/F,qBAAa,YAAa,SAAQ,aAAa;;IAK7C,wBAAwB,IAAI,UAAU,EAAE;IAIlC,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;YAwBlE,eAAe;YA6Df,gBAAgB;YA2BhB,gBAAgB;CAyD/B;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB;;OAEG;IACH,MAAM,CAAC,KAAK,CACV,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;QAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,GACA,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;IAexB;;OAEG;IACH,MAAM,CAAC,aAAa,CAClB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,GACA,GAAG,EAAE,EAAE;IAaV;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,MAAM,EAAE;IAM9E;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,GACA,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;IAOxB;;OAEG;IACH,MAAM,CAAC,KAAK,CACV,WAAW,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EAChC,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,GACA,MAAM;IA6BT;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,EAClC,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;IAKxB;;OAEG;IACH,MAAM,CAAC,IAAI,CACT,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,KAAK,GAAG,MAAc,EAC7B,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;CAYzB;AAED,eAAe,YAAY,CAAC"}
|