@zola_do/docx 0.2.5 → 0.2.7

package/README.md

@@ -1,7 +1,20 @@
 # @zola_do/docx
 
+[![npm version](https://img.shields.io/npm/v/@zola_do/docx.svg)](https://www.npmjs.com/package/@zola_do/docx)
+[![npm downloads](https://img.shields.io/npm/dm/@zola_do/docx.svg)](https://www.npmjs.com/package/@zola_do/docx)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
 DOCX template processing for NestJS using docx-templates.
 
+## Overview
+
+`@zola_do/docx` provides:
+
+- **Template Population** — Fill DOCX templates with data
+- **Placeholder Validation** — Check for required placeholders
+- **Handlebars Syntax** — Supports loops, conditionals, images
+- **Buffer Output** — Returns generated DOCX as Buffer
+
 ## Installation
 
 ```bash
@@ -12,13 +25,43 @@ npm install @zola_do/docx
 npm install @zola_do/nestjs-shared
 ```
 
-## Usage
+### Dependencies
+
+```bash
+npm install docx-templates
+```
+
+## Quick Start
 
-### Module Setup
+### 1. Create a Template
+
+Create a Word document with placeholders:
+
+```docx
+Dear {{name}},
+
+Thank you for your order #{{orderNumber}}.
+
+Order Details:
+{{#each items}}
+  - {{this.name}}: ${{this.price}}
+{{/each}}
+
+Total: ${{total}}
+
+{{#if isPremium}}
+  As a premium member, you get 10% off your next order!
+{{/if}}
+
+Best regards,
+{{companyName}}
+```
+
+### 2. Register Module
 
 ```typescript
-import { Module } from '@nestjs/common';
-import { DocxModule } from '@zola_do/docx';
+import { Module } from "@nestjs/common";
+import { DocxModule } from "@zola_do/docx";
 
 @Module({
   imports: [DocxModule],
@@ -26,54 +69,372 @@ import { DocxModule } from '@zola_do/docx';
 export class AppModule {}
 ```
 
-### Generating Documents
-
-Fill a DOCX template with data. Use `{placeholder}` syntax in your Word document:
+### 3. Generate Document
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { DocxService } from '@zola_do/docx';
+import { Injectable } from "@nestjs/common";
+import { DocxService } from "@zola_do/docx";
 
 @Injectable()
 export class ReportService {
   constructor(private readonly docxService: DocxService) {}
 
-  async generateReport(templateBuffer: Buffer, data: Record<string, any>) {
-    // Template contains {name}, {date}, etc.
-    const result = await this.docxService.generateDocx(templateBuffer, data);
+  async generateInvoice(order: Order) {
+    const templateBuffer = await this.loadTemplate("invoice.docx");
+
+    const result = await this.docxService.generateDocx(templateBuffer, {
+      name: order.customerName,
+      orderNumber: order.number,
+      items: order.items,
+      total: order.total,
+      isPremium: order.customer.isPremium,
+      companyName: "My Company",
+    });
+
     return result; // Buffer of filled DOCX
   }
 }
 ```
 
-### Validating Templates
+## Template Syntax
+
+The package uses [docx-templates](https://github.com/guigrpa/docx-templates) for template rendering.
+
+### Basic Placeholders
+
+```handlebars
+{{variableName}}
+
+{{nested.property}}
+
+{{array.index}}
+```
+
+### Conditionals
+
+```handlebars
+{{#if condition}}
+  Content when true
+{{else}}
+  Content when false
+{{/if}}
+
+{{#unless condition}}
+  Content when false
+{{/unless}}
+```
+
+### Loops
+
+```handlebars
+{{#each items}}
+  {{this.name}}
+  - ${{this.price}}
+{{/each}}
+
+{{#each orders}}
+  Order #{{this.number}}:
+  {{#each this.items}}
+    -
+    {{this.name}}
+  {{/each}}
+{{/each}}
+```
+
+### Nested Data
+
+```handlebars
+{{customer.name}}
+{{customer.address.city}}
+{{customer.address.zip}}
+```
+
+### Helpers
+
+```handlebars
+{{uppercase name}}
+{{lowercase email}}
+{{formatDate date "MMMM YYYY"}}
+{{currency amount}}
+```
+
+### Images
+
+```handlebars
+{{#image filename width height}}
+  logo.png
+{{/image}}
+
+{{#imageUrl url width height}}
+  https://example.com/logo.png
+{{/imageUrl}}
+```
+
+## Advanced Templates
+
+### Table with Rows
+
+```handlebars
+| Product | Quantity | Price | |---------|----------|-------|
+{{#each items}}
+  |
+  {{this.name}}
+  |
+  {{this.quantity}}
+  | ${{this.price}}
+  |
+{{/each}}
+| **Total** | | **${{total}}** |
+```
+
+### Nested Tables
+
+```handlebars
+{{#each orders}}
+  Order #{{this.number}}
+  -
+  {{this.date}}
+
+  | Item | Qty | Price | |------|-----|-------|
+  {{#each this.items}}
+    |
+    {{name}}
+    |
+    {{qty}}
+    | ${{price}}
+    |
+  {{/each}}
+
+  ---
+{{/each}}
+```
+
+### Conditional Sections
+
+```handlebars
+{{#if hasDiscount}}
+  Original Price: ~~${{originalPrice}}~~ Discounted Price: ${{discountedPrice}}
+{{else}}
+  Price: ${{price}}
+{{/if}}
+```
+
+## Validation
+
+### Validate Document
+
+Check that a template contains all required placeholders:
+
+```typescript
+async validateInvoiceTemplate() {
+  const templateBuffer = await this.loadTemplate('invoice.docx');
+
+  const missingProps = await this.docxService.validateDocument(
+    templateBuffer,
+    ['name', 'orderNumber', 'items', 'total', 'companyName'],
+  );
+
+  if (missingProps.length > 0) {
+    throw new Error(`Missing placeholders: ${missingProps.join(', ')}`);
+  }
+}
+```
+
+### Validation Result
+
+```typescript
+interface ValidationResult {
+  missing: string[]; // Placeholders not in template
+  unused: string[]; // Data properties not in template
+}
+```
+
+## Real-World Examples
 
-Ensure a template has all required placeholders before generating:
+### Invoice Generation
 
 ```typescript
-const missingProps = await this.docxService.validateDocument(
-  templateBuffer,
-  ['name', 'date', 'amount'],
-);
-if (missingProps.length > 0) {
-  throw new Error(`Missing placeholders: ${missingProps.join(', ')}`);
+async generateInvoice(orderId: string): Promise<Buffer> {
+  const order = await this.orderService.findOne(orderId);
+  const template = await this.loadTemplate('invoice.docx');
+
+  const data = {
+    invoiceNumber: order.invoiceNumber,
+    date: new Date().toLocaleDateString(),
+    customer: {
+      name: order.customer.name,
+      email: order.customer.email,
+      address: `${order.customer.address}\n${order.customer.city}, ${order.customer.zip}`,
+    },
+    items: order.items.map(item => ({
+      name: item.productName,
+      quantity: item.quantity,
+      price: item.unitPrice.toFixed(2),
+      subtotal: item.subtotal.toFixed(2),
+    })),
+    subtotal: order.subtotal.toFixed(2),
+    tax: order.tax.toFixed(2),
+    total: order.total.toFixed(2),
+    isPaid: order.status === 'PAID',
+    paymentInfo: order.paymentInfo,
+  };
+
+  return this.docxService.generateDocx(template, data);
 }
 ```
 
-## Template Syntax
+### Certificate Generation
+
+```typescript
+async generateCertificate(userId: string, courseId: string): Promise<Buffer> {
+  const [user, course] = await Promise.all([
+    this.userService.findOne(userId),
+    this.courseService.findOne(courseId),
+  ]);
+
+  const template = await this.loadTemplate('certificate.docx');
+
+  return this.docxService.generateDocx(template, {
+    recipientName: user.fullName,
+    courseName: course.name,
+    completionDate: new Date().toLocaleDateString('en-US', {
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+    }),
+    instructorName: course.instructor.name,
+    certificateId: generateCertificateId(),
+    companyName: 'My Organization',
+    logoPath: '/templates/logo.png',
+  });
+}
+```
+
+## Template Preparation
+
+### Creating Templates
+
+1. Open Microsoft Word or LibreOffice
+2. Create a new document
+3. Add placeholders using `{{placeholderName}}` syntax
+4. Save as `.docx` format
+
+### Recommended Placeholder Names
+
+```handlebars
+{{firstName}}
+{{lastName}}
+{{email}}
+{{phone}}
+{{address}}
+{{city}}
+{{orderNumber}}
+{{orderDate}}
+{{totalAmount}}
+{{status}}
+{{companyName}}
+{{logoPath}}
+```
+
+### Testing Templates
+
+```typescript
+const testData = {
+  name: "Test User",
+  orderNumber: "ORD-001",
+  items: [
+    { name: "Product A", price: 10 },
+    { name: "Product B", price: 20 },
+  ],
+  total: 30,
+  isPremium: false,
+  companyName: "Test Company",
+};
+
+const result = await docxService.generateDocx(templateBuffer, testData);
+// Verify result is valid DOCX
+```
 
-Uses [docx-templates](https://github.com/guigrpa/docx-templates) syntax. Placeholders use `{variableName}`. Supports loops, conditionals, and images—see the docx-templates documentation.
+## API Reference
 
-## Exports
+### Module
 
-- `DocxModule` — Register the DOCX module
-- `DocxService` — `generateDocx`, `validateDocument`
+```typescript
+DocxModule.forRoot(options?: DocxModuleOptions)
+```
+
+### Service
+
+```typescript
+class DocxService {
+  async generateDocx(
+    template: Buffer,
+    data: Record<string, any>,
+  ): Promise<Buffer>;
+
+  async validateDocument(
+    template: Buffer,
+    requiredPlaceholders: string[],
+  ): Promise<string[]>;
+}
+```
+
+## Troubleshooting
+
+### Q: Placeholder not replaced?
+
+Check for typos in template:
+
+```handlebars
+{{naem}}
+← Wrong
+{{name}}
+← Correct
+```
+
+### Q: Loop not working?
+
+Ensure data is an array:
+
+```typescript
+// ❌ Won't iterate
+items: "not an array";
+
+// ✅ Will iterate
+items: [{ name: "A" }, { name: "B" }];
+```
+
+### Q: Image not displaying?
+
+Use correct image syntax:
+
+```handlebars
+{{#image path width height}}
+  relative/path/to/image.png
+{{/image}}
+```
+
+### Q: Conditional not working?
+
+Ensure condition is boolean:
+
+```typescript
+// ❌ String
+isPremium: "true";
+
+// ✅ Boolean
+isPremium: true;
+```
 
 ## Related Packages
 
-- [@zola_do/document-manipulator](../document-manipulator) — PDF/DOCX merge and conversion, uses similar template population
+- [@zola_do/document-manipulator](../document-manipulator) — PDF/DOCX merge and conversion
 - [@zola_do/minio](../minio) — Store generated documents
 
+## License
+
+ISC
+
 ## Community
 
 - [Contributing](../../CONTRIBUTING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zola_do/docx",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "DOCX template processing for NestJS",
   "author": "zolaDO",
   "license": "ISC",