zig-pug 4.0.5 → 4.0.6

package/README.md

@@ -17,6 +17,7 @@ High-performance Pug template engine powered by Zig and mujs.
 - ✅ **TypeScript support** - Full type definitions included
 - ✅ **Bun.js compatible** - 2-5x faster than Node.js
 - ✅ **Structured errors** - Detailed error messages with line numbers, hints, and context
+- ✅ **Output formatting** - Minify, pretty-print, or format modes
 - ⚡ **Native performance** - Written in Zig, compiled to native code
 - 🔋 **Zero dependencies** - Only Zig and embedded mujs
 - 🌍 **i18n ready** - Spanish, Portuguese, French, German, and more
@@ -88,6 +89,73 @@ console.log(html);
 // <h1>My Page</h1>
 ```
 
+## Output Formatting
+
+zig-pug supports multiple output modes to suit different use cases:
+
+### Default (Minified)
+
+By default, HTML is minified for production use:
+
+```javascript
+const compiler = new PugCompiler();
+const html = compiler.compile('div\n  h1 Hello\n  p World');
+// Output: <div><h1>Hello</h1><p>World</p></div>
+```
+
+### Pretty Mode (Development)
+
+Pretty-print with indentation and HTML comments for debugging:
+
+```javascript
+const compiler = new PugCompiler({ pretty: true });
+const html = compiler.compile('div\n  h1 Hello\n  p World');
+// Output:
+// <div>
+//   <h1>Hello</h1>
+//   <p>World</p>
+// </div>
+```
+
+### Format Mode (Readable)
+
+Pretty-print without comments for readable production output:
+
+```javascript
+const compiler = new PugCompiler({ format: true });
+const html = compiler.compile('div\n  h1 Hello\n  p World');
+// Output: formatted HTML without comments
+```
+
+### Minify Mode (Explicit)
+
+Explicitly minify to ensure smallest file size:
+
+```javascript
+const compiler = new PugCompiler({ minify: true });
+const html = compiler.compile('div\n  h1 Hello\n  p World');
+// Output: <div><h1>Hello</h1><p>World</p></div>
+```
+
+### Override Options at Compile Time
+
+The hybrid approach allows you to set default options in the constructor and override them per compilation:
+
+```javascript
+// Create compiler with minify by default
+const compiler = new PugCompiler({ minify: true });
+compiler.set('title', 'Hello');
+
+// Production build (uses default minify)
+const prod = compiler.compile('h1= title');
+
+// Debug build (overrides with pretty)
+const debug = compiler.compile('h1= title', { pretty: true });
+
+// Readable build (overrides with format)
+const readable = compiler.compile('h1= title', { format: true });
+```
+
 ### Express Integration
 
 ```javascript
@@ -136,8 +204,8 @@ import { compile, PugCompiler, ZigPugCompilationError } from 'zig-pug';
 // Simple compilation with type inference
 const html: string = compile('p Hello #{name}', { name: 'TypeScript' });
 
-// Using PugCompiler class
-const compiler: PugCompiler = new PugCompiler();
+// Using PugCompiler class with formatting options
+const compiler: PugCompiler = new PugCompiler({ pretty: true });
 compiler
     .setString('title', 'My Page')
     .setNumber('count', 42)
