dynamic-docx-generator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dynamic-docx-generator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,315 @@
+# dynamic-docx-generator
+
+Generate dynamic DOCX documents from templates with placeholder replacement, tables, and images.
+
+[![npm version](https://badge.fury.io/js/dynamic-docx-generator.svg)](https://www.npmjs.com/package/dynamic-docx-generator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 📝 **Template-based generation** - Use existing DOCX files as templates
+- 🔄 **Placeholder replacement** - Replace `{{placeholder}}` tags with dynamic data
+- 📊 **Dynamic tables** - Generate tables from data arrays
+- 🖼️ **Image insertion** - Embed images from files, URLs, or buffers
+- 📄 **Header/Footer support** - Customize document headers and footers
+- ⚡ **Fluent API** - Chain methods for clean, readable code
+- 📦 **Zero system dependencies** - No external tools like LibreOffice needed
+- 🔧 **TypeScript support** - Full type definitions included
+
+## Installation
+
+```bash
+npm install dynamic-docx-generator
+```
+
+## Quick Start
+
+```javascript
+const { DocxGenerator } = require('dynamic-docx-generator');
+
+async function generateDocument() {
+  const generator = new DocxGenerator();
+  
+  // Load a DOCX template
+  await generator.loadTemplate('./template.docx');
+  
+  // Replace placeholders
+  generator.setData({
+    companyName: 'Acme Corporation',
+    productName: 'Widget Pro',
+    date: '2026-01-09'
+  });
+  
+  // Save the generated document
+  await generator.save('./output.docx');
+  
+  console.log('Document generated successfully!');
+}
+
+generateDocument();
+```
+
+## API Reference
+
+### DocxGenerator
+
+The main class for document generation.
+
+#### Constructor
+
+```typescript
+const generator = new DocxGenerator(options?: GeneratorOptions);
+```
+
+**Options:**
+- `tempDir?: string` - Custom temporary directory for processing
+
+#### Methods
+
+##### loadTemplate(source)
+
+Load a DOCX template from a file path or buffer.
+
+```typescript
+await generator.loadTemplate('./template.docx');
+// or
+await generator.loadTemplate(buffer);
+```
+
+##### setData(data)
+
+Set placeholder values for the document body.
+
+```typescript
+generator.setData({
+  name: 'John Doe',
+  company: 'Acme Corp',
+  date: new Date().toLocaleDateString()
+});
+```
+
+##### setHeader(data)
+
+Set placeholder values for document headers.
+
+```typescript
+generator.setHeader({
+  documentTitle: 'Annual Report',
+  version: '1.0'
+});
+```
+
+##### setFooter(data)
+
+Set placeholder values for document footers.
+
+```typescript
+generator.setFooter({
+  copyright: '© 2026 Acme Corp'
+});
+```
+
+##### setImages(images)
+
+Add images to be inserted into the document.
+
+```typescript
+generator.setImages([
+  {
+    placeholder: 'logo',
+    path: './logo.png',
+    width: 914400  // In EMUs (914400 EMUs = 1 inch)
+  },
+  {
+    placeholder: 'signature',
+    url: 'https://example.com/signature.png',
+    width: 457200,
+    height: 228600
+  }
+]);
+```
+
+##### addTable(config)
+
+Add a dynamic table to the document.
+
+```typescript
+generator.addTable({
+  placeholder: 'itemsTable',
+  headers: [
+    { name: 'Item', key: 'item', width: 3000 },
+    { name: 'Quantity', key: 'qty', width: 1500 },
+    { name: 'Price', key: 'price', width: 1500 }
+  ],
+  rows: [
+    ['Widget A', '10', '$99.00'],
+    ['Widget B', '5', '$149.00'],
+    ['Widget C', '3', '$199.00']
+  ],
+  style: {
+    headerBgColor: 'C9DAF8',
+    fontSize: 24
+  }
+});
+```
+
+##### generate()
+
+Generate the document and return as a Buffer.
+
+```typescript
+const buffer = await generator.generate();
+```
+
+##### save(outputPath)
+
+Generate and save the document to a file.
+
+```typescript
+await generator.save('./output.docx');
+```
+
+##### reset()
+
+Reset generator state while keeping the template loaded.
+
+```typescript
+generator.reset();
+```
+
+## Template Format
+
+Create your template in Microsoft Word or any DOCX-compatible editor:
+
+1. Add placeholders using `{{placeholderName}}` syntax
+2. For tables, add a placeholder like `{{itemsTable}}`
+3. For images, add a placeholder like `{{logo}}`
+
+**Example template content:**
+
+```
+Document Title: {{documentTitle}}
+Company: {{companyName}}
+Date: {{date}}
+
+{{itemsTable}}
+
+Signature: {{signature}}
+```
+
+## Image Units (EMUs)
+
+DOCX uses English Metric Units (EMUs) for dimensions:
+- **914400 EMUs = 1 inch**
+- **360000 EMUs = 1 cm**
+- **9525 EMUs = 1 pixel (at 96 DPI)**
+
+Helper functions are available:
+
+```typescript
+const { ImageUtils } = require('dynamic-docx-generator');
+
+// Convert to EMUs
+const widthInEmu = ImageUtils.pixelsToEmu(200);  // 200px -> EMUs
+const heightInEmu = ImageUtils.inchesToEmu(2);   // 2 inches -> EMUs
+const sizeInEmu = ImageUtils.cmToEmu(5);         // 5cm -> EMUs
+```
+
+## Complete Example
+
+```javascript
+const { DocxGenerator, ImageUtils } = require('dynamic-docx-generator');
+const path = require('path');
+
+async function createInvoice() {
+  const generator = new DocxGenerator();
+  
+  await generator.loadTemplate('./invoice-template.docx');
+  
+  // Company details
+  generator.setData({
+    invoiceNumber: 'INV-2026-001',
+    date: '2026-01-09',
+    customerName: 'John Doe',
+    customerAddress: '123 Main Street, City',
+    total: '$447.00',
+    tax: '$44.70',
+    grandTotal: '$491.70'
+  });
+  
+  // Header
+  generator.setHeader({
+    companyName: 'Acme Corp'
+  });
+  
+  // Company logo
+  generator.setImages([
+    {
+      placeholder: 'companyLogo',
+      path: './assets/logo.png',
+      width: ImageUtils.inchesToEmu(1.5)
+    }
+  ]);
+  
+  // Line items table
+  generator.addTable({
+    placeholder: 'lineItems',
+    headers: [
+      { name: 'Description', key: 'desc', width: 4000 },
+      { name: 'Qty', key: 'qty', width: 1000 },
+      { name: 'Unit Price', key: 'price', width: 1500 },
+      { name: 'Total', key: 'total', width: 1500 }
+    ],
+    rows: [
+      ['Widget Pro', '2', '$99.00', '$198.00'],
+      ['Widget Plus', '1', '$149.00', '$149.00'],
+      ['Premium Support', '1', '$100.00', '$100.00']
+    ]
+  });
+  
+  await generator.save('./generated-invoice.docx');
+  console.log('Invoice generated!');
+}
+
+createInvoice();
+```
+
+## TypeScript Usage
+
+```typescript
+import { DocxGenerator, ImageConfig, TableConfig } from 'dynamic-docx-generator';
+
+async function generateReport(): Promise<void> {
+  const generator = new DocxGenerator();
+  
+  await generator.loadTemplate('./template.docx');
+  
+  const images: ImageConfig[] = [
+    { placeholder: 'chart', path: './chart.png', width: 914400 }
+  ];
+  
+  const table: TableConfig = {
+    placeholder: 'dataTable',
+    headers: [
+      { name: 'Name', key: 'name', width: 3000 },
+      { name: 'Value', key: 'value', width: 2000 }
+    ],
+    rows: [['Item 1', '100'], ['Item 2', '200']]
+  };
+  
+  generator
+    .setData({ title: 'Monthly Report' })
+    .setImages(images)
+    .addTable(table);
+  
+  await generator.save('./report.docx');
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © 2026

package/dist/DocxGenerator.d.ts

@@ -0,0 +1,135 @@
+/**
+ * DocxGenerator - Main class for dynamic DOCX document generation
+ *
+ * @example
+ * ```typescript
+ * const generator = new DocxGenerator();
+ * await generator.loadTemplate('./template.docx');
+ * generator.setData({ name: 'John', company: 'Acme' });
+ * await generator.save('./output.docx');
+ * ```
+ */
+import { GeneratorOptions, PlaceholderData, ImageConfig, TableConfig } from './types';
+export declare class DocxGenerator {
+    private options;
+    private zip;
+    private templateLoaded;
+    private data;
+    private headerData;
+    private footerData;
+    private images;
+    private tables;
+    private tempDir;
+    /**
+     * Create a new DocxGenerator instance
+     * @param options - Configuration options
+     */
+    constructor(options?: GeneratorOptions);
+    /**
+     * Load a DOCX template from file path or buffer
+     * @param source - Path to template file or Buffer containing template
+     * @returns this for method chaining
+     */
+    loadTemplate(source: string | Buffer): Promise<this>;
+    /**
+     * Set placeholder data for document body
+     * @param data - Key-value pairs where key is placeholder name and value is replacement text
+     * @returns this for method chaining
+     *
+     * @example
+     * ```typescript
+     * generator.setData({
+     *   companyName: 'Acme Corp',
+     *   productName: 'Widget Pro',
+     *   date: '2026-01-09'
+     * });
+     * ```
+     */
+    setData(data: PlaceholderData): this;
+    /**
+     * Set placeholder data for document header
+     * @param data - Key-value pairs for header placeholders
+     * @returns this for method chaining
+     */
+    setHeader(data: PlaceholderData): this;
+    /**
+     * Set placeholder data for document footer
+     * @param data - Key-value pairs for footer placeholders
+     * @returns this for method chaining
+     */
+    setFooter(data: PlaceholderData): this;
+    /**
+     * Add images to be inserted into the document
+     * @param images - Array of image configurations
+     * @returns this for method chaining
+     *
+     * @example
+     * ```typescript
+     * generator.setImages([
+     *   { placeholder: '{{logo}}', path: './logo.png', width: 200 }
+     * ]);
+     * ```
+     */
+    setImages(images: ImageConfig[]): this;
+    /**
+     * Add a dynamic table to the document
+     * @param config - Table configuration
+     * @returns this for method chaining
+     *
+     * @example
+     * ```typescript
+     * generator.addTable({
+     *   placeholder: '{{itemsTable}}',
+     *   headers: [
+     *     { name: 'Item', key: 'item', width: 3000 },
+     *     { name: 'Quantity', key: 'qty', width: 1500 }
+     *   ],
+     *   rows: [['Widget A', '10'], ['Widget B', '5']]
+     * });
+     * ```
+     */
+    addTable(config: TableConfig): this;
+    /**
+     * Process placeholders in XML content
+     */
+    private processPlaceholders;
+    /**
+     * Process tables in XML content
+     */
+    private processTables;
+    /**
+     * Process images and add them to the document
+     */
+    private processImages;
+    /**
+     * Update document relationships with images
+     */
+    private updateRelationships;
+    /**
+     * Add image files to the media folder
+     */
+    private addImageFiles;
+    /**
+     * Replace image placeholders in document content
+     */
+    private replaceImagePlaceholders;
+    /**
+     * Generate the final DOCX document as a Buffer
+     * @returns Buffer containing the generated DOCX file
+     */
+    generate(): Promise<Buffer>;
+    /**
+     * Save the generated document to a file
+     * @param outputPath - Path where the document should be saved
+     */
+    save(outputPath: string): Promise<void>;
+    /**
+     * Reset the generator state (keeps template loaded)
+     */
+    reset(): this;
+    /**
+     * Check if a template has been loaded
+     */
+    isTemplateLoaded(): boolean;
+}
+//# sourceMappingURL=DocxGenerator.d.ts.map

package/dist/DocxGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocxGenerator.d.ts","sourceRoot":"","sources":["../src/DocxGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,EACH,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,WAAW,EAEd,MAAM,SAAS,CAAC;AAOjB,qBAAa,aAAa;IACtB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAS;IAExB;;;OAGG;gBACS,OAAO,GAAE,gBAAqB;IAK1C;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB1D;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAKpC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAKtC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAKtC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI;IAKtC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAKnC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;OAEG;IACH,OAAO,CAAC,aAAa;IAwBrB;;OAEG;YACW,aAAa;IAuB3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAqC3B;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAYhC;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IA+DjC;;;OAGG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7C;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACH,gBAAgB,IAAI,OAAO;CAG9B"}