@shad0wz7/nestjs-pdf 2.0.0 → 2.1.0

package/README.md

@@ -3,13 +3,12 @@
 A small NestJS library to generate and manipulate PDFs using Puppeteer and multiple template engines, including Handlebars, EJS, Pug, and MJML.
 
 Main features:
+
 - Generate PDFs from HTML, Handlebars, EJS, Pug or MJML templates
 - Concurrency limiting for Puppeteer jobs (p-limit)
 - Add signature fields based on a text anchor in an existing PDF
 - Simple API (module and service) to integrate easily into a Nest application
 
-> Note: this repository contains the library source. To use it in another project, you can either install it from npm or import the local package from the source.
-
 ## Installation
 
 To add the library inside your project :
@@ -29,6 +28,14 @@ pnpm add ../path/to/nestjs-pdf
 
 Import the module and configure it in your Nest application:
 
+To use a template engine, you need to install the corresponding package as a dependency in your project:
+
+- For Handlebars: `npm install @gboutte/nestjs-hbs`
+- For EJS: `npm install ejs`
+- For Pug: `npm install pug`
+- For MJML: `npm install mjml`
+- For Nunjucks: `npm install nunjucks`
+
 ```ts
 import { Module } from '@nestjs/common';
 import { NestjsPdfModule } from 'nestjs-pdf';
@@ -68,11 +75,17 @@ Use a Handlebars template (string or file):
 
 ```ts
 const template = '<h1>{{title}}</h1><p>{{content}}</p>';
-const pdf = await pdfService.generatePdfFromTemplateHbsString(template, { title: 'T', content: '...' });
+const pdf = await pdfService.generatePdfFromTemplateHbsString(template, {
+  title: 'T',
+  content: '...',
+});
 ```
 
 ```ts
-const pdf = await pdfService.generatePdfFromTemplateHbsFile(filePath, { title: 'T', content: '...' });
+const pdf = await pdfService.generatePdfFromTemplateHbsFile(filePath, {
+  title: 'T',
+  content: '...',
+});
 ```
 
 Add a signature field to an existing PDF (anchor-based):
@@ -94,9 +107,65 @@ If the anchor is not found, the signature field will be added at a default posit
 
 The library exposes Puppeteer options via the `PuppeteerParameters` interface (see `src/puppeteer/puppeteer-parameters.interface.ts`). You can configure:
 
-- `headless` (boolean | 'shell')
-- `pdfOptions` (native Puppeteer options for `page.pdf`)
-- `extraPuppeteerArgs` (launch arguments for Chromium)
+
+|                             | Description                                                                                                                                                                                                                                                                                    |
+|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `pdfOptions`                | The pdf options can be found on: https://pptr.dev/api/puppeteer.pdfoptions. Native Puppeteer options for `page.pdf`                                                                                                                                                                            |
+| `hbsOptions`                | The handlebars can be found on [@gboutte/nestjs-hbs](https://github.com/gboutte/nestjs-hbs) as it use a peer dependency and not handlebars directly                                                                                                                                            |
+| `ejsOptions`                | The ejs options can be found on [EJS documentation](https://ejs.co/#options)                                                                                                                                                                                                                   |
+| `pugOptions`                | The pug options can be found on [Pug documentation](https://pugjs.org/api/reference.html#options)                                                                                                                                                                                              |
+| `mjmlOptions`               | The mjml options can be found on [MJML documentation](https://mjml.io/documentation/#options)                                                                                                                                                                                                  |
+| `nunjucksOptions`           | The nunjucks options can be found on [Nunjucks documentation](https://mozilla.github.io/nunjucks/api.html#configure)                                                                                                                                                                           |
+| `browser`                   | The browser to use for the PDF generation. By default: `Browser.CHROMIUM`. Allowed values `Browser.CHROMIUM`, `Browser.CHROMEHEADLESSSHELL`, `Browser.CHROME`, `Browser.FIREFOX`, `Browser.CHROMEDRIVER` ([Official documentation of Browser](https://pptr.dev/browsers-api/browsers.browser)) |
+| `browserTag`                | The version of the browser to use for the PDF generation. By default: `BrowserTag.LATEST` if Browser is **CHROMIUM** else `BrowserTag.STABLE`. Allowed values `BrowserTag.STABLE`, `BrowserTag.LATEST`, `BrowserTag.BETA`, `BrowserTag.DEV`, `BrowserTag.CANARY`                               |
+| `browserInstallBaseUrl`     | The baseUrl used for the installation of the browser. This baseUrl is passed to the [`install`](https://pptr.dev/browsers-api/browsers.install) method of `@puppeteer/browsers`                                                                                                                |
+| `headless`                  | Define if you want to use chromium headless or not, or the old headless version (`shell`). By default it's `true`. Allowed values: `true`,`false`,`"shell"`                                                                                                                                    |
+| `useLockedBrowser`          | Define if you want to use the locked version of the browser. By default it's `false`. Allowed values: `true`,`false`                                                                                                                                                                           |
+| `buildId`                   | You can force the build id. Should be `string`                                                                                                                                                                                                                                                 |
+| `cleanupBrowserCacheOnExit` | Define if you want to clean up the browser cache folder on exit. By default it's `true`. Allowed values: `true`,`false`                                                                                                                                                                        |
+| `extraPuppeteerArgs`        | It passes some extra arguments to Puppeteer's launch method. You can check the default args at bellow. Should be `string[]`                                                                                                                                                                    |
+
+these are the default extra arguments passed to Puppeteer:
+```ts
+[
+  '--autoplay-policy=user-gesture-required',
+  '--disable-background-networking',
+  '--disable-background-timer-throttling',
+  '--disable-backgrounding-occluded-windows',
+  '--disable-breakpad',
+  '--disable-client-side-phishing-detection',
+  '--disable-component-update',
+  '--disable-default-apps',
+  '--disable-dev-shm-usage',
+  '--disable-domain-reliability',
+  '--disable-extensions',
+  '--disable-features=AudioServiceOutOfProcess',
+  '--disable-hang-monitor',
+  '--disable-ipc-flooding-protection',
+  '--disable-notifications',
+  '--disable-offer-store-unmasked-wallet-cards',
+  '--disable-popup-blocking',
+  '--disable-print-preview',
+  '--disable-prompt-on-repost',
+  '--disable-renderer-backgrounding',
+  '--disable-setuid-sandbox',
+  '--disable-speech-api',
+  '--disable-sync',
+  '--hide-scrollbars',
+  '--ignore-gpu-blacklist',
+  '--metrics-recording-only',
+  '--mute-audio',
+  '--no-default-browser-check',
+  '--no-first-run',
+  '--no-pings',
+  '--password-store=basic',
+  '--use-gl=swiftshader',
+  '--use-mock-keychain',
+  '--disable-accelerated-2d-canvas',
+  '--no-zygote',
+  '--disable-gpu',
+];
+```
 
 You can use `forRootAsync(...)` if you need to provide configuration asynchronously.
 

package/dist/index.d.mts

@@ -6,6 +6,7 @@ import { Browser, BrowserContext, PDFOptions } from 'puppeteer';
 import { MJMLParsingOptions } from 'mjml-core';
 import pug, { LocalsObject } from 'pug';
 import { Options, Data } from 'ejs';
+import { ConfigureOptions } from 'nunjucks';
 import { HandlebarsService } from '@gboutte/nestjs-hbs';
 
 declare enum BrowserTag {
@@ -67,12 +68,26 @@ declare class EjsService {
     renderFile(filePath: string, data?: Data, options?: EjsOptions): Promise<string>;
 }
 
+interface NunjucksOptions extends Partial<ConfigureOptions> {
+    noCache?: boolean;
+    watch?: boolean;
+    throwOnUndefined?: boolean;
+    trimBlocks?: boolean;
+    lstripBlocks?: boolean;
+}
+declare class NunjucksService {
+    constructor();
+    render(template: string, data?: Record<string, unknown>, options?: NunjucksOptions): string;
+    renderFile(filePath: string, data?: Record<string, unknown>, options?: NunjucksOptions): string;
+}
+
 interface PuppeteerParameters {
     pdfOptions?: PDFOptions;
     hbsOptions?: HandlebarsOptions;
     mjmlOptions?: MJMLParsingOptions;
     pugOptions?: PugOptions;
     ejsOptions?: EjsOptions;
+    nunjucksOptions?: NunjucksOptions;
     chromiumRevision?: string;
     buildId?: string;
     headless?: boolean | 'shell';
@@ -105,7 +120,8 @@ declare class PuppeteerService {
     private readonly mjmlService?;
     private readonly pugService?;
     private readonly ejsService?;
-    constructor(hbsService: HandlebarsService, browserService: BrowserService, options: PuppeteerParameters, mjmlService?: MjmlService | undefined, pugService?: PugService | undefined, ejsService?: EjsService | undefined);
+    private readonly nunjucksService?;
+    constructor(hbsService: HandlebarsService, browserService: BrowserService, options: PuppeteerParameters, mjmlService?: MjmlService | undefined, pugService?: PugService | undefined, ejsService?: EjsService | undefined, nunjucksService?: NunjucksService | undefined);
     private readonly limit;
     generatePdfFromHtml(html: string, options?: PuppeteerParameters): Promise<Uint8Array>;
     generatePdfFromTemplateHbsString(template: string, parameters?: any, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
@@ -116,6 +132,8 @@ declare class PuppeteerService {
     generatePdfFromPugFile(file: string, data?: LocalsObject, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
     generatePdfFromEjsString(template: string, data?: Data, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
     generatePdfFromEjsFile(file: string, data?: Data, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
+    generatePdfFromNunjucksString(template: string, data?: Record<string, unknown>, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
+    generatePdfFromNunjucksFile(file: string, data?: Record<string, unknown>, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
 }
 
 declare class NestjsPdfService {
@@ -128,24 +146,6 @@ declare class NestjsPdfService {
      * @description This method uses the Puppeteer service to generate a PDF from an HTML string. Generation options can be customized by passing a `PuppeteerParameters` object as the second argument. This allows you to control various aspects of PDF rendering, such as page size, margins, background display, etc. If no options are provided, the default parameters defined in the Puppeteer service will be used.
      */
     generatePdfFromHtml(html: string, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
-    /**
-     * @deprecated Use the new method generatePdfFromTemplateHbsString
-     * @param template Handlebars template string
-     * @param parameters Data parameters to inject into the template
-     * @param options PDF generation options (optional)
-     * @returns PDF generated from the provided Handlebars template with parameters applied
-     * @description This method generates a PDF from a Handlebars template provided as a string. The parameters to inject into the template are passed in the `parameters` object, which is used to render the template before converting it to PDF. PDF generation options can also be customized by passing a `PuppeteerParameters` object as the third argument. This allows you to control various aspects of PDF rendering, such as page size, margins, background display, etc. If no options are provided, the default parameters defined in the Puppeteer service will be used.
-     */
-    generatePdfFromTemplateString(template: string, parameters?: any, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
-    /**
-     * @deprecated Use the new method generatePdfFromTemplateHbsFile
-     * @param file Path to the Handlebars template file
-     * @param parameters Data parameters to inject into the template
-     * @param options PDF generation options (optional)
-     * @returns PDF generated from the Handlebars template at the provided file path with parameters applied
-     * @description This method generates a PDF from a Handlebars template located at the specified file path. The file path is passed as a string in the `file` parameter. The parameters to inject into the template are passed in the `parameters` object, which is used to render the template before converting it to PDF. PDF generation options can also be customized by passing a `PuppeteerParameters` object as the third argument. This allows you to control various aspects of PDF rendering, such as page size, margins, background display, etc. If no options are provided, the default parameters defined in the Puppeteer service will be used.
-     */
-    generatePdfFromTemplateFile(file: string, parameters?: any, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
     /**
      * @param template Handlebars template string
      * @param parameters Data parameters to inject into the template
@@ -208,6 +208,22 @@ declare class NestjsPdfService {
      * @description This method generates a PDF from a Pug template located at the specified file path. The file path is passed as a string in the `file` parameter. The data to inject into the template is passed in the `data` object, which is used to render the template before converting it to PDF. PDF generation options can be customized by passing a `PuppeteerParameters` object as the third argument.
      */
     generatePdfFromPugFile(file: string, data?: LocalsObject, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
+    /**
+     * @param template Nunjucks template string
+     * @param data Data to inject into the template
+     * @param options PDF generation options (optional)
+     * @returns PDF generated from the provided Nunjucks template with data applied
+     * @description This method generates a PDF from a Nunjucks template provided as a string. Nunjucks is a powerful templating language with support for inheritance, macros, and filters. The data to inject into the template is passed in the `data` object, which is used to render the template before converting it to PDF. PDF generation options can be customized by passing a `PuppeteerParameters` object as the third argument.
+     */
+    generatePdfFromNunjucksString(template: string, data?: Record<string, unknown>, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
+    /**
+     * @param file Path to the Nunjucks template file
+     * @param data Data to inject into the template
+     * @param options PDF generation options (optional)
+     * @returns PDF generated from the Nunjucks template at the provided file path with data applied
+     * @description This method generates a PDF from a Nunjucks template located at the specified file path. The file path is passed as a string in the `file` parameter. The data to inject into the template is passed in the `data` object, which is used to render the template before converting it to PDF. PDF generation options can be customized by passing a `PuppeteerParameters` object as the third argument.
+     */
+    generatePdfFromNunjucksFile(file: string, data?: Record<string, unknown>, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
     /**
      * @param pdf The PDF bytes to modify
      * @param fieldName The name of the signature field to add (default: 'SignatureDebtor')
@@ -257,4 +273,4 @@ declare class PuppeteerModule implements OnModuleInit {
  */
 declare function getRelativePathToValue(moduleDir: string, relativeToModule: string): string;
 
-export { type EjsOptions, EjsService, MjmlService, NestjsPdfModule, NestjsPdfService, type PdfLibModuleAsyncOptions, type PugOptions, PugService, PuppeteerModule, type PuppeteerModuleAsyncOptions, type PuppeteerParameters, PuppeteerService, getRelativePathToValue };
+export { type EjsOptions, EjsService, MjmlService, NestjsPdfModule, NestjsPdfService, type NunjucksOptions, NunjucksService, type PdfLibModuleAsyncOptions, type PugOptions, PugService, PuppeteerModule, type PuppeteerModuleAsyncOptions, type PuppeteerParameters, PuppeteerService, getRelativePathToValue };

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { Browser, BrowserContext, PDFOptions } from 'puppeteer';
 import { MJMLParsingOptions } from 'mjml-core';
 import pug, { LocalsObject } from 'pug';
 import { Options, Data } from 'ejs';
+import { ConfigureOptions } from 'nunjucks';
 import { HandlebarsService } from '@gboutte/nestjs-hbs';
 
 declare enum BrowserTag {
@@ -67,12 +68,26 @@ declare class EjsService {
     renderFile(filePath: string, data?: Data, options?: EjsOptions): Promise<string>;
 }
 
+interface NunjucksOptions extends Partial<ConfigureOptions> {
+    noCache?: boolean;
+    watch?: boolean;
+    throwOnUndefined?: boolean;
+    trimBlocks?: boolean;
+    lstripBlocks?: boolean;
+}
+declare class NunjucksService {
+    constructor();
+    render(template: string, data?: Record<string, unknown>, options?: NunjucksOptions): string;
+    renderFile(filePath: string, data?: Record<string, unknown>, options?: NunjucksOptions): string;
+}
+
 interface PuppeteerParameters {
     pdfOptions?: PDFOptions;
     hbsOptions?: HandlebarsOptions;
     mjmlOptions?: MJMLParsingOptions;
     pugOptions?: PugOptions;
     ejsOptions?: EjsOptions;
+    nunjucksOptions?: NunjucksOptions;
     chromiumRevision?: string;
     buildId?: string;
     headless?: boolean | 'shell';
@@ -105,7 +120,8 @@ declare class PuppeteerService {
     private readonly mjmlService?;
     private readonly pugService?;
     private readonly ejsService?;
-    constructor(hbsService: HandlebarsService, browserService: BrowserService, options: PuppeteerParameters, mjmlService?: MjmlService | undefined, pugService?: PugService | undefined, ejsService?: EjsService | undefined);
+    private readonly nunjucksService?;
+    constructor(hbsService: HandlebarsService, browserService: BrowserService, options: PuppeteerParameters, mjmlService?: MjmlService | undefined, pugService?: PugService | undefined, ejsService?: EjsService | undefined, nunjucksService?: NunjucksService | undefined);
     private readonly limit;
     generatePdfFromHtml(html: string, options?: PuppeteerParameters): Promise<Uint8Array>;
     generatePdfFromTemplateHbsString(template: string, parameters?: any, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
@@ -116,6 +132,8 @@ declare class PuppeteerService {
     generatePdfFromPugFile(file: string, data?: LocalsObject, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
     generatePdfFromEjsString(template: string, data?: Data, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
     generatePdfFromEjsFile(file: string, data?: Data, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
+    generatePdfFromNunjucksString(template: string, data?: Record<string, unknown>, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
+    generatePdfFromNunjucksFile(file: string, data?: Record<string, unknown>, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
 }
 
 declare class NestjsPdfService {
@@ -128,24 +146,6 @@ declare class NestjsPdfService {
      * @description This method uses the Puppeteer service to generate a PDF from an HTML string. Generation options can be customized by passing a `PuppeteerParameters` object as the second argument. This allows you to control various aspects of PDF rendering, such as page size, margins, background display, etc. If no options are provided, the default parameters defined in the Puppeteer service will be used.
      */
     generatePdfFromHtml(html: string, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
-    /**
-     * @deprecated Use the new method generatePdfFromTemplateHbsString
-     * @param template Handlebars template string
-     * @param parameters Data parameters to inject into the template
-     * @param options PDF generation options (optional)
-     * @returns PDF generated from the provided Handlebars template with parameters applied
-     * @description This method generates a PDF from a Handlebars template provided as a string. The parameters to inject into the template are passed in the `parameters` object, which is used to render the template before converting it to PDF. PDF generation options can also be customized by passing a `PuppeteerParameters` object as the third argument. This allows you to control various aspects of PDF rendering, such as page size, margins, background display, etc. If no options are provided, the default parameters defined in the Puppeteer service will be used.
-     */
-    generatePdfFromTemplateString(template: string, parameters?: any, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
-    /**
-     * @deprecated Use the new method generatePdfFromTemplateHbsFile
-     * @param file Path to the Handlebars template file
-     * @param parameters Data parameters to inject into the template
-     * @param options PDF generation options (optional)
-     * @returns PDF generated from the Handlebars template at the provided file path with parameters applied
-     * @description This method generates a PDF from a Handlebars template located at the specified file path. The file path is passed as a string in the `file` parameter. The parameters to inject into the template are passed in the `parameters` object, which is used to render the template before converting it to PDF. PDF generation options can also be customized by passing a `PuppeteerParameters` object as the third argument. This allows you to control various aspects of PDF rendering, such as page size, margins, background display, etc. If no options are provided, the default parameters defined in the Puppeteer service will be used.
-     */
-    generatePdfFromTemplateFile(file: string, parameters?: any, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
     /**
      * @param template Handlebars template string
      * @param parameters Data parameters to inject into the template
@@ -208,6 +208,22 @@ declare class NestjsPdfService {
      * @description This method generates a PDF from a Pug template located at the specified file path. The file path is passed as a string in the `file` parameter. The data to inject into the template is passed in the `data` object, which is used to render the template before converting it to PDF. PDF generation options can be customized by passing a `PuppeteerParameters` object as the third argument.
      */
     generatePdfFromPugFile(file: string, data?: LocalsObject, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
+    /**
+     * @param template Nunjucks template string
+     * @param data Data to inject into the template
+     * @param options PDF generation options (optional)
+     * @returns PDF generated from the provided Nunjucks template with data applied
+     * @description This method generates a PDF from a Nunjucks template provided as a string. Nunjucks is a powerful templating language with support for inheritance, macros, and filters. The data to inject into the template is passed in the `data` object, which is used to render the template before converting it to PDF. PDF generation options can be customized by passing a `PuppeteerParameters` object as the third argument.
+     */
+    generatePdfFromNunjucksString(template: string, data?: Record<string, unknown>, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
+    /**
+     * @param file Path to the Nunjucks template file
+     * @param data Data to inject into the template
+     * @param options PDF generation options (optional)
+     * @returns PDF generated from the Nunjucks template at the provided file path with data applied
+     * @description This method generates a PDF from a Nunjucks template located at the specified file path. The file path is passed as a string in the `file` parameter. The data to inject into the template is passed in the `data` object, which is used to render the template before converting it to PDF. PDF generation options can be customized by passing a `PuppeteerParameters` object as the third argument.
+     */
+    generatePdfFromNunjucksFile(file: string, data?: Record<string, unknown>, options?: PuppeteerParameters): Promise<Uint8Array<ArrayBufferLike>>;
     /**
      * @param pdf The PDF bytes to modify
      * @param fieldName The name of the signature field to add (default: 'SignatureDebtor')
@@ -257,4 +273,4 @@ declare class PuppeteerModule implements OnModuleInit {
  */
 declare function getRelativePathToValue(moduleDir: string, relativeToModule: string): string;
 
-export { type EjsOptions, EjsService, MjmlService, NestjsPdfModule, NestjsPdfService, type PdfLibModuleAsyncOptions, type PugOptions, PugService, PuppeteerModule, type PuppeteerModuleAsyncOptions, type PuppeteerParameters, PuppeteerService, getRelativePathToValue };
+export { type EjsOptions, EjsService, MjmlService, NestjsPdfModule, NestjsPdfService, type NunjucksOptions, NunjucksService, type PdfLibModuleAsyncOptions, type PugOptions, PugService, PuppeteerModule, type PuppeteerModuleAsyncOptions, type PuppeteerParameters, PuppeteerService, getRelativePathToValue };