node-pptx-templater 1.0.2 → 1.0.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.0.2",
-  "description": "Low-level PowerPoint OpenXML template engine for Node.js — generate and edit PPTX files directly through XML manipulation without relying on PowerPoint generation libraries.",
+  "version": "1.0.4",
+  "description": "High-performance, low-level PowerPoint (PPTX) OpenXML template engine for Node.js. Dynamically replace text, insert images, update charts (with Excel workbook data caching), and merge table cells without PowerPoint corruption or Repair Mode prompts.",
   "main": "./src/index.js",
   "type": "commonjs",
   "exports": {
@@ -43,7 +43,16 @@
     "report",
     "generator",
     "nodejs",
-    "esm"
+    "powerpoint-automation",
+    "pptx-template-engine",
+    "merge-cells",
+    "table-merge",
+    "chart-update",
+    "dynamic-slides",
+    "mail-merge",
+    "report-generator",
+    "xml-manipulation",
+    "pptx-editor"
   ],
   "author": {
     "name": "node-pptx-templater contributors"

package/src/cli/commands/build.js

@@ -2,11 +2,11 @@
  * @fileoverview `build` CLI command — builds a PPTX from a template + JSON data.
  */
 
-const chalk = require('chalk');
-const ora = require('ora');
-const { readFileSync } = require('fs');
-const { resolve } = require('path');
-const { PPTXTemplater } = require('../../index.js');
+const chalk = require('chalk')
+const ora = require('ora')
+const { readFileSync } = require('fs')
+const { resolve } = require('path')
+const { PPTXTemplater } = require('../../index.js')
 
 /**
  * Executes the `build` CLI command.
@@ -16,66 +16,65 @@ const { PPTXTemplater } = require('../../index.js');
  * @param {Object} opts - CLI options.
  */
 async function buildCommand(templatePath, outputPath, opts) {
-  const spinner = ora(`Loading template: ${templatePath}`).start();
+  const spinner = ora(`Loading template: ${templatePath}`).start()
 
   try {
     // Load the template
-    const ppt = await PPTXTemplater.load(resolve(templatePath));
-    spinner.succeed(`Loaded template (${ppt.slideCount} slides)`);
+    const ppt = await PPTXTemplater.load(resolve(templatePath))
+    spinner.succeed(`Loaded template (${ppt.slideCount} slides)`)
 
     // Apply slide filter if provided
     if (opts.slide) {
-      const slideNumbers = opts.slide.split(',').map(n => parseInt(n.trim(), 10));
-      ppt.useSlide(...slideNumbers);
-      console.log(chalk.cyan(`  → Using slides: ${slideNumbers.join(', ')}`));
+      const slideNumbers = opts.slide.split(',').map(n => parseInt(n.trim(), 10))
+      ppt.useSlide(...slideNumbers)
+      console.log(chalk.cyan(`  → Using slides: ${slideNumbers.join(', ')}`))
     }
 
     // Apply data from JSON file if provided
     if (opts.data) {
-      spinner.start(`Loading data: ${opts.data}`);
-      const data = JSON.parse(readFileSync(resolve(opts.data), 'utf-8'));
+      spinner.start(`Loading data: ${opts.data}`)
+      const data = JSON.parse(readFileSync(resolve(opts.data), 'utf-8'))
 
       // Apply text replacements
       if (data.text) {
-        ppt.replaceText(data.text);
-        console.log(chalk.cyan(`  → Replaced ${Object.keys(data.text).length} text placeholder(s)`));
+        ppt.replaceText(data.text)
+        console.log(chalk.cyan(`  → Replaced ${Object.keys(data.text).length} text placeholder(s)`))
       }
 
       // Apply chart updates
       if (data.charts) {
         for (const [chartId, chartData] of Object.entries(data.charts)) {
-          ppt.updateChart(chartId, chartData);
-          console.log(chalk.cyan(`  → Updated chart: ${chartId}`));
+          ppt.updateChart(chartId, chartData)
+          console.log(chalk.cyan(`  → Updated chart: ${chartId}`))
         }
       }
 
       // Apply table updates
       if (data.tables) {
         for (const [tableId, tableData] of Object.entries(data.tables)) {
-          ppt.updateTable(tableId, tableData);
-          console.log(chalk.cyan(`  → Updated table: ${tableId}`));
+          ppt.updateTable(tableId, tableData)
+          console.log(chalk.cyan(`  → Updated table: ${tableId}`))
         }
       }
 
-      spinner.succeed('Data applied');
+      spinner.succeed('Data applied')
     }
 
     // Save output
-    spinner.start(`Saving to: ${outputPath}`);
-    await ppt.saveToFile(resolve(outputPath));
-    spinner.succeed(chalk.green(`✓ Saved: ${outputPath}`));
-
-    console.log(chalk.dim(`\n  Slides: ${ppt.slideCount}`));
-    console.log(chalk.dim(`  Template: ${templatePath}`));
-    console.log(chalk.dim(`  Output: ${outputPath}\n`));
+    spinner.start(`Saving to: ${outputPath}`)
+    await ppt.saveToFile(resolve(outputPath))
+    spinner.succeed(chalk.green(`✓ Saved: ${outputPath}`))
 
+    console.log(chalk.dim(`\n  Slides: ${ppt.slideCount}`))
+    console.log(chalk.dim(`  Template: ${templatePath}`))
+    console.log(chalk.dim(`  Output: ${outputPath}\n`))
   } catch (err) {
-    spinner.fail(chalk.red(`Build failed: ${err.message}`));
+    spinner.fail(chalk.red(`Build failed: ${err.message}`))
     if (process.env.PPTX_LOG_LEVEL === 'debug') {
-      console.error(err.stack);
+      console.error(err.stack)
     }
-    process.exit(1);
+    process.exit(1)
   }
 }
 
-module.exports = { buildCommand };
+module.exports = { buildCommand }

package/src/cli/commands/debug.js

@@ -1,47 +1,47 @@
 /**
  * @fileoverview `debug` CLI command — diagnoses and repairs corrupted PPTX files.
  */
-const chalk = require('chalk');
-const ora = require('ora');
-const { resolve } = require('path');
-const { PPTXTemplater } = require('../../index.js');
+const chalk = require('chalk')
+const ora = require('ora')
+const { resolve } = require('path')
+const { PPTXTemplater } = require('../../index.js')
 
 async function debugCommand(filePath, opts) {
-  const spinner = ora(`Loading PPTX for debug: ${filePath}`).start();
+  const spinner = ora(`Loading PPTX for debug: ${filePath}`).start()
 
   try {
-    const ppt = await PPTXTemplater.load(resolve(filePath));
-    spinner.succeed('Loaded successfully');
+    const ppt = await PPTXTemplater.load(resolve(filePath))
+    spinner.succeed('Loaded successfully')
 
-    const result = ppt.validate();
+    const result = ppt.validate()
 
-    console.log(chalk.bold.cyan('\n═══ Debug Report ═══\n'));
-    console.log(chalk.bold('Validation:'));
+    console.log(chalk.bold.cyan('\n═══ Debug Report ═══\n'))
+    console.log(chalk.bold('Validation:'))
 
     if (result.valid) {
-      console.log(chalk.green('  ✓ Structure is valid'));
+      console.log(chalk.green('  ✓ Structure is valid'))
     } else {
-      console.log(chalk.red(`  ✗ ${result.errors.length} error(s) found`));
-      result.errors.forEach(e => console.log(chalk.red(`    • ${e}`)));
+      console.log(chalk.red(`  ✗ ${result.errors.length} error(s) found`))
+      result.errors.forEach(e => console.log(chalk.red(`    • ${e}`)))
     }
 
     if (result.warnings.length > 0) {
-      console.log(chalk.yellow(`\n  ${result.warnings.length} warning(s):`));
-      result.warnings.forEach(w => console.log(chalk.yellow(`    • ${w}`)));
+      console.log(chalk.yellow(`\n  ${result.warnings.length} warning(s):`))
+      result.warnings.forEach(w => console.log(chalk.yellow(`    • ${w}`)))
     }
 
     if (opts.fix && opts.out) {
-      spinner.start('Attempting repairs...');
-      await ppt.saveToFile(resolve(opts.out));
-      spinner.succeed(chalk.green(`✓ Repaired PPTX saved to: ${opts.out}`));
+      spinner.start('Attempting repairs...')
+      await ppt.saveToFile(resolve(opts.out))
+      spinner.succeed(chalk.green(`✓ Repaired PPTX saved to: ${opts.out}`))
     }
 
-    console.log('');
+    console.log('')
   } catch (err) {
-    spinner.fail(chalk.red(`Debug failed: ${err.message}`));
-    if (process.env.PPTX_LOG_LEVEL === 'debug') console.error(err.stack);
-    process.exit(1);
+    spinner.fail(chalk.red(`Debug failed: ${err.message}`))
+    if (process.env.PPTX_LOG_LEVEL === 'debug') console.error(err.stack)
+    process.exit(1)
   }
 }
 
-module.exports = { debugCommand };
+module.exports = { debugCommand }

package/src/cli/commands/extract.js

@@ -1,44 +1,44 @@
 /**
  * @fileoverview `extract` CLI command — extracts XML parts from a PPTX.
  */
-const chalk = require('chalk');
-const { resolve } = require('path');
-const { writeFileSync } = require('fs');
-const { PPTXTemplater } = require('../../index.js');
+const chalk = require('chalk')
+const { resolve } = require('path')
+const { writeFileSync } = require('fs')
+const { PPTXTemplater } = require('../../index.js')
 
 async function extractCommand(filePath, opts) {
   try {
-    const ppt = await PPTXTemplater.load(resolve(filePath));
+    const ppt = await PPTXTemplater.load(resolve(filePath))
 
     if (opts.slide) {
-      const slideNum = parseInt(opts.slide, 10);
+      const slideNum = parseInt(opts.slide, 10)
       // Access internal zip via the engine's buffer
-      const buffer = await ppt.toBuffer();
-      const JSZip = require('jszip');
-      const zip = await JSZip.loadAsync(buffer);
-      const slideFile = zip.file(`ppt/slides/slide${slideNum}.xml`);
+      const buffer = await ppt.toBuffer()
+      const JSZip = require('jszip')
+      const zip = await JSZip.loadAsync(buffer)
+      const slideFile = zip.file(`ppt/slides/slide${slideNum}.xml`)
 
       if (!slideFile) {
-        console.error(chalk.red(`Slide ${slideNum} not found`));
-        process.exit(1);
+        console.error(chalk.red(`Slide ${slideNum} not found`))
+        process.exit(1)
       }
 
-      const xml = await slideFile.async('text');
+      const xml = await slideFile.async('text')
 
       if (opts.out) {
-        writeFileSync(resolve(opts.out), xml, 'utf-8');
-        console.log(chalk.green(`✓ Extracted slide ${slideNum} to ${opts.out}`));
+        writeFileSync(resolve(opts.out), xml, 'utf-8')
+        console.log(chalk.green(`✓ Extracted slide ${slideNum} to ${opts.out}`))
       } else {
-        console.log(xml);
+        console.log(xml)
       }
     } else {
-      console.log(chalk.yellow('Specify --slide <number> to extract'));
-      process.exit(1);
+      console.log(chalk.yellow('Specify --slide <number> to extract'))
+      process.exit(1)
     }
   } catch (err) {
-    console.error(chalk.red(`Extract failed: ${err.message}`));
-    process.exit(1);
+    console.error(chalk.red(`Extract failed: ${err.message}`))
+    process.exit(1)
   }
 }
 
-module.exports = { extractCommand };
+module.exports = { extractCommand }

package/src/cli/commands/inspect.js

@@ -1,41 +1,41 @@
 /**
  * @fileoverview `inspect` CLI command — detailed PPTX structure inspection.
  */
-const chalk = require('chalk');
-const ora = require('ora');
-const { resolve } = require('path');
-const { PPTXTemplater } = require('../../index.js');
+const chalk = require('chalk')
+const ora = require('ora')
+const { resolve } = require('path')
+const { PPTXTemplater } = require('../../index.js')
 
 async function inspectCommand(filePath, opts) {
-  const showAll = opts.all;
-  const spinner = ora(`Inspecting: ${filePath}`).start();
+  const showAll = opts.all
+  const spinner = ora(`Inspecting: ${filePath}`).start()
 
   try {
-    const ppt = await PPTXTemplater.load(resolve(filePath));
-    const info = ppt.getInfo();
-    spinner.stop();
+    const ppt = await PPTXTemplater.load(resolve(filePath))
+    const info = ppt.getInfo()
+    spinner.stop()
 
-    console.log(chalk.bold.cyan('\n═══ PPTX Inspection Report ═══\n'));
-    console.log(chalk.bold('General:'));
-    console.log(`  Title:    ${info.title || chalk.dim('(none)')}`);
-    console.log(`  Author:   ${info.author || chalk.dim('(none)')}`);
-    console.log(`  Created:  ${info.created || chalk.dim('(unknown)')}`);
-    console.log(`  Slides:   ${chalk.cyan(info.slideCount)}`);
-    console.log(`  Media:    ${chalk.cyan(info.mediaCount)} files`);
+    console.log(chalk.bold.cyan('\n═══ PPTX Inspection Report ═══\n'))
+    console.log(chalk.bold('General:'))
+    console.log(`  Title:    ${info.title || chalk.dim('(none)')}`)
+    console.log(`  Author:   ${info.author || chalk.dim('(none)')}`)
+    console.log(`  Created:  ${info.created || chalk.dim('(unknown)')}`)
+    console.log(`  Slides:   ${chalk.cyan(info.slideCount)}`)
+    console.log(`  Media:    ${chalk.cyan(info.mediaCount)} files`)
 
     if (opts.slides || showAll) {
-      console.log(chalk.bold('\nSlides:'));
+      console.log(chalk.bold('\nSlides:'))
       for (const slide of info.slides) {
-        const tags = slide.tags.length > 0 ? chalk.dim(` [${slide.tags.join(', ')}]`) : '';
-        console.log(`  ${chalk.cyan(slide.index.toString().padStart(2))}. ${slide.zipPath}${tags}`);
+        const tags = slide.tags.length > 0 ? chalk.dim(` [${slide.tags.join(', ')}]`) : ''
+        console.log(`  ${chalk.cyan(slide.index.toString().padStart(2))}. ${slide.zipPath}${tags}`)
       }
     }
 
-    console.log('');
+    console.log('')
   } catch (err) {
-    spinner.fail(chalk.red(`Inspect failed: ${err.message}`));
-    process.exit(1);
+    spinner.fail(chalk.red(`Inspect failed: ${err.message}`))
+    process.exit(1)
   }
 }
 
-module.exports = { inspectCommand };
+module.exports = { inspectCommand }

package/src/cli/commands/validate.js

@@ -1,38 +1,38 @@
 /**
  * @fileoverview `validate` CLI command.
  */
-const chalk = require('chalk');
-const ora = require('ora');
-const { resolve } = require('path');
-const { PPTXTemplater } = require('../../index.js');
+const chalk = require('chalk')
+const ora = require('ora')
+const { resolve } = require('path')
+const { PPTXTemplater } = require('../../index.js')
 
 async function validateCommand(filePath, opts) {
-  const spinner = ora(`Validating: ${filePath}`).start();
+  const spinner = ora(`Validating: ${filePath}`).start()
   try {
-    const ppt = await PPTXTemplater.load(resolve(filePath));
-    const result = ppt.validate();
-    spinner.stop();
+    const ppt = await PPTXTemplater.load(resolve(filePath))
+    const result = ppt.validate()
+    spinner.stop()
 
     if (result.valid && result.warnings.length === 0) {
-      console.log(chalk.green(`\n✓ Valid PPTX (${ppt.slideCount} slides)\n`));
+      console.log(chalk.green(`\n✓ Valid PPTX (${ppt.slideCount} slides)\n`))
     } else {
       if (result.errors.length > 0) {
-        console.log(chalk.red(`\n✗ Validation errors (${result.errors.length}):\n`));
-        result.errors.forEach(e => console.log(chalk.red(`  • ${e}`)));
+        console.log(chalk.red(`\n✗ Validation errors (${result.errors.length}):\n`))
+        result.errors.forEach(e => console.log(chalk.red(`  • ${e}`)))
       }
       if (result.warnings.length > 0) {
-        console.log(chalk.yellow(`\n⚠ Warnings (${result.warnings.length}):\n`));
-        result.warnings.forEach(w => console.log(chalk.yellow(`  • ${w}`)));
+        console.log(chalk.yellow(`\n⚠ Warnings (${result.warnings.length}):\n`))
+        result.warnings.forEach(w => console.log(chalk.yellow(`  • ${w}`)))
       }
     }
 
     if (!result.valid || (opts.strict && result.warnings.length > 0)) {
-      process.exit(1);
+      process.exit(1)
     }
   } catch (err) {
-    spinner.fail(chalk.red(`Validation failed: ${err.message}`));
-    process.exit(1);
+    spinner.fail(chalk.red(`Validation failed: ${err.message}`))
+    process.exit(1)
   }
 }
 
-module.exports = { validateCommand };
+module.exports = { validateCommand }

package/src/cli/index.js

@@ -18,40 +18,43 @@
  *   node-pptx-templater --help
  */
 
-const { Command } = require('commander');
-const chalk = require('chalk');
-const { readFileSync } = require('fs');
-const { resolve } = require('path');
-const { buildCommand } = require('./commands/build.js');
-const { validateCommand } = require('./commands/validate.js');
-const { inspectCommand } = require('./commands/inspect.js');
-const { extractCommand } = require('./commands/extract.js');
-const { debugCommand } = require('./commands/debug.js');
+const { Command } = require('commander')
+const chalk = require('chalk')
+const { readFileSync } = require('fs')
+const { resolve } = require('path')
+const { buildCommand } = require('./commands/build.js')
+const { validateCommand } = require('./commands/validate.js')
+const { inspectCommand } = require('./commands/inspect.js')
+const { extractCommand } = require('./commands/extract.js')
+const { debugCommand } = require('./commands/debug.js')
 
 // Read version from package.json
-const pkg = JSON.parse(
-  readFileSync(resolve(__dirname, '../../package.json'), 'utf-8')
-);
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'))
 
 /**
  * CLI banner displayed on startup.
  */
 function printBanner() {
-  console.log(chalk.bold.cyan(`
+  console.log(
+    chalk.bold.cyan(`
 ╔═══════════════════════════════════════════════╗
 ║  node-pptx-templater v${pkg.version.padEnd(17)}║
 ║  Low-level OpenXML PowerPoint template engine ║
 ╚═══════════════════════════════════════════════╝
-`));
+`)
+  )
 }
 
-const program = new Command();
+const program = new Command()
 
 program
   .name('node-pptx-templater')
   .description('Low-level PowerPoint OpenXML template engine for Node.js')
   .version(pkg.version, '-v, --version', 'Display version number')
-  .addHelpText('before', chalk.bold.cyan('\nnode-pptx-templater — PowerPoint XML manipulation engine\n'));
+  .addHelpText(
+    'before',
+    chalk.bold.cyan('\nnode-pptx-templater — PowerPoint XML manipulation engine\n')
+  )
 
 // ─── build command ─────────────────────────────────────────────────────────
 program
@@ -61,9 +64,9 @@ program
   .option('-s, --slide <numbers>', 'Comma-separated slide numbers to include (e.g., 1,3,5)')
   .option('--no-banner', 'Suppress the banner')
   .action(async (template, output, opts) => {
-    if (!opts.noBanner) printBanner();
-    await buildCommand(template, output, opts);
-  });
+    if (!opts.noBanner) printBanner()
+    await buildCommand(template, output, opts)
+  })
 
 // ─── validate command ───────────────────────────────────────────────────────
 program