@@ -170,6 +238,7 @@ try {
 
 - `PugCompiler` - Main compiler class
 - `PugVariables` - Type for template variables
+- `CompilationOptions` - Formatting options (pretty, format, minify)
 - `CompilationErrorInfo` - Individual error information
 - `CompilationErrors` - Collection of compilation errors
 - `ZigPugCompilationError` - Extended Error with compilation details
@@ -288,48 +357,66 @@ html
 
 ## API Reference
 
-### `compile(template, data)`
+### `compile(template, data, options)`
 
-Compile a template with data.
+Compile a template with data and formatting options.
 
 **Parameters:**
 - `template` (string) - Pug template source
 - `data` (object) - Variables to interpolate
+- `options` (object) - Formatting options (optional)
+  - `pretty` (boolean) - Enable pretty-print with comments
+  - `format` (boolean) - Enable pretty-print without comments
+  - `minify` (boolean) - Enable HTML minification
+  - `includeComments` (boolean) - Include HTML comments
 
 **Returns:** (string) Compiled HTML
 
 ```javascript
 const html = zigpug.compile(
     'p Hello #{name}!',
-    { name: 'Alice' }
+    { name: 'Alice' },
+    { pretty: true }
 );
 ```
 
 ### `PugCompiler`
 
-Reusable compiler with state.
+Reusable compiler with state and formatting options.
 
 ```javascript
 const { PugCompiler } = require('zig-pug');
 
-const compiler = new PugCompiler();
+const compiler = new PugCompiler({ pretty: true });
 compiler.set('key', 'value');      // String/Number
 compiler.setBool('flag', true);    // Boolean
 
 const html = compiler.compile(template);
 ```
 
+**Constructor Options:**
+- `pretty` (boolean) - Enable pretty-print with indentation and comments
+- `format` (boolean) - Enable pretty-print without comments
+- `minify` (boolean) - Enable HTML minification
+- `includeComments` (boolean) - Include HTML comments
+
 **Methods:**
-- `set(key, value)` - Set string or number variable
+- `set(key, value)` - Set string, number, array, or object variable (auto-detects type)
+- `setString(key, value)` - Set string variable
+- `setNumber(key, value)` - Set number variable
 - `setBool(key, value)` - Set boolean variable
-- `compile(template)` - Compile template with current variables
+- `setArray(key, value)` - Set array variable
+- `setObject(key, value)` - Set object variable
+- `setVariables(object)` - Set multiple variables from an object
+- `compile(template, options)` - Compile template with current variables
+- `render(template, variables, options)` - Compile template with variables in one call
 
 ### `version()`
 
 Get zig-pug version.
 
 ```javascript
-console.log(zigpug.version()); // "0.2.0"
+console.log(zigpug.version()); // "0.4.0"
 ```
 
 ## Platform Support
@@ -382,6 +469,7 @@ console.log(`${iterations} in ${elapsed}ms`);
 1. **Reuse PugCompiler** - Faster than creating new context each time
 2. **Pre-load templates** - Read files once at startup
 3. **Use Bun.js** - 2-5x faster than Node.js
+4. **Use minify in production** - Smaller output, faster rendering
 
 ## Examples
 
@@ -390,6 +478,7 @@ See the [examples](https://github.com/carlos-sweb/zig-pug/tree/main/examples) di
 - **Node.js**: `examples/nodejs/`
 - **Bun.js**: `examples/bun/`
 - **Express**: `examples/nodejs/05-express-integration.js`
+- **TypeScript**: `examples/nodejs/08-typescript-example.ts`
 
 ## Documentation
 

package/index.d.ts

@@ -65,6 +65,20 @@ export interface PugVariables {
     [key: string]: PugVariable;
 }
 
+/**
+ * Compilation options for formatting output
+ */
+export interface CompilationOptions {
+    /** Enable pretty-print with indentation and comments (development mode) */
+    pretty?: boolean;
+    /** Enable pretty-print without comments (readable mode) */
+    format?: boolean;
+    /** Enable HTML minification (production mode) */
+    minify?: boolean;
+    /** Include HTML comments in output (only with pretty/format) */
+    includeComments?: boolean;
+}
+
 /**
  * PugCompiler class for advanced usage with reusable context
  *
@@ -79,9 +93,22 @@ export interface PugVariables {
 export class PugCompiler {
     /**
      * Create a new PugCompiler instance
+     * @param options - Default compilation options
      * @throws {Error} If context creation fails
+     *
+     * @example
+     * ```typescript
+     * // Development mode with pretty-printing
+     * const devCompiler = new PugCompiler({ pretty: true });
+     *
+     * // Production mode with minification
+     * const prodCompiler = new PugCompiler({ minify: true });
+     *
+     * // Readable mode without comments
+     * const readableCompiler = new PugCompiler({ format: true });
+     * ```
      */
-    constructor();
+    constructor(options?: CompilationOptions);
 
     /**
      * Set a variable (auto-detects type)
@@ -203,6 +230,7 @@ export class PugCompiler {
     /**
      * Compile a Pug template to HTML
      * @param template - Pug template string
+     * @param options - Compilation options (overrides constructor options)
      * @returns Compiled HTML string
      * @throws {TypeError} If template is not a string
      * @throws {ZigPugCompilationError} If compilation fails with structured error info
@@ -211,7 +239,12 @@ export class PugCompiler {
      * @example
      * ```typescript
      * try {
+     *     // Use default options from constructor
      *     const html = compiler.compile('h1= title');
+     *
+     *     // Override options for this compilation
+     *     const prettyHtml = compiler.compile('h1= title', { pretty: true });
+     *
      *     console.log(html);
      * } catch (error) {
      *     if ((error as ZigPugCompilationError).compilationErrors) {
@@ -223,12 +256,13 @@ export class PugCompiler {
      * }
      * ```
      */
-    compile(template: string): string;
+    compile(template: string, options?: CompilationOptions): string;
 
     /**
      * Compile a template with variables in one call
      * @param template - Pug template string
      * @param variables - Variables to set before compiling
+     * @param options - Compilation options (overrides constructor options)
      * @returns Compiled HTML string
      * @throws {TypeError} If template is not a string
      * @throws {ZigPugCompilationError} If compilation fails
@@ -236,15 +270,17 @@ export class PugCompiler {
      * @example
      * ```typescript
      * const html = compiler.render('h1= title', { title: 'Hello' });
+     * const prettyHtml = compiler.render('h1= title', { title: 'Hello' }, { pretty: true });
      * ```
      */
-    render(template: string, variables?: PugVariables): string;
+    render(template: string, variables?: PugVariables, options?: CompilationOptions): string;
 }
 
 /**
  * Compile a Pug template string to HTML (simple API)
  * @param template - Pug template string
  * @param variables - Optional variables for interpolation
+ * @param options - Optional compilation options
  * @returns Compiled HTML string
  * @throws {ZigPugCompilationError} If compilation fails
  *
@@ -252,14 +288,18 @@ export class PugCompiler {
  * ```typescript
  * const html = compile('p Hello #{name}!', { name: 'World' });
  * console.log(html); // <p>Hello World!</p>
+ *
+ * // With pretty-print
+ * const prettyHtml = compile('div\n  p Hello', {}, { pretty: true });
  * ```
  */
-export function compile(template: string, variables?: PugVariables): string;
+export function compile(template: string, variables?: PugVariables, options?: CompilationOptions): string;
 
 /**
  * Compile a Pug template from a file
  * @param filename - Path to .pug file
  * @param variables - Optional variables for interpolation
+ * @param options - Optional compilation options
  * @returns Compiled HTML string
  * @throws {Error} If file cannot be read
  * @throws {ZigPugCompilationError} If compilation fails
@@ -270,9 +310,12 @@ export function compile(template: string, variables?: PugVariables): string;
  *     title: 'Home',
  *     user: { name: 'John' }
  * });
+ *
+ * // Development mode with pretty-print
+ * const devHtml = compileFile('./views/index.pug', { title: 'Home' }, { pretty: true });
  * ```
  */
-export function compileFile(filename: string, variables?: PugVariables): string;
+export function compileFile(filename: string, variables?: PugVariables, options?: CompilationOptions): string;
 
 /**
  * Get zig-pug version string

package/index.js

@@ -43,13 +43,28 @@ if (fs.existsSync(prebuiltPath)) {
 
 /**
  * PugCompiler class - High-level API for compiling Pug templates
+ * @param {Object} options - Compiler options
+ * @param {boolean} options.pretty - Enable pretty-print with indentation and comments (development mode)
+ * @param {boolean} options.format - Enable pretty-print without comments (readable mode)
+ * @param {boolean} options.minify - Enable HTML minification (production mode)
+ * @param {boolean} options.includeComments - Include HTML comments (only with pretty/format)
  */
 class PugCompiler {
-    constructor() {
+    constructor(options = {}) {
         this.context = binding.createContext();
         if (!this.context) {
             throw new Error('Failed to create zig-pug context');
         }
+
+        // Default options
+        this.defaultOptions = {
+            pretty: options.pretty || false,
+            format: options.format || false,
+            minify: options.minify || false,
+            includeComments: options.includeComments !== undefined
+                ? options.includeComments
+                : (options.pretty || false)
+        };
     }
 
     /**
@@ -199,18 +214,42 @@ class PugCompiler {
     /**
      * Compile a Pug template to HTML
      * @param {string} template - Pug template string
+     * @param {Object} options - Compilation options (overrides constructor options)
+     * @param {boolean} options.pretty - Enable pretty-print with indentation and comments
+     * @param {boolean} options.format - Enable pretty-print without comments
+     * @param {boolean} options.minify - Enable HTML minification
+     * @param {boolean} options.includeComments - Include HTML comments
      * @returns {string} - Compiled HTML
      */
-    compile(template) {
+    compile(template, options = {}) {
         if (typeof template !== 'string') {
             throw new TypeError('Template must be a string');
         }
 
-        const html = binding.compile(this.context, template);
+        let html = binding.compile(this.context, template);
         if (!html) {
             throw new Error('Failed to compile template');
         }
 
+        // Merge default options with compile-time options
+        const finalOptions = { ...this.defaultOptions, ...options };
+
+        // Apply formatting based on options
+        if (finalOptions.minify) {
+            const minified = binding.minify(html);
+            if (minified) {
+                html = minified;
+            }
+        } else if (finalOptions.pretty || finalOptions.format) {
+            const includeComments = finalOptions.includeComments !== undefined
+                ? finalOptions.includeComments
+                : finalOptions.pretty;
+            const formatted = binding.prettyPrint(html, includeComments);
+            if (formatted) {
+                html = formatted;
+            }
+        }
+
         return html;
     }
 
@@ -218,11 +257,12 @@ class PugCompiler {
      * Compile a template with variables in one call
      * @param {string} template - Pug template string
      * @param {Object} variables - Variables to set before compiling
+     * @param {Object} options - Compilation options (overrides constructor options)
      * @returns {string} - Compiled HTML
      */
-    render(template, variables = {}) {
+    render(template, variables = {}, options = {}) {
         this.setVariables(variables);
-        return this.compile(template);
+        return this.compile(template, options);
     }
 }
 
@@ -230,10 +270,11 @@ class PugCompiler {
  * Convenience function to compile a template with variables
  * @param {string} template - Pug template string
  * @param {Object} variables - Variables for the template
+ * @param {Object} options - Compilation options
  * @returns {string} - Compiled HTML
  */
-function compile(template, variables = {}) {
-    const compiler = new PugCompiler();
+function compile(template, variables = {}, options = {}) {
+    const compiler = new PugCompiler(options);
     return compiler.render(template, variables);
 }
 
@@ -241,12 +282,13 @@ function compile(template, variables = {}) {
  * Convenience function to compile a template from a file
  * @param {string} filename - Path to the Pug template file
  * @param {Object} variables - Variables for the template
+ * @param {Object} options - Compilation options
  * @returns {string} - Compiled HTML
  */
-function compileFile(filename, variables = {}) {
+function compileFile(filename, variables = {}, options = {}) {
     const fs = require('fs');
     const template = fs.readFileSync(filename, 'utf8');
-    return compile(template, variables);
+    return compile(template, variables, options);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zig-pug",
-  "version": "4.0.5",
+  "version": "4.0.6",
   "description": "High-performance Pug template engine powered by Zig and mujs. Native N-API addon with ES5.1 JavaScript support, full UTF-8 (emoji, accents), Builder API for dynamic data construction, comprehensive C/C++ API, and fast compilation. Compatible with Node.js and Bun.",
   "type": "commonjs",
   "main": "index.js",