@@ -71,9 +74,9 @@ program
   .description('Validate the structure of a PPTX file')
   .option('--strict', 'Exit with error code on warnings too')
   .action(async (file, opts) => {
-    printBanner();
-    await validateCommand(file, opts);
-  });
+    printBanner()
+    await validateCommand(file, opts)
+  })
 
 // ─── inspect command ────────────────────────────────────────────────────────
 program
@@ -86,9 +89,9 @@ program
   .option('--rels', 'Show relationship tree')
   .option('--all', 'Show everything')
   .action(async (file, opts) => {
-    printBanner();
-    await inspectCommand(file, opts);
-  });
+    printBanner()
+    await inspectCommand(file, opts)
+  })
 
 // ─── extract command ────────────────────────────────────────────────────────
 program
@@ -99,8 +102,8 @@ program
   .option('--chart <name>', 'Extract chart XML by name')
   .option('--rels', 'Extract relationship files')
   .action(async (file, opts) => {
-    await extractCommand(file, opts);
-  });
+    await extractCommand(file, opts)
+  })
 
 // ─── debug command ──────────────────────────────────────────────────────────
 program
@@ -109,23 +112,23 @@ program
   .option('--fix', 'Attempt automatic repairs')
   .option('-o, --out <path>', 'Output repaired file path')
   .action(async (file, opts) => {
-    printBanner();
-    await debugCommand(file, opts);
-  });
+    printBanner()
+    await debugCommand(file, opts)
+  })
 
 // ─── Global error handling ──────────────────────────────────────────────────
-program.exitOverride();
+program.exitOverride()
 
 async function main() {
   try {
-    await program.parseAsync(process.argv);
+    await program.parseAsync(process.argv)
   } catch (err) {
     if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
-      process.exit(0);
+      process.exit(0)
     }
-    console.error(chalk.red(`\n✗ Error: ${err.message}\n`));
-    process.exit(1);
+    console.error(chalk.red(`\n✗ Error: ${err.message}\n`))
+    process.exit(1)
   }
 }
 
-main();
+main